Framework-based Agents

Framework-based agents use a standard configuration method. The next sections describe:

  • The command line format to invoke an agent

  • The exit codes provided by an agent

  • General information about configuration file formats

  • General information about the search request file format

Command Line Format

The command line format to invoke a framework-based agent is as follows:

agent.bat configuration_file (on Windows platforms)

agent.sh configuration_file (on UNIX platforms)

configuration_file

Specifies the name of the file that contains the specifications for the import procedure. All other parameters for correct agent operation are defined in the agent’s configuration file in XML format.

Exit Codes

The following table describes the standard exit codes provided when an agent finishes running.

Exit Code Description

0

Agent completed successfully.

1

Agent completed with errors. Details are described in the specified trace file unless this file cannot be created due to a file exception error.

60

Agent completed with warnings. For details see the specified trace file.

Configuration File Formats

Framework-based agents use configuration files that control import and export of data into a target system.

This section describes the general structure of a configuration file.

General Structure of a Configuration File

The configuration file’s format is XML. It is composed of multiple sub-units (connectors). Normally you should not change the general structure of a configuration file. Instead, you configure some well-defined attribute values to the specific environment in which the agent runs.

Tags

The configuration files contain the tags job, connector, logging and connection.

  • job - Defines the file’s document tag, with connector sub-tags

  • connector - Configures the properties of one connector, has connection and/or logging sub tags

  • connection - Configures connection parameters, for example filename for a reader/writer or host/port/credentials for a network connector

Attributes

A connector tag can have the following attributes:

  • name - The connector’s name

  • role - One of reader, controller, connector, responseWriter or requestCryptTransformer

  • className - The name of the Java class that implements the connector

  • logging - Configures the logging properties of a connector

The connection parameters of the specific connectors are described in their connection sub-tags.

Each connection tag has the attribute

  • type - The type of connection (file format, protocol)

Readers and response writers are configured by the attribute

  • filename - The pathname of the input or output file.

Dependent on the type of connectors additional properties may be defined in this section.

Encryption transformers are configured by these attributes

  • firstAttribute …​ lastAttribute - This list of parameters specifies the names of the attributes which can be encrypted in the input of the agent. All encrypted user attributes must be listed here to allow the agent to decrypt them. There’s no limit of the number of encrypted attributes in the configuration file.

A connection to the target system is configured by some attributes that might differ dependent on the target system. Typical attributes are:

  • host - the host to access

  • port - the port to use

  • user - the user for simple bind operation

  • password - the user password for simple bind operation

The agent’s logging is configured in the controller’s logging tag by the attributes:

  • level - The integers 0-9, where 0 indicates no logging and 9 indicates full logging
    0 - none
    1 - FatalError and Error
    2 - FatalError, Error and Warning
    3 - FatalError, Error and Warning
    4 - FatalError, Error and Warning
    5 - FatalError, Error, Warning and Trace
    6 - FatalError, Error, Warning and Trace
    7 - FatalError, Error, Warning and Trace
    8 - FatalError, Error, Warning and Trace
    9 - FatalError, Error, Warning and Trace (and additional HTML files)

  • filename - The path and name of the trace file

  • debugmode - a boolean switch to specify a special debug mode (possible values: true and false)

Example of an Import Configuration File

The import configuration file has the format defined above. The following generic example describes shows the general layout. The attribute values that can be configured are shown in bold italic, e.g. level:

<?xml version="1.0" encoding="UTF–8" ?>
<job>

<connector name="Default Controller" version="0.1" role="controller"
className="siemens.dxm.connector.framework.DefaultControllerStandalone">
<logging level="level" filename="traceFileName" />
</connector>

<connector role="reader" name="LDIF change file reader"
className="siemens.dxm.connector.framework.LdifChangeReader">
<connection type="LDIF change" filename="inputFileName" />
<property name="ExtractRDN" value="false"/>
<property name="IncludingNamingAttribute" value="false"/>
</connector>

<connector role="RequestCryptTransformer" name="Crypto Transformer"
className="siemens.dxm.connector.framework.CryptTransformer">
<mvproperty name="encryptedAttributes">
<value> firstAttribute </value>
...
<value> lastAttribute </value>
</mvproperty>
</connector>
<connector role="connector" name="agent_name"
className="siemens.dxm.connector...">
<connection type="connection_type"
user="account"
password="password"
... >
<property name="property_name" value="property_value"/>
</connection>
</connector>

<connector role="responseWriter" name="LDIF file writer"
className="siemens.dxm.connector.framework.LdifFileWriter">
<connection type="LDIF" filename="responseFilename" />
<property name="contenttype" value="LDIF-CONTENT"/>
</connector>

</job>

Search Request File Format

The objects to be exported are defined in a Service Provisioning Markup Language (SPML) search request. SPML is an XML format. The search request contains an LDAP-like filter and searchBase. Its configuration is described by the following template. The attribute values that can be configured are shown in bold (blue) italic; for example, subtree:

<?xml version="1.0" ?>
<spml:searchRequest xmlns="urn:oasis:names:tc:SPML:1:0"
xmlns:spml="urn:oasis:names:tc:SPML:1:0" requestID="search_01">
  <spml:operationalAttributes>
    <attr name="scope"> <value>scope</value> </attr>
  </spml:operationalAttributes>
  <spml:searchBase type="urn:oasis:names:tc:SPML:1:0#DN">
    <spml:id>searchBase</spml:id>
  </spml:searchBase>
  <filter>
    <substrings name="attribute">
      <initial>value</initial>
    </substrings>
  </filter>
  <spml:attributes>
    <attribute name="attribute1" />
    <attribute name="attribute2" />
  </spml:attributes>
</spml:searchRequest>
searchBase

searchBase specifies the base object for the search .

This definition is dependent on the target system.

scope

scope specifies the depth of the search. It must have one of the following values:

base

The base object defined in searchBase

onelevel

The base object and all objects located one level below it.

subtree:::The base object and the entire subtree under this object.

filter

filter is a tag that specifies the search criteria. It supports an LDAP-like structure, with the operator tags <and>, <or>, <not>, corresponding to the LDAP operators (& …​), (|…​), (! …) and the tags <substrings> and <equalityMatch>.

The previous example uses a substrings tag, but you can use all the tags and combinations of the tags defined here.

equalityMatch

equalityMatch is a filter sub-tag that specifies that an attribute value must be exactly equal to the value defined in the <value> tag.

Example:

<equalityMatch name="objectclass">
         <value>user</value>
</ equalityMatch >
substrings

substrings is a filter sub-tag that specifies that an attribute value must start with, end with, or contain a value defined in its <initial>, <contains>, or <final> sub-tag.

Example:

<substrings name="objectclass">
        <initial>ro</initial>
</substrings>
and

and specifies the tags it contains to be "and" related.

Example:

<and>
    <substrings name="name">
         <initial>develop</initial>
    </substrings>
    <equalityMatch name="objectclass">
         <value>folder</value>
    </ equalityMatch >
   </and>
or

or specifies the tags it contains to be "or" related.

Example:

<or>
    <substrings name="name">
          <initial>develop</initial>
    </substrings>
    <substrings name="name">
          <initial>market</initial>
    </substrings>
</or>
not

not specifies that the tag it contains must evaluate to false.

Example:

<not>
    <equalityMatch name="objectclass">
         <value>folder</value>
    </ equalityMatch >
</not>
spml:attributes

spml:attributes specifies the attributes attribute1, attribute2,…​ to be returned by the search.