Release 1.x‎ > ‎

Configuration Reference

This guide will cover sections and options related to Project OpenPTK's XML configuration file. A complete Sample XML Configuration File (openptk.xml) is available for reference.

Sections:

Contexts Context
    Subject
    Service
      Properties Property
    Query
Subjects Subject
    Attributes Attribute
        Transformations Transform
            Operations Operation
            Arguments Argument

Top

Contexts

This section defines the available Contexts and sets some global values used by the Framework.

Syntax

<Contexts default="Person-SPML-Sun"
          logger="UnixLogFile"
          debug="4"
          audit="false"
          timestamp="true">
   <Context ...>
   </Context>
   ...
</Contexts>

Arguments

Name Required Description Example
default Yes Which Context should be used if a Context is not specified. default="Person-SPML-Sun"
logger Yes Which Logger should be used. The Logger is used by the Framework to handle all types of information that needs to be recorded to a log. logger="UnixLogFile"
debug Yes Specifies what level of debugging data should be sent to the Logger. A value of "0" turns of all debugging output (only INFO and ERRORS are sent to the Logger. To turn on the debug out, set the value between "1" and "4". The higher the number, the more details. debug="4"
audit Yes Send audit information to the Logger. Values are "true" or "false". audit="false"
timestamp Yes Collect timestamp information send timings to the Logger. Values are "true" or "false". timestamp="true"

Parent Element

<OpenPTK>

Child Element(s)

Top

Contexts.Context

A Context defines the association of a Subject and a Service with an optional Query.

Syntax

<Context id="Person-SPML" classname="org.openptk.provision.common.TimeoutContext">
  <Subject .../>
  <Service ...>
    ...
  </Service>
  <Query .../>
</Context>

Arguments

Name Required Description Example
id Yes A unique identifier for the Context id="Person-SPML"
classname Yes The fully qualified name of the Java class that implements the Context Interface classname="org.openptk.provision.common.TimeoutContext"

Parent Element

Contexts

Child Element(s)

Top

Contexts.Context.Subject

Syntax

<Subject id="Person"/>

Arguments

Name Required Description Example
id Yes The unique id of a valid Subject id="Person"

Parent Element

Context

Child Element(s)

  • (none)

Top

Contexts.Context.Service

Syntax

<Service id="SPML">
  <Properties>
    ...  
  </Properties>
</Service>

Arguments

Name Required Description Example
id Yes The unique id of a valid Service id="SPML"

Parent Element

Context

Child Element(s)

Top

Contexts.Context.Service.Properties

The Properties defined within the Service of a Context, will be added to any Properties that already defined within the Service. If there is a Property with the same name, as defined in the Service, the Property will be replaced with the value defined in this Context.

Syntax

<Properties>
  <Property name="url" value="http://sample.openptk.org:80/idm/servlet/rpcrouter2"/>
  <Property name="objectclass" value="user"/>                    
</Properties>

Arguments

Name Required Description Example
name Yes The name of the Property name="foo"
value Yes The value of the Property value="bar"

Parent Element

Service

Child Element(s)

  • (none)

Top

Contexts.Context.Query

The Query Element is used to define scoping of the Context. The Query is not actually used by the Context, it is made available to the Service. The Context will create a PTK Query object and automatically add it to the Service's Operations. The Service implementation may or may not use the Query Element. Please refer to the Java Docs for details on configuring Query objects.

Syntax

<!-- simple query -->
<Query type="EQ" name="MemberObjectGroups" value="All People"/>

<!-- complex query -->
<Query type="AND">
  <Query type="EQ" name="MemberObjectGroups" serviceName="MemberObjectGroups" value="All People"/>
  <Query type="EQ" name="objectclass" value="user"/>
</Query>

Arguments

Name Required Description Example
type Yes The queries Type. Refer to the Java Docs for available Types. For a "Simple Query", the type will be a typical evaluation key word (such as "EQ"). For a "Complex Query", the type will use either "AND" or "OR" for keywords. type="EQ"
name Yes The name of the value that's used for evaluation name="objectClass"
value Yes The value that will be used for evaluation value="inetOrgPerson"

Parent Element

Context

Child Element(s)

  • (none)

Top

Subjects

This section defines the available Subjects

A Subject is an abstract object. It can be used to model (represent) many actual objects (Person, Role, Group, Computer, etc.)

Syntax

<Subjects>
  <Subject id="Person" key="uniqueid" password="password" role="Roles" classname="org.openptk.provision.api.Person">
    <Attributes>
    ...
    </Attributes>
  </Subject>
  ...
</Subjects>

Arguments

Name Required Description Example
id Yes A unique identifier for the Subject id="MySubject"
key Yes Defines which Attribute (within the Subject) that is the unique id (primary key) for the Subject key="empno"
password No Defines which Attribute (within the Subject) that is the password password="userpwd"
role No Defines which Attribute (within the Subject) that is the role role="roles"
classname Yes A fully qualified name of the Java class that implements the Subject Interface classname="org.openptk.provision.api.Person"

Parent Element

<OpenPTK>

Child Element(s)

Top

Subjects.Subject.Attributes

This section defines the available Attributes for a Subject

Syntax

<Attributes>
  <Attribute id="uniqueid" required="true" type="String">
    ...
  </Attribute>
  ...
</Attributes>

Arguments

Name Required Description Example
id Yes The unique identifier for the Attribute id="firstname"
required No Flags the Attribute as being required. Valid settings are true or false. The default value is false. If the setting is true, then one of two things could happen. If there IS a Transformation then it will be used to automatically generate a value for the attribute. If there IS NOT a Transformation then an error is returned to the Consumer Tier application. required="true"
type No Defines the data type for the Attribute. Valid settings are: String, StringArray. If not set, the default value is String type="String"
encrypted No Indicates that the data within the Attribute is encrypted. Valid settings are true and false. The default setting is false. Note: This flag is currently not being used. encrypted="true"
access No Defines what parts of the Framework should have "access" to the Attribute. Valid settings are public and private. The default setting is public. When set to public the Attribute is available to the internal Framework and to the Consumer Tier applications. When set to private the Attribute is only available to the internal Framework. private Attributes are typically used for transformations where they are used only for internal operations but should not be made available to the Consumer Tier applications (such as a users password). access="private"

Parent Element

Subjects

Child Element(s)

Top

Subjects.Subject.Attributes.Attribute.Transformations

A collection of Transforms related to an Attribute. There is, at most, only two sub Transforms one for toService and toFramework.

A Transform is used to automatically derive the Attribute. Attribute derivation can be processed differently for outbound (toService) and inbound (toFramework) Operations. There can be only one Transform for each type. The Transform will be activated under one or both of these two conditions:

  1. The Consumer Tier applications adds the Attribute to the Input object.
  2. The Attribute has the argument required set to true.

Syntax

<Transformations>
  <Transform type="toService" classname="org.openptk.provision.transform.ModifyAttributes">
    <Operations>
    ...
    </Operations>
    <Arguments>
    ...
    </Arguments>
  </Transform>
</Transformation>

Arguments

Name Required Description Example
type Yes The Transform type. There are two allowed values: toService and toFramework. The toService Transform is evaluated when there is an operation and processing is "from the Framework to the Service". The toFramework _Transform is evaluated when there is an operation and processing is "from the Service to the Framework". type="toFramework"
classname Yes A fully qualified Java classname that implements the Transform Interface classname="org.openptk.provision.transform.ConcatStrings"
useexisting No This is a flag to the Framework. The default setting is false. Valid settings are true and false. If the setting is true then the Transform will look to see if the Attribute already has a value. If it has a value then the Transform will NOT be used and the provided "existing" value will be used. useexisting="true"

Parent Element

Attribute

Child Elements

Top

Subjects.Subject.Attributes.Attribute.Transformations.Transform.Operations

Operations contain one or more Operation Elements that define when to apply a Transformation to an Attribute. Valid Operation types include:

  • create
  • read
  • update
  • search

Syntax

<Operations>
  <Operation type="create"/>
  <Operation type="update"/>
  ...
</Operations>

Arguments

Name Required Description Example
type Yes The name of the operation. There is no default value. type="read"

Parent Element

Transform

Child Element(s)

  • (none)

Top

Subjects.Subject.Attributes.Attribute.Transformations.Transform.Arguments

Arguments are used by the Transform implementation. There are two types of Arguments:

arg description
attribute The value is a name of an Attribute and it's value is assigned to the name of the Argument
literal The value is treated as a constant string and is assigned to the name of the Argument

Syntax

<Arguments>
  <Argument name="first" arg="attribute" value="firstname"/>
  <Argument name="dot" arg="literal" value="."/>
  <Argument name="last" arg="attribute" value="lastname"/>
  <Argument name="at" arg="literal" value="@"/>
  <Argument name="domainname" arg="literal" value="openptk.org"/>
 </Arguments>

Arguments

Name Required Description Example
name Yes A unique name for the Argument name="first"
arg Yes The argument type. The value must be either literal or attribute arg="attribute"
value Yes The value of the Argument. value="firstname"

Parent Element

Transform

Child Element(s)

  • (none)

Top

Services

This section defines the available Subjects

A Service is an interface to a "back-end" user repository. A Service will be implemented via a class that supports the Service Interface. Defined Properties will be made available to the Service. The Operations declare what capabilities a given Service supports. The Attributes define what is available from the user repository.

Syntax

<Services>
  <Service id="SPML" classname="org.openptk.provision.spi.SpmlService" description="Sun Identity Manager SPML"  sort="lastname,firstname">
    <Properties>
    ...
    </Properties>
    <Operations>
    ...
    </Operations>
    <Attributes>
    ...
    </Attributes>
  </Service>
</Services>

Arguments

Name Required Description Example
id Yes A unique identifier for the Service id="SPML"
description No A description of the Service descriptopn="My Service"
classname Yes A fully qualified name of the Java class that implements the Service Interface classname="org.openptk.provision.spi.SpmlService"
sort No A comma separated list of Attributes (within the Service) that will be used to build a "sorting string". If this argument is used, then the Framework will sort search results using this "sorting string". If this argument is NOT used, then search results will NOT be sorted. sort="lastname,firstname"

Parent Element

<OpenPTK>

Child Elements

Top

Services.Service.Properties

Properties that are specific to a Service. These Properties will be replaced by Properties in a Context if the y have the same name.

Syntax

<Properties>
  <Property name="url" value="http://sample.openptk.org:80/idm/servlet/rpcrouter2"/>
</Properties>

Arguments

Name Required Description Example
name Yes The name of the Property name="foo"
value Yes The value of the Property value="bar"

Parent Element

Service

Child Element(s)

  • (none)

Top

Services.Service.Operations

Defines what Operations the Service supports.

Valid Operation types include:

  • create
  • read
  • update
  • delete
  • search
  • passwordChange
  • passwordReset

Syntax

<Operations>
  <Operation type="create" timeout="8000"/>
  <Operation type="update"/>
  ...
</Operations>

Arguments

Name Required Description Example
type Yes The name of the operation. There is no default value. type="read"
timeout No Set the timeout value (milliseconds) for the operations. If not set, the timeout value will assume a defult (usually set in the Context) timeout="8000"

Parent Element

Service

Child Element(s)

  • (none)

Top

Services.Service.Attributes

Defines what Attributes the Service supports. The id defines the Attributes name which is how Consumer Tier applications will reference the Attributes. The back-end Service name will use the same value as the id unless it is explicitly set using the servicename argument. The servicename argument allows a Framework Attribute to have a Consumer Tier name that is different then the Attributes name known by the Service.

Syntax

<Attributes>
  <Attribute id="uniqueid"  servicename="uid"/>
  <Attribute id="firstname" servicename="gn" />
  <Attribute id="lastname" servicename="sn" />
  <Attribute id="manager"/>
  <Attribute id="email"/>
  ...
</Attributes>

Arguments

Name Required Description Example
id Yes The name of the Attribute as known by the Framework, what the Consumer Tier Applications will reference. id="firstname"
servicename No The name of the Attribute as known by the back-end Service. This name is not exposed to the Consumer Tier applications. servicename="gn"

Parent Element

Service

Child Elements

(none)

Top

Loggers

A Logger is used to capture INFO, WARNING, ERROR, and DEBUG messages.

Syntax

<Loggers>
  <Logger id="UnixLogFile" classname="org.openptk.provision.logging.AtomicLogger">
   ...
  </Logger>
  ...
</Loggers>

Arguments

Name Required Description Example
id Yes A unique identifier for the Logger id="MyLogger"
classname Yes The fully qualified classname that implements the Loggin interface. classname="org.openptk.provision.logging.AtomicLogger"

Parent Element

<OpenPTK>

Child Element(s)

Top

Loggers.Logger.Properties

Properties that are used by the Logger.

Syntax

<Properties>
  <Property name="file" value="/var/tmp/openptk.log"/>                   
</Properties>

Arguments

Name Required Description Example
name Yes The name of the Property name="foo"
value Yes The value of the Property value="bar"

Parent Element

Logger

Child Element(s)

  • (none)