4 Using the Connector

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

This chapter discusses the following connector configuration procedures:

4.1 Configuring Reconciliation

Reconciliation involves duplicating in Oracle Identity Manager the creation of and modifications to user accounts on the target system. While configuring the connector, the target system can be designated as a trusted source or target resource.

If you designate the target system as a trusted source, then during a reconciliation run:

  • For each newly created user on the target system, an OIM User is created.

  • Updates made to each user on the target system are propagated to the corresponding OIM User.

If you designate the target system as a target resource, then during a reconciliation run:

  • For each account created on the target system, a resource is assigned to the corresponding OIM User.

  • Updates made to each account on the target system are propagated to the corresponding resource.

This section discusses the following topics related to configuring reconciliation:

4.1.1 Performing Full Reconciliation

Full reconciliation involves reconciling all existing user records from the target system into Oracle Identity Manager. After you deploy the connector, you must first perform full reconciliation.

To perform a full reconciliation run, remove (delete) any value currently assigned to the Filter attribute of the Target User Reconciliation scheduled task. See Scheduled Tasks for Reconciliation for information about this scheduled task.

During a full reconciliation run, if you provide both batching parameters and filters, the connector processes the data in batches. Then, filters are applied to the processed data.

4.1.2 Performing Limited Reconciliation

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 can perform limited reconciliation by creating filters for the reconciliation module. This connector provides a Filter attribute (a scheduled task attribute) that allows you to use Webservices resource attributes to filter the target system records.

For detailed information about ICF Filters, see ICF Filter Syntax in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.

While deploying the connector, follow the instructions in Configuring Scheduled Jobs to specify attribute values.

4.1.3 Performing Batched Reconciliation

During a reconciliation run, all changes in the target system records are reconciled into Oracle Identity Manager. Depending on the number of records to be reconciled, this process may require a large amount of time. In addition, if the connection breaks during reconciliation, then the process would take longer to complete.

You can configure batched reconciliation to avoid these problems.

To configure batched reconciliation, you must specify values for the Batch Size scheduled task attribute. Use this attribute to specify the number of records that must be included in each batch.

By default, the value of Batch Size attribute is blank, indicating that all records will be included (no batched reconciliation). You specify a value for this attribute by following the instructions described in Configuring Scheduled Jobs.

The mechanism of returning multiple records during a search operation may vary with the target webservice. For batching, the connector includes two parameters, batch start index and batch end index. Some target webservices expect different parameters such as Start index and Page size. In such cases, the page size in the SOA composite should be defined in terms of connector parameters, for example, batchEnd - batchStart + 1 as shown below:

acmews:getVariableData('SearchOp_InputVariable','parameters','/ns2:search/batchEnd') - acmews:getVariableData('SearchOp_InputVariable','parameters','/ns2:search/batchStart') + 1

4.1.4 Configuring the Target System As a Trusted Source

Note:

Skip this section if you do not want to designate the target system as a trusted source for reconciliation.

To configure trusted source reconciliation:

  1. Log in to Oracle Identity Manager Administrative and User Console.
  2. Update the Configuration Lookup parameter of the IT Resource to Lookup.ACME.Configuration.Trusted, where ACME indicates the target system.

    You can change the entries in this configuration lookup if needed.

4.2 Scheduled Tasks

When you run the Connector Installer or import the connector XML file, the following reconciliation scheduled tasks are automatically created in Oracle Identity Manager:

This section also discusses the following topics related to scheduled tasks:

4.2.1 Scheduled Task for Lookup Field Synchronization

The ACME Webservice Lookup Reconciliation scheduled task is used for lookup field synchronization. The ACME Webservice code indicates the target system.

You can specify values for the attributes of this scheduled job listed in the following table:

Table 4-1 Attributes of the Scheduled Task for Lookup Field Synchronization

Attribute Description

Code Key Attribute

Enter the name of the connector or target system attribute that is used to populate the Code Key column of the lookup definition (specified as the value of the Lookup Name attribute).

Default value: __UID__

Note: Do not modify the value of this attribute.

Decode Attribute

Enter the name of the connector or target system attribute that is used to populate the Decode column of the lookup definition (specified as the value of the Lookup Name attribute).

Sample value: __NAME__

Note: Do not modify the value of this attribute.

IT Resource Name

Enter the name of the IT resource for the target system installation from which you want to reconcile user records.

Default value: ACME Webservice Server

where ACME Webservice indicates the target system.

Lookup Name

This attribute holds the name of the lookup definition that maps each lookup definition with the data source from which values must be fetched.

By default, this field is blank.

For example, in the case of Roles, create a new lookup definition such Lookup.ACME.Roles in the Design Console and provide the lookup name as the value of this attribute.

Object Type

Enter the type of object whose values must be synchronized.

Sample value for Role lookup reconciliation: Roles

Resource Object Name

Enter the name of the resource object that is used for reconciliation.

Default value: ACME Webservice User

where ACME Webservice indicates the target system.

4.2.2 Scheduled Tasks for Reconciliation

ACME Webservice User Target Reconciliation scheduled job is used to reconcile user data in the target resource (account management) mode of the connector.

ACME Webservice User Trusted Reconciliation scheduled job is used to reconcile user data in the trusted source (identity management) mode of the connector.

The ACME Webservice code in the job names indicate the target system configured with the connector.

Table 4-2 describes the attributes of the scheduled tasks.

Table 4-2 Attributes of the Scheduled Tasks for Reconciliation

Attribute Description

Batch Size

Specify the number of records that must be included in each batch

By default, this field is blank.

See Performing Batched Reconciliation for more information.

Filter

Expression for filtering records that must be reconciled by the scheduled task

By default, the value of this attribute is empty.

Sample value: equalTo('LastName','USER1')

See Performing Limited Reconciliation for the syntax of this expression.

Incremental Recon Attribute

Name of the target system attribute that holds last update-related number, non-decreasing value. For example, numeric or strings.

The value in this attribute is used during incremental reconciliation to determine the newest or youngest record reconciled from the target system.

Sample value: timestamp

Note: Ensure that the timestamp value is correctly mapped in the SOA composite in the search operation output transformation.

Provide the timestamp value only if you want to run incremental reconciliation. Leave this field blank for full reconciliation.

IT Resource Name

Name of the IT resource for the target system installation from which you want to reconcile user records

Default value: ACME Webservice Server

where ACME Webservice indicates the target system.

Latest Token

Timestamp at which the last reconciliation run started.

Note: Do not enter a value for this attribute. The reconciliation engine automatically enters a value in this attribute. If the value is already set, you can clear the value to run full reconciliation instead of incremental reconciliation.

Object Type

Type of object you want to reconcile

Default value: User

Resource Object Name

Name of the resource object that is used for reconciliation

Default value for User Target Reconciliation: ACME Webservice User

Default value for User Trusted Reconciliation: ACME Webservice User Trusted

where ACME Webservice indicates the target system.

Scheduled Task Name

Name of the scheduled task

Note: For the scheduled task shipped with this connector, you must not change the value of this attribute. However, if you create a copy of the task, then you can enter the unique name for that scheduled task as the value of this attribute.

4.2.3 Delete User Target Reconciliation

The ACME Webservice Delete User Target Reconciliation scheduled job is used to reconcile data about deleted users and user records. The ACME Webservice indicates the target system name. Table 4-3 lists the attributes of this scheduled job.

Table 4-3 Attributes of the Delete User Target Reconciliation Scheduled Job

Attribute Description

IT Resource Name

Name of the IT resource instance that the connector must use to reconcile data.

Default value: ACME Webservice Server

Object Type

Type of object you want to reconcile.

Default value: User

Resource Object Name

Name of the resource object against which reconciliation runs must be performed.

Default value: ACME Webservice User

Note: For the resource object shipped with this connector, you must not change the value of this attribute. However, if you create a copy of the resource object, then you can enter the unique name for that resource object as the value of this attribute.

4.2.4 Adding defaultBatchSize as a Configuration Property

You can add defaultBatchSize as a configuration property to specify the default batch size for the reconciliation of records during delete reconciliation. The "defaultBatchSize" attribute can also be used for reconciliation in general.

To add defaultBatchSize as a configuration property, perform the following procedure:

Note:

The following procedure is optional.

  1. Log in to the Design Console.
  2. Expand Administration and double-click Lookup Definition.
  3. Search for and open the existing Webservice Connector configuration lookup definition.
  4. In the lookup configuration, provide a value for the defaultBatchSize parameter to make it as the default batch size.
  5. Click Save.

4.2.5 Configuring Scheduled Jobs

To configure a scheduled task:

  1. If you are using Oracle Identity Manager release 11.1.1, then:

    1. Log in to the Administrative and User Console.

    2. On the Welcome to Oracle Identity Manager Self Service page, click Advanced in the upper-right corner of the page.

  2. If you are using Oracle Identity Manager release 11.1.2.x, then:

    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 job as follows:

    1. If you are using Oracle Identity Manager release 11.1.1, then on the Welcome to Oracle Identity Manager Advanced Administration page, in the System Management region, click Search Scheduled Jobs.

    2. 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.

    3. 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.

    • Attributes of the scheduled jobs are described in the earlier sections in this chapter.

  6. After specifying the attributes, click Apply to save the changes.

    Note:

    The Stop Execution option is available in the Administrative and User Console. You can use the Scheduler Status page to either start, stop, or reinitialize the scheduler.

4.3 Configuring Provisioning in Oracle Identity Manager Release 11.1.1

Provisioning a resource for an OIM User involves using Oracle Identity Manager to create a target system account for the user.

If you have configured the connector for request-based provisioning, then the process form is suppressed and the object form is displayed. In other words, direct provisioning is disabled when you configure the connector for request-based provisioning. If you want to revert to direct provisioning, then perform the steps described in Switching Between Request-Based Provisioning and Direct Provisioning.

The following are types of provisioning operations:

  • Direct provisioning

  • Request-based provisioning

  • Provisioning triggered by policy changes

See Also:

Manually Completing a Task in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Manager for information about the types of provisioning

This section discusses the following topics:

4.3.1 Configuring Direct Provisioning

When you install the connector on Oracle Identity Manager, the direct provisioning feature is automatically enabled. This means that the process form is enabled when you install the connector.

In direct provisioning, the Oracle Identity Manager administrator uses the Administrative and User Console to create a target system account for a user.

To provision a resource by using the direct provisioning approach:

  1. Log in to the Administrative and User Console.
  2. On the Welcome to Identity Administration page, in the Users region, click Create User.
  3. On the Create User page, enter values for the OIM User fields, and then click Save.
  4. If you want to provision a target system account to an existing OIM User, then:

    • On the Welcome to Identity Administration page, search for the OIM User by selecting Users from the list on the left pane.

    • From the list of users displayed in the search results, select the OIM User. The user details page is displayed on the right pane.

  5. On the user details page, click the Resources tab.
  6. From the Action menu, select Add Resource. Alternatively, you can click the add resource icon with the plus (+) sign. The Provision Resource to User page is displayed in a new window.
  7. On the Step 1: Select a Resource page, select ACME Webservice User from the list and then click Continue.
  8. On the Step 2: Verify Resource Selection page, click Continue.
  9. On the Step 5: Provide Process Data for User Details page, enter the details of the account that you want to create on the target system and then click Continue.
  10. On the Step 6: Verify Process Data page, verify the data that you have provided and then click Continue.
  11. Close the window displaying the "Provisioning has been initiated" message.
  12. On the Resources tab, click Refresh to view the newly provisioned resource.

4.3.2 Configuring Request-Based Provisioning

In request-based provisioning, an end user creates a request for a resource by using the Administrative and User Console. Administrators or other users can also create requests for a particular user. Requests for a particular resource on the resource can be viewed and approved by approvers designated in Oracle Identity Manager.

The following are features of request-based provisioning:

  • A user can be provisioned only one resource (account) on the target system.

    Note:

    Direct provisioning allows the provisioning of multiple target system accounts on the target system.

  • Direct provisioning cannot be used if you enable request-based provisioning.

Note:

The request dataset provided with the connector does not contain the User Login field, which is usually fed directly from Oracle Identity Manager user profile to the process form using a prepopulate adapter.

To include the User Login field in request dataset, perform the following procedure:

  1. Export the current dataset using the MDS export utility.

  2. Update the dataset to include the User Login field.

  3. Import the updated dataset using the MDS import utility.

  4. Purge the cache, as described in Clearing Content Related to Connector Resource Bundles from the Server Cache.

For information about exporting and importing request datasets, see http://docs.oracle.com/cd/E14571_01/doc.1111/e14309/utils.htm#BEIHDGCD.

For information about uploading request datasets into MDS, see http://docs.oracle.com/cd/E14571_01/doc.1111/e14309/request.htm#CIHIBFFA.

The following sections discuss the steps to be performed to enable request-based provisioning:

Note:

The procedures described in these sections are built on an example in which the end user raises or creates a request for provisioning a target system account. This request is then approved by the approver.

4.3.2.1 End User's Role in Request-Based Provisioning

The following steps are performed by the end user in a request-based provisioning operation:

  1. Log in to the Administrative and User Console.
  2. On the Welcome page, click Advanced in the upper-right corner of the page.
  3. On the Welcome to Identity Administration page, click the Administration tab, and then click the Requests tab.
  4. From the Actions menu on the left pane, select Create Request.

    The Select Request Template page is displayed.

  5. From the Request Template list, select Provision Resource and click Next.
  6. On the Select Users page, specify a search criterion in the fields to search for the user that you want to provision the resource, and then click Search. A list of users that match the search criterion you specify is displayed in the Available Users list.
  7. From the Available Users list, select the user to whom you want to provision the account.

    If you want to create a provisioning request for more than one user, then from the Available Users list, select users to whom you want to provision the account.

  8. Click Move or Move All to include your selection in the Selected Users list, and then click Next.
  9. On the Select Resources page, click the arrow button next to the Resource Name field to display the list of all available resources.
  10. From the Available Resources list, select ACME Webservice User, move it to the Selected Resources list, and then click Next.
  11. On the Resource Details page, enter details of the account that must be created on the target system, and then click Next.
  12. On the Justification page, you can specify values for the following fields, and then click Finish.

    • Effective Date

    • Justification

    On the resulting page, a message confirming that your request has been sent successfully is displayed along with the Request ID.

  13. If you click the request ID, then the Request Details page is displayed.
  14. To view details of the approval, on the Request Details page, click the Request History tab.

4.3.2.2 Approver's Role in Request-Based Provisioning

The following are steps performed by the approver in a request-based provisioning operation:

The following are steps that the approver can perform:

  1. Log in to the Administrative and User Console.
  2. On the Welcome page, click Self-Service in the upper-right corner of the page.
  3. On the Welcome to Identity Manager Self Service page, click the Tasks tab.
  4. On the Approvals tab, in the first section, you can specify a search criterion for request task that is assigned to you.
  5. From the search results table, select the row containing the request you want to approve, and then click Approve Task.

    A message confirming that the task was approved is displayed.

4.3.2.3 Enabling the Auto Save Form Feature

To enable the Auto Save Form feature:

  1. Log in to the Design Console.
  2. Expand Process Management, and then double-click Process Definition.
  3. Search for and open the ACME Webservice User process definition.
  4. Select the Auto Save Form check box.
  5. Click Save.

4.3.2.4 Running the PurgeCache Utility

Run the PurgeCache utility to clear content belonging to the Metadata category from the server cache. See Clearing Content Related to Connector Resource Bundles from the Server Cache for instructions.

The procedure to configure request-based provisioning ends with this step.

4.3.3 Switching Between Request-Based Provisioning and Direct Provisioning

If you have configured the connector for request-based provisioning, you can always switch to direct provisioning. Similarly, you can always switch back to request-based provisioning any time.

Note:

It is assumed that you have performed the procedure described in Configuring Request-Based Provisioning.

This section discusses the following topics:

4.3.3.1 Switching From Request-Based Provisioning to Direct Provisioning

If you want to switch from request-based provisioning to direct provisioning, then:

  1. Log in to the Design Console.

  2. Disable the Auto Save Form feature as follows:

    1. Expand Process Management, and then double-click Process Definition.

    2. Search for and open the ACME Webservice User process definition.

    3. Deselect the Auto Save Form check box.

    4. Click Save.

  3. If the Self Request Allowed feature is enabled, then:

    1. Expand Resource Management, and then double-click Resource Objects.

    2. Search for and open the ACME Webservice User resource object.

    3. Deselect the Self Request Allowed check box.

    4. Click Save.

4.3.3.2 Switching From Direct Provisioning to Request-Based Provisioning

If you want to switch from direct provisioning back to request-based provisioning, then:

  1. Log in to the Design Console.

  2. Enable the Auto Save Form feature as follows:

    1. Expand Process Management, and then double-click Process Definition.

    2. Search for and open the ACME Webservice User process definition.

    3. Select the Auto Save Form check box.

    4. Click Save.

  3. If you want to enable end users to raise requests for themselves, then:

    1. Expand Resource Management, and then double-click Resource Objects.

    2. Search for and open the ACME Webservice User resource object.

    3. Select the Self Request Allowed check box.

    4. Click Save.

4.4 Configuring Provisioning in Oracle Identity Manager Release 11.1.2

To configure provisioning operations in Oracle Identity Manager release 11.1.2.x:

Note:

The time required to complete a provisioning operation that you perform the first time by using this connector takes longer than usual.

  1. Log in to Oracle Identity System Administration.

  2. Create and activate a sandbox. For detailed instructions on creating and activating a sandbox, see Managing Sandboxes in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.

  3. Create an application instance. To do so:

    1. In the left pane, under Configuration, click Application Instances. The Application Instances page is displayed.

    2. From the Actions menu, select Create. Alternatively, click Create on the toolbar. The Create Application Instance page is displayed.

    3. Specify values for the following fields:

      - Name: The name of the application instance.

      - Display Name: The display name of the application instance.

      - Description: A description of the application instance.

      - Resource Object: The resource object name. Click the search icon next to this field to search for and select ACME Webservice.

      - IT Resource Instance: The IT resource instance name. Click the search icon next to this field to search for and select ACME Webservice Server.

      - Form: Select the form name, for example, ACME. To do so, click Create. against the Form list, specify the form name, and then create it. On the Create Application Instance page, click the Refresh icon next to the Form field. From this list, select the form name that you created.

  4. Publish the sandbox.

  5. Run lookup field synchronization. See Scheduled Task for Lookup Field Synchronization for more information.

  6. Search for and run the Entitlement List scheduled job to populate the ENT_LIST table. See Configuring Scheduled Jobs for more information about configuring and running scheduled jobs.

  7. Publish the application instance (created in Step 3) to an organization. To do so:

    1. On the Organizations tab of the Application Instance page, click Assign.

    2. In the Select Organizations dialog box, select the organization to which you want to publish the application instance.

    3. Select the Apply to entitlements checkbox.

    4. Click OK.

  8. Search for and run the Catalog Synchronization Job scheduled job. See Configuring Scheduled Jobs for more information about configuring and running scheduled jobs.

  9. Log in to Oracle Identity Administrative and User console.

  10. Create a user. See Creating a User in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Manager for more information about creating a user.

  11. On the Account tab, click Request Accounts.

  12. In the Catalog page, search for and add to cart the application instance created in Step 3, and then click Checkout.

  13. Specify value for fields in the application form and then click Ready to Submit.

  14. Click Submit.

  15. 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.

4.5 Uninstalling the Connector

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