3 Deploying the Connector

The procedure to deploy the connector is divided into these stages.

Note:

In this guide, a target system that exposes webservice endpoint has been referred to as the target system. ACME Webservice is used as a sample target system to discuss the configurations and the connector objects.

3.1 Installation

Installation on Oracle Identity Manager consists of the following procedures:

Note:

In this guide, the term Connector Installer has been used to refer to the Connector Installer feature of the Oracle Identity Manager Administrative and User Console.

Installing the connector on a Connector Server is not supported.

3.1.1 Running the Connector Installer

Note:

In this guide, the term Connector Installer has been used to refer to the Connector Installer feature of the Administrative and User Console.

To run the Connector Installer:

  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 Identity Manager Advanced Administration page, in the System Management region, click Manage Connector.

  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 Manage Connector.

  3. In the Manage Connector page, click Install.

  4. From the Connector List list, select ACME Webservice 11.1.1.5.0. This list displays the names and release numbers of connectors whose installation files you copy into the default connector installation directory in Step 1.

    The name of the connector is derived from the LONG_CODE provided when building the connector in the preinstallation steps.

    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 ACME Webservice 11.1.1.5.0.

  5. Click Load.

  6. 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 (by using the 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 is 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 1.

  7. If all three tasks of the connector installation process are successful, then a message indicating successful installation is displayed. In addition, a list of steps that you must perform after the installation is displayed. These steps are as follows:

    1. Configuring the IT resource for the connector

      See Configuring the IT Resource for more information.

    2. Configuring the scheduled tasks

      See Configuring Scheduled Jobs for more information.

When you run the Connector Installer, it copies the connector files and external code files to destination directories on the Oracle Identity Manager host computer.

3.1.2 Configuring the IT Resource

Note:

If you have configured your target system as a trusted source, then create an IT resource of type WEBSERVICES. For example, Webservices Trusted. The parameters of this IT resource are the same as the parameters of the IT resources described in Table 3-1 of this section. See Creating IT Resources in Oracle Fusion Middleware Administering Oracle Identity Manager for more information about creating an IT resource.

The IT resource for the target system contains details of the SOA server where the webservice composite is deployed. Oracle Identity Manager uses this information during reconciliation.

When you run the Connector Installer, the ACME Webservice Server IT resource is automatically created in Oracle Identity Manager. As an example, ACME Webservice is the name of the target system that exposes webservice endpoint. You can specify values for the parameters of this IT resource as follows:

  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 page, click Advanced in the upper-right corner of the page.

    3. On the Welcome to Oracle Identity Manager Advanced Administration page, in the Configuration region, click Manage IT Resource.

  2. If you are using Oracle Identity Manager release 11.1.2.x, then create a sandbox as follows:

    See Also:

    Managing Sandboxes in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for more information about application instance and sandbox

    1. Log in to Oracle Identity System Administration

    2. On the upper navigation bar, click Sandboxes. The Manage Sandboxes page is displayed.

    3. On the toolbar, click Create Sandbox. The Create Sandbox dialog box is displayed.

    4. In the Sandbox Name field, enter a name for the sandbox. This is a mandatory field.

    5. In the Sandbox Description field, enter a description of the sandbox. This is an optional field.

    6. Click Save and Close. A message is displayed with the sandbox name and creation label.

    7. Click OK. The sandbox is displayed in the Available Sandboxes section of the Manage Sandboxes page.

    8. Select the sandbox that you created.

    9. On the toolbar, click Activate Sandbox.

      The table refreshes and a marker in the Active column is displayed. In addition, the Sandboxes link on the upper navigation bar also displays the active sandbox name in parentheses.

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

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

    12. Enter the values of the attributes. For example:

      Name: ACMEInstance

      Display Name: ACMEInstance

      Resource Object: ACME Webservice

      IT Resource Instance: ACME Webservice Server

    13. Click Save. The application instance is created, and the details of the application instance is displayed in a page.

    14. To create a form to be associated with the application instance, open the Create Application Instance page or the Attributes tab of the Application Instance details page.

    15. Adjacent to the Forms field, click Create. The Create Form page is displayed.

    16. Enter values for the form attributes. For example:

      Resource Type: ACME Webservice

      Form Name: ACME Form

    17. Click Create. A message is displayed stating that the form is created.

    18. In the Create Application Instance page or the Attributes tab of the Application Instance details page, click Refresh adjacent to the Form field. The newly created form is available for selection in the Form list.

    19. Select the new form from the drop-down list and click Save.

      The application instance is created.

    20. Before publishing the sandbox, close all the open tabs and pages.

    21. From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you created.

    22. On the toolbar, click Publish Sandbox. A message is displayed asking for confirmation.

    23. Click Yes to confirm. The sandbox is published and the customizations it contained are merged with the main line.

    24. In the left pane, under Configuration, click IT Resource.

  3. In the IT Resource Name field on the Manage IT Resource page, enter ACME Webservice Server and then click Search. Alternatively, from the IT Resource Type menu, select ACME Webservice Server, and then click Search.

  4. Click the edit icon for the IT resource.

  5. From the list at the top of the page, select Details and Parameters.

  6. Specify values for the parameters discussed in Table 3-1. The remaining parameters of IT resource are not applicable for this connector.

    Table 3-1 IT Resource Parameters

    Code Key Decode Description

    Configuration lookup

    Lookup.ACME.Configuration

    Name of the lookup definition that contains configuration information.

    Note: You must not change the value of this parameter. However, if you create a copy of all the connector objects, then you can specify the unique name of the copy of this lookup definition as the value of the Configuration Lookup Name parameter in the copy of the IT resource.

    passcode

    		  

    Encryption key that will be used for encrypting passwords and other sensitive information that is passed to the SOA composite.

    Note: This field is mandatory. See "Guidelines for Passcode" for more information.

    Handling Passwords describes the procedure for configuring decryption.

    securityPolicies

    oracle/wss_username_token_client_policy

    OWSM security policy used to authenticate the webservice client endpoint.

    soaServiceWSDL

    http://soa-host:soa-port

    WSDL URL of the connector webservice that invokes the target webservice operations.

    You can copy the complete URL from the WSDL text box field in the SOA composite testing page from Enterprise Manager.

    soaUserName

    weblogic

    SOA server user name where the SOA composite is deployed.

    soaUserPassword

    		  

    Password of the SOA server user entered in previous field.

    WSS_CSF_KEY

    		  

    CSF key of SOA server credentials.

    This field is optional.

    The following is a screenshot of the View IT Resource Details and Parameters page. The screenshot displays sample values for the parameters of the IT resource.

    Description of it_resource.png follows
    Description of the illustration it_resource.png

  7. To save the values, click Update.

3.2 Postinstallation

Postinstallation information is divided across the following sections:

3.2.1 Configuring Oracle Identity Manager 11.1.2 or Later

If you are using Oracle Identity Manager release 11.1.2 or later, you must create additional metadata such as a UI form and an application instance. In addition, you must run entitlement and catalog synchronization jobs. These procedures are described in the following sections:

3.2.1.1 Creating and Activating a Sandbox

Create and activate a sandbox as follows. For detailed instructions, see Managing Sandboxes in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.

  1. On the upper navigation bar, click Sandboxes. The Manage Sandboxes page is displayed.
  2. On the toolbar, click Create Sandbox. The Create Sandbox dialog box is displayed.
  3. In the Sandbox Name field, enter a name for the sandbox. This is a mandatory field.
  4. In the Sandbox Description field, enter a description of the sandbox. This is an optional field.
  5. Click Save and Close. A message is displayed with the sandbox name and creation label.
  6. Click OK. The sandbox is displayed in the Available Sandboxes section of the Manage Sandboxes page.
  7. Select the sandbox that you created.
  8. From the table showing the available sandboxes in the Manage Sandboxes page, select the newly created sandbox that you want to activate.
  9. On the toolbar, click Activate Sandbox.

    The sandbox is activated.

3.2.1.2 Creating a New UI Form

Create a new UI form as follows. For detailed instructions, see Managing Forms in Oracle Fusion Middleware Administering Oracle Identity Manager.

  1. In the left pane, under Configuration, click Form Designer.
  2. Under Search Results, click Create.
  3. Select the resource type for which you want to create the form.
  4. Enter a form name and click Create.

3.2.1.3 Creating an Application Instance

Create an application instance as follows. For detailed instructions, see Managing Application Instances in Oracle Fusion Middleware Administering Oracle Identity Manager.

  1. In the System Administration page, under Configuration in the left pane, click Application Instances.
  2. Under Search Results, click Create.
  3. Enter appropriate values for the fields displayed on the Attributes form and click Save.
  4. In the Form drop-down list, select the newly created form and click Apply.
  5. Publish the application instance for a particular organization.

3.2.1.4 Publishing a Sandbox

To publish the sandbox that you created in Creating and Activating a Sandbox:

  1. Close all the open tabs and pages.
  2. From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you created in Creating and Activating a Sandbox.
  3. On the toolbar, click Publish Sandbox. A message is displayed asking for confirmation.
  4. Click Yes to confirm. The sandbox is published and the customizations it contained are merged with the main line.

3.2.1.5 Harvesting Entitlements and Sync Catalog

To harvest entitlements and sync catalog:

  1. Run the scheduled jobs for lookup field synchronization listed in Scheduled Task for Lookup Field Synchronization.
  2. Run the Entitlement List scheduled job to populate Entitlement Assignment schema from child process form table.
  3. Run the Catalog Synchronization Job scheduled job. See Predefined Scheduled Tasks in Oracle Fusion Middleware Administering Oracle Identity Manager for more information about this scheduled job.

3.2.1.6 Updating an Existing Application Instance with a New Form

For any changes you do in the Form Designer, you must create a new UI form and update the changes in an application instance. To update an existing application instance with a new form:

  1. Create a sandbox and activate it as described in Creating and Activating a Sandbox.
  2. Create a new UI form for the resource as described in Creating a New UI Form.
  3. Open the existing application instance.
  4. In the Form field, select the new UI form that you created.
  5. Save the application instance.
  6. Publish the sandbox as described in Publishing a Sandbox.

3.2.2 Managing Logging

Oracle Identity Manager uses the Oracle Diagnostic Logging (ODL) logging service for recording all types of events pertaining to the connector.

The following topics provide detailed information about logging:

3.2.2.1 Understanding Log Levels

Oracle Identity Manager uses Oracle Java Diagnostic Logging (OJDL) for logging. OJDL is based on java.util.logger. To specify the type of event for which you want logging to take place, you can set the log level to one of the following:

  • SEVERE.intValue()+100

    This level enables logging of information about fatal errors.

  • SEVERE

    This level enables logging of information about errors that might allow Oracle Identity Manager to continue running.

  • WARNING

    This level enables logging of information about potentially harmful situations.

  • INFO

    This level enables logging of messages that highlight the progress of the application.

  • CONFIG

    This level enables logging of information about fine-grained events that are useful for debugging.

  • FINE, FINER, FINEST

    These levels enable logging of information about fine-grained events, where FINEST logs information about all events.

These log levels are mapped to ODL message type and level combinations as shown in Table 3-2.

Table 3-2 Log Levels and ODL Message Type:Level Combinations

Log Level ODL Message Type:Level

SEVERE.intValue()+100

INCIDENT_ERROR:1

SEVERE

ERROR:1

WARNING

WARNING:1

INFO

NOTIFICATION:1

CONFIG

NOTIFICATION:16

FINE

TRACE:1

FINER

TRACE:16

FINEST

TRACE:32

The configuration file for OJDL is logging.xml, which is located at the following path:

DOMAIN_HOME/config/fmwconfig/servers/OIM_SERVER/logging.xml

Here, DOMAIN_HOME and OIM_SERVER are the domain name and server name specified during the installation of Oracle Identity Manager.

3.2.2.2 Enabling logging

To enable logging in Oracle WebLogic Server:

  1. Edit the logging.xml file as follows:

    1. Add the following blocks in the file:

      <log_handler name='webservice-handler' level='[LOG_LEVEL]' class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='logreader:' value='off'/>
     <property name='path' value='[FILE_NAME]'/>
     <property name='format' value='ODL-Text'/>
     <property name='useThreadName' value='true'/>
     <property name='locale' value='en'/>
     <property name='maxFileSize' value='5242880'/>
     <property name='maxLogSize' value='52428800'/>
     <property name='encoding' value='UTF-8'/>
   </log_handler>

      <logger name="ORG.IDENTITYCONNECTORS.GENERICWS" level="[LOG_LEVEL]" useParentHandlers="false">
<handler name="webservice-handler"/>
<handler name="console-handler"/>
</logger>

    2. Replace all occurrences of [LOG_LEVEL] with the ODL message type and level combination that you require. Table 3-2 lists the supported message type and level combinations.

      Similarly, replace [FILE_NAME] with the full path and name of the log file in which you want log messages to be recorded.

      The following blocks show sample values for [LOG_LEVEL] and [FILE_NAME]:

      <log_handler name='webservice-handler' level='NOTIFICATION:1' class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='logreader:' value='off'/>
     <property name='path' value='F:\MyMachine\middleware\user_projects\domains\base_domain1\servers\oim_server1\logs\oim_server1-diagnostic-1.log'/>
     <property name='format' value='ODL-Text'/>
     <property name='useThreadName' value='true'/>
     <property name='locale' value='en'/>
     <property name='maxFileSize' value='5242880'/>
     <property name='maxLogSize' value='52428800'/>
     <property name='encoding' value='UTF-8'/>
   </log_handler>

      <logger name="ORG.IDENTITYCONNECTORS.GENERICWS" level="NOTIFICATION:1" useParentHandlers="false">
     <handler name="webservice-handler"/>
     <handler name="console-handler"/>
   </logger>

      With these sample values, when you use Oracle Identity Manager, all messages generated for this connector that are of a log level equal to or higher than the NOTIFICATION:1 level are recorded in the specified file.

      Note:

      The logging level for console-handler must be as fine as the level set in the loggers.For example, if the NOTIFICATION:1 level is specified in the ORG.IDENTITYCONNECTORS.GENERICWS logger, and the console-handler has ERROR:1 level, then only logs at ERROR:1 or coarser levels would be available.

  2. Click Save and close the file.

  3. Restart the application server.

3.2.3 Setting up the Lookup Definition for Connection Pooling

By default, this connector uses the ICF connection pooling. Table 3-3 lists the connection pooling properties, their description, and default values set in ICF:

Table 3-3 Connection Pooling Properties

Property Description

Pool Max Idle

Maximum number of idle objects in a pool.

Default value: 10

Pool Max Size

Maximum number of connections that the pool can create.

Default value: 10

Pool Max Wait

Maximum time, in milliseconds, the pool must wait for a free object to make itself available to be consumed for an operation.

Default value: 150000

Pool Min Evict Idle Time

Minimum time, in milliseconds, the connector must wait before evicting an idle object.

Default value: 120000

Pool Min Idle

Minimum number of idle objects in a pool.

Default value: 1

If you want to modify the connection pooling properties to use values that suit requirements in your environment, then:

  1. Log in to the Design Console.
  2. Expand Administration, and then double-click Lookup Definition.
  3. Search for and open the configuration lookup definition.

    For example, Lookup.ACME.Configuration.

  4. On the Lookup Code Information tab, click Add.

    A new row is added.

  5. In the Code Key column of the new row, enter Pool Max Idle.
  6. In the Decode column of the new row, enter a value corresponding to the Pool Max Idle property.
  7. Repeat Steps 4 through 6 for adding each of the connection pooling properties listed in Table 3-3.
  8. Click Save.

3.2.4 Changing to the Required Input Locale

Changing to the required input locale (language and country setting) involves installing the required fonts and setting the required input locale.

You may require the assistance of the system administrator to change to the required input locale.

3.2.5 Clearing Content Related to Connector Resource Bundles from the Server Cache

When you deploy the connector, the resource bundles are copied from the resources directory on the installation media into the Oracle Identity Manager database. Whenever you add a new resource bundle to the connectorResources directory or make a change in an existing resource bundle, you must clear content related to connector resource bundles from the server cache.

To clear content related to connector resource bundles from the server cache:

  1. In a command window, switch to the OIM_HOME/server/bin directory.
  2. Enter one of the following commands:

    Note:

    You can use the PurgeCache utility to purge the cache for any content category. Run PurgeCache.bat CATEGORY_NAME on Microsoft Windows or PurgeCache.sh CATEGORY_NAME on UNIX. The CATEGORY_NAME argument represents the name of the content category that must be purged.

    For example, the following commands purge Metadata entries from the server cache:

    PurgeCache.bat MetaData

    PurgeCache.sh MetaData

    On Microsoft Windows: PurgeCache.bat All

    On UNIX: PurgeCache.sh All

    When prompted, enter the user name and password of an account belonging to the SYSTEM ADMINISTRATORS group. In addition, you are prompted to enter the service URL in the following format:

    t3://OIM_HOST_NAME:OIM_PORT_NUMBER

    In this format:

    • Replace OIM_HOST_NAME with the host name or IP address of the Oracle Identity Manager host computer.

    • Replace OIM_PORT_NUMBER with the port on which Oracle Identity Manager is listening.

3.2.6 Disabling Child Tables

Some target systems do not support multivalued attributes. For such target systems, disable the corresponding child table of the process form in Oracle Identity Manager Design Console. The connector includes a default multivalued attribute called Role, which is stored in child tables in Oracle Identity Manager. You can disable the child table if your target system does not support multivalued attributes.

To disable a child table of a process form:

  1. Log in to the Oracle Identity Manager Design Console.
  2. Expand Development Tools.
  3. Double-click Form Designer.
  4. Search for and open the parent process form, such as UD_ACME_USR.
  5. Click Create New Version.

    On the Create a new version dialog box, enter a new version in the Label field, and then click Save.

  6. Click the Child Tables tab and delete the child table.
  7. Click the Save.
  8. Click Make Version Active to activate the newly created form.

3.2.7 Removing Bulk Attribute Update Task

Some target systems do not support bulk update of attributes. For such target systems, remove the corresponding adapter task from the process definition in Oracle Identity Manager Design Console.

The process task will be in the name of FORM_NAME Updated. In the case of the ACME webservice, remove the UD_ACME_USR Updated task from the process definition.

3.2.8 Localizing Field Labels in UI Forms

Note:

Perform the procedure described in this section only if you are using Oracle Identity Manager release 11.1.2.x or later and you want to localize UI form field labels.

To localize field label that is added to the UI forms:

  1. Log in to Oracle Enterprise Manager.

  2. In the left pane, expand Application Deployments and then select oracle.iam.console.identity.sysadmin.ear.

  3. In the right pane, from the Application Deployment list, select MDS Configuration.

  4. On the MDS Configuration page, click Export and save the archive to the local computer.

  5. Extract the contents of the archive, and open one of the following files in a text editor:

    • For Oracle Identity Manager 11g Release 2 PS2 (11.1.2.2.0):

      SAVED_LOCATION\xliffBundles\oracle\iam\ui\runtime\BizEditorBundle_en.xlf

    • For releases prior to Oracle Identity Manager 11g Release 2 PS2 (11.1.2.2.0):

      SAVED_LOCATION\xliffBundles\oracle\iam\ui\runtime\BizEditorBundle.xlf

  6. Edit the BizEditorBundle.xlf file in the following manner:

    1. Search for the following text:

      <file source-language="en"  
original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
datatype="x-oracle-adf">

    2. Replace with the following text:

      <file source-language="en" target-language="LANG_CODE"
original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
datatype="x-oracle-adf">

      In this text, replace LANG_CODE with the code of the language that you want to localize the form field labels. The following is a sample value for localizing the form field labels in Japanese:

      <file source-language="en" target-language="ja"
original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
datatype="x-oracle-adf">

    3. Search for the application instance code. This procedure shows a sample edit for ACME Webservice application instance. The original code is:

      <trans-unit id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_ACME_USR_COUNTRY__c_description']}">
<source>Country</source>
</target>
</trans-unit>
<trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.ACMEWS.entity.ACMEWSEO.UD_ACME_USR_COUNTRY__c_LABEL">
<source>Country</source>
</target>
</trans-unit>

    4. Open the resource file from the connector package, for example ACMEWS_ja.properties, and get the value of the attribute from the file, for example, global.udf.UD_ACME_USR_COUNTRY=\u56FD.

    5. Replace the original code shown in Step 6.b with the following:

      <trans-unit id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_ACME_USR_COUNTRY__c_description']}">
<source>Country</source>
<target>\u56FD</target>
</trans-unit>
<trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.ACMEWS.entity.ACMEWSEO.UD_ACME_USR_COUNTRY__c_LABEL">
<source>Country</source>
<target>\u56FD</target>
</trans-unit>

    6. Repeat Steps 6.a through 6.d for all attributes of the process form.

    7. Save the file as BizEditorBundle_LANG_CODE.xlf. In this file name, replace LANG_CODE with the code of the language to which you are localizing.

      Sample file name: BizEditorBundle_ja.xlf.

  7. Repackage the ZIP file and import it into MDS.

    See Also:

    Deploying and Undeploying Customizations in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager, for more information about exporting and importing metadata files

  8. Log out of and log in to Oracle Identity Manager.