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:
| Subjects | Subject | ||||||
|---|---|---|---|---|---|---|---|
| Attributes | Attribute | ||||||
| Transformations | Transform | ||||||
| Operations | Operation | ||||||
| Arguments | Argument |
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)
- Context (required: one or more)
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
Child Element(s)
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
Child Element(s)
- (none)
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
Child Element(s)
- Properties (optional: none or 1)
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
Child Element(s)
- (none)
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
Child Element(s)
- (none)
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)
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
Child Element(s)
- Transformations (none or only 1)
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:
- The Consumer Tier applications adds the Attribute to the Input object.
- 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
Child Elements
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
Child Element(s)
- (none)
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
Child Element(s)
- (none)
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
- Properties (none or 1)
- Operations (only 1)
- Attributes (only 1)
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
Child Element(s)
- (none)
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
Child Element(s)
- (none)
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
Child Elements
(none)
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)
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
Child Element(s)
- (none)
Sign up or Log in to add a comment or watch this page.