5 Using the Generic REST Connector

You can use the connector for performing reconciliation and provisioning operations after configuring it to meet your requirements.

This chapter is discusses the following topics:

Note:

These sections provide both conceptual and procedural information about configuring the connector. It is recommended that you read the conceptual information before you perform the procedures.

• Configuring Reconciliation

• Scheduled Jobs

• Performing Provisioning Operations

• Uninstalling the Connector

5.1 Configuring Reconciliation

You can configure the connector to specify the type of reconciliation and its schedule.

This section discusses the following topics related to configuring reconciliation:

• Reconciliation Rules for the Generic REST Connector

• Full Reconciliation and Incremental Reconciliation

• Updating the User Reconciliation Scheduled Job for Incremental Reconciliation

• Limited (Filtered) Reconciliation

• Lookup Field Synchronization

• Reconciling Large Number of Records

5.1.1 Reconciliation Rules for the Generic REST Connector

Reconciliation rules are automatically created when you generate the Generic REST connector.

The following is the format of the rule element:

User Login Equals NameAttribute

In this rule element:

• User Login is the User ID field on the OIM User form.

• NameAttribute is the value of the account qualifier in the schema.properties file that you created in Creating a Schema File.

For example, if the value of the NameAttribute account qualifier is __NAME__, then the rule element is as follows:

User Login Equals__NAME__

5.1.2 Full Reconciliation and Incremental Reconciliation

Full reconciliation involves reconciling all existing user records from the target system into Oracle Identity Manager. In incremental reconciliation, only records created or modified after the latest date or timestamp the last reconciliation was run are considered for reconciliation.

After you deploy the connector, you must first perform full reconciliation.

You can perform a full reconciliation run by removing or deleting any value currently assigned to the Filter Suffix attribute and then run the scheduled job for user data reconciliation. See Scheduled Jobs for Reconciliation of User Records for more information about the user reconciliation scheduled job and Filter Suffix attribute.

If the target system contains more number of records than what it can return in a single response, then use the Flat File connector to perform full reconciliation. See Reconciling Large Number of Records.

To perform incremental reconciliation, you must update and run the scheduled job for user data reconciliation to include the following attributes:

• Incremental Recon Attribute — Name of the target system attribute that holds the time stamp at which the record was last modified. The value in this attribute is used to determine the newest or latest record reconciled from the target system.

• Latest Token — Holds the value of the attribute that is specified as the value of the Incremental Recon Attribute attribute. The Latest Token attribute is used for internal purposes. Do not enter a value for this attribute. The reconciliation engine automatically enters a value in this attribute. Sample value: 1354753427000

See Updating the User Reconciliation Scheduled Job for Incremental Reconciliation for more information about the scheduled job for incremental reconciliation.

5.1.3 Updating the User Reconciliation Scheduled Job for Incremental Reconciliation

If your target system contains an attribute that holds the timestamp at which an object is created or modified, then you must manually update the user reconciliation schedule job to include attributes for incremental reconciliation.

Note:

See Exporting Deployments and Importing Deployments in Oracle Fusion Middleware Administering Oracle Identity Manager for detailed instructions on performing each of the steps discussed in this procedure.

To create a scheduled job for incremental reconciliation:

1. Log in to Identity System Administration.
2. Add the user reconciliation scheduled job file to the Deployment Manager for export.
3. Edit the user reconciliation scheduled job file to include the Incremental Recon Attribute and Latest Token attributes.
4. Import the user reconciliation scheduled job file into Oracle Identity Manager.

5.1.4 Limited (Filtered) Reconciliation

Limited or filtered reconciliation is the process of limiting the number of records being reconciled based on a set filter criteria.

By default, all target system records that are added or modified after the last reconciliation run are reconciled during the current reconciliation run. You can customize this process by specifying the subset of added or modified target system records that must be reconciled. You do this by creating filters for the reconciliation module.

You can perform limited reconciliation by creating filters that your target system supports. This connector provides the Filter Suffix attribute (scheduled task attributes) that allows you to use any of the attributes of the target system to filter target system records.

5.1.5 Lookup Field Synchronization

Lookup field synchronization involves obtaining the most current values from specific attributes in the target system to the lookup definitions (used as an input source for lookup fields) in Oracle Identity Manager.

You can perform lookup field synchronization by configuring and running the scheduled jobs for lookup field synchronization.

Scheduled jobs for lookup field synchronization are created only if you have specified a value for the lookupAttributeList entry in the GenericRestConfiguration.groovy file. The names of these scheduled jobs are in the following format:

IT_RES_NAME Target FIELD_NAME Lookup Reconciliation

For every attribute specified in the lookupAttributeList entry, a corresponding scheduled job for reconciling lookup values from the target system is created. This is illustrated by the following example:

Suppose the value of the itResourceDefName entry is GenRest. If the value of the lookupAttributeList entry is ['Roles', 'Groups'], then the connector creates the following scheduled jobs:

• GenRest Target Roles Lookup Reconciliation

• GenRest Target Groups Lookup Reconciliation

  Note:

  See Scheduled Job for Lookup Field Synchronization.

5.1.6 Reconciling Large Number of Records

During a reconciliation run, if the target system contains more number of records than what it can return in a single response, then you must use the Flat File connector to fetch all the records into Oracle Identity Manager.

To reconcile a large number of records from the target system into Oracle Identity Manager:

1. Export all users in the target system to a flat file.
2. Copy the flat file to a location that is accessible from Oracle Identity Manager.
3. Create a schema file representing the structure of the flat file. See Creating a Schema File in  Oracle Identity Manager Connector Guide for Flat File.
4. Install the Flat File connector. See Running the Connector Installer in  Oracle Identity Manager Connector Guide for Flat File.
5. Configure the Flat File IT resource. See Configuring the IT Resource in  Oracle Identity Manager Connector Guide for Flat File.
6. If you want to perform trusted source reconciliation, then configure and run the Flat File Users Loader scheduled job.
   While configuring this scheduled job, ensure that you set the value of the Target IT Resource Name attribute to the name of the IT resource for the target system installation from which you want to reconcile user records and Target Resource Object Name to the name of the resource object used for trusted source reconciliation.
   See Flat File Users Loader and IT_RES_NAME Flat File Users Loader in  Oracle Identity Manager Connector Guide for Flat File for information about the attributes of the Flat File Users Loader scheduled job.
7. If you want to perform target resource reconciliation, then configure and run the Flat File Accounts Loader scheduled job.
   While configuring this scheduled job, ensure that you set the value of the Target IT Resource Name attribute to the name of the IT resource for the target system installation from which you want to reconcile user records and Target Resource Object Name to the name of the resource object used for target resource reconciliation.
   See Flat File Accounts Loader and IT_RES_NAME Flat File Accounts Loader in  Oracle Identity Manager Connector Guide for Flat File for information about the attributes of the Flat File Users Loader scheduled job.

5.2 Scheduled Jobs

When you run the Connector Installer, reconciliation scheduled jobs are automatically created in Oracle Identity Manager. You must configure these scheduled jobs to suit your requirements by specifying values for its attributes.

This section discusses the following scheduled jobs that you can configure for reconciliation:

• Scheduled Job for Lookup Field Synchronization

• Scheduled Jobs for Reconciliation of User Records

• Configuring Scheduled Jobs

5.2.1 Scheduled Job for Lookup Field Synchronization

After you generate the connector, scheduled jobs for lookup field synchronization are created only if you have specified a value for the lookupAttributeList entry in the GenericRestConfiguration.groovy file. For every attribute specified in the lookupAttributeList entry, a corresponding scheduled job for reconciling lookup values from the target system is created.

Table 5-1 describes the attributes of the scheduled job for lookup field synchronization.

Table 5-1 Attributes of the Scheduled Job for Lookup Field Synchronization

Attribute	Description
Code Key Attribute	Enter the name of the attribute that is used to populate the Code Key column of the lookup definition (specified as the value of the Lookup Name attribute).
Decode Attribute	Enter the name of the attribute that is used to populate the Decode column of the lookup definition (specified as the value of the Lookup Name attribute).
IT Resource Name	Name of the IT resource for the target system installation from which you want to reconcile records. The default value of this attribute is the same as the value of the ITResourceDefName entry in the GenericRestConfiguration.groovy file.
Lookup Name	Name of the lookup definition in Oracle Identity Manager that must be populated with values fetched from the target system. The value for this attribute is populated automatically if you have specified a value for the lookupAttributeList entry while configuring the GenericRestConfiguration.groovy file. The value of this attribute is in the following format: Lookup.${IT_RES_NAME}.${FIELD_NAME} For example, if you have specified Roles as the value of the lookupAttributeList entry, then the value of this attribute is Lookup.GenRestTrusted.Roles.
Object Type	Enter the type of object you want to reconcile. Default value: OTHER Note: For lookup field synchronization, the object type must be any object other than "User."

5.2.2 Scheduled Jobs for Reconciliation of User Records

After you generate the connector, the scheduled task for user data reconciliation is automatically created in Oracle Identity Manager. A scheduled job, which is an instance of this scheduled task is used to reconcile user data from the target system.

The following scheduled jobs are used for user data reconciliation:

• RESOURCE Target Resource User Reconciliation

  This scheduled job is used to reconcile user data in the target resource (account management) mode of the connector.

• RESOURCE Trusted Resource User Reconciliation

  This scheduled job is used to reconcile user data in the trusted source (identity management) mode of the connector.

Table 5-2 describes the attributes of both scheduled jobs.

Table 5-2 Attributes of the User Reconciliation Scheduled Jobs

Attribute	Description
Filter Suffix	Enter the search filter for fetching user records from the target system during a reconciliation run. See Limited (Filtered) Reconciliation.
IT Resource Name	Name of the IT resource for the target system installation from which you want to reconcile user records. Sample value: GenRestTrusted
Object Type	Type of object you want to reconcile. Default value: User Note: User is the only object that is supported. Therefore, do not change the value of this attribute.
Resource Object Name	Name of the resource object that is used for reconciliation. Sample value: GenRestTrusted User
Scheduled Task Name	Name of the scheduled task that is used for reconciliation. The default value of this attribute in the RESOURCE Target Resource User Reconciliation scheduled job is RESOURCE Target Resource User Reconciliation. The default value of this attribute in the RESOURCE Trusted Resource User Reconciliation scheduled job is RESOURCE Trusted Resource User Reconciliation.

5.2.3 Configuring Scheduled Jobs

You configure scheduled jobs to perform reconciliation runs that check for new information on your target system periodically and replicates the data in Oracle Identity Manager.

To configure a scheduled job:

1. Log in to Oracle Identity System Administration.
2. In the left pane, under System Management, click Scheduler.
3. Search for and open the scheduled task as follows:
   1. On the left pane, in the Search field, enter the name of the scheduled job as the search criterion. Alternatively, you can click Advanced Search and specify the search criterion.
   2. In the search results table on the left pane, click the scheduled job in the Job Name column.
4. On the Job Details tab, you can modify the following parameters:
   • Retries: Enter an integer value in this field. This number represents the number of times the scheduler tries to start the job before assigning the Stopped status to the job.
   • Schedule Type: Depending on the frequency at which you want the job to run, select the appropriate schedule type.

   Note:

   See Creating Jobs in Oracle Fusion Middleware Administering Oracle Identity Manager for detailed information about schedule types.

   In addition to modifying the job details, you can enable or disable a job.
5. On the Job Details tab, in the Parameters region, specify values for the attributes of the scheduled task.

   Note:

   • Attribute values are predefined in the connector XML file that you import. Specify values only for those attributes that you want to change.

   • Values (either default or user-defined) must be assigned to all the attributes. If even a single attribute value is left empty, then reconciliation is not performed.

   • Attributes of the scheduled job are discussed in Scheduled Jobs.

6. Click Apply to save the changes.

   Note:

   You can use the Scheduler Status page in Identity System Administration to either start, stop, or reinitialize the scheduler.

5.3 Performing Provisioning Operations

You create a new user in Oracle Identity Self Service by using the Create User page. You provision or request for accounts on the Accounts tab of the User Details page.

To perform provisioning operations in Oracle Identity Manager:

1. Log in to Identity Self Service.
2. Create a user. See Creating a User in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Manager.
3. On the Account tab, click Request Accounts.
4. In the Catalog page, search for and add to cart the application instance created for the IT resource (in Associating the Form with the Application Instance), and then click Checkout.

   Note:

   Ensure to select proper values for lookup type fields as there are a few dependent fields. Selecting a wrong value for such fields may result in provisioning failure.
5. Click Ready to Submit.
6. Click Submit.
7. If you want to provision entitlements, then:
   1. On the Entitlements tab, click Request Entitlements.
   2. In the Catalog page, search for and add to cart the entitlement, and then click Checkout.
   3. Click Submit.

5.4 Uninstalling the Connector

Uninstalling the connector involves deleting data related to the connector from Oracle Identity Manager Database. You use the Uninstall Connectors utility to uninstall a connector.

If you want to uninstall the connector for any reason, see Uninstalling Connectors in Oracle Fusion Middleware Administering Oracle Identity Manager.