3 Configuring the Connector

After you deploy the connector, you must configure it to meet your requirements. This chapter discusses the following connector configuration procedures:

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
Configuring the Connector for Multiple Installations of the Target System

Configuring Reconciliation

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

Partial Reconciliation
Specifying the Number of Records to Be Reconciled
Configuring Trusted Source Reconciliation
Configuring the Reconciliation Scheduled Tasks
Adding Custom Attributes for Reconciliation
Encrypting a New Oracle Identity Manager Password

Partial 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 do this by creating filters for the reconciliation module.

Creating a filter involves specifying a value for a target system attribute, which will be used in the query SELECT criteria to retrieve the records to be reconciled. You can specify values for any one or a combination of the following target system attributes:

LastName
DeptId
Postal

If you want to use multiple target system attributes to filter records, then you must also specify the logical operator (AND or OR) that you want to apply to the combination of target system attributes that you select.

While deploying the connector, follow the instructions in the "Specifying Values for the Scheduled Task Attributes" section to specify values for these attributes and the logical operator that you want to apply.

Specifying the Number of Records to Be Reconciled

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 specify the number of records to be reconciled. To do this, you use the NoOfRecordsToBeReconciled scheduled task attribute.

You specify a value for the NoOfRecordsToBeReconciled attribute by following the instructions described in the "Specifying Values for the Scheduled Task Attributes" section.

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.

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, adpPSFT_XellerateUser_RECON_DM.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 adpPSFT_XellerateUser_RECON_DM.xml file while you have another trusted source configured, then both connector reconciliations would stop working.
Specify values for the attributes of the PSFTHRTrustedUserRecon 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 locating files is displayed.
Locate and open the adpPSFT_XellerateUser_RECON_DM.xml file, which is in the OIM_home/xlclient 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.

Configuring the Reconciliation Scheduled Tasks

When you perform the procedure described in the "Step 6: Importing the Connector XML File" section, the scheduled tasks for lookup fields, trusted source user, and nontrusted user reconciliations are automatically created in Oracle Identity Manager. To configure these 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 tasks 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.
To set the task to run only once, select the Once option in the Interval region.
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.
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.
Repeat Steps 5 through 10 to create the second scheduled task.

After you create the scheduled task, proceed to the "Adding Custom Attributes for Reconciliation" section.

Specifying Values for the Scheduled Task Attributes

The user reconciliation scheduled task has been divided into two scheduled tasks, one each for trusted employee reconciliation and nontrusted employee reconciliation.

Employee Reconciliation Scheduled Tasks

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

PSFTHRTrustedUserRecon (Scheduled task for trusted source reconciliation)
PSFTHRNonTrustedUserRecon (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 Name	Description	Sample Value
`FolderPath`	Directory path where employee reconciliation files generated by PeopleSoft Employee Reconciliation are stored	`C:/PSFTHR/UserRecon`
`TargetSystem`	Name of the resource object	`PSFT_HR_RO`
`IsTrusted`	Specifies whether or not reconciliation is to be performed 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`.
`XellerateOrganization`	Default name for the Oracle Identity Manager organization This value is used to create the Xellerate User in trusted source reconciliation mode. Note: This attribute is specific to the scheduled task for trusted source reconciliation.	`Xellerate Users`
`NoOfRecordsToBeReconciled`	Specifies the number of records to be reconciled Default value: `all`	Any integer value greater than zero
`Lastname`	Specifies the Lastname attribute value for which you want to perform reconciliation During reconciliation, only those target system records that contain the Lastname value you specify are reconciled.	`Nodata`
`Postal`	Specifies the `Postal` attribute value for which you want to perform reconciliation During reconciliation, only those target system records that contain the `Postal` value you specify are reconciled.	`Nodata`
`DeptId`	Specifies the `DeptId` attribute value for which you want to perform reconciliation During reconciliation, only those target system records that contain the `DeptId` value you specify are reconciled.	`Nodata`
`Operator`	Specifies the `Operator` attribute value for which you want to perform reconciliation During reconciliation, only those target system records that contain the `Operator` value you specify are reconciled.	`Nodata`

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

Adding Custom Attributes for Reconciliation

Note:

In this section, the term "attribute" refers to the identity data fields that store user data.

Standard change-based reconciliation involves the reconciliation of predefined attributes. If required, you can add custom attributes to the list of attributes that are reconciled.

Note:

Before you can add custom attributes, you must complete the connector deployment procedure described in Chapter 2.

The procedure to add a custom attribute for reconciliation depends on the release of PeopleTools that you are using:

Adding a Custom Attribute for Reconciliation on PeopleTools 8.22
Adding a Custom Attribute for Reconciliation on PeopleTools 8.45 Through 8.47

Adding a Custom Attribute for Reconciliation on PeopleTools 8.22

To add a custom attribute for reconciliation on PeopleTools 8.22:

In PeopleSoft Application Designer:
1. Select Open from the File menu. The Open Definition dialog box is displayed.
2. Select Application Engine program from the Definition list, enter BLKPRCS_HR in the Name Selection Criteria field, and then click Enter. The details of the BLKPRCS_HR Application Engine program are displayed.
3. Click the plus sign (+) that is displayed before the MAIN section in the Application Engine Program under which the Populate step is listed.
4. Double-click the PeopleCode action. A new PeopleCode window is displayed.
5. In the PeopleCode window, copy the code from the OIM_home/xellerate/Scripts/HRMSBulkRecon.txt file. A sample directory path for the output file is given in this code. Change the sample directory path to a directory path on the PeopleSoft Employee Reconciliation server.
6. Save the Application Engine program, and then close the window.
7. To run the Application Engine program, follow the steps described in the "Running the Application Engine Program on PeopleTools 8.22" section.
Make the required changes in the PeopleCode given in the HRMSBulkRecon.txt file. This file is in the OIM_home/xellerate/Scripts directory. The required changes are as follows:
1. Modify the following line in the file:
```
&hdr = "EMPLID,LASTNAME,FIRSTNAME,SEX,POSTAL,CITY,SSN,PHONE,BIRTHDATE,COUNTRY,ADDRESS,STATE,HIRE_DATE,DEPTID,JOBCODE";
```
  For example, to add the LOCATION column, add LOCATION at the end of the list of the list of column names as follows:
```
&hdr = "EMPLID,LASTNAME,FIRSTNAME,SEX,POSTAL,CITY,SSN,PHONE,BIRTHDATE,COUNTRY,ADDRESS,STATE,HIRE_DATE,DEPTID,JOBCODE,LOCATION";
```
2. At the end of the SQL statements section, edit the SQL statement to retrieve the column values for the new attribute and store the values in local variables.
  
  For example, suppose you want to add the job location attribute, LOCATION, to the list of attributes that are reconciled. Then, performing this step involves editing the SQL statement as follows, so that it retrieves the values of the LOCATION column from the JOB table:
```
SQLExec("select DEPTID, JOBCODE, LOCATION from ps_job a where emplid =:1 and effdt=(select max(effdt) from ps_job b where a.emplid=b.emplid and effseq =(select max(effseq) from ps_job c where b.emplid = c.emplid and b.effdt=c.effdt))", &empid, &deptid, &jobcd, &location); 
```
3. Add the required lines at the end of the block of code for adding data to the XML message. For example, to add the LOCATION column to the JOB tag, add the lines highlighted in bold in the following code sample:
```
/* FOR JOB RECORD */
&MSG_ROWSET.GetRow(1).JOB.JOBCODE.Value = &jobcd;
&MSG_ROWSET.GetRow(1).JOB.DEPTID.Value = &deptid;
&MSG_ROWSET.GetRow(1).JOB.LOCATION.Value = &location;
```
To extract the contents of the peopleSoftApp.war file into a temporary directory, enter the following command:
```
jar –xvf peopleSoftApp.war
```
Copies of this file are in the application server deployment directory and the OIM_home/xellerate/webapp directory.
In the attributemap.properties file, add the XPath (key-value entry) of the custom attribute. For example, you can add the following XPath for the LOCATION attribute:
```
Users.LOCATION=//Transaction/DEPT_TBL/LOCATION
```
Delete the existing peopleSoftApp.war file from the temporary directory into which you extract it, and then enter the following command to re-create the file:
```
jar –cvf peopleSoftApp.war .
```
Delete the old version of the peopleSoftApp.war file from the application server deployment directory and the OIM_home/xellerate/webapp directory.
Copy the newly created peopleSoftApp.war file into the application server deployment directory and the OIM_home/xellerate/webapp directory.
In the Oracle Identity Manager Design Console, make the required changes as follows:

See:
Oracle Identity Manager Design Console for detailed instructions on performing the following steps
1. Add a column corresponding to the new attribute in the User Defined process form, UD_PSFT_HR. For the example described earlier, you can add the UD_PSFT_HR_LOCATION column.
2. Add a reconciliation field corresponding to the new attribute in the resource object, PSFT_HR_RO. For the example described earlier, you can add the Users.LOCATION reconciliation field.
3. Modify the PSFT_HR Process process definition to include the mapping between the newly added attribute and the corresponding reconciliation field. For the example described earlier, the mapping is as follows:
```
Users.LOCATION = UD_PSFT_HR_LOCATION
```
4. Modify the attributemapping_recon.properties file, which is in the OIM_home/xellerate/XLIntegrations/PSFTHR/config directory.
  
  You can also add new attributes in this file. The format that you must use is as follows:
```
TargetAttribute=Users.OimAttributeName
```
  For example:
```
LOCATION=Users.LOCATION
```
  In this example, LOCATION is the reconciliation field and also the equivalent target system attribute. As a standard, the prefix "Users." is added at the start of all reconciliation field names.
Restart the Oracle Identity Manager server and client.

Adding a Custom Attribute for Reconciliation on PeopleTools 8.45 Through 8.47

To add a custom attribute for reconciliation on PeopleTools 8.45 through 8.47:

Make the required changes in the PeopleCode given in the HRMSCBRecon.txt file. This file is in the OIM_home/xellerate/Scripts directory. The required changes are as follows:
1. At the end of the SQL statements section, add a SQL statement to retrieve the column values for the new attribute and store the values in local variables.
  
  For example, suppose you want to add the department location attribute, LOCATION, to the list of attributes that are reconciled. Then, performing this step involves adding the following SQL statement to retrieve the values of the LOCATION column from the PS_DEPT_TBL table:
```
SQLExec("SELECT DESCR, LOCATION FROM PS_DEPT_TBL WHERE DEPTID=:1", &deptid, &deptname, &location);
```
2. Add the required lines at the end of the block of code for adding data to the XML message. For example, to add the LOCATION column to the DEPT_TBL tag, add the lines highlighted in bold in the following code sample:
```
&recnode = &fieldtypenode.AddElement("DEPT_TBL");
&recnode.AddAttribute("class", "R");
&fields = &recnode.AddElement("DEPTNAME");
&fields.AddAttribute("type", "CHAR");
&fields = &recnode.AddElement("LOCATION");
&fields.AddAttribute("type", "CHAR");
```
3. Add the required lines at the end of the block of code for adding data to the XML message. For example, to add the LOCATION column to the DEPT_TBL tag, add the lines highlighted in bold in the following code sample:
```
&datarecnode = &transnode.AddElement("DEPT_TBL");
&datarecnode.AddAttribute("class", "R");
&datafldnode = &datarecnode.AddElement("DEPTNAME");
&textnode = &datafldnode.AddText(&deptname);
&datafldnode = &datarecnode.AddElement("LOCATION");
&textnode = &datafldnode.AddText(&location);
```
In PeopleSoft Application Designer, copy the contents of the HRMSCBRecon.txt file into the savePostChange event for the PERSONAL_DATA component.
To extract the contents of the peopleSoftApp.war file into a temporary directory, enter the following command:
```
jar –xvf peopleSoftApp.war
```
Copies of this file are in the application server deployment directory and the OIM_home/xellerate/webapp directory.
In the attributemap.properties file, add the XPath (key-value entry) of the custom attribute. For example, you can add the following XPath for the LOCATION attribute:
```
Users.LOCATION=//Transaction/DEPT_TBL/LOCATION
```
Delete the existing peopleSoftApp.war file from the temporary directory into which you extract it, and then enter the following command to re-create the file:
```
jar –cvf peopleSoftApp.war .
```
Delete the old version of the peopleSoftApp.war file from the application server deployment directory and the OIM_home/xellerate/webapp directory.
Copy the newly created peopleSoftApp.war file into the application server deployment directory and the OIM_home/xellerate/webapp directory.
In the Oracle Identity Manager Design Console, make the required changes as follows:

See:
Oracle Identity Manager Design Console for detailed instructions on performing the following steps
1. Add a column corresponding to the new attribute in the User Defined process form, UD_PSFT_HR. For the example described earlier, you can add the UD_PSFT_HR_LOCATION column.
2. Add a reconciliation field corresponding to the new attribute in the resource object, PSFT_HR_RO. For the example described earlier, you can add the Users.LOCATION reconciliation field.
3. Modify the PSFT_HR Process process definition to include the mapping between the newly added attribute and the corresponding reconciliation field. For the example described earlier, the mapping is as follows:
```
Users.LOCATION = UD_PSFT_HR_LOCATION
```
4. Modify the attributemapping_recon.properties file, which is in the OIM_home/xellerate/XLIntegrations/PSFTHR/config directory.
  
  You can also add new attributes in this file. The format that you must use is as follows:
```
TargetAttribute=Users.OimAttributeName
```
  For example:
```
LOCATION=Users.LOCATION
```
  In this example, LOCATION is the reconciliation field and also the equivalent target system attribute. As a standard, the prefix "Users." is added at the start of all reconciliation field names.
Restart the Oracle Identity Manager server and client.

Encrypting a New Oracle Identity Manager Password

If the password of the Oracle Identity Manager administrator is different from the default password, then you must encrypt the Oracle Identity Manager password as follows:

Note:

The default administrator user ID is xelsysadm.

On the Oracle Identity Manager server, open a command window.
In the command window, change to the OIM_home/xellerate/ScheduleTask directory.
Enter the following command:
```
java -classpath xlPSFTHRRecon.jar  \
com.thortech.xl.Integration.peoplesoft.util.tcUtilEncryption -e \
OIM_plaintext_password
```
In this command, OIM_plaintext_password is the new Oracle Identity Manager administrator password that you want to encrypt.

The encrypted password is displayed in the command window.
Copy the encrypted password into the xlsession.properties file. This file is compressed in the OIM_home/xlclient/lib/peopleSoftApp.war file.
Delete the peopleSoftApp.war file from the temporary directory in which you extract it, and then use the following command to re-create the file:
```
jar –cvf peopleSoftApp.war .
```
Ensure that the old version of the peopleSoftApp.war file is removed from the application server (JBoss Application Server, IBM WebSphere, BEA WebLogic, or OC4J) deployment directory and the OIM_home/xellerate/webapp directory.
Copy the newly created peopleSoftApp.war file into the application server (JBoss, IBM WebSphere, BEA WebLogic, or OC4J) deployment directory and the OIM_home/xellerate/webapp directory.
Restart the Oracle Identity Manager server and client.

Configuring the Connector for Multiple Installations of the Target System

Note:

Perform this procedure only if you want to configure the connector for multiple installations of PeopleSoft Employee Reconciliation.

You may want to configure the connector for multiple installations of PeopleSoft Employee Reconciliation. The following example illustrates this requirement:

The Tokyo, London, and New York offices of Acme Multinational Inc. have their own installations of PeopleSoft Employee Reconciliation. The company has recently installed Oracle Identity Manager, and they want to configure Oracle Identity Manager to link all the installations of PeopleSoft Employee Reconciliation.

To meet the requirement posed by such a scenario, you must configure the connector for multiple installations of PeopleSoft Employee Reconciliation.

To configure the connector for multiple installations of the target system: