Oracle Stack: Adding Attributes to an ICF Connector for Provisioning

Version: Oracle Identity Manager 11.1.2.2.0
Description: Shows how to add a resource attribute to an Identity Connector Framework (ICF) OIM connector for provisioning in general. The Database Application Tables (DBAT) 11.1.1.5.0 connector is used as an example. Refer to here for setting up the DBAT connector.
References: https://docs.oracle.com/cd/E22999_01/index.htm
https://docs.oracle.com/cd/E22999_01/doc.111/e20277/extnd_func.htm#CDEJFECH
Prerequisites
1. Design console must be installed. You can start the client by executing xlclient.sh, which is located in "$MW_HOME/Oracle_IDM1/designconsole" directory.

2. Add the new attribute in the target system. For the database table as a target system, add a column to the target table by executing the following SQL:

/*Add a column to target table DBAT_USER*/
ALTER TABLE DBAT_USER ADD (MIDDLE_NAME VARCHAR(40));

Add Field to Process Form
The process form is used in OIM to store target resource account data. It contains fields in order to store the data of the target resource attributes, and propagate changes downstream.

1. Log in to Design Console.

2. Expand Development Tools, double click on Form Designer, and search for the process form for your target system. Side Note: You can query the Table Name (E.g. UD_DBATUSR) directly from the database to inspect all process form instances of a particular resource in your current OIM system.

3. Click Create New Version, enter form version label, save, and then close window. A new form version is needed in order to make changes.

4. On the Additional Columns tab, click Add, and specify Name, Variant Type, Length, Field Label, Field Type, and Order in order to create a field on the process form. Then save by clicking the floppy disc icon.
Example:
Name: UD_DBATUSR_MIDDLENAME
Variant Type: String
Length: 40 (NOTE: This should typically match the length of the target system attribute.)
Field Label: Middle Name
Field Type: TextField
Order: 6

Note: If the attribute on the target system is of the Date, Time, or Timestamp format, then set the value of the Variant Type column to String.
5. Click Make Version Active in order for the new form to be in use. Then click OK on the dialog box.

Lookup.RESOURCE.UM.ProvAttrMap
This lookup definition is used to define a mapping between the resource attribute defined in OIM process form and the resource attribute on the actual target system.

1. On the left pane of design console, expand Administration and double-click on Lookup Definition.

2. Search for Lookup.RESOURCE.UM.ProvAttrMap, replacing RESOURCE with the name of your resource. Side Note: If you do not know the name of your resource, you can search for *ProvAttMap to get all resource provisioning attribute map lookup definitions.

3. Click Add, and provide an entry for your new resource attribute mapping. For Code Key column, use the attribute's Field Label from the process form. For Decode column, use the name of the resource attribute on the target system. For the database table example:
Code Key = Middle Name (Field Label on the UD_DBATUSR process form)
Decode = MIDDLE_NAME (Column Name on the target table DBAT_USR)

4. Then save by clicking the floppy disc icon.

Process Task for Updates
In order for the changes on the process form to propagate to the target system, an Updated process task needs to be created for each new attribute.

1. On the left pane of design console, expand Process Management, and click Process Definition.

2. Search for the name of your Process Definition.

3. On the Tasks tab, click Add.

4. On the General tab of the dialog box that is displayed, enter a name and description for the task.

The Task Name must follow the following format:
PROCESS_FORM_FIELD_LABEL Updated
Example: Middle Name Updated

Then select the following fields in the Task Properties section:

- Conditional

- Allow Cancellation while Pending

- Allow Multiple Instances

Side Note: It is highly recommended to set the Retry Period in Minutes and Retry Count task properties. If a process task fails, OIM attempts to kick off the process task again through an OOTB scheduled job. Failed process tasks can be retried manually through Resource History of an account or in Administration -> Open Tasks.

Resource History button for resource account

Resource History: Process Task Triggered

Open Tasks section

5. On the Integration tab, attach the adapter responsible for performing the update account provisioning operations and map the adapter variables.

Click Add

Select Adapter as the Handler Type, and
then select DBAT Update Attribute adapter.

Map the adapter variables.

Variable Name: itResourceFieldName
Data Type String
Map To: Literal
Qualifier: String
Literal Value: {Server Field Column Name on Process Form}

Variable Name: attrFieldName
Data Type: String
Map To: Literal
Qualifier: String
Literal Value: {Attribute Field Label on Process Form}

Variable Name: objectType
Data Type: String
Map To: Literal
Qualifier: String
Literal Value: User

Variable Name: Adapter return value
Data Type: Object
Map To: Response Code

Variable Name: procInstanceKey
Data Type: Long
Map To: Process Data
Qualifier: Process Instance

Side Note: The adapter methods from oracle.iam.connectors.icfcommon.prov.ICFProvisioningManager class are used in all ICF connectors including custom ones.

6. On the Responses tab, add SUCCESS and ERROR responses. Then save.

Update UI Form
1. Log in to Identity System Administration.

2. Create and active a sandbox.

On top right menu, click Sandboxes.

Click Create Sandbox.

3. On the left pane, click Form Designer under Configuration.

4. On the Search Form page, click Create.

5. Specify Resource Type, Form Name, and Form Type. Ensure the new attribute is listed in the Available form fields section, and then click Create.

6. On the left pane, click Application Instances under Configuration, and then search for the name of your application instance.

7. On application instance form, change the Form parameter to the form you created. Then click Apply.

8. Publish the sandbox.

Update Process Form Instances
Ensure the process form instances are using the latest form version. You can query the UD table to check the form version being used for each process form instance. Inconsistent form version can happened when there are existing provisioned resource accounts in OIM, and later on you decide to add a new attribute on the process form.