C.1 Variables in a Driver Configuration File

For the iManager plug-ins, several node types are defined for the driver configuration files. The following is a list of actions that the Identity Manager engine supports:

The primary new node types are:

To view the driver configuration file XML extensions, see DriverConfigXMLExtension.txt.

In addition, be aware of the following notes:

C.1.1 General Notes

  • The variable-decls can contain text-var but not node-var. It can contain variable-refs as long as the order they are resolved is taken into account.

  • If a variable-decl contains an optional prompt attribute and an optional prompt-type attribute and does not contain an optional browse=“yes” attribute setting, the prompt-type is treated as follows:

    • A prompt-type of "ipa" results in two edit fields. See Figure C-1 for an example. The value the user specifies for the first part is appended by a colon (:) and the value the user specifies for the second part in the value is rendered by the variable.

      Figure C-1 Two Edit Fields

    • A prompt-type of "password" results in two password edit fields. See Figure C-2 for an example. The first prompt is for the actual password, and the second prompt is used to verify that the password specified in the first field is correct. The value rendered by the variable reference is the password.

      Figure C-2 Two Password Fields

    • A prompt-type of "hidden" results in a field that is not displayed, but is checked to make sure a previous condition is met before proceeding to the next screen.

    • Any other prompt-type value is ignored.

  • If a variable-decl contains an optional description attribute in addition to a prompt attribute, the description is displayed in the UI along with the prompt. The purpose of the description attribute is to allow a complete description of what’s being asked for along with a simple prompt.

    For example:

    <text-var
        var-name="eProv.Company"
        prompt="Company name:" description="Please enter the name of your company. This must be the same name as you entered during the initial installation."
        browse="no">
      Novell
    </text-var>

    Note the differences between the prompt and the description.

    If a variable-decl contains an optional description attribute and an optional highlight attribute, the highlight attribute is handled as follows:

    • If the highlight is not two characters in length, it is ignored.

    • If the highlight is two characters in length, all occurrences of the first character are preceded with HTML tags to turn on highlighting and all occurrences of the second character are followed by HTML tags to turn off highlighting.

      For example:

      <text-var
            var-name="foo"
            prompt="Foo:"
            description="Please enter some foo.  Format:  [foo looks like this]">
          Bar
        </text-var>

      When the description is displayed, [foo looks like this] is displayed and highlighted.

  • If a variable-decl contains a browse=“yes” attribute, it is assumed to supply a DN and is formatted in slash format by default when applied to the driver configuration file.

    This is assumed to be more generally useful for driver writers and can be overridden on a per reference basis by adding a dn-format=“dot” attribute to variable-ref nodes that reference it.

  • If a variable-ref is to text-var with a prompt-type="ipa" attribute, a part="..." attribute can be included in the variable-ref. Supported parts are "ipa" and "port". If part="ipa" is specified, only the IP address portion of the variable's value is returned. If part="port" is specified, only the port portion of the variable's value is returned. Any other setting is ignored and the variable's entire value is returned.

  • A dn-format attribute on a variable-ref that does not have browse="yes" specified in its variable-decl causes that variable to be treated as though it supplies a DN. The DN is rendered in the dn-format specified.

  • The supported values for the dn-format attribute are "dot" and "slash". Any other value is treated as "slash" and without an error being generated.

  • The built-in defined variables are:

    • System.TreeName

    • System.DSetDN

    • System.DSetName

    • System.DriverDN

    • System.DriverName

    • System.ServerDN

    • System.ServerName

  • Built-in variables can be overridden. If you include a variable-decl for a variable named with one of the built-in variable names, your definition overrides the built-in variable of the same name.

    This is implemented after all variable declarations have been processed (prompting, ...). Just before the code begins applying values, it walks the variables and defines all the built-ins that haven't otherwise been defined.

  • The built-in variables that provide a DN can include a dn-format attribute in the variable-ref to control the format the DN is rendered in. By default, these are rendered in slash format.

  • A node-var and a text-var cannot be named the same thing. They use the same namespace.

  • If a variable-ref references a node-var and contains an attr-name attribute, the XSL string value of the node-var is stored in as the named attribute on the parent node of the variable-ref. The node-var used in this manner can have a node-name attribute of "#text", which removes the requirement of having an attr-name attribute on the node-var.

    A node-var with a node-name of "#text" can only be referenced in this manner. Any other reference causes an error when the driver configuration file is imported.

  • At patch time after the user has responded to the prompts but before the XML is actually imported. patching is done in the following order:

    1. The text-var variable-refs are processed.

    2. The node-var variable-refs are processed.

    3. The xsl-modify commands are processed.

    4. The ds-object commands are processed.

      • Patching is performed in the variable-decl so that by the time the node-var commands are patched, all the text-var commands contained in them have been resolved.

      • The node-var commands cannot contain node-var variable-ref.

C.1.2 Import Driver Notes

  • The order in which the selected driver configuration files are processed is not defined and no order can be assumed.

  • For variable-decl commands:

    • Commands from selected drivers are carried forward from driver to driver.

    • The first one wins.

      • The first driver encountered that defines a variable foo has its variable foo used throughout all remaining driver configuration files. Care must be taken to coordinate this between drivers.

      • A variable foo that is used in multiple driver configuration files is only prompted for once, with the first driver configuration file encountered that declares it.

  • Built-in variables are not propagated between drivers. This includes any variables you define to override a built-in variable. The built-in variables for each driver are handled separately.

  • Other prompting is handled unchanged at the beginning of each driver configuration file's import sequence.

  • Refer to Section C.2, Flexible Prompting in a Driver Configuration File for information about prompt layering supported by flexible prompting.