33
Synchronization with Oracle Human Resources

If you store employee data in Oracle Internet Directory, and if you use Oracle Human Resources to create, modify, and delete that data, then you must ensure that the data is synchronized between the two. The Oracle Human Resources connector enables you to do this.

This chapter introduces the Oracle Human Resources connector and explains how to deploy it. It contains these topics:

• Introduction
• Data that You Can Import from Oracle Human Resources
• Managing Synchronization with Oracle Human Resources

Introduction

The Oracle Human Resources connector enables you to import a subset of employee data from Oracle Human Resources into Oracle Internet Directory. It is installed, with a default configuration, along with Oracle Internet Directory. It is ready to run out of the box.

You can schedule the Oracle Human Resources connector to run at any time, configuring it to extract incremental changes from the Oracle Human Resources system as often as every second. You can also set and modify attribute mapping between Oracle Human Resources and Oracle Internet Directory.

The Oracle Human Resources connector executable name is odihragent and is located in the $ORACLE_HOME/ldap/odi/bin directory. You can manage the Oracle Human Resources connector by using Oracle Directory Manager.

Data that You Can Import from Oracle Human Resources

Table 33-1 lists the tables in the Oracle Human Resources schema, most of whose attributes you can import into Oracle Internet Directory:

Table 33-1  Tables in Oracle Human Resources Schema

All of these tables are visible if the login to the Oracle Human Resources database is done with the apps account.

Because attributes can be added or deleted at runtime from the configuration file, the Oracle Human Resources connector dynamically creates a SQL statement that selects and retrieves only the required attributes.

Table 33-2 shows some of the fields in the Oracle Human Resources user interface. These fields appear when you add or modify employee data.

Table 33-2  Fields in the Oracle Human Resources User Interface

Managing Synchronization with Oracle Human Resources

This section contains these topics:

• Configuring a Directory Integration Profile for the Oracle Human Resources Connector
• Customizing the List of Attributes to Be Synchronized with Oracle Internet Directory
• Customizing Mapping Rules for the Oracle Human Resources Connector
• Running Synchronization from Oracle Human Resources to Oracle Internet Directory

Configuring a Directory Integration Profile for the Oracle Human Resources Connector

To deploy the Oracle Human Resources connector, you must create a directory integration profile for it in Oracle Internet Directory. You can do this by using the procedures outlined in Chapter 30, "Oracle Directory Integration Server Administration". However, if you have a server installation--that is, a typical installation--then you can use the default integration profile that the Oracle Universal Installer created in the directory for you. A client-only installation does not include this integration profile.

The integration profile contains several attributes and attribute values. Table 33-3 lists these attributes by both their friendly names as used by Oracle Directory Manager--for example, Profile Name--and their actual names--for example, orclodipAgentName. It provides a description of each attribute, and, where appropriate, the default values in the Oracle Human Resources connector integration profile. Some cells in Table 33-3 contain italicized text providing information and instructions specific to the Oracle Human Resources connector

Table 33-3  Attributes in the Oracle Human Resources Connector Integration Profile

odihragent   connect=hrdb \                                              
login=%orclodipConDirAccessAccount \
pass=%orclodipConDirAccessPassword \                                             
date=%orclODIPLastSuccessfulExecutionTime \

Customizing the List of Attributes to Be Synchronized with Oracle Internet Directory

You can customize the list of Oracle Human Resources attributes you want to synchronize with Oracle Internet Directory. To help you do this, Oracle Internet Directory includes a default list of Oracle Human Resources attributes to be synchronized. You can modify this list by including additional attributes in it, or excluding some from it.

The default attribute list is stored in the orclodipAgentConfigInfo attribute as part of the integration profile. The integration profile is loaded into Oracle Internet Directory as part of a typical installation. The list is also contained in the file named oraclehragent.cfg.master and is located under the $ORACLE_HOME/ldap/odi/conf directory.

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

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

Including Additional Oracle Human Resources Attributes for Synchronization

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

1. Copy the oraclehragent.cfg.master file and name it anything other than Agent_Name.cfg. This is because the directory integration server generates a configuration file with that name, using it to pass the configuration information to the Oracle Human Resources connector at run time.
2. 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 33-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 by which this attribute is identified in the output file. This tag is also 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. See "Creating Oracle Human Resources Attribute Mapping Rules" for instructions about creating mapping rules.

3. Load the file into the orclodipAgentConfigInfo attribute by using the ldapmodify tool. The changes take effect the next time the connector runs.

Excluding Oracle Human Resources Attributes from Synchronization

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

1. Copy the oraclehragent.cfg.master file and name it anything other than Agent_Name.cfg. This is because the directory integration server generates a configuration file with that name, using it to pass the configuration information to the Oracle Human Resources connector at run time.
2. 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
3. Load the file into the orclodipAgentConfigInfo attribute by using the ldapmodify tool. The changes take effect the next time the connector runs.

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 connector also supports execution of a preconfigured SQL SELECT statement in the configuration file. There is a TAG to indicate this in the config file, namely, a "[SELECT]" in the config file.

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

All the columns expressions fetched in the SELECT must have column names--for example, REPLACE(ppx.email_address),'@ORACLE.COM','') is fetched 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'''.

[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')

Customizing Mapping Rules for the Oracle Human Resources Connector

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

To help you do this, Oracle Internet Directory includes a default list of Oracle Human Resources mapping rules for the Oracle Human Resources system. You configure, modify, and delete mapping rules by editing this list.

The default list of mapping rules is stored in the orclodipAttributeMappingRules attribute in the integration profile. In addition, the rules are also in the file named oraclehragent.map.master located under the $ORACLE_HOME/ldap/odi/conf directory.

Default Oracle Human Resources Connector Mapping Rules

The oraclehragent.map.master file contains the following:

DomainRules
NONLDAP:dc=metaagt,dc=com:uid=%dc=metaagt,dc=com
AttributeRules
firstname: : : :cn: :person
email : : : :cn: :person: trunc(email,'@')
email : : : :uid: :person:trunc(email,'@')
firstname,lastname: : : :cn: :person: firstname+","+lastname
lastname,firstname: : : :cn: :person: lastname+","+firstname
firstname,lastname: : : :sn: :person: lastname | firstname
EmployeeNumber: : : :employeenumber: :inetOrgperson
EMail: : : :mail: :inetOrgperson
TelephoneNumber1: : : :telephonenumber: :person
TelephoneNumber2: : : :telephonenumber: :person
TelephoneNumber3: : : :telephonenumber: :person
Address1: : : :postaladdress: :person
state: : : :st: :locality
street1: : : :street: :locality
zip: : : :postalcode: :locality
town_or_city: : : :l: :locality
Title: : : :title: :organizationalperson
#Sex: : : :sex: :person

In the sample mapping file, `dc=metaagt,dc=com' is assumed as the `synchronization domain'. This domain name needs to be changed according to deployment requirements.

AttributeRules
firstname: : : :cn: :person
lastname: : : :sn: :person
lastname: : : :cn: :person
 : : : :cn: :person: trunc(email,'@')
 : : : :cn: :person: firstname+","+lastname
 : : : :cn: :person: lastname+","+firstname
EmployeeNumber: : : :employeenumber: :inetOrgperson
EMail: : : :mail: :inetOrgperson
TelephoneNumber1: : : :telephonenumber: :person
TelephoneNumber2: : : :telephonenumber: :person
TelephoneNumber3: : : :telephonenumber: :person
Address1: : : :postaladdress: :person
Address1: : : :postaladdress: :person
Address1: : : :postaladdress: :person
state: : : :st: :locality
street1: : : :street: :locality
zip: : : :postalcode: :locality
town_or_city: : : :l: :locality
Title: : : :title: :organizationalperson
Sex: : : :sex: :person
socialsecurity: : : :ssn: :person
country: : : :c: :country
BirthDate: : : :birthday: :organizationalperson
 : : : :userpassword: :person: "welcome"
changetype
###

The default mapping rules in the orclodipAttributeMappingRules attribute correspond to the default Oracle Human Resources attributes list in the orclodipAgentConfigInfo attribute. To establish mappings between Oracle Human Resources attributes and Oracle Internet Directory attributes, the mapping rules use the ATTRNAME column in each record of the Oracle Human Resources attributes list.

Creating Oracle Human Resources Attribute Mapping Rules

To create Oracle Human Resources attribute mapping rules, you modify the orclodipAttributeMappingRules attribute. To do this:

1. Copy the oraclehragent.map.master file to Agent_Name.tmp.
2. Add a new rule to this file by adding a record to it. To do this, you need this information:
   • The Oracle Human Resources attribute name that is mapped to Oracle Internet Directory
   • The corresponding attribute in Oracle Internet Directory and its object class to which the Oracle Human Resources attribute are to map
   • The import rule that determines how to map the Oracle Human Resources attribute to the Oracle Internet Directory attribute
3. Load the file into the orclodipAttributeMappingRules attribute by using the following script:
   $ORACLE_HOME/ldap/odi/admin/ldapUploadAgentFile.sh. The changes take effect the next time the profile runs.

Modifying Oracle Human Resources Attribute Mapping Rules

To modify existing Oracle Human Resources attribute mapping rules, you modify the orclodipAttributeMappingRules attribute. To do this:

1. Copy the oraclehragent.map.master file Profile_Name.map.
2. Edit this file.
3. Load the file into the orclodipAttributeMappingRules attribute by using the ldapmodify tool. The changes take effect the next time the connector runs.

Deleting Oracle Human Resources Attribute Mapping Rules

To delete existing Oracle Human Resources attribute mapping rules, you modify the orclodipAttributeMappingRules attribute. To do this:

1. Copy the oraclehragent.map.master file and name it anything other than Agent_Name.map, which is reserved for use by the directory integration server.
2. Do one of the following:
   • Delete the rule from the file
   • Comment it out by putting a hash (#) sign in front of it
3. Load the file into the orclodipAttributeMappingRules attribute by using the following script:
   $ORACLE_HOME/ldap/odi/admin/ldapUploadAgentFile.sh. The changes take effect the next time the profile runs.

   Note: To run shell script tools on the Windows operating system, you need one of the following UNIX emulation utilities: Cygwin 1.0. Visit: http://sources.redhat.com/cygwin/ MKS Toolkit 5.1 or 6.0. Visit: http://www.datafocus.com/products/

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

During synchronization, the Oracle Directory Integration Platform uses an import file. This file can contain a few or many changes that the Oracle Human Resources connector extracts from the Oracle Human Resources system.

This file is in the tagged format and acts as input to the Oracle directory server. It is named Oracle_HR_Agent_Name.data and is located in $ORACLE_HOME/ldap/odi/import.

You do not need to modify this file, but the last version of it is stored in the directory $ORACLE_HOME/ldap/odi/import/archive to help you with troubleshooting.

This is an example of an Oracle Human Resources change record in the import file:

FirstName: John
LastName: Liu
EmployeeNumber: 12345
Title: Mr.
Sex: M
MaritalStatus: Married
TelephoneNumber: 123-456-7891
Mail: Jliu@my_company.com
Address: 100 Jones Parkway
City: MyTown

Preparing for Synchronization

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

1. Ensure that the Oracle Human Resources connector and the directory integration 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 Release 9.2 for more details

2. 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
3. Ensure that the directory integration server on this host is registered in Oracle Internet Directory.

   See Also: ""Registering the Oracle Directory Integration Server" for registration instructions

4. Configure an integration profile for the Oracle Human Resources connector, as described in "Configuring 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
5. Once everything is properly set, set the Profile Status attribute to ENABLE. This indicates that the Oracle Human Resources connector is ready to run.
6. Start the Oracle directory server and the Oracle Human Resources system if they are not already running on the respective hosts.
7. When everything is ready, start the directory integration server if it is not already running on this host.

   See Also: "Managing the Oracle Directory Integration Server" for instructions about starting and stopping the directory integration server

The Synchronization Process

Once the Oracle Human Resources system, Oracle Internet Directory, and the directory integration server are running and the Oracle Human Resources connector is enabled, the directory integration server automatically starts synchronizing changes from the Oracle Human Resources system into Oracle Internet Directory. It follows this process:

1. Depending on the value specified in the Last Execution Time (orclodipLastExecutionTime) and the Scheduling Interval (orclodipschedulinginterval), the directory integration server invokes the Oracle Human Resources connector.
2. The Human Resources Connector extracts all the changes from the Oracle Human Resources System based on the time specified in the orclodipLastSuccessfulExecutionTime attribute in the integration profile. It writes the changes into the Oracle Human Resources import file, namely $ORACLE_HOME/ldap/odi/import/HR_Agent_Name.dat. It extracts only the attributes specified in the orclodipAgentConfigInfo attribute in the integration profile.
3. After the agent completes the execution, the directory integration server imports the changes to Oracle Internet Directory by doing the following:
   • Reading each change record from the import file
   • Converting each change record into an LDAP change entry based on the rules specified in the Mapping Rules (orclodipAttributeMappingRules) in the integration profile.
4. After successfully importing all the changes successfully to Oracle Internet Directory, Oracle Human Resources connector moves the import file to the archive directory, $ORACLE_HOME/ldap/odi/import/archive. The status attributes Last Execution Time (orclodipLastExecutionTime) and Last Successful Execution Time (orclodipLastSuccessfulExecutionTime) are updated to the current time.
5. If the import operation fails, only the Last Execution Time is updated, and the connector once again attempts to extract the changes from Human Resources system based on the Last Successful Execution Time. The reason for failure is logged in the trace file in $ORACLE_HOME/ldap/odi/HR_Agent_Name.trc file.

Boostrapping Oracle Internet Directory from Oracle Human Resources

There are two ways to bootstrap Oracle Internet Directory from Oracle Human Resources:

• Use the Oracle Human Resources connector. In the integration profile, set the orclodipConDirLastAppliedChgTime to a time before Oracle Human Resources was installed.
• Use external tools to migrate data from Oracle Human Resources into Oracle Internet Directory

  See Also: Chapter 32, "Bootstrapping of a Directory in the Oracle Directory Integration Platform" for further instructions about initial bootstrapping