18 Configuring Connectors for Installation and Testing

The guidelines explained in this chapter are aimed at ensuring that your custom connectors meet the compatibility requirements for using the connector installer and the Diagnostic Dashboard. These guidelines apply only to specific areas of custom connector development.

This chapter contains the following sections:

Structure of the Configuration XML File
Developing the Test Class for the Connector
Structure of the Connector Pack Directory

18.1 Structure of the Configuration XML File

This section discusses the structure of the configuration XML file that is used during the connector installation process. Use the information in this section to create configuration XML files for your custom connectors.

The following is the recommended path for copying the installation files for the predefined connectors:

OIM_HOME/xellerate/ConnectorDefaultDirectory

When you install Oracle Identity Manager, the following files are copied into the ConnectorDefaultDirectory directory:

ConnectorConfigTemplate.xml

This is a template of the configuration XML file. Use a copy of this file to create the configuration XML file.
ConnectorSchema.xsd

This is the XML schema document (XSD) against which you must validate the configuration XML file that you create.

Table 18-1 lists the elements in the configuration XML file. Use the links in this table to access sections on each element.

Table 18-1 Elements in the Configuration XML File

Root Element	Level 1 Element	Level 2 Element	Level 3 Element
connector Element
	connector-name Element
	connector-version Element
	filecopy Element	destination Element	file Element
	configuration Element	source Element	file Element
	pre-Install Element	title Element	step Element
	dependency-connector Element	dependency-connector-name Element
		dependency-connector-version Element

See "Sample Configuration XML File" for the contents of a sample configuration XML file.

18.1.1 connector Element

The following table summarizes the properties of the connector element:

Property	Value
Parent Element	NA
Attributes	NA In the template XML file, do not change the values of attributes of this element.
Child Elements	`connector-name`, `connector-version`, `filecopy`, `configuration`, `pre-Install`, and `dependency-connector`
Number of Occurrences	One
Element Value	NA

The connector element is the root element in the configuration XML file. See the following sections for information about the child elements of the connector element:

connector-name Element
connector-version Element
filecopy Element
configuration Element
pre-Install Element
dependency-connector Element

18.1.2 connector-name Element

The following table summarizes the properties of the connector-name element:

Property	Value
Parent Element	`connector`
Attributes	None
Child Elements	None
Number of Occurrences	One
Element Value	Name of the connector

Use the connector-name element to specify the name of the target system of the connector. The connector name value is displayed on most of the connector installation pages.

Sample usage:

<connector-name>Active Directory</connector-name>

18.1.3 connector-version Element

The following table summarizes the properties of the connector-version element:

Property	Value
Parent Element	`connector`
Attributes	None
Child Elements	None
Number of Occurrences	One
Element Value	Release number of the connector

Use the connector-version element to specify the connector release number. The release number is displayed along with the name of the connector. It is also used to compare releases and provide upgrade guidelines to users.

Sample usage:

<connector-version>9.1.0</connector-version>

Apply the following guidelines whenever you specify a value for the connector-version element:

Use only numerals and periods (.) to specify the connector release number.
Ensure that there are no spaces in the connector release number.
Trailing zeros in the connector release number are discarded when the release number of a connector is compared with the release number of another connector. For example, the values 9.1.0 and 9.1.0.0 are considered the same by the code that compares release numbers.

18.1.4 filecopy Element

The following table summarizes the properties of the filecopy element:

Property	Value
Parent Element	`connector`
Attributes	None
Child Elements	`destination`
Number of Occurrences	One
Element Value	NA

The filecopy element serves as the container for destination elements, which hold details of the files to be copied from specific directories in the connector installation media directory.

The "destination Element" section discusses the child element of the filecopy element.

18.1.5 destination Element

The following table summarizes the properties of the destination element:

Property	Value
Parent Element	`filecopy`
Attributes	`folder`
Child Elements	`file`
Number of Occurrences	One for each type of file to be copied
Element Value	The value can be `JavaTasks`, `ScheduleTask`, `connectorResources`, or `ThirdParty`.

Use the folder attribute of the destination element to specify the name of the folder on the Oracle Identity Manager server into which a certain type of connector files must be copied. As mentioned in the table, you can specify any one of the following folders:

connectorResources: Specify this folder if the connector installation media contains resource bundles.
JavaTasks: Specify this folder if the connector installation media contains JAR files for provisioning.
ScheduleTask: Specify this folder if the connector installation media contains JAR files for reconciliation.
ThirdParty: Specify this folder if the connector installation media contains external code files that the connector requires for provisioning or reconciliation.

The "file Element" section discusses the child elements of the filecopy element.

18.1.6 file Element

The following table summarizes the properties of the file element:

Property	Value
Parent Element	`destination` or `source` Note: The `source` element is described later in this chapter.
Attributes	None
Child Elements	None
Number of Occurrences	At least one
Element Value	Name of file to be copied

Use the file element to specify the name of the file that must be copied into the folder specified by the parent destination element. The case of the file name (uppercase and lowercase) that you specify must be the same as that of the actual name. For a given file name, the installation program searches the entire connector installation media directory to locate the file and then copies the file into the folder specified by the parent destination element.

Sample usage:

<file>ActiveDirectory.properties</file>

If you want the same file to be copied into multiple directories, then you must specify the file name in file elements under the required destination elements. For example, suppose you want the connector.jar file to be copied into both the JavaTasks and ScheduleTask directories, then add the following lines in the XML file:

<destination folder="JavaTasks">
  <file>connector.jar</file>
</destination>
<destination folder="ScheduleTask">
  <file>connector.jar</file>
</destination>

18.1.7 configuration Element

The following table summarizes the properties of the configuration element:

Property	Value
Parent Element	`connector`
Attributes	None
Child Elements	`destination`
Number of Occurrences	One
Element Value	NA

The configuration element is used to hold information about the XML files that are to be imported during the installation process.

The "source Element" section discusses the child element of the configuration element.

18.1.8 source Element

The following table summarizes the properties of the source element:

Property	Value
Parent Element	`configuration`
Attributes	`folder`
Child Elements	`file` Note: The `file` element is described earlier in this chapter.
Number of Occurrences	One
Element Value	`xml`

The source element is used to specify the xml folder in the connector installation media directory in which the connector XML files are stored. During the installation process, the Deployment Manager is called to import these XML files.

The following sample code lines show how the configuration, source, and file elements must be used:

<configuration>
  <source folder="xml">
    <file>xliADResourceObject.xml</file>
    <file>xliADXLResourceObject.xml</file>
  </source>
</configuration>

18.1.9 pre-Install Element

The following table summarizes the properties of the pre-Install element:

Property	Value
Parent Element	`connector`
Attributes	None
Child Elements	`title`
Number of Occurrences	One
Element Value	NA

You might need to perform certain tasks before you can start using some connectors. For example, the Microsoft Active Directory connector requires you to configure Secure Sockets Layer (SSL) to secure communication between Oracle Identity Manager and the target system. These prerequisite tasks can be displayed at the end of the connector installation process by using the child elements of the pre-Install element.

If you do not want to display prerequisite tasks at the end of the connector installation process, then do not include the pre-Install element in the XML file.

The "title Element" section discusses the child element of the pre-Install element.

18.1.10 title Element

The following table summarizes the properties of the title element:

Property	Value
Parent Element	`pre-Install`
Attributes	`description`
Child Elements	`step`
Number of Occurrences	At least one
Element Value	Key value of the resource bundle line that contains the text to be displayed

In the resource bundle, there is a line that specifies the title of the section containing prerequisite tasks for the connector. Use the description attribute of the title element to specify the key value of this resource bundle line.

Note:

The key value of a resource bundle line is the text to the left of the equal sign (=) in the resource bundle. See Oracle Identity Manager Globalization Guide for more information about resource bundles.

The "step Element" section discusses the child element of the title element. The example in that section illustrates how you must use this element.

18.1.11 step Element

The following table summarizes the properties of the step element:

Property	Value
Parent Element	`title`
Attributes	None
Child Elements	None
Number of Occurrences	One
Element Value	Key value of the resource bundle line that contains the text to be displayed

Use the step element to specify the key value of the resource bundle line that describes a single prerequisite task for the connector.

The following example uses the Microsoft Active Directory connector to illustrate how you must use the pre-Install, title, and step elements:

The following is a partial listing of the prerequisite tasks that are displayed after the installation of the Microsoft Active Directory connector:

Enabling LDAPS
- Ensure that Certificate Services are installed on the server.
- Open the default group policy for the Domain Controller on the server (in Active Directory Users and Computers).
- Right-click the domain node, and select Properties.Click the Group Policy tab.
- Select Default Domain Policy.
 . . .
 
Setting Up the Microsoft Active Directory Certificate as a Trusted Certificate
- To make the Microsoft Active Directory certificate a trusted certificate, export the certificate and import it into the keystore of the Oracle Xellerate Identity Provisioning server as a trusted CA certificate.
 . . .

The following is a partial listing of the resource bundle lines that contain the prerequisite tasks that appear after the installation of the Microsoft Active Directory connector:

AD-connector.prerequisite.enablingldaps=Enabling LDAPS

AD-connector.prerequisite.enablingldapsteps=<ul><li>Ensure that Certificate Services are installed on the server</li><li>Open the default group policy for the Domain Controller on the server (in Active Directory Users and Computers).</li><li>Right-click the domain node, and select Properties.</li><li>Click the Group Policy tab.</li><li>Select Default Domain Policy.</li>. . . </ul>

AD-connector.prerequisite.setupad=Setting Up the Microsoft Active Directory Certificate as a Trusted Certificate

AD-connector.prerequisite.setupadsteps=<ul><li>To make the Microsoft Active Directory certificate a trusted certificate, export the certificate and import it into the keystore of the Oracle Xellerate Identity Provisioning server as a trusted CA certificate.</li> . . .</ul>

To enable the display of these resource bundle lines at the end of the installation process, you must add the following lines in the configuration XML file:

<pre-Install>
  <title description="AD-connector.prerequisite.enablingldaps">
    <step>AD-connector.prerequisite.enablingldapsteps</step>
  </title>
  <title description="AD-connector.prerequisite.setupad">
    <step>AD-connector.prerequisite.setupadsteps</step>
  </title>
</pre-Install>

18.1.12 dependency-connector Element

The following table summarizes the properties of the dependency-connector element:

Property	Value
Parent Element	`connector`
Attributes	None
Child Elements	`dependency-connector-name`, `dependency-connector-version`
Number of Occurrences	At least one
Element Value	NA

You can start using certain connectors only after the installation of certain other connectors. For example, you can start using the Novell GroupWise connector only after you install the Novell eDirectory connector. In the Oracle Identity Manager context, the connector whose installation is a prerequisite is called the dependent connector. For example, the Novell eDirectory connector is the dependent (required) connector for the Novell GroupWise connector.

The dependency-connector element is used to hold information about dependent connectors for your connector. If your connector has multiple dependent connectors, then add one dependency-connector element in the XML file for each dependent connector.

The following sections discuss the child elements of the dependency-connector element:

dependency-connector-name Element
dependency-connector-version Element

18.1.13 dependency-connector-name Element

The following table summarizes the properties of the dependency-connector-name element:

Property	Value
Parent Element	`dependency-connector`
Attributes	None
Child Elements	None
Number of Occurrences	At least one
Element Value	Name of the dependent connector

Use the dependency-connector-name element to specify the name of the dependent connector for your connector. The name that you specify must be the same as the name that is specified in the connector-name element of the XML file for the dependent connector.

The "dependency-connector-version Element" section contains an example that illustrates how you must use the dependency-connector-name element.

18.1.14 dependency-connector-version Element

The following table summarizes the properties of the dependency-connector-version element.

Property	Value
Parent Element	`dependency-connector`
Attributes	None
Child Elements	None
Number of Occurrences	One for each occurrence of the `dependency-connector-name` element
Element Value	Release number of the dependent connector

Use the dependency-connector-version element to specify the release number of the dependent connector for your connector. The release number that you specify must be the same as the release number that is specified in the connector-version element of the configuration XML file for the dependent connector. Ensure that there are no spaces in the connector version value that you specify.

The following example illustrates how to use the dependency-connector, dependency-connector-name, and dependency-connector-version elements.

DepConn1 and DepConn2 are dependent connectors for your connector. Their release numbers are 9.0.3 and 9.0.4.1, respectively. For these dependent connectors, you must add the following lines in the configuration XML file of your connector:

<dependency-connector>
  <dependency-connector-name>DepConn1<dependency-connector-name>
  <dependency-connector-version>9.0.3<dependency-connector-version>
</dependency-connector>
<dependency-connector>
  <dependency-connector-name>DepConn2</dependency-connector-name>
  <dependency-connector-version>9.0.4.1<dependency-connector-version>
</dependency-connector>

If your connector has no dependent connectors, then you need not add the dependency-connector element.

18.1.15 Sample Configuration XML File

The following are the contents of a sample configuration XML file:

<?xml version="1.0" encoding="UTF-8" ?> 
<connector orderid="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\ConnectorSchema.xsd">
<connector-name>Active Directory</connector-name>
<connector-version>9.1.0</connector-version>
<filecopy>
<destination folder="ConnectorResources">
  <file>ActiveDirectory.properties</file>
<destination folder="JavaTasks">
  <file>connector.jar</file>
</destination>
<destination folder="ScheduleTask">
  <file>connector.jar</file>
</destination>
</filecopy>
<configuration>
  <source folder="xml">
    <file>ActiveDirectory.xml</file>
  </source>
</configuration>
<pre-Install>
  <title description="AD-connector.prerequisite.enablingldaps">
    <step>AD-connector.prerequisite.enablingldapsteps</step>
  </title>
  <title description="AD-connector.prerequisite.setupad">
    <step>AD-connector.prerequisite.setupadsteps</step>
  </title>
</pre-Install>
<dependency-connector>
  <dependency-connector-name>DepConn1<dependency-connector-name>
  <dependency-connector-version>9.0.3<dependency-connector-version>
</dependency-connector>
<dependency-connector>
  <dependency-connector-name>DepConn2</dependency-connector-name>
  <dependency-connector-version>9.0.4.1<dependency-connector-version>
</dependency-connector>

18.2 Developing the Test Class for the Connector

You must develop a test class for the connector. When you use the Diagnostic Dashboard to test connectivity, reconciliation, or provisioning, this class is used to run the test.

The following are guidelines on creating the test class:

The test class must implement the testBasicConnectivity, testProvisioning, and testReconciliation methods. These methods must accept a hashmap parameter.
The name of the test class must be in the following format:
```
connector_nameConnectorTest.java
```
To apply this format, replace connector_name with the value of the ITResourceDef attribute of the SPD_KEY element in the following file:
```
Connector_Pack_Directory/xml/xliconnector_nameResourceObject.xml
```
Remove spaces, if there are any, from the value of the ITResourceDef attribute. For example, suppose the SPD_KEY element in the XML file is as follows:
```
<SPD_KEY ITResourceDef="AD Server"/>
```
In this case, set the name of the test class to ADServerConnectorTest.java.
Include the test class file in the connector JAR file, and then copy the JAR file into the lib directory inside the connector pack directory.

18.3 Structure of the Connector Pack Directory

After you create the connector files, you must place them in the directories described in Table 18-2. These directories are placed in the connector pack directory for your connector. For example, the connector pack directory for the Microsoft Active Directory connector is ActiveDirectory.

Table 18-2 Structure of the Connector Pack Directory

Directory	Description
`configuration`	In this directory, place the configuration XML file to be used during the installation process. For example: `ActiveDirectorConnectorConfig.xml`
`ext`	In this directory, place all third-party JAR files. During the installation process, files in this directory are copied into the `ThirdParty` directory. For example, the `ldap.jar` file is required for using the Sun Java System Directory connector.
`lib`	In this directory, place the JAR files required for reconciliation and provisioning operations. During the installation process, JAR files for reconciliation are copied into the `ScheduleTask` directory and JAR files for provisioning are copied into the `JavaTasks` directory. For example: `xliActiveDirectory.jar`
`resources`	In this directory, place the resource bundles. During the installation process, these resource bundles are copied into the `connectorResources` directory. For example: `ActiveDirectory_en.properties`
`scripts`	In this directory, place the scripts that must be run as part of the manual connector configuration process. These scripts are not used during the installation process performed by using the Administrative and User Console.
`xml`	In this directory, place the connector XML files for trusted source and target resource reconciliation. During the installation process, the connector XML files mentioned in the configuration XML file are imported by the Deployment Manager. For example: `ActiveDirectorConnectorConfig.xml`