Global configuration values (GCVs) are values that can be used by the driver to control functionality. GCVs are defined on the driver or on the driver set. Driver set GCVs can be used by all drivers in the driver set. Driver GCVs can be used only by the driver on which they are defined. GCVs contain definitions related to the XML representation of global configuration values.
The precedence order in which the GCV definitions are loaded is:
GCV definitions on the driver object.
GCV definitions in the DirXML-GlobalConfigDef objects linked to the driver.
GCV definitions on the Driverset object.
GCV definitions in the DirXML- GlobalConfigDef objects linked to the Driverset.
GCVs in a driver configuration provide one or more typed values which are presented to the user (typically an administrator) by a user interface agent such as iManager or Designer, hereafter referred to as the Agent. The user can set values via the Agent. These values are used to make decisions in the driver configuration's policies.
Control values are described syntactically by an XML vocabulary. The vocabulary consists of structural elements, definition elements, reference elements, and control elements. Structural elements are essentially housekeeping units that serve to fulfill XML syntax requirements. Definition elements define the actual control values with their data types and other information. Reference elements are used to refer to data outside the definition document. Control elements affect how the Agent presents the values to the user. The following is an example of a control value XML definition:
<configuration-values> <definitions> <definition display-name="Send email on failure" name="send-email" type="boolean"> <value>true </value> </definition> </definitions> </configuration-values>
The control value definitions might be standalone XML documents or embedded in other XML documents depending on usage. For example, GCVs are defined in stand-alone documents found in stream-syntax attributes on DirXML-DriverSet and DirXML-Driver objects while Shim Parameters are embedded in a <driver-config> XML document. GCV definitions can also be present in the DirXML-Config driver object (resource object) or the driver set object. In past GCV's have been stored this way; however, with Identity Manager 4.0, GCVs are stored in the DirXML-Config objects. The DirXMl-ShimConfigInfo attribute uses the same DTD to define driver Configuration settings.An Agent that presents control values to a user is responsible for parsing the XML definition, presenting the values in a meaningful way, allowing the user to make allowable changes to the values, and finally for storing the XML definition with updated values. Some Agents might also provide for defining CVs in some cases (e.g., Designer as part of editing a driver configuration or as part of creating a Job definition). There exist Java classes in Identity Manager that can be used by Agents to assist with the parsing, correctness checking, and serialization of CV definition documents.
The following XML attributes are required (or have a default value) on a <definition> element and are common to all types:
Attribute |
Possible Values |
Default Value |
---|---|---|
name |
NMTOKEN The configuration value name. Must be unique among all descendant <definition> elements found under the <definitions> element. |
#REQUIRED |
display-name |
CDATA The string presented to the user to identify the value. |
String |
display-name-ref |
Display names or descriptions that have localization refs. |
#IMPLIED |
dn-type |
“ldap”, "slash”, “qualifiedslash”, “dot”, “qualifieddot”, “custom” Specifies the syntax allowed for the value. Agents must enforce this when the user enters the value. |
#IMPLIED |
hide |
Boolean |
#IMPLIED |
mandatory |
"true" or "false" If "true" the Agent must require the user to supply a value for the CV. |
|
type |
"string", "boolean", "integer", "real", "dn", "enum", "list", "passwordref", "dn-ref" The value type. If not present, the type defaults to string. |
#IMPLIED |
The following elements are content of a <definition> element and are common to all types except the "gcvref" type:
Name |
Explanation |
---|---|
value |
Contains the current value of the CV. Actual allowed content is defined by the individual types. |
description |
A string presented to the user to explain the value in greater detail than is present in the display-name attribute. Note that the description text might contain line breaks that must be honored when displaying the description.Description may have a description-ref attribute that is part of the localization scheme used with ECVs. |
Each configuration value has an associated data type. If the data type is not specified on the value's XML <definition> element, the data type defaults to “string”.
The engine enforces configuration value data typing. If a configuration value definition has an invalid data type, the operation depending on the configuration value definition fails (for example, starting a driver or job).
Values of data type “string” have a value that is a sequence of Unicode characters. Any valid XML character that is allowed in XML PCDATA is allowed in the value of a string value. String values might be empty (such as, the string value might have zero length). A string value might have a multiline attribute on the <definition> element. If multiline has a value of "true", the Agent should present the value honoring any embedded end-of-line characters and allow the user to specify line breaks.
Values of data type “boolean” have a value that is either “true” or “false”. Boolean values might not have empty values. The content of the value element must match the following production:Boolean ::= 'true' | 'false'
Example:
<definition type="boolean" name="perform-magic" display-name="Do what I mean, not what I say" > <value>true</value> <description>This is an example of a boolean value</description> </definition>
Values of data type “integer” have a value that is one or more Unicode characters that match the XML specification pattern Digit. Integer values might optionally be preceded by a '-' (hyphen) character indicating negation. The minimum and maximum integer values are those that can be represented in a signed, twos-complement 32-bit value as in the Java language int type. Integer values may be restricted in range. A lower bound, an upper bound, or both may be specified. The content of the value element must match the following pattern:Integer ::= '-'? Digit+Digit ::= '1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9'
Example:
<definition type="integer" name="how-much" display-name="Enter the amount to send to Perin"> <value>0</value> <description>This amount will be deducted automatically from your credit card account and sent to Perin.</description> </definition> <definition type="integer" name="port-number" display-name="Enter the TCP port to use" range-lo="1024" range-hi="65535"> <value>8080</value> <description>This is the TCP port that will be used for connecting to the application.</description> </definition> <definition type="integer" name="timeout" display-name="Timeout value in seconds" range-lo="1"> <value>10</value> <description>This is the timeout value in seconds; the driver will wait up to this number of seconds for a connection.</description> </definition>
Values of data type “real” have a value that describes a real (or floating-point) number. The total allowable range of values for a real value are those that can be represented by a 64-bit double-precision floating point value as in the Java language double type. Real values might be restricted in range. A lower bound, an upper bound, or both might be specified. The content of the value element must match the following production:Real ::= Integer | ('-'? Digit+ '.' Digit+)
Example:
<definition type="real" name="multiplier" display-name="Factor by which to multiply collective IQ" range-hi="1.0"> <value>0.6</value> <description>When one or more managers walk into a room, the collective IQ is affected. This value is used to calculate the approximate resulting collective IQ.</description> </definition>
Values of data type “dn” have a value that must be a syntactically-legal distinguished name. DN values must be further qualified with a dn-type attribute that specifies the DN syntax. A DN value might have an empty value. If dn-space="dirxml", an object selection button should be presented.
Examples:
<definition type="dn" name="user-account" display-name="Enter the user account to be used for authentication" dn-type="ldap"> <value>cn=admin,ou=ITDept,o=TheCompany</value> <description>This value specifies the DN of a user account used to authenticate to the LDAP directory.</description> </definition> <definition type="dn" name="exchange-account" display-name="Enter the DN of the Exchange user" dn-type="custom" dn-delims="10./+=*\"> <value>CN=Admin+UID=1056/OU=Mayberry</value> </definition>
Values of data type “enum” have a value that is one of a defined set of strings. Each defined string must conform to the string production.
Example:
<definition type="enum" name="magical-features" display-name="Choose the magical feature set"> <value>full</value> <enum-choice display-name="Full-on, magical stuff">full</enum-choice> <enum-choice display-name="Partial magic, but no rabbits">partial</enumchoice> <enum-choice display-name="No magic, just boring normal life">none</enumchoice> </definition> <definition display-name="xlfid(submit-method)Scheduled action" name="action" type="enum"> <enum-choice display-name="xlfid(start)Start the driver">start</enumchoice> <enum-choice display-name="xlfid(stop)Stop the driver">stop</enum-choice> <enum-choice display-name="xlfid(toggle)Toggle the driver">toggle</enumchoice> <value>start</value> </definition>
Values of data type “list” have a value that is an ordered list of zero or more strings. The list value also specifies a delimiter character that is used when outputting the list value in a non-structured location (e.g., as a single string consisting of each individual string in the list separated by the delimiter character).
The content of each <item> element must match the following production:String ::= Char*The list items can be empty or duplicate other list items. The order of list items is significant. The Agent must preserve all characters in a list item exactly as specified by the user. This includes whitespace. The Agent serializing the definition XML must therefore specify an xml:space="preserve" attribute on the value element. It might also be necessary to use character entity references for some whitespace based on the XML rules for parsers:
Example:
<definition display-name="List o' things" item-separator=";" name="ingredients" type="list"> <value> <item>Snips</item> <item>Snails</item> <item>Puppy Dog Tails</item> <item>Sugar</item> <item>Spice</item> <item>Everything Nice</item> </value> </definition>
Values of data type “structured” have two fundamental parts: a template that defines a set of simple types (string, enum, etc.), and zero or more instances that contain the actual values of the structured control value. In a sense structured values are similar to structures in the C programming language. The structured value also specifies delimiter strings that are used when outputting the value as a single string. The delimiters are used for string representation, but in a nodeset context, you get the <instance> node tree fragments. The string representation of the value contains all the components of the structured value separated by the delimiter, for example, <ipaddress>, <port>, and so on. However, the xml representation of the structured GCV has instances that contain the actual Global Definition values.
Example: Suggested Agent presentation for nested control value presentation with buttons for adding and removing instances. The example allows for template creation and editing.
<definition display-name="Servers list" value-separator=";" instance-separator=" " name="servers" type="structured"> <template> <definition name="host" display-name="Host" type="string"> <value/> </definition> <definition name="port" display-name="TCP port" type="integer" rangelo=" 1" range-hi="65535"> <value>1</value> </definition> </template> <value> <instance> <definition name="host" display-name="Host" type="string"> <value>192.168.0.1</value> </definition> <definition name="port" display-name="TCP port" type="integer" range-lo="1" range-hi="65535"> <value>8028</value> </definition> </instance> <instance> <definition name="host" display-name="Host" type="string"> <value>10.0.0.1</value> </definition> <definition name="port" display-name="TCP port" type="integer" range-lo="1" range-hi="65535"> <value>8028</value> </definition> </instance> </value> </definition>
Values of data type “password-ref” have a value that is the key value of a named password. Named password key values might be any non-empty sequence of Unicode characters. Because of the representation of CV definitions in XML, the actual set of Unicode characters allowed are those that are legal in XML PCCHAR data. The Agent presenting the password-ref value is responsible for setting any user-entered password value to the named password. If the referenced named password does not exist then the Agent must create it. The user-entered value must not be placed in the XML definition.
Example for Agent presentation of password field, associated confirmation field, and associated clear value button.
<definition type="password-ref" name="account-pwd" display-name="Password for the authentication account"> <value>auth-acct-pwd</value> </definition>
The dn-ref data type does not have a a value of its own. Instead, it assumes any value obtained from a DN-syntax eDirectory attribute on the object containing the value definition. The information about the eDirectory attribute is specified by XML attributes on the <definition> element.
The following example shows an Agent presentation of an entry field with the associated object selection button.
<definition type="dn-ref" name="pwd-policy" display-name="Password Policy object used for password generation" attr-name="nspmPasswordPolicyDN" aux-class-name="DirXML-PasswordGeneration"> <target-class>nspmPasswordPolicy</target-class> <value>DirXML-PasswordPolicy.Password Policies.Security</value> </definition>
A GCV reference value does not have a value of its own and is not defined with a <definition> element. Instead, a value is obtained from and stored to a GCV in an enclosing logical structure. For example, a gcv-ref value in shim parameters refers to a GCV defined for the driver. The GCV is specified by the name attribute on the <gcv-ref> element.
The following example shows an Agent presentation that depends on the referenced GCV:
<gcv-ref name="placement-base"/> <definition display-name="Placement base container" name="placement-base" type="string"> <description>This is the placement base container</description> <value></value> </definition>
The XML that defines GCVs consists of a <definition> section. The GCV DTD is as follows:
<!ENTITY % Value-Type "string | boolean | integer | real | dn | enum | list | password-ref | dn-ref"> <!ENTITY % Dn-Type "ldap | slash | qualified-slash | dot | qualified-dot | custom"> <!ENTITY % Dn-Space "dirxml | application"> <!ENTITY % Boolean "true | false"> <!ELEMENT configuration-values (definitions)> <!ELEMENT definitions (definition | gcv-ref | header | group)*> <!-- FIXIT: one value, one description --> <!ELEMENT definition (value | description | enum-choice | target-class)*> <!ATTLIST definition name NMTOKEN #REQUIRED display-name CDATA #REQUIRED type (%Value-Type;) "string" dn-type (%Dn-Type;) #IMPLIED dn-delims CDATA #IMPLIED dn-space (%Dn-Space;) #IMPLIED range-lo CDATA #IMPLIED range-hi CDATA #IMPLIED multiline CDATA "false" attr-name CDATA #IMPLIED aux-class-name CDATA #IMPLIED item-separator CDATA #IMPLIED display-name-ref CDATA #IMPLIED hide (%Boolean;) #IMPLIED > <!ELEMENT gcv-ref EMPTY> <!ATTLIST gcv-ref name NMTOKEN #REQUIRED> <!ELEMENT group ((definition | gcv-ref),(definition | gcv-ref | subordinates | header | group)*)> <!ELEMENT subordinates (group | definition | gcv-ref | header)*> <!ATTLIST subordinates active-value CDATA #REQUIRED> <!ELEMENT header EMPTY> <!ATTLIST header display-name CDATA #REQUIRED> <!ELEMENT value (#PCDATA | item)*> <!ATTLIST value xml:space (preserve|default) #IMPLIED> <!ELEMENT description (#PCDATA)> <!ATTLIST description description-ref CDATA #IMPLIED> <!ELEMENT enum-choice (#PCDATA)> <!ATTLIST enum-choice display-name CDATA #REQUIRED> <!ELEMENT item (#PCDATA)> <!ATTLIST item xml:space (preserve) #FIXED "preserve"> <!ELEMENT target-class (#PCDATA)>
Definition elements define the actual control values with their data types and other information.
The following XML attributes are required (or have a default value) on a <definition> element and are common to all types:
Attribute |
Possible Values |
Default Value |
---|---|---|
attr-name |
A non-empty CDATA value. The name of the eDirectory attribute containing the value. The attribute must be of syntax "Distinguished Name". |
#IMPLIED |
aux-class-name |
A non-empty CDATA value. The name of the eDirectory auxiliary class that attaches the eDirectory attribute to the object containing the CV definition. |
#IMPLIED |
description |
A string presented to the user to explain the value in greater detail than is present in the display-name attribute. Note that the description text might contain line breaks that must be honored when displaying the description.Description may have a description-ref attribute that is part of the localization scheme used with ECVs. |
|
display-name |
CDATA The string presented to the user to identify the value. |
"string" |
display-name-ref |
non-empty CDATA value Used with ECVs as part of the localization scheme. |
#IMPLIED |
dn-type |
“ldap”, "slash”, “qualifiedslash”, “dot”, “qualifieddot”, “custom” Specifies the syntax allowed for the value. Agents must enforce this when the user enters the value. |
#IMPLIED |
dn-delims |
A sequence of at least eight characters that specify the custom DN format delimiters. If dn-type = "custom" then dn-delims must contain the "delimiter set" for the custom DN syntax. The delimiter set is at least 8 characters as follows:
Any characters after the eighth are additional characters that must always be escaped in the DN syntax. Note that dn-delims is ignored if dn-type is equal to anything other than "custom". |
#IMPLIED |
dn-space |
"dirxml" or "application" If the value is "dirxml" then the Agent should present an "object selector" button that allows an object to be selected from eDirectory. |
#IMPLIED |
hide |
Boolean |
#IMPLIED |
item-separator |
A non-empty CDATA value. The value is used as a separator between list item strings when the list value is output in a non-structured location (e.g., as part of a single string). For example, if the list items are "one", "two", and "three", and the item-separator value is ";", the following is the unstructured output:"one;two;three" |
#IMPLIED |
multiline |
"true" or "false" If "true" then the Agent should present the value in a multi-line edit field and allow the user to specify line breaks. The content of the value element must match the following production: String ::= Char* The Agent must preserve all characters exactly as specified by the user. This includes whitespace. The Agent serializing the definition XML must therefore specify an xml:space="preserve" attribute on the value element. It may also be necessary to use character entity references for some whitespace based on the XML rules for parsers:Whitespace HandlingEnd-of-line Handling |
False |
name |
NMTOKEN The configuration value name. Must be unique among all descendant <definition> elements found under the <definitions> element. |
#REQUIRED |
range-hi |
A CDATA value that matches the syntax allowed for the value element content. Specifies the maximum integer or real value allowed. The Agent must enforce this when the user specifies the value. |
#IMPLIED |
range-lo |
A CDATA value that matches the syntax allowed for the value element content. Specifies the minimum integer or real value allowed. The Agent must enforce this when the user specifies the value. |
#IMPLIED |
type |
"string", "boolean", "integer", "real", "dn", "enum", "list", "passwordref", "dn-ref" The value type. If not present, the type defaults to "string". |
#IMPLIED |
value |
Contains the current value of the CV. Actual allowed content is defined by the individual types. |
|
Specifies the GCV description.
Attribute |
Possible Values |
Default Value |
---|---|---|
description ref |
CDATA |
#IMPLIED |
A GCV reference value does not have a value of its own and is not defined with a <definition> element. Instead, any value is obtained from and stored to a GCV in an enclosing logical structure (e.g., a gcv-ref value in Shim Parameters refers to a GCV defined for the driver). The referred to GCV is specified by the name attribute on the <gcv-ref> element.
Attribute |
Possible Values |
Default Value |
---|---|---|
gcv-ref name |
A non-empty CDATA value. The name of the referenced GCV. |
#REQUIRED |
driver-param name |
A string that matches the XML Name production. The name of the driver parameter element when constructing shim parameters. Normally, the name of the driver parameter used is the name of the referred-to GCV; if this attribute's value is non-empty then the attribute value is used as the name of the driver parameter. |
string |
Example 8-1 Example:
<gcv-ref name="placement-base"/>
A <group> element instructs the user interface Agent to consider all content of the <group> element as related. The first element child of the group is the group leader and must be either a boolean or an enum type value (or a <gcv-ref> that refers to a boolean or an enum). Subsequent members of the group should be displayed as subordinate to the group leader.If the group leader is a <gcv-ref>, the definition it refers to must be a boolean or an enum.
Attribute |
Possible Values |
Default Value |
---|---|---|
definition |
"boolean" or "enum" The <group> might contain any number of <definition> elements. If the first <group> child element is a <definition> element, the type attribute value must be boolean or enum. |
|
gcv-ref |
The <group> may contain any number of <gcv-ref> elements. If the first <group> child is <gcv-ref> then the referenced GCV must be a boolean or enum. |
|
subordinates |
Any number of <subordinates> elements may appear as children of a <group> element. However, a <subordinates> element may not be the first child of a <group> element. |
|
header |
Any number of <header> elements may appear as children of a <group> element. However, a <header> element may not be the first child of a <group> element. |
|
group |
Any number of <group> elements may appear as children of a <group> element. However, a <group> element may not be the first child of a <group> element. |
#REQUIRED |
Example:
<header display-name="TCP parameters"/> <group> <definition type="boolean" name="server-connect" display-name="Connect to remote server" > <value>true</value> </definition> <definition type="string" name="host-name" display-name="Host name or IP address of server" > <value>192.168.0.1</value> </definition> <definition type="integer" name="port" display-name="HTTP port number of server" range-lo="1" range-hi="65535" > <value>80</value> </definition> </group>
A <subordinates> element only appears as part of a group and delimits content that is conditionally displayed by the user interface Agent. A <subordinates> element may not be a group leader; instead, the group leader's value determines whether the <subordinates> element's content is displayed or not. The value that will cause the <subordinates> element's content to be displayed is determined by the value of the active-value attribute.
Attribute |
Possible Values |
Default Value |
---|---|---|
active-value |
A non-empty CDATA value. Specifies the value of the group leader definition that causes the Agent to display the contents of the <subordinates> element. The value must be a legal value for the group leader. |
#REQUIRED |
A group can have more than one subordinates element under it. Each subordinate has a different value for the active-value attribute.
Element Name |
Explanation |
---|---|
definition |
The <subordinates> element might contain any number of <definition> elements. |
gcv-ref |
The <subordinates> element might contain any number of <gcv-ref> elements. |
header |
The <subordinates> element might contain any number of <header> elements. |
group |
The <subordinates> element might contain any number of <group> elements. |
A header instructs the user interface Agent to display some sort of delimiter or header with the display-name text. Any number of <header> elements may appear as children of a <group> element. However, a <header> element might not be the first child of a <group> element.
Attribute |
Possible Values |
Default Value |
---|---|---|
display-name |
A CDATA value. The string that will be presented to the user. |
#REQUIRED |
Example for Agent presentation for larger type for display name, some sort of horizontal rule:
<header display-name="TCP parameters"/>
Example for Agent presentation for indent subordinates.
<header display-name="TCP parameters"/> <group> <definition type="boolean" name="server-connect" display-name="Connect to remote server"> <value>true</value> </definition> <definition type="string" name="host-name" display-name="Host name or IP address of server"> <value>192.168.0.1</value> </definition> <definition type="integer" name="port" display-name="HTTP port number of server" range-lo="1" range-hi="65535"> <value>80</value> </definition> </group>
The content of the value element must either be empty or be a sequence of characters that is syntactically valid for the DN syntax specified by the dn-type attribute on the <definition> element. The content of the value element must a string from one of the <enum-choice> elements. The value element content must not be empty. The content of the value element must be zero or more <item> elements. The content of the value element must be non-empty and is the key value (name) of a named password.
Attribute |
Possible Values |
Default Value |
---|---|---|
xml:space |
preserve|default |
#IMPLIED |
One or more <enum-choice> elements must be children of the <definition> element. Each <enum-choice> element has a display-name attribute that is used by the Agent to present the choice to the user. The content of an <enum-choice> element must conform to the following production: String ::= Char+. The content of an <enum-choice> element must not be empty and defines one of the allowable strings for the <value> element content.
Attribute |
Possible Values |
Default Value |
---|---|---|
display-name |
|
#REQUIRED |
The content of the value element must be zero or more <item> elements. The content of each <item> element must match the following production:String ::= Char*Note that this means that list items may be empty. List items may duplicate other list items. The order of list items is significant. The Agent must preserve all characters in a list item exactly as specified by the user. This includes whitespace. The Agent serializing the definition XML must therefore specify an xml:space="preserve" attribute on the value element.
Attribute |
Possible Values |
Default Value |
---|---|---|
xml:space="preserve" |
|
#FIXED |
One or more <target-class> elements can appear as children of the <definition> element. The content of each <target-class> element is an eDirectory class name specifying an object class, objects of which may be referred to by the eDirectory attribute specified by the attr-name attribute on the <definition> element. The absence of a <target-class> element indicates that any object is allowable.
Attribute |
Possible Values |
Default Value |
---|---|---|
|
|
Example for Agent presentation for entry field with associated object selection button:
<definition type="dn-ref" name="pwd-policy" display-name="Password Policy object used for password generation" attr-name="nspmPasswordPolicyDN" aux-class-name="DirXML-PasswordGeneration"> <target-class>nspmPasswordPolicy</target-class> </definition>
See Table 8-1 for a list of method summary....
The following table shows the types used to represent the various GCV syntaxes.
The following table contains a list of GCV methods:
Table 8-1 GCV Methods
Element |
Description |
---|---|
clone () |
Creates and returns a copy of an object. |
equals () |
Indicates whether some other object is "equal to" this one. |
finalize () |
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. |
getClass () |
Returns the runtime class of an object. |
hashCode () |
Returns a hash code value for the object. |
notify () |
Wakes up a single thread that is waiting on this object's monitor. |
notifyAll () |
Wakes up all threads that are waiting on this object's monitor. |
toString () |
Returns a string representation of the object. |
wait () |
Causes current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object. |
wait (long timeout) |
Causes current thread to wait until either another thread invokes the notify() method or the notifyAll() method for this object, or a specified amount of time has elapsed. |
wait (long timeout, int nanos) |
Causes current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. |
Table 8-2 GCV Syntaxes
Syntax |
Type |
Components (Notes) |
---|---|---|
VAL_STRING |
|
|
VAL_BOOLEAN |
|
|
VAL_INTEGER |
|
|
VAL_REAL |
|
|
VAL_DN |
|
|
VAL_ENUM |
|
|
VAL_PASSWORD_REF |
|
|
VAL_DN_REF |
|
|
VAL_LIST |
|
|
VAL_STRUCTURED |
|
|
VAL_LDAP |
|
|
VAL_SLASH |
|
|
VAL_QUALIFIED_SLASH |
|
|
VAL_DOT |
|
|
VAL_QUALIFIED_DOT |
|
|
VAL_CUSTOM |
|
|
VAL_DIRXML |
|
|
VAL_APPLICATION |
|
|
VAL_TRUE |
|
|
VAL_FALSE |
|
|
ATTR_NAME |
|
|
ATTR_DISPLAY_NAME |
|
|
ATTR_DISPLAY_NAME_REF |
|
|
ATTR_DESCRIPTION_REF |
|
|
ATTR_TYPE |
|
|
ATTR_DN_TYPE |
|
|
ATTR_DN_DELIMS |
|
|
ATTR_DN_SPACE |
|
|
ATTR_RANGE_LO |
|
|
ATTR_RANGE_HI |
|
|
ATTR_HIDE |
|
|
ATTR_ITEM_SEPARATOR |
|
|
ATTR_ATTR_NAME |
|
|
ATTR_AUX_CLASS_NAME |
|
|
ATTR_MULTILINE |
|
|
ATTR_TYPE_HINT |
|
|
ATTR_MANDATORY |
|
|
ATTR_DRIVER_PARAM_NAME |
|
|
ATTR_MIN_COUNT |
|
|
ATTR_MAX_COUNT |
|
|
ATTR_VALUE_SEPARATOR |
|
|
ATTR_INSTANCE_SEPARATOR |
|
|
TAG_CONFIGURATION_VALUES |
|
|
TAG_DEFINITIONS |
|
|
TAG_DEFINITION |
|
|
TAG_VALUE |
|
|
TAG_DESCRIPTION |
|
|
TAG_ENUM_CHOICE |
|
|
TAG_HEADER |
|
|
TAG_GROUP |
|
|
TAG_SUBORDINATES |
|
|
TAG_GCV_REF |
|
|
TAG_LIST |
|
|
TAG_ITEM |
|
|
TAG_TARGET_CLASS |
|
|
TAG_TEMPLATE |
|
|
TAG_INSTANCE |
|
|
ATTR_XML_SPACE |
|
|
VAL_PRESERVE |
|
|
EX_TAG_CONFIGURATION_VALUES |
|
|
EX_TAG_DEFINITION |
|
|
EX_TAG_VALUE |
|
|
EX_ATTR_NAME |
|
|
EX_ATTR_TYPE |
|
|
EX_ATTR_DISPLAY_NAME |
|
|
The following table shows which CV types are used by which CV implementations:
Value Types |
GCVs |
ECVs |
Shim Parameters |
Resource Parameters |
Job Parameters |
---|---|---|---|---|---|
string |
yes |
yes |
yes |
yes |
yes |
boolean |
yes |
yes |
yes |
yes |
yes |
integer |
yes |
yes |
yes |
yes |
yes |
real |
yes |
yes |
yes |
yes |
yes |
dn |
yes |
yes |
yes |
yes |
yes |
enum |
yes |
yes |
yes |
yes |
yes |
list |
yes |
yes |
yes |
no |
yes |
structured |
yes |
no |
yes |
no |
yes |
password-ref |
yes |
no |
yes |
yes |
yes |
The following table shows which CV types are used by which CV implementations.
Value type |
GCVs |
ECVs |
ShimParameters |
ResourceParameters |
Job Parameters |
---|---|---|---|---|---|
string |
yes |
yes |
yes |
yes |
yes |
boolean |
yes |
yes |
yes |
yes |
yes |
integer |
yes |
yes |
yes |
yes |
yes |
real |
yes |
yes |
yes |
yes |
yes |
dn |
yes |
yes |
yes |
yes |
yes |
enum |
yes |
yes |
yes |
yes |
yes |
list |
yes |
yes |
yes |
no |
yes |
structured |
yes |
no |
yes |
no |
yes |
password-ref |
no |
no |
yes |
yes |
yes |
gcv-ref |
no |
no |
yes |
no |
no |
dn-ref |
no |
no |
no |
no |
yes |
GCVs are available to the driver policy and shim parameters. The actual values available are a combination of the following:
GCV definitions on the DirXML-DriverSet object
GCV definitions on the DirXML-Driver object
Automatic GCVs
If there are any name collisions between the three sources the order of precedence is: driver object, driver set object, automatic. Automatic GCVs are values that are supplied by the Engine and provide information about the runtime environment. The automatic GCVs are:
Table 8-3 Automatic GCVs
Name |
Type |
Explanation |
---|---|---|
dirxml.auto.treename |
string |
The name of the eDirectory tree. |
dirxml.auto.driverdn |
string |
The slash-form DN of the DirXML-Driver object. |
dirxml.auto.driverguid |
string |
The value of the GUID attribute of the DirXML-Driver object in the following form: {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} where each 'x' is a hexadecimal digit. |
dirxml.auto.localserverdn |
string |
The DN of the local server. |
There are two basic ways to access a GCV from policy:
The following syntax is used to supply the value of a GCV via text replacement:
~gcv-name~
where "gcv-name" is the name of the desired GCV.
Text replacement works by replacing such references with the value of the GCV in policy source and in the following shim configuration fields:
Table 8-4 Shim Configuration Fields with GCV Replacement
Field |
DirXML-Driver attribute |
Explanation |
---|---|---|
shim auth id |
DirXML-ShimAuthID |
Typically presented by user agents as "Authentication ID", this value is usually used by a shim as the account name with which to authenticate to the target application. |
shim auth server |
DirXML-ShimAuthServer |
Typically presented by user agents as "Authentication context", this value is usually used by a shim as connection information for the target application. |
In policy source (both DirXML-Script and XSLT) the text replacement is straightforward and consists of simply replacing the reference with the string value of the GCV with one exception: List values will be output as either a string or as structured XML depending on the replacement context. In particular, if the list GCV reference appears in element content then the list will be output in a structured form. If the list GCV reference appears in an attribute value then the list will be output as a delimited string.
Several examples will help to illustrate text replacement (note the use of quotes around the GCV reference when the result needs to be a string):
Table 8-5 GCV Text Replacement Example
|
|
---|---|
GCV Definition |
<definition name="my-gcv" type="string" display-name="Source subtree" > <value>\mytree\novell\</value> </definition> |
Reference |
<xsl:if test="starts-with(@src-dn,'~my-gcv~'"> |
Result |
<xsl:if test="starts-with(@src-dn,'\mytree\novell\'"> |
When the ~GCV~ notation is executed as a string replace at driver startup in XSLT or XPATH, the strings must be enclosed. However, in XPATH a single $GCV is sufficient, and need not be string enclosed.In variable expansion supporting fields, $GCVName$ is sufficient and is not equal to ~GCVName~ as the $GCVName$ expansion is executed at run time as it is encountered, but ~GCVName~ is evaluated at driver start time.
See the DirXML Script documentation for the full description. GCVs can be accessed in DirXML Script policies in several ways:
XPath Variables: XPath expressions in DirXML-Script can reference GCVs through the standard XPath "$name" syntax for variables. For more information, see XPath Variables documentation.
Conditions and Tokens: The <if-global-variable> condition and the <token-global-variable> token. For more information, see DirXMLScript DTD.
Variable Expansion: Many conditions and tokens support the DirXML Script variable expansion where the GCV is referenced as $gcv-name$. For more information, see DirXMLScript DTD.