{anchor:Top}
This guide will cover sections and options related to Project OpenPTK's XML configuration file. A complete [Sample XML Configuration File (openptk.xml)|openptk:Release 1.1 Sample XML file] is available for reference.
{anchor:Sections}
h1. Sections:
|| [Contexts|#Contexts] || [Context|#Contexts-Context] ||
| | | [Subject|#Contexts-Context-Subject] |
| | | [Service|#Contexts-Context-Service] |
| | | | [Properties|#C-C-S-P] | [Property|#C-C-S-P] |
| | | [Query|#Contexts-Context-Query] |
|| [Subjects|#Subjects] || [Subject|#Subjects] ||
| | | [Attributes|#Subjects-Subject-Attributes] | [Attribute|#Subjects-Subject-Attributes] |
| | | | | [Transformations|#S-S-A-A-T] | [Transform|#S-S-A-A-T] |
| | | | | | | [Operations|#S-S-A-A-T-T-O] | [Operation|#S-S-A-A-T-T-O] |
| | | | | | | [Arguments|#S-S-A-A-T-T-A] | [Argument|#S-S-A-A-T-T-A] |
|| [Services|#Services] || [Service|#Services] ||
| | | [Properties|#Services-Service-Properties] | [Property|#Services-Service-Properties] |
| | | [Operations|#Services-Service-Operations] | [Operation|#Services-Service-Operations] |
| | | [Attributes|#Services-Service-Attributes] | [Attribute|#Services-Service-Attributes] |
|| [Loggers|#Loggers] || [Logger|#Loggers] ||
| | | [Properties|#Loggers-Properties] | [Property|#Loggers-Properties] |
[Top|#Top]
----
{anchor:Contexts}
h2. Contexts
This section defines the available _Contexts_ and sets some global values used by the Framework.
h3. Syntax
{code:xml}
<Contexts default="Person-SPML-Sun"
logger="UnixLogFile"
debug="4"
audit="false"
timestamp="true">
<Context ...>
</Context>
...
</Contexts>
{code}
h3. Arguments
||Name||Required||Description||Example||
| {{default}} | Yes | Which [Context|#ContextsContext] should be used if a Context is not specified. | {{default="Person-SPML-Sun"}} |
| {{logger}} | Yes | Which [Logger|#LoggersLogger] 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"}} |
h3. Parent Element
{{<OpenPTK>}}
h3. Child Element(s)
* [Context|#Contexts-Context] (required: one or more)
[Top|#Top]
----
{anchor:Contexts-Context}
h2. Contexts.Context
A Context defines the association of a [Subject|#Subjects-Subject] and a [Service|#Services-Service] with an optional [Query|#Contexts-Context-Query].
h3. Syntax
{code:xml}
<Context id="Person-SPML" classname="org.openptk.provision.common.TimeoutContext">
<Subject .../>
<Service ...>
...
</Service>
<Query .../>
</Context>
{code}
h3. 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"}} |
h3. Parent Element
[Contexts|#Contexts]
h3. Child Element(s)
* [Subject|#Contexts-Context-Subject] (required: only 1)
* [Service|#Contexts-Context-Service] (required: only 1)
* [Query |#Contexts-Context-Query] (optional: none or 1)
[Top|#Top]
----
{anchor:Contexts-Context-Subject}
h2. Contexts.Context.Subject
h3. Syntax
{code:xml}
<Subject id="Person"/>
{code}
h3. Arguments
|| Name || Required || Description || Example ||
| {{id}} | Yes | The unique id of a valid [Subject|#Subjects-Subject] | {{id="Person"}} |
h3. Parent Element
[Context|#Contexts-Context]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Contexts-Context-Service}
h2. Contexts.Context.Service
h3. Syntax
{code:xml}
<Service id="SPML">
<Properties>
...
</Properties>
</Service>
{code}
h3. Arguments
|| Name || Required || Description || Example ||
| {{id}} | Yes | The unique id of a valid [Service|#Services-Service] | {{id="SPML"}} |
h3. Parent Element
[Context|#Contexts-Context]
h3. Child Element(s)
* [Properties|#C-C-S-P] (optional: none or 1)
[Top|#Top]
----
{anchor:C-C-S-P}
h2. 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_.
h3. Syntax
{code:xml}
<Properties>
<Property name="url" value="http://sample.openptk.org:80/idm/servlet/rpcrouter2"/>
<Property name="objectclass" value="user"/>
</Properties>
{code}
h3. Arguments
||Name||Required||Description||Example||
|{{name}} | Yes | The name of the Property | {{name="foo"}} |
|{{value}} | Yes | The value of the Property | {{value="bar"}} |
h3. Parent Element
[Service|#Contexts-Context-Service]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Contexts-Context-Query}
h2. 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|http://sample.openptk.org/javadoc] for details on configuring _Query_ objects.
h3. Syntax
{code:xml}
<!-- simple query -->
<Query type="EQ" name="MemberObjectGroups" value="All People"/>
{code}
{code:xml}
<!-- complex query -->
<Query type="AND">
<Query type="EQ" name="MemberObjectGroups" serviceName="MemberObjectGroups" value="All People"/>
<Query type="EQ" name="objectclass" value="user"/>
</Query>
{code}
h3. 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"}} |
h3. Parent Element
[Context|#Contexts-Context]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Subjects}
h2. 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.)
h3. Syntax
{code:xml}
<Subjects>
<Subject id="Person" key="uniqueid" password="password" role="Roles" classname="org.openptk.provision.api.Person">
<Attributes>
...
</Attributes>
</Subject>
...
</Subjects>
{code}
h3. 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"}} |
h3. Parent Element
{{<OpenPTK>}}
h3. Child Element(s)
* [Attributes|#Subjects-Subject-Attributes]
[Top|#Top]
----
{anchor:Subjects-Subject-Attributes}
h2. Subjects.Subject.Attributes
This section defines the available _Attributes_ for a _Subject_
h3. Syntax
{code:xml}
<Attributes>
<Attribute id="uniqueid" required="true" type="String">
...
</Attribute>
...
</Attributes>
{code}
h3. 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"}} |
h3. Parent Element
[Subjects|#Subjects]
h3. Child Element(s)
* [Transformations|#S-S-A-A-T] (none or only 1)
[Top|#Top]
----
{anchor:S-S-A-A-T}
h2. 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}}.
h3. Syntax
{code:xml}
<Transformations>
<Transform type="toService" classname="org.openptk.provision.transform.ModifyAttributes">
<Operations>
...
</Operations>
<Arguments>
...
</Arguments>
</Transform>
</Transformation>
{code}
h3. 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"}}|
h3. Parent Element
[Attribute|#Subjects-Subject-Attributes]
h3. Child Elements
* [Operations|#S-S-A-A-T-T-O]
* [Arguments|#S-S-A-A-T-T-A]
[Top|#Top]
----
{anchor:S-S-A-A-T-T-O}
h2. 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}}
h3. Syntax
{code:xml}
<Operations>
<Operation type="create"/>
<Operation type="update"/>
...
</Operations>
{code}
h3. Arguments
||Name||Required||Description||Example||
| {{type}} | Yes | The name of the operation. There is no default value. | {{type="read"}} |
h3. Parent Element
[Transform|#S-S-A-A-T]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:S-S-A-A-T-T-A}
h2. 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 |
h3. Syntax
{code:xml}
<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>
{code}
h3. 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"}} |
h3. Parent Element
[Transform|#S-S-A-A-T]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Services}
h2. 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.
h3. Syntax
{code:xml}
<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>
{code}
h3. 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"}} |
h3. Parent Element
{{<OpenPTK>}}
h3. Child Elements
* [Properties|#Services-Service-Properties] (none or 1)
* [Operations|#Services-Service-Operations] (only 1)
* [Attributes|#Services-Service-Attributes] (only 1)
[Top|#Top]
----
{anchor:Services-Service-Properties}
h2. 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.
h3. Syntax
{code:xml}
<Properties>
<Property name="url" value="http://sample.openptk.org:80/idm/servlet/rpcrouter2"/>
</Properties>
{code}
h3. Arguments
||Name||Required||Description||Example||
|{{name}} | Yes | The name of the Property | {{name="foo"}} |
|{{value}} | Yes | The value of the Property | {{value="bar"}} |
h3. Parent Element
[Service|#Services]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Services-Service-Operations}
h2. Services.Service.Operations
Defines what _Operations_ the _Service_ supports.
Valid _Operation_ types include:
* {{create}}
* {{read}}
* {{update}}
* {{delete}}
* {{search}}
* {{passwordChange}}
* {{passwordReset}}
h3. Syntax
{code:xml}
<Operations>
<Operation type="create" timeout="8000"/>
<Operation type="update"/>
...
</Operations>
{code}
h3. 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"}} |
h3. Parent Element
[Service|#Services]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Services-Service-Attributes}
h2. 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_.
h3. Syntax
{code:xml}
<Attributes>
<Attribute id="uniqueid" servicename="uid"/>
<Attribute id="firstname" servicename="gn" />
<Attribute id="lastname" servicename="sn" />
<Attribute id="manager"/>
<Attribute id="email"/>
...
</Attributes>
{code}
h3. 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"}} |
h3. Parent Element
[Service|#Services]
h3. Child Elements
(none)
[Top|#Top]
----
{anchor:Loggers}
h2. Loggers
A Logger is used to capture INFO, WARNING, ERROR, and DEBUG messages.
h3. Syntax
{code:xml}
<Loggers>
<Logger id="UnixLogFile" classname="org.openptk.provision.logging.AtomicLogger">
...
</Logger>
...
</Loggers>
{code}
h3. 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"}} |
h3. Parent Element
{{<OpenPTK>}}
h3. Child Element(s)
* [Properties|#Loggers-Properties]
[Top|#Top]
----
{anchor:Loggers-Properties}
h2. Loggers.Logger.Properties
Properties that are used by the Logger.
h3. Syntax
{code:xml}
<Properties>
<Property name="file" value="/var/tmp/openptk.log"/>
</Properties>
{code}
h3. Arguments
||Name||Required||Description||Example||
|{{name}} | Yes | The name of the Property | {{name="foo"}} |
|{{value}} | Yes | The value of the Property | {{value="bar"}} |
h3. Parent Element
[Logger|#Loggers]
h3. Child Element(s)
* (none)
[Top|#Top]
----
This guide will cover sections and options related to Project OpenPTK's XML configuration file. A complete [Sample XML Configuration File (openptk.xml)|openptk:Release 1.1 Sample XML file] is available for reference.
{anchor:Sections}
h1. Sections:
|| [Contexts|#Contexts] || [Context|#Contexts-Context] ||
| | | [Subject|#Contexts-Context-Subject] |
| | | [Service|#Contexts-Context-Service] |
| | | | [Properties|#C-C-S-P] | [Property|#C-C-S-P] |
| | | [Query|#Contexts-Context-Query] |
|| [Subjects|#Subjects] || [Subject|#Subjects] ||
| | | [Attributes|#Subjects-Subject-Attributes] | [Attribute|#Subjects-Subject-Attributes] |
| | | | | [Transformations|#S-S-A-A-T] | [Transform|#S-S-A-A-T] |
| | | | | | | [Operations|#S-S-A-A-T-T-O] | [Operation|#S-S-A-A-T-T-O] |
| | | | | | | [Arguments|#S-S-A-A-T-T-A] | [Argument|#S-S-A-A-T-T-A] |
|| [Services|#Services] || [Service|#Services] ||
| | | [Properties|#Services-Service-Properties] | [Property|#Services-Service-Properties] |
| | | [Operations|#Services-Service-Operations] | [Operation|#Services-Service-Operations] |
| | | [Attributes|#Services-Service-Attributes] | [Attribute|#Services-Service-Attributes] |
|| [Loggers|#Loggers] || [Logger|#Loggers] ||
| | | [Properties|#Loggers-Properties] | [Property|#Loggers-Properties] |
[Top|#Top]
----
{anchor:Contexts}
h2. Contexts
This section defines the available _Contexts_ and sets some global values used by the Framework.
h3. Syntax
{code:xml}
<Contexts default="Person-SPML-Sun"
logger="UnixLogFile"
debug="4"
audit="false"
timestamp="true">
<Context ...>
</Context>
...
</Contexts>
{code}
h3. Arguments
||Name||Required||Description||Example||
| {{default}} | Yes | Which [Context|#ContextsContext] should be used if a Context is not specified. | {{default="Person-SPML-Sun"}} |
| {{logger}} | Yes | Which [Logger|#LoggersLogger] 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"}} |
h3. Parent Element
{{<OpenPTK>}}
h3. Child Element(s)
* [Context|#Contexts-Context] (required: one or more)
[Top|#Top]
----
{anchor:Contexts-Context}
h2. Contexts.Context
A Context defines the association of a [Subject|#Subjects-Subject] and a [Service|#Services-Service] with an optional [Query|#Contexts-Context-Query].
h3. Syntax
{code:xml}
<Context id="Person-SPML" classname="org.openptk.provision.common.TimeoutContext">
<Subject .../>
<Service ...>
...
</Service>
<Query .../>
</Context>
{code}
h3. 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"}} |
h3. Parent Element
[Contexts|#Contexts]
h3. Child Element(s)
* [Subject|#Contexts-Context-Subject] (required: only 1)
* [Service|#Contexts-Context-Service] (required: only 1)
* [Query |#Contexts-Context-Query] (optional: none or 1)
[Top|#Top]
----
{anchor:Contexts-Context-Subject}
h2. Contexts.Context.Subject
h3. Syntax
{code:xml}
<Subject id="Person"/>
{code}
h3. Arguments
|| Name || Required || Description || Example ||
| {{id}} | Yes | The unique id of a valid [Subject|#Subjects-Subject] | {{id="Person"}} |
h3. Parent Element
[Context|#Contexts-Context]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Contexts-Context-Service}
h2. Contexts.Context.Service
h3. Syntax
{code:xml}
<Service id="SPML">
<Properties>
...
</Properties>
</Service>
{code}
h3. Arguments
|| Name || Required || Description || Example ||
| {{id}} | Yes | The unique id of a valid [Service|#Services-Service] | {{id="SPML"}} |
h3. Parent Element
[Context|#Contexts-Context]
h3. Child Element(s)
* [Properties|#C-C-S-P] (optional: none or 1)
[Top|#Top]
----
{anchor:C-C-S-P}
h2. 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_.
h3. Syntax
{code:xml}
<Properties>
<Property name="url" value="http://sample.openptk.org:80/idm/servlet/rpcrouter2"/>
<Property name="objectclass" value="user"/>
</Properties>
{code}
h3. Arguments
||Name||Required||Description||Example||
|{{name}} | Yes | The name of the Property | {{name="foo"}} |
|{{value}} | Yes | The value of the Property | {{value="bar"}} |
h3. Parent Element
[Service|#Contexts-Context-Service]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Contexts-Context-Query}
h2. 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|http://sample.openptk.org/javadoc] for details on configuring _Query_ objects.
h3. Syntax
{code:xml}
<!-- simple query -->
<Query type="EQ" name="MemberObjectGroups" value="All People"/>
{code}
{code:xml}
<!-- complex query -->
<Query type="AND">
<Query type="EQ" name="MemberObjectGroups" serviceName="MemberObjectGroups" value="All People"/>
<Query type="EQ" name="objectclass" value="user"/>
</Query>
{code}
h3. 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"}} |
h3. Parent Element
[Context|#Contexts-Context]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Subjects}
h2. 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.)
h3. Syntax
{code:xml}
<Subjects>
<Subject id="Person" key="uniqueid" password="password" role="Roles" classname="org.openptk.provision.api.Person">
<Attributes>
...
</Attributes>
</Subject>
...
</Subjects>
{code}
h3. 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"}} |
h3. Parent Element
{{<OpenPTK>}}
h3. Child Element(s)
* [Attributes|#Subjects-Subject-Attributes]
[Top|#Top]
----
{anchor:Subjects-Subject-Attributes}
h2. Subjects.Subject.Attributes
This section defines the available _Attributes_ for a _Subject_
h3. Syntax
{code:xml}
<Attributes>
<Attribute id="uniqueid" required="true" type="String">
...
</Attribute>
...
</Attributes>
{code}
h3. 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"}} |
h3. Parent Element
[Subjects|#Subjects]
h3. Child Element(s)
* [Transformations|#S-S-A-A-T] (none or only 1)
[Top|#Top]
----
{anchor:S-S-A-A-T}
h2. 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}}.
h3. Syntax
{code:xml}
<Transformations>
<Transform type="toService" classname="org.openptk.provision.transform.ModifyAttributes">
<Operations>
...
</Operations>
<Arguments>
...
</Arguments>
</Transform>
</Transformation>
{code}
h3. 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"}}|
h3. Parent Element
[Attribute|#Subjects-Subject-Attributes]
h3. Child Elements
* [Operations|#S-S-A-A-T-T-O]
* [Arguments|#S-S-A-A-T-T-A]
[Top|#Top]
----
{anchor:S-S-A-A-T-T-O}
h2. 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}}
h3. Syntax
{code:xml}
<Operations>
<Operation type="create"/>
<Operation type="update"/>
...
</Operations>
{code}
h3. Arguments
||Name||Required||Description||Example||
| {{type}} | Yes | The name of the operation. There is no default value. | {{type="read"}} |
h3. Parent Element
[Transform|#S-S-A-A-T]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:S-S-A-A-T-T-A}
h2. 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 |
h3. Syntax
{code:xml}
<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>
{code}
h3. 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"}} |
h3. Parent Element
[Transform|#S-S-A-A-T]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Services}
h2. 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.
h3. Syntax
{code:xml}
<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>
{code}
h3. 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"}} |
h3. Parent Element
{{<OpenPTK>}}
h3. Child Elements
* [Properties|#Services-Service-Properties] (none or 1)
* [Operations|#Services-Service-Operations] (only 1)
* [Attributes|#Services-Service-Attributes] (only 1)
[Top|#Top]
----
{anchor:Services-Service-Properties}
h2. 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.
h3. Syntax
{code:xml}
<Properties>
<Property name="url" value="http://sample.openptk.org:80/idm/servlet/rpcrouter2"/>
</Properties>
{code}
h3. Arguments
||Name||Required||Description||Example||
|{{name}} | Yes | The name of the Property | {{name="foo"}} |
|{{value}} | Yes | The value of the Property | {{value="bar"}} |
h3. Parent Element
[Service|#Services]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Services-Service-Operations}
h2. Services.Service.Operations
Defines what _Operations_ the _Service_ supports.
Valid _Operation_ types include:
* {{create}}
* {{read}}
* {{update}}
* {{delete}}
* {{search}}
* {{passwordChange}}
* {{passwordReset}}
h3. Syntax
{code:xml}
<Operations>
<Operation type="create" timeout="8000"/>
<Operation type="update"/>
...
</Operations>
{code}
h3. 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"}} |
h3. Parent Element
[Service|#Services]
h3. Child Element(s)
* (none)
[Top|#Top]
----
{anchor:Services-Service-Attributes}
h2. 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_.
h3. Syntax
{code:xml}
<Attributes>
<Attribute id="uniqueid" servicename="uid"/>
<Attribute id="firstname" servicename="gn" />
<Attribute id="lastname" servicename="sn" />
<Attribute id="manager"/>
<Attribute id="email"/>
...
</Attributes>
{code}
h3. 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"}} |
h3. Parent Element
[Service|#Services]
h3. Child Elements
(none)
[Top|#Top]
----
{anchor:Loggers}
h2. Loggers
A Logger is used to capture INFO, WARNING, ERROR, and DEBUG messages.
h3. Syntax
{code:xml}
<Loggers>
<Logger id="UnixLogFile" classname="org.openptk.provision.logging.AtomicLogger">
...
</Logger>
...
</Loggers>
{code}
h3. 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"}} |
h3. Parent Element
{{<OpenPTK>}}
h3. Child Element(s)
* [Properties|#Loggers-Properties]
[Top|#Top]
----
{anchor:Loggers-Properties}
h2. Loggers.Logger.Properties
Properties that are used by the Logger.
h3. Syntax
{code:xml}
<Properties>
<Property name="file" value="/var/tmp/openptk.log"/>
</Properties>
{code}
h3. Arguments
||Name||Required||Description||Example||
|{{name}} | Yes | The name of the Property | {{name="foo"}} |
|{{value}} | Yes | The value of the Property | {{value="bar"}} |
h3. Parent Element
[Logger|#Loggers]
h3. Child Element(s)
* (none)
[Top|#Top]
----