2 Deploying the Connector

Deploying the connector involves the following steps:

Step 1: Verifying Deployment Requirements
Step 2: Configuring the Target System
Step 3: Copying the Connector Files and External Code Files
Step 4: Configuring the Oracle Identity Manager Server
Step 5: Importing the Connector XML File
Step 6: Configuring Reconciliation
Step 7: Compiling Adapters

If you want to configure the connector for multiple sets of database application tables, then perform the following procedure:

Configuring the Connector for Multiple Sets of Database Applications Table

2.1 Step 1: Verifying Deployment Requirements

The following table lists the deployment requirements for the connector.

Item	Requirement
Oracle Identity Manager	Oracle Identity Manager release 8.5.3 or later
Target systems	The target system can be any one of the following: IBM DB2 UDB version 9.1 Microsoft SQL Server 2000, Microsoft SQL Server 2005 Oracle8i Database, Oracle9i Database, Oracle Database 10g Sybase 12.5.2
External code	`xerces.jar` (the XML parser) `db2jcc.jar` and `db2jcc_license_cu.jar` (for IBM DB2 UDB) `classes12.jar` (for Oracle Database) `jconn2.jar` (for Sybase) `mssqlserver.jar`, `msbase.jar`, and `msutil.jar` (Microsoft SQL Server 2000) `sqljdbc.jar` (Microsoft SQL Server 2005)
Target system user account	If target database tables are to be created, then the user account must have the CONNECT privilege. If existing target database tables are to be used, then the user account must have the following privileges on the tables: CONNECT INSERT DELETE UPDATE SELECT You provide the credentials of this user account while performing the procedure in the "Defining IT Resources" section. If the specified privileges were not assigned to the target system user account, then the "Insufficient Privileges Assigned" message would be displayed.

In addition to the requirements mentioned in the preceding table, you must ensure that the following requirements are addressed:

JDBC connectivity is available to the target database.
The target database application schema is analyzed and the corresponding XML file is available according to the IT resource definition.
The JDBC driver and Xerces classes are available in the CLASSPATH environment variable on the Oracle Identity Manager server.
For secure connectivity to the target database, the required configuration has been performed on the database server.

2.2 Step 2: Configuring the Target System

You do not need to perform any configuration steps on the target system. However, to enable provisioning, reconciliation, or a combination of provisioning and reconciliation, you must modify and use one of the configuration XML files shipped on the installation media. Chapter 3 provides instructions to perform this procedure.

2.3 Step 3: Copying the Connector Files and External Code Files

The connector files to be copied and the directories to which you must copy them are given in the following table.

Note:

The directory paths given in the first column of this table correspond to the location of the connector files in the following directory on the installation media:

Database Servers/Database Application Table

Refer to the "Files and Directories That Comprise the Connector" section for more information about these files.

Files in the Installation Media Directory	Destination Directory
lib/dbadapter.jar	OIM_home/xellerate/JavaTasks OIM_home/xellerate/ScheduleTask
Files in the `resources` directory	OIM_home/xellerate/connectorResources
Files and directories in the `test` directory	OIM_home/xellerate/DBAppTables
Files in the `xml/Xellerate Config` directory	OIM_home/xellerate/XLIntegrations/DBAppTables/xml/Xellerate_Config Note: You must ensure that there are no spaces in this directory path.
Files in the `xml/DB Schema XML` directory	OIM_home/xellerate/XLIntegrations/DBAppTables/xml/DB_Schema

After you copy the connector files listed in the preceding table, copy the following files to the OIM_home/xellerate/ThirdParty directory:

The following table gives the source location of the files to be copied.

Database	File to Be Copied
IBM DB2 UDB	IBMDB2UDB_installation/SQLLIB/java/db2jcc.jar IBMDB2UDB_installation/SQLLIB/java/db2jcc_license_cu.jar Here, `IBMDB2UDB_installation` is the full path of the directory in which you install the database.
Microsoft SQL Server 2000	`mssqlserver.jar`, `msbase.jar`, and `msutil.jar` You can download these JAR files from the Microsoft Web site.
Microsoft SQL Server 2005	`sqljdbc.jar` You can download this JAR file from the Microsoft Web site.
Oracle Database	ORACLE_HOME/ora92/jdbc/lib/classes12.jar Here, `ORACLE_HOME` is the full path of the directory in which you install the database.
Sybase	sybase_installation/jConnect-5_2/classes/jconn2.jar Here, `sybase_installation` is the full path of the directory in which you install the database.

Note:

You must ensure that either the JAR files for SQL Server 2000 or the JAR files for SQL Server 2005 are copied into the ThirdParty directory. If you copy both sets of JAR files, then the connector would not work.

xerces.jar

This file is already present in the OIM_home/xellerate/ext directory. If you are using Oracle Containers for J2EE (OC4J), then you must also copy this file into the following directory:
```
OIM_home/xellerate/ThirdParty
```

After you copy the JAR files to the required directories, it is recommended that you restart Oracle Identity Manager to refresh the classpath.

Note:

While installing Oracle Identity Manager in a clustered environment, you copy the contents of the installation directory to each node of the cluster. Similarly, you must copy the contents of the connectorResources directory and the JAR files to the corresponding directories on each node of the cluster.

2.4 Step 4: Configuring the Oracle Identity Manager Server

Configuring the Oracle Identity Manager server involves the following procedures:

Note:

In a clustered environment, you must perform this step on each node of the cluster.

Changing to the Required Input Locale
Clearing Content Related to Connector Resource Bundles from the Server Cache
Enabling Logging

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

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

While performing the instructions described in the "Step 3: Copying the Connector Files and External Code Files" section, you copy files from the resources directory on the installation media into the OIM_home/xellerate/connectorResources directory. Whenever you add a new resource bundle in 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:

In a command window, change to the OIM_home/xellerate/bin directory.
Note:
You must perform Step 1 before you perform Step 2. An exception is thrown if you run the command described in Step 2 as follows:
```
OIM_home/xellerate/bin/batch_file_name
```
Enter one of the following commands:
- On Microsoft Windows:
```
PurgeCache.bat ConnectorResourceBundle
```
- On UNIX:
```
PurgeCache.sh ConnectorResourceBundle
```
Note:
You can ignore the exception that is thrown when you perform Step 2.

In this command, ConnectorResourceBundle is one of the content categories that you can remove from the server cache. Refer to the following file for information about the other content categories:
```
OIM_home/xellerate/config/xlConfig.xml
```

2.4.3 Enabling Logging

When you enable logging, Oracle Identity Manager automatically stores in a log file information about events that occur during the course of provisioning and reconciliation operations. 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:

ALL

This level enables logging for all events.
DEBUG

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

This level enables logging of informational messages that highlight the progress of the application at coarse-grained level.
WARN

This level enables logging of information about potentially harmful situations.
ERROR

This level enables logging of information about error events that may still allow the application to continue running.
FATAL

This level enables logging of information about very severe error events that could cause the application to stop functioning.
OFF

This level disables logging for all events.

The file in which you set the log level depends on the application server that you use:

BEA WebLogic

To enable logging:
1. Add the following line in the OIM_home/xellerate/config/log.properties file:
```
log4j.logger.DBAdapterLogger=log_level
```
2. In this line, replace log_level with the log level that you want to set.
  
  For example:
```
log4j.logger.DBAdapterLogger=INFO
```
After you enable logging, log information is written to the following file:
```
WebLogic_home/user_projects/domains/domain_name/server_name/server_name.log
```
IBM WebSphere

To enable logging:
1. Add the following line in the OIM_home/xellerate/config/log.properties file:
```
log4j.logger.DBAdapterLogger=log_level
```
2. In this line, replace log_level with the log level that you want to set.
  
  For example:
```
log4j.logger.DBAdapterLogger=INFO
```
After you enable logging, log information is written to the following file:
```
WebSphere_home/AppServer/logs/server_name/startServer.log
```
JBoss Application Server

To enable logging:
1. In the JBoss_home/server/default/conf/log4j.xml file, locate the following lines:
```
<category name="DBAdapterLogger">
   <priority value="log_level"/>
</category>
```
2. In the second XML code line, replace log_level with the log level that you want to set. For example:
```
<category name="DBAdapterLogger">
   <priority value="INFO"/>
</category>
```
After you enable logging, log information is written to the following file:
```
JBoss_home/server/default/log/server.log
```
OC4J

To enable logging:
1. Add the following line in the OIM_home/xellerate/config/log.properties file:
```
log4j.logger.DBAdapterLogger=log_level
```
2. In this line, replace log_level with the log level that you want to set.
  
  For example:
```
log4j.logger.DBAdapterLogger=INFO
```
After you enable logging, log information is written to the following file:
```
OC4J_home/opmn/logs/default_group~home~default_group~1.log
```

2.5 Step 5: Importing the Connector XML File

To import the connector XML file into Oracle Identity Manager:

Open the Oracle Identity Manager Administrative and User Console.
Click the Deployment Management link on the left navigation bar.
Click the Import link under Deployment Management. A dialog box for opening files is displayed.
Locate and open the DBTable_nonTrusted.xml file, which is in the OIM_home/xellerate/XLIntegrations/DBAppTables/xml/Xellerate_Config directory. Details of this XML file are shown on the File Preview page.
Click Add File. The Substitutions page is displayed.
Click Next. The Confirmation page is displayed.
Click Next. The Provide IT Resource Instance Data page for the IT resource is displayed.
Specify values for the parameters of the IT resource. Refer to the table given in the "Defining IT Resources" section for information about the values to be specified.
Click Next. The Provide IT Resource Instance Data page for a new instance of the Database IT resource type is displayed.
Click Skip to specify that you do not want to define another IT resource. The Confirmation page is displayed.

See Also:
If you want to define another IT resource, then refer to Oracle Identity Manager Tools Reference Guide for instructions.
Click View Selections.

The contents of the XML file are displayed on the Import page. You may see a cross-shaped icon along with some nodes. These nodes represent Oracle Identity Manager entities that are redundant. Before you import the connector XML file, you must remove these entities by right-clicking each node and then selecting Remove.
Click Import. The connector file is imported into Oracle Identity Manager.

After you import the connector XML file, proceed to the "Step 6: Configuring Reconciliation" section.

2.5.1 Defining IT Resources

You must specify values for the IT resource parameters listed in the following table.

Parameter	Description
`Database User ID`	Database user ID on the target database Sample value: `xeluser`
`Database Password`	Database user password on the target database
`Database URL`	JDBC URL for the target database Format and sample values for Oracle Database: jdbc:oracle:thin:@host:port:sid jdbc:oracle:thin@145.125.23.26:1521:cust_db jdbc:oracle:oci:userid/password@host:port:sid jdbc:oracle:oci:scott/tiger@145.125.23.26:1521:cust_db Format and sample values for SQL Server 2000: jdbc:microsoft:sqlserver://Target_host:1433;DatabaseName=databaseName jdbc:microsoft:sqlserver://172.21.106.76:1433;DatabaseName=master Format and sample values for SQL Server 2005: jdbc:sqlserver://Target_host:1433;database=databaseName jdbc:sqlserver://172.21.106.76:1433;database=master Format and sample values for IBM DB2 UDB: jdbc:db2://Target_host:50000/DatabaseName jdbc:db2://172.21.106.76:50000/master Note: Use the IP address, not the computer name or the host name in the URL. The port number used in the example is the default port number. It may change depending on the port on which your application is running. Format and sample values for Sybase: jdbc:sybase:Tds:host:port/database jdbc:sybase:Tds:123.432.154.12:2639/sales
`Database Driver`	JDBC driver class Value for Oracle Database: oracle.jdbc.driver.OracleDriver Value for SQL Server 2000: com.microsoft.jdbc.sqlserver.SQLServerDriver Value for SQL Server 2005: com.microsoft.sqlserver.jdbc.SQLServerDriver Value for IBM DB2 UDB: com.ibm.db2.jcc.DB2Driver Value for Sybase: com.sybase.jdbc3.jdbc.SybDriver
`Application Name`	Target application name Sample value: `myapplication`
`Configuration XML Path`	Directory path and name of the configuration XML file Sample value: OIM_home/xellerate/XLIntegrations/DBAppTables/xml/DB_Schema/OraApp2.xml Note: You must ensure that the path that you specify does not contain spaces. See Also: The "Files and Directories That Comprise the Connector" section for information about the various configuration XML files that are available in the connector installation media directory. Based on the description of each configuration XML file, select an XML file that meets your requirements.
`Reconciliation Timestamp`	Last create/update reconciliation time This value is updated by the reconciliation adapter. You need not manually provide any data.

After you specify values for these IT resource parameters, proceed to Step 9 of the procedure to import connector XML files.

2.6 Step 6: Configuring Reconciliation

As mentioned earlier in this guide, reconciliation involves duplicating in Oracle Identity Manager the creation of and modifications to user accounts on the target system. This section discusses the following topics related to configuring reconciliation:

Configuring Trusted Source Reconciliation
Configuring the Reconciliation Scheduled Tasks

2.6.1 Configuring Trusted Source Reconciliation

While configuring the connector, the target system can be designated as a trusted source or a target resource. If you designate the target system as a trusted source, then both newly created and modified user accounts are reconciled in Oracle Identity Manager. If you designate the target system as a target resource, then only modified user accounts are reconciled in Oracle Identity Manager.

Configuring trusted source reconciliation involves the following steps:

Note:

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

Import the XML file for trusted source reconciliation, DBTable_trusted.xml, by using the Deployment Manager. This section describes the procedure to import the XML file.

Note:
Only one target system can be designated as a trusted source. If you import the DBTable_trusted.xml file while you have another trusted source configured, then both connector reconciliations would stop working.
Specify values for the attributes of the dbTableReconcile_trustedmode scheduled task. This procedure is described later in this guide.

To configure trusted source reconciliation:

Open the Oracle Identity Manager Administrative and User Console.
Click the Deployment Management link on the left navigation bar.
Click the Import link under Deployment Management. A dialog box for opening files is displayed.
Locate and open the DBTable_trusted.xml file, which is in the OIM_home/xellerate/XLIntegrations/DBAppTables/xml/Xellerate_Config directory. Details of this XML file are shown on the File Preview page.
Click Add File. The Substitutions page is displayed.
Click Next. The Confirmation page is displayed.
Click Import.
In the message that is displayed, click Import to confirm that you want to import the XML file and then click OK.

2.6.2 Configuring the Reconciliation Scheduled Tasks

To create the reconciliation scheduled tasks:

Open the Oracle Identity Manager Design Console .
Expand the Xellerate Administration folder.
Select Task Scheduler.
Click Find. The details of the predefined scheduled task are displayed.
Enter a number in the Max Retries field. This number represents the number of times Oracle Identity Manager must attempt to complete the task before assigning the ERROR status to the task.
Ensure that the Disabled and Stop Execution check boxes are not selected.
In the Start region, double-click the Start Time field. From the date-time editor that is displayed, select the date and time at which you want the task to run.
In the Interval region, set the following schedule parameters:
- To set the task to run on a recurring basis, select the Daily, Weekly, Recurring Intervals, Monthly, or Yearly option.
  
  If you select the Recurring Intervals option, then you must also specify the time interval at which you want the task to run on a recurring basis.
- To set the task to run only once, select the Once option.
Provide values for the attributes of the scheduled task. Refer to the "Specifying Values for the Scheduled Task Attributes" section for information about the values to be specified.

See Also:
Oracle Identity Manager Design Console Guide for information about adding and removing task attributes
Click Save. The scheduled task is created. The INACTIVE status is displayed in the Status field, because the task is not currently running. The task is run at the date and time that you set in Step 7.

After you define the scheduled task, proceed to the "Step 7: Compiling Adapters" section.

2.6.2.1 Specifying Values for the Scheduled Task Attributes

Depending on whether you want to implement trusted or nontrusted soured reconciliation, you must specify values for the attributes of one of the following user reconciliation scheduled tasks:

dbTableReconcile_trustedmode (Scheduled task for trusted source reconciliation)
dbTableReconcile (Scheduled task for nontrusted source reconciliation)

The following table describes the attributes of both scheduled tasks.

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 were left empty, then reconciliation would not be performed.

Attribute	Description
`resource`	Name of the IT resource for which the reconciliation process is to be run Sample value: `Oracle Application2`
`application`	Name of the target database application that should be reconciled Sample value: `Oracle Application2`
`objectName`	Resource object name of the connector Sample value: `Database Application Resource`
`isTrusted`	Specifies whether or not reconciliation is to be carried out in trusted mode For trusted source reconciliation, set the value of this attribute to `Yes`. For nontrusted source reconciliation, set the value of this attribute to `No`.
`isFilter`	Specifies whether or not partial reconciliation is to be applied The value can be `Yes` or `No`.
`record_count`	Specifies the number of records to be reconciled during trial reconciliation The value can be any integer. If you do not want to use this feature, then specify `nodata.`

After you specify values for these scheduled task attributes, proceed to Step 10 of the procedure to create scheduled tasks.

2.7 Step 7: Compiling Adapters

Note:

Configuring provisioning involves modifying the configuration XML file for provisioning and compiling adapters. This section describes the procedure to compile adapters. Refer to Chapter 3 for information about modifying the configuration XML file for provisioning.

The following adapters are imported into Oracle Identity Manager when you import the XML connector file:

DBRES Create User
DBRES Update First Name
DBRES Update Last Name
DBRES Update Password
DBRES Update Status
DBRES Update Title
DBRES Update Department
DBRES Update Email
DBRES Update Communication Language
DBRES Update Logon Language
DBRES Update Time Zone
DBRES Update Date Format
DBRES Update Telephone Number
DBRES Update Decimal Notation
DBRES Delete User
DBRES Update Role
DBRES Update Group
DB Transfer Value

You must compile these adapters before they can be used in provisioning operations.

To compile adapters by using the Adapter Manager form:

Open the Adapter Manager form.
To compile all the adapters that you import into the current database, select Compile All.

To compile multiple (but not all) adapters, select the adapters you want to compile. Then, select Compile Selected.

Note:
Click Compile Previously Failed to recompile only those adapters that were not compiled successfully. Such adapters do not have an OK compilation status.
Click Start. Oracle Identity Manager compiles the selected adapters.
If Oracle Identity Manager is installed in a clustered environment, then copy the compiled adapters from the OIM_home/xellerate/Adapter directory to the same directory on each of the other nodes of the cluster. If required, overwrite the adapter files on the other nodes.

If you want to compile one adapter at a time, then use the Adapter Factory form.

2.8 Configuring the Connector for Multiple Sets of Database Applications Table

Note:

Perform this procedure only if you want to configure the connector for multiple database application tables. Refer to Oracle Identity Manager Design Console Guide for detailed instructions on performing each step of this procedure.

To configure the connector for multiple sets of database application tables:

Create and configure one IT resource for each set of database application tables.

The IT Resources form is in the Resource Management folder. The Oracle Application2 IT resource is created when you import the connector XML file. You can use this IT resource as the template for creating the remaining IT resources, of the same resource type.
Configure reconciliation for each set of database application tables. Refer to the "Step 6: Configuring Reconciliation" section for instructions. Note that only the value of the resource attribute needs to be changed for each reconciliation scheduled task.

When you use the Administrative and User Console to perform provisioning, you can specify the IT resource corresponding to the set of database application tables to which you want to provision the user.