3 Installing the Generic REST Connector

You must install the connector in Oracle Identity Manager. If necessary, you can also deploy the connector in a Connector Server.

The Generic REST connector installation can be divided into various stages, as illustrated in the following figure:

Figure 3-1 Stages of Connector Installation

Description of "Figure 3-1 Stages of Connector Installation"

Installation information is divided across the following sections:

3.1 Installing the Connector Installation Package

You must install the connector installation package by running the Connector Installer. When you run the Connector Installer, it automatically copies configuration files to Oracle Identity Manager and uploads the connector bundle, org.identityconnectors.genericrest-1.0.1115.jar, to the Oracle Identity Manager database.

If your target system uses an authentication mechanism that is not supported by this connector, then before you install the connector installation package, you must implement the authentication that your target system uses as described in Implementing Custom Authentication.Similarly, if the reconciliation data from your target system is not in JSON format, then you must write a custom parser implementation for your data format as described in Implementing Custom Parsing.

To install the connector installation package:

Copy the contents of the unzipped connector installation media to the following directory:

OIM_HOME/server/ConnectorDefaultDirectory
Log in to Oracle Identity System Administration.
In the left pane, under Provisioning Configuration, click Manage Connector.
In the Manage Connector page, click Install.
From the Connector List, select Generic REST Connector-RELEASE_NUMBER..

This list displays the names and release numbers of connectors whose installation files you copy into the default connector installation directory in Step 1

If you have copied the installation files into a different directory, then:
1. In the Alternative Directory field, enter the full path and name of that directory.
2. To repopulate the list of connectors in the Connector List list, click Refresh.
3. From the Connector List list, select the relevant connector name depending on whether you are installing the connector included in the connector installation media or the generated connector.
Click Load.
To start the installation process, click Continue.
The following tasks are performed in sequence:
1. Configuration of connector libraries
2. Import of the connector XML files (Using Deployment Manager).
3. Compilation of Adapter Definitions
On successful completion of a task, a check mark is displayed for the task. If a task fails, then an X mark and a message stating the reason for failure are displayed. Depending on the reason for the failure, make the required correction and then perform one of the following steps:
- Retry the installation by clicking Retry.
  
  Cancel the installation and begin again from Step 3.
If all three tasks of the connector installation process are successful, then a message indicating successful installation is displayed.
Click Exit to close the installation page.

3.2 Generating and Installing the Connector Metadata Package

You must run the Metadata Generator to generator the connector metadata package and then install it.

Topics

3.2.1 Running the Metadata Generator

You generate a connector metadata package for your target system by running the metadata generator.

You invoke the metadata generator from the command line by using the executable file named GenericRestGenerator.cmd or GenericRestGenerator.sh.

To run the metadata generator, in a command window, change to the genericrest-RELEASE_NUMBER/metadata-generator/bin directory (for example, genericrest-11.1.1.5.0/bin) and run one of the following commands depending on the operating system that you are using:

For Microsoft Windows

GenericRestGenerator.cmd CONFIG_FILE CONFIG_NAME
For UNIX

GenericRestGenerator.sh CONFIG_FILE CONFIG_NAME

In this command, replace:

CONFIG_FILE with the absolute or relative path name of the GenericRestConfiguration.groovy file.
CONFIG_NAME with the name of the configuration section within the GenericRestConfiguration.groovy file, being used for the target system. The sample configuration within this file are trusted and target. You can create additional custom configurations with different names depending on your requirements.

The following is a sample command: GenericRestGenerator.cmd ..\resources\GenericRestConfiguration.groovy target

In this command, "target" denotes the name of the section in the GenericRestConfiguration.groovy file for which you have specified values. .

If you encounter any errors while running the metadata generator, then you must fix it and then resume running the metadata generator.

3.2.2 Installing the Connector Metadata Package

You must install the connector metadata package by running the Connector Installer. When you run the Connector Installer, it automatically imports the metadata files into Oracle Identity Manager, generates all the connector components, and compiles adapters used for provisioning.

To install the connector metadata package:

Copy the contents of the unzipped connector metadata package to the following directory:

OIM_HOME/server/ConnectorDefaultDirectory
Log in to Oracle Identity System Administration.
In the left pane, under Provisioning Configuration, click Manage Connector.
In the Manage Connector page, click Install.
From the Connector List, select the name of the connector metadata package that you generated.

This list displays the names and release numbers of connectors whose installation files you copy into the default connector installation directory in Step 1

If you have copied the installation files into a different directory, then:
1. In the Alternative Directory field, enter the full path and name of that directory.
2. To repopulate the list of connectors in the Connector List list, click Refresh.
3. From the Connector List list, select the relevant connector name depending on whether you are installing the connector included in the connector installation media or the generated connector.
Click Load.
To start the installation process, click Continue.
The following tasks are performed in sequence:
1. Configuration of connector libraries
2. Import of the connector XML files (Using Deployment Manager).
3. Compilation of Adapter Definitions
On successful completion of a task, a check mark is displayed for the task. If a task fails, then an X mark and a message stating the reason for failure are displayed. Depending on the reason for the failure, make the required correction and then perform one of the following steps:
- Retry the installation by clicking Retry.
  
  Cancel the installation and begin again from Step 3.
If all three tasks of the connector installation process are successful, then a message indicating successful installation is displayed.
Click Exit to close the installation page.

3.2.3 Understanding the Generated Connector Metadata Package for the Generic REST Connector

The connector metadata package is a ZIP file that is generated in the GenericRest-RELEASE_NUMBER/metadata-generator/ directory.

For example, if you have specified GenRest as the value of the itResourceDefName entry in the GenericRestConfiguration.groovy file, then the connector package ZIP (GenRest.zip) file is generated in the GenericRest-11.1.1.5.0/metadata-generator/directory. The directory structure of the connector metadata package is as follows:

CONNECTOR_METADATA_PCKG/
         configuration/
                  IT_RES_DEF-CI.xml
         resources/
                  genericrest-generator.properties
         xml/
                 IT_RES_DEF-ConnectorConfig.xml

In this directory structure:

CONNECTOR_METADATA_PCKG is replaced with the name of the IT resource definition specified as the value of the itResourceDefName entry in the GenericRestConfiguration.groovy file.
IT_RES_DEF is replaced with the name of the IT resource definition specified as the value of the itResourceDefName entry in the GenericRestConfiguration.groovy file.

The following behavior is observed after generation of the connector configuration XML file:

The length of a field (column) from the target system is not fetched into the process form. Therefore, except for the Unique ID and Password fields, the length of all other data fields (of the String data type) on the process form is always set to 255 characters. The length of the Unique ID and Password fields is set to 40 characters.