10.3 Managing Synchronization Between Oracle Human Resources and Oracle Internet Directory

This section contains these topics:

Task 1: Configure a Directory Integration Profile for the Oracle Human Resources Connector
Task 2: Configure the List of Attributes to Be Synchronized with Oracle Internet Directory
Task 3: Configure Mapping Rules for the Oracle Human Resources Connector
Task 4: Prepare for Synchronization from Oracle Human Resources to Oracle Internet Directory

10.3.1 Task 1: Configure a Directory Integration Profile for the Oracle Human Resources Connector

To configure the prepackaged integration profile that is installed with the Oracle Human Resources connector, you can use either the Oracle Directory Integration and Provisioning Server Administration tool or the Directory Integration and Provisioning Assistant. For information on the Oracle Directory Integration and Provisioning Server Administration tool, see Chapter 7, "Administration of Directory Synchronization". For information on the Directory Integration and Provisioning Assistant, see the dipassistant section in the Oracle Directory Integration and Provisioning tools chapter of the Oracle Directory Integration and Provisioning tools chapter in the Oracle Identity Management User Reference.

For some of the parameters in the prepackaged integration profile, you must specify values specific to integration with the Human Resources Connector. The parameters specific to the Human Resources Connector are listed in Table 10-3.

Table 10-3 Attributes Specific to Oracle Human Resources Connector Integration Profile

Attribute	Description
Profile Name (`orclODIPAgentName`)	Unique name by which the connector is identified in the system, used as an RDN component of the DN that identifies the integration profile. The name can contain only alpha-numeric characters. This attribute is mandatory and not modifiable. The default name is `OracleHRAgent`.
Synchronization Mode (`ModeorclODIPSynchronizationMode`)	The direction of synchronization between Oracle Internet Directory and a connected directory. `IMPORT` indicates importing changes from a connected directory to Oracle Internet Directory. `EXPORT` indicates exporting changes from Oracle Internet Directory to a connected directory. The default is `IMPORT`. This attribute is mandatory and modifiable. Note: In Oracle Internet Directory 10g Release 2 (10.1.2), only import operations for Oracle Human Resources are supported.
Execution Information
Agent Execution Command (`orclODIPAgentExeCommand`)	Connector executable name and argument list used by the directory integration and provisioning server to execute the connector. This attribute is mandatory and modifiable. The default is: odihragent OracleHRAgent connect=hrdb \ login=%orclodipConDirAccessAccount \ pass=%orclodipConDirAccessPassword \ date=%orclODIPLastSuccessfulExecutionTime \ You must set the value in the argument `connect=hrdb` to the connect string of the Oracle Human Resources system database.
Connected Directory Account (`orclodipConDirAccessAccount`)	Valid user account in the connected directory to be used by the connector for synchronization. For the Human Resources Agent, it is a valid user identifier in the Oracle Human Resources database. See Also: Chapter 10, "Synchronization with Oracle Human Resources" for typical usage of passing it in the command-line
Additional Config Info (`orclODIPAgentConfigInfo`)	Any configuration information that you want the connector to store in Oracle Internet Directory. It is passed by the directory integration and provisioning server to the connector at time of connector invocation. The information is stored as an attribute and the directory integration and provisioning server does not have any knowledge of its content. The value stored in this attribute represents (for Oracle Human Resources connector) all attributes that need to be synchronized from Oracle Human Resources. See Also: "Task 2: Configure the List of Attributes to Be Synchronized with Oracle Internet Directory" This attribute is mandatory for the Oracle Human Resources connector, and modifiable by editing the configuration file and uploading it again into the profile. You cannot modify this attribute by using the Oracle Directory Integration and Provisioning Server Administration tool.
Connected Directory URL	The host and port details of the connected directory. It must be entered in this format: `host`:`port`:`sid`.
Interface Type (`orclODIPInterfaceType`)	The interface used for data transfer. Since it is in the form of a tagged file, it is set to `TAGGED`. Note: You should not modify this attribute for Oracle Human Resources Profile.
Mapping Information
Mapping Rules (`orclODIPAttributeMappingRules`)	Attribute for storing the mapping rules. Store the mapping rules in a file by using the Directory Integration and Provisioning Assistant. This attribute is mandatory for Oracle Human Resources and is modifiable. See Also: "Mapping Rules and Formats" "Configuring Mapping Rules"
Connected Directory Matching Filter (`orclODIPConDirMatchingFilter`)	This is not used in Oracle Human Resources connectivity.
OID Matching Filter (`orclODIPOIDMatchingFilter`)	This attribute names an LDAP filter that is used to search for a target entry in Oracle Internet Directory. The Oracle directory integration and provisioning server uses this filter to find out what kind of LDAP operation it needs to do to synchronize. It is of the form `employeenumber=%` It is optional and modifiable.
Status Information
OID Last Applied Change Number (`orcllastappliedChangenumber`)	This attribute, standard for all EXPORT profiles, does not apply to Oracle Human Resources synchronization.
Last Applied Change Number (`orclODIPConDirLastAppliedChgNum`)	This attribute, standard for all profiles, does not apply to the Oracle Human Resources synchronization.

10.3.2 Task 2: Configure the List of Attributes to Be Synchronized with Oracle Internet Directory

The default Oracle Human Resources profile provides a default list of attributes to be synchronized from Oracle Human Resources to Oracle Internet Directory. You can customize this list, adding attributes to it or removing attributes from it.

The default attribute list is stored in the orclodipAgentConfigInfo attribute as part of the integration profile.The configuration information is also available in the file oraclehragent.cfg.master that is located under the $ORACLE_HOME/ldap/odi/conf directory.

Note:

Do not modify the oraclehragent.cfg.master file; it serves as a backup.

The columns in the default list of Oracle Human Resources attributes are:

Table 10-4 Oracle Human Resources Attributes Synchronized with Oracle Internet Directory by Default

Column	Description
ATTRNAME	The output tag generated in the output data file
COLUMN_NAME	Database column name from where to obtain this value
TABLE_NAME	Database table name from where to obtain this value
FORMAT	The column data type of this attribute. (ASCII, NUMBER, DATE)
MAP	Indicator of whether to extract this attribute from Oracle Human Resources or not. A value of `Y` indicates that it will be extracted and a value of `N` indicates that it will not be.

The oraclehragent.cfg.master file contains the following:

ATTRNAME:COLUMN_NAME:TABLE_NAME:FORMAT:MAP
PersonId:person_id:PER:NUMBER:Y
PersonType:person_type_id:PER:NUMBER:Y
PersonTypeName:system_person_type:PPT:ASCII:Y
LastName:last_name:PER:ASCII:Y
StartDate:start_date:PER:DATE:Y
BirthDate:date_of_birth:PER:DATE:Y
EMail:email_address:PER:ASCII:Y
EmployeeNumber:employee_number:PER:NUMBER:Y
FirstName:first_name:PER:ASCII:Y
FullName:full_name:PER:ASCII:Y
knownas:known_as:PER:ASCII:Y
MaritalStatus:marital_status:PER:ASCII:Y
middleName:middle_names:PER:ASCII:Y
country:country:PA:ASCII:Y
socialsecurity:national_identifier:PER:ASCII:Y
Sex:sex:PER:ASCII:Y
Title:title:PER:ASCII:Y
suffix:suffix:PER:ASCII:Y
street1:address_line1:PA:ASCII:Y
zip:postal_code:PA:ASCII:Y
Address1:address_line1:PA:ASCII:Y
Address2:address_line2:PA:ASCII:Y
Address3:address_line3:PA:ASCII:Y
TelephoneNumber1:telephone_number_1:PA:ASCII:Y
TelephoneNumber2:telephone_number_2:PA:ASCII:Y
TelephoneNumber3:telephone_number_3:PA:ASCII:Y
town_or_city:town_or_city:PA:ASCII:Y
state:region_2:PA:ASCII:Y
Start_date:effective_start_date:PER:DATE:Y
End_date:effective_end_date:PER:DATE:Y
per_updateTime:last_update_date:PER:DATE:Y
pa_updateTime:last_update_date:PA:DATE:Y

10.3.2.1 Modifying Additional Oracle Human Resources Attributes for Synchronization

To include additional Oracle Human Resources attributes for synchronization, follow these steps:

Copy the oraclehragent.cfg.master file and name it anything other than Agent_Name.cfg. This is because the directory integration and provisioning server generates a configuration file with that name, using it to pass the configuration information to the Oracle Human Resources agent at run time.

Include an additional Oracle Human Resources attribute for synchronization by adding a record to this file. To do this, you need this information:

Table name in the database from which the attribute value is to be extracted. These tables are listed in Table 10-1. The file uses abbreviated names for the four tables used in the synchronization.
Column name in the table
Column datatype. Valid values are ASCII, NUMBER, DATE

You also need to assign an attribute name to the column name. This acts as the output tag that is used to identify this attribute in the output file. This tag is used in the mapping rules to establish a rule between the Oracle Human Resources attribute and the Oracle Internet Directory attribute.

You must also ensure that the map column—that is, the last column in the record—is set to the value Y.

Note:

If you add a new attribute in the attribute list, then you must define a corresponding rule in the orclodipAttributeMappingRules attribute. Otherwise the Oracle Human Resources attribute is not synchronized with the Oracle Internet Directory even if it is being extracted by the Oracle Human Resources connector.

10.3.2.2 Excluding Oracle Human Resources Attributes from Synchronization

To exclude an Oracle Human Resources attribute that is currently being synchronized with Oracle Internet Directory:

Copy the oraclehragent.cfg.master file and name it anything other than Agent_Name.cfg. This is because the directory integration and provisioning server generates a configuration file with that name, using it to pass the configuration information to the Oracle Human Resources connector at run time.
Do one of the following:
- Comment out the corresponding record in the attribute list by putting a hash sign (#) in front of it
- Set the value of the column map to N

10.3.2.3 Configuring a SQL SELECT Statement in the Configuration File to Support Complex Selection Criteria

If the previous supporting attribute configuration is not sufficient to extract data from the Oracle Human Resources database, then the Oracle Human Resources agent also supports execution of a pre configured SQL SELECT statement in the configuration file. There is a TAG to indicate this in the configuration file, namely, a [SELECT] in the configuration file.

The following example shows a sample select statement to retrieve some information from the Oracle Human Resources database. Note that only the SQL statement should follow the [SELECT] Tag. The BINDVAR Bind Variable needs to be there to retrieve incremental changes. The substitutes passes this value (the time stamp) to the Oracle Human Resources connector.

All the columns expressions retrieved in the SELECT statement must have column names—for example, REPLACE(ppx.email_address),'@ORACLE.COM','') is retrieved as EMAILADDRESS. The Oracle Human Resources connector writes out EMAILADDRESS as the attribute name in the output file with its value as the result of the expression REPLACE(ppx.email_address),'@ORACLE.COM'''.

The following is an example of a a SELECT statement in a configuration file.

[SELECT]

SELECT
     REPLACE(ppx.email_address),'@ORACLE.COM',''), EMAILADDRESS ,
     UPPER(ppx.attribute26) GUID,
     UPPER(ppx.last_name) LASTNAME,
     UPPER(ppx.first_name) FIRSTNAME,
     UPPER(ppx.middle_names) MIDDLENAME,
     UPPER(ppx.known_as) NICKNAME,
     UPPER(SUBSTR(ppx.date_of_birth,1,6)) BIRTHDAY,
     UPPER(ppx.employee_number) EMPLOYEEID,
     UPPER(ppos.date_start)  HIREDATE,
FROM
   hr_organization_units hou,
   per_people_x ppx,
   per_people_x mppx,
   per_periods_of_service ppos
  WHERE
      pax.supervisor_id  = mppx.person_id(+)
  AND pax.organization_id = hou.organization_id(+)
  AND ppx.person_id = ppos.person_id
  AND ppx.person_id = pax.person_id
  AND ppos.actual_termination_date IS NULL
  AND UPPER(ppx.current_employee_flag) = 'Y'
  AND ppx.last_update_date >= (:BINDVAR,'YYYYMMDDHH24MISS')

10.3.3 Task 3: Configure Mapping Rules for the Oracle Human Resources Connector

Attribute mapping rules govern how the directory integration and provisioning server converts attributes between Oracle Human Resources and Oracle Internet Directory. You can customize the mapping rules you want the directory integration and provisioning server to use.

The Oracle Human Resources agent profile has a default mapping file with a set of mapping rules in the attribute orclodipAttributeMappingRules. This information is also stored in the file named oraclehragent.map.master located under the $ORACLE_HOME/ldap/odi/conf directory.

Note:

Do not modify the oraclehragent.map.master file. It serves as a backup.

10.3.4 Task 4: Prepare for Synchronization from Oracle Human Resources to Oracle Internet Directory

This section explains how to set up synchronization from Oracle Human Resources to Oracle Internet Directory.

10.3.4.1 Preparing for Synchronization

To prepare for synchronization between Oracle Human Resources and Oracle Internet Directory, follow these steps:

Ensure that the Oracle Human Resources connector and the directory integration and provisioning server are installed on the host from which you want to run the Oracle Human Resources connector.

See Also:
The file install.txt and the Release Notes for Oracle Internet Directory 10g Release 2 (10.1.2) for more details

Ensure that you have the information for accessing the Oracle Human Resources system, including:
- Connect string to the Oracle Human Resources system database
- Access account
- Password
Configure an integration profile for the Oracle Human Resources connector, as described in "Task 1: Configure a Directory Integration Profile for the Oracle Human Resources Connector". Ensure that all values in the integration profile are properly set, including:
- Oracle Human Resources attribute list
- Oracle Human Resources attribute mapping rules
- Scheduling interval
Once everything is properly set, set the Profile Status (orclodipagentcontrol) attribute to ENABLE. This indicates that the Oracle Human Resources connector is ready to run.
Start the Oracle directory server and the Oracle Human Resources system if they are not already running on the respective hosts.

When everything is ready, start the directory integration and provisioning server if it is not already running on this host.