28
The Oracle Directory Synchronization Service

This chapter discusses synchronization, which uses the first of the two types of integration profiles--namely, the directory synchronization profile. This profile provides the configuration information necessary to make Oracle Internet Directory and connected directories consistent.

This chapter discusses the synchronization profiles and connectors that link Oracle Internet Directory and connected directories. It contains these topics:

• About Connectors and Directory Integration Profiles
• Managing Synchronization Profiles
• Managing Synchronization Profiles by Using Command-Line Tools

  See Also: "Oracle Directory Provisioning Integration Service" for a discussion of the second type of integration profile, called a provisioning integration profile, which identifies the data and methods for notifying an application of changes in user or group data

About Connectors and Directory Integration Profiles

This section contains these topics:

• Connectors
• Synchronization Scenarios
• Directories with Unique Formats
• Directory Synchronization Profiles
• Registration of Connectors into Oracle Directory Integration Platform
• Additional Connector Configuration Information
• Mapping Rules and Formats
• Location and Naming of Files

Connectors

In the Oracle Directory Integration Platform, a connector represents a prepackaged connectivity solution between Oracle Internet Directory and a connected directory. Minimally, it consists of a connector profile, called a directory integration profile. This profile contains all the configuration information required to synchronize Oracle Internet Directory and a connected directory.

Using Connectors with Supported Interfaces

If the connected directory can use one of the interfaces supported by the Oracle Directory Integration Platform for exchanging data, then a connector requires only a directory integration profile for synchronization to occur. One example is the iPlanet connector provided with Oracle Internet Directory. Because Oracle Internet Directory and iPlanet Directory can synchronize by using the LDAP interface, the iPlanet connector consists simply of a pre-packaged directory integration profile.

Using Connectors Without Supported Interfaces

If a connected directory cannot use one of the interfaces supported by the Oracle Directory Integration Platform, then, in addition to the directory integration profile, it requires an agent. The agent transforms the data from one of the formats supported by the Oracle Directory Integration Platform into one supported by the connected directory. An example is the Oracle Human Resources connector. It has both a prepackaged integration profile and an Oracle Human Resources agent. The agent uses the tagged file format supported by the Oracle Directory Integration Platform to communicate with Oracle Internet Directory, and it uses SQL (through an OCI interface) to communicate with the Oracle Human Resources system.

Synchronization Scenarios

Synchronization can occur from a connected directory to Oracle Internet Directory, from Oracle Internet Directory to a connected directory, or both.

Synchronizing from Oracle Internet Directory to a Connected Directory

A numbered entry is stored in the change log container for each change to Oracle Internet Directory. Each time the Oracle Directory Synchronization Service processes a synchronization profile, it:

1. Retrieves the number of the change log entry last used to update the corresponding connected directory
2. Checks each change log entry more recent than that number
3. Uses the profile's filtering rules to select changes requiring synchronization with the corresponding connected directory

The appropriate entries or attributes are then updated in that connected directory. (If it does not use PL/SQL, LDAP, tagged, or LDIF formats directly, then the connector identified in its profile is invoked.) The last log number successfully used is then stored in the profile.

Oracle Internet Directory periodically purges the change log after all profiles have used what they need, and identifies where subsequent synchronization should begin.

Synchronizing from a Connected Directory to Oracle Internet Directory

When a connected directory uses PL/SQL, LDAP, tagged, or LDIF formats directly, changes to its entries or attributes are automatically synchronized by the Oracle Directory Synchronization Service. Otherwise, the connector identified in its synchronization profile must write the changes to an export file in tagged or LDIF format. The Oracle Directory Synchronization Service then uses this file of connected directory data to update Oracle Internet Directory.

Directories with Unique Formats

Some connected directories cannot receive data by using any of the interfaces supported by Oracle Internet Directory. The profiles for this type of directory contain an attribute identifying a separate program for synchronization. This program, called an agent, translates between the connected directory's specialized format and a tagged or LDIF file containing the synchronization data. The Oracle Directory Synchronization Service invokes the agent identified in the profile to perform the synchronization.

When exporting data from Oracle Internet Directory for import into this type of connected directory, the Oracle Directory Synchronization Service creates the necessary file in the tagged or LDIF format. The agent then reads that file, translates it into the correct format for the receiving connected directory, and stores the data in that directory.

When exporting data from this type of connected directory for import into Oracle Internet Directory, the agent creates the necessary tagged or LDIF format file. The Oracle Directory Synchronization Service then uses this file data to update the Oracle Internet Directory.

Directory Synchronization Profiles

A directory integration profile for synchronization is called a directory synchronization profile. It contains all the configuration information required for synchronization including:

• Direction of Synchronization

  One part of the configuration information has to do with the direction of the synchronization. Some connected directories only receive data from Oracle Internet Directory, others only supply data to it, and some do both. A separate profile is used for each direction--that is, one profile for information coming into Oracle Internet Directory, and another for information going from Oracle Internet Directory to the connected directories.

• Type of Interface

  Another part of the configuration information has to do with the type of interface to be used. Some connected directories can receive data in any of the interfaces built into the Oracle Directory Integration Platform. These interfaces now include PL/SQL, LDAP, tagged, and LDIF. For these connected directories, the Oracle Directory Synchronization Service performs the synchronization itself, directly, using the information stored in the profile.

• Other Information

  The directory synchronization profile also stores such information as the name and type of an agent, how and when to invoke it, and the mapping information required for synchronizing entries and attributes.

Changes requiring synchronization can occur in Oracle Internet Directory or in a connected directory. The Oracle Directory Synchronization Service periodically checks each profile, comparing its last successful update time and change number against the contents of the change log. When as-yet-unsynchronized changes are found, the Oracle Directory Synchronization Service initiates synchronization. Import and export operations for Oracle Internet Directory are handled directly by the Oracle directory integration server. If synchronization with a particular connected directory requires an agent, then that need is specified in the profile and the agent is automatically invoked.

Registration of Connectors into Oracle Directory Integration Platform

Before deploying a connector, you register it in Oracle Internet Directory. This registration involves creating a directory synchronization profile, which is stored as an entry in the directory. To create it, you can use either Oracle Directory Manager or command-line tools, as described in subsequent sections of this chapter.

Most of the information needed to synchronize the data with the connected directory--such as account name, password, host name, port number--is stored in the synchronization profile. However, if the connector execution requires any additional information, it can be stored in the orclOdipAgentConfigInfo attribute of the synchronization profile entry.

o

Attributes in a synchronization profile entry belong to the object class orclodiProfile. The only exception is the orcllastappliedchangenumber attribute, which belongs to the object class orclchangesubscriber.

The Object Identifier prefix 2.16.840.1.113894.7 is assigned to platform-related classes and attributes. Table 28-1 lists all the attributes in the Oracle Directory Integration Platform profile.

Table 28-1  Attributes in the Oracle Directory Integration Platform Profile

Attribute	Description
General Information
ProfileName (orclOdipAgentName)	Name of the integration profile.
ProfileStatus (orclOdipAgentControl)	Indicator whether the profile is enabled or disabled.
Profile Password (orclOdipProfilePassword)	The password used by the profile to bind to Oracle Internet Directory. In case of import, the changes are made as with profilename as the identity.
SynchronizationMode (orclOdipSynchronizationMode)	Either of the following: Import--Changes from the connected directory are imported to Oracle Internet Directory Export--Changes from Oracle Internet Directory are extracted and given to the connected directory
SchedulingInterval (orclOdipSchedulingInterval)	The interval with which the connector synchronizes.
Number of Retries (orclodipSyncRetryCount)	Maximum number of times the agent or synchronization is attempted in case of failure. By default, the Oracle directory integration server tries the synchronization a maximum of 10 times. The first retry takes place 1 minute after the first failure, the second retry happens 2 minutes after the second failure and, subsequently, the n-th retry takes place n minutes after the n-th failure.
ProfileVersion (orclVersion)	Identifier indicating the integration profile version. It has a value of 1.0. If this field has a value other than 1.0, the profile is not processed.
Execution Information
AgentExecutionCommand (orclodipAgentExeCommand)	Connector executable name and argument list used by the directory integration server. It can be passed as a command-line argument when the connector is invoked. See Also: Chapter 33, "Synchronization with Oracle Human Resources" for typical usage of passing it in the command-line
ConnectedDirectory Account (orclOdipConDirAccessAccount)	Valid user account in the connected directory to be used by the connector for synchronization. For instance, for the Iplanet synchronization connector, it is the valid binddn in the iPlanet directory. For Hragent, it is a valid user identifier in the Oracle Human Resources database. For other connectors, it can be passed as a command-line argument when the connector is invoked. See Also: Chapter 33, "Synchronization with Oracle Human Resources" for typical usage of passing it in the command-line
ConnectedDirectory AccountPassword (orclOdipConDirAccessPassword)	Password to be used by the user identifier specified in the ConnectedDrectoryAccount attribute to connect to the connected directory. For instance, for the Iplanet synchronization connector, it is the valid bind password in the iPlanet directory. For Hragent, it is the Oracle Human Resources database password.
Connected Directory URL (orclOdipConDirURL)	Connect details required to connect to the connected directory. In the case of iPlanet synchronization, this parameter refers to the host name and port number as host:port. Similarly, for the database, this can be used in the form of Host:port:oraclesid.
Interface Type (orclodipDataInterfaceType)	The data format or protocol used in synchronization. Supported values are: LDIF--Import or export from a LDIF File Tagged--Import or export from a Tagged File--a proprietary format supported by the Oracle directory integration server, similar to LDIF format See Also: Appendix A, "Syntax for LDIF and Command-Line Tools" LDAP--Import from or export to an LDAP-compliant directory DB --Import from or export to an Oracle9i Database Server directory
Additional Config Info (orclOdipAgentConfigInfo)	Any additional configuration information that needs to be passed onto the connector. When the connector is scheduled for execution, the value of the attribute is stored in the file, $ORACLE_HOME/ ldap/odi/conf/profile_name.cfg that can be processed by the connector.
Mapping Information
Attribute Mapping Rules (orclOdipAttributeMappingRules)	Mapping rules for converting data from a connected directory to Oracle Internet Directory. This information is stored as a binary attribute. See Also: Mapping Rules and Formats on "Default Oracle Human Resources Connector Mapping Rules" for an example of mapping rules.
ConnectedDirectoryMatchingFilter (orclOdipConDirMatchingFilter)	Attribute to select changes to Oracle Internet Directory that are to be applied to the connected directory
OIDMatchingFilter (orclOdipOIDMatchingFilter)	Attribute to select changes to the connected directory that are to be applied to Oracle Internet Directory
Status Information
LastExecutionTime (orclOdipLastExecutionTime)	Time when synchronization was last carried out. Its format is dd-mon-yyyy hh:mm:ss, where hh is the time of day in 24-hour format.
LastSuccessfulExecutionTime (orclOdipLastSuccessfulExecutionTime)	Time of the last successful synchronization, in the format dd-mon-yyyy hh:mm:ss, where hh is the hour in 24-hour format.
Synchronization Status (orclOdipSynchronizationStatus)	Synchronization status of the last execution: Success or failure.
SynchronizationError (orclodipSynchronizationErrors)	Reason for failure if last execution failed
Con Dir Last Applied Change Num (orclodipConDirLastAppliedChgNum)	For import operations, the last change from the connected directory that was applied to Oracle Internet Directory
OIDLastAppliedChangeNumber (orclOdipLastAppliedChgNum)	For export operations, the last change from Oracle Internet Directory that was applied to the connected directory

The various synchronization profile entries in the directory are created under the container cn=subscriber profile,cn=changelog subscriber,cn=oracle internet directory. For example, a connector called OracleHRAgent is stored in the directory as
orclodipagentname=OracleHRAgent,cn=subscriber profile,cn=changelog subscriber,cn=oracle internet directory.

Additional Connector Configuration Information

Although the synchronization profile stores most of the information needed by a connector to synchronize Oracle Internet Directory with connected directories, some connectors may need more. This is because some operations might require additional configuration information at runtime.

You can store such additional connector configuration information wherever and however you want. However, the Oracle Directory Integration Platform enables you to store it in the synchronization profile as an attribute called orclODIPAgentConfigInfo. Its use is optional--that is, if a connector does not require such information, then the corresponding attribute in the synchronization profile is simply left empty. If such information would be useful, you can load it into this attribute by using the script named oidmuplf.sh. The type and format of the data stored in the additional configuration information attribute are determined by each executable's needs.

This configuration information can pertain to the connector, the connected directory, or both. Oracle Internet Directory and Oracle directory integration server do not read or modify this information. When the connector is invoked, the Oracle directory integration server simply provides it with the information in this attribute, as a temporary file.

Mapping Rules and Formats

In a directory synchronization environment, a typical set of entries from one domain can be moved to another domain. Similarly, a set of attributes can be mapped onto another set of attributes.

Mapping rules are the entities that govern the conversion of attributes between a connected directory and Oracle Internet Directory. Each connector stores a set of these rules in the orclodipAttributeMappingRules attribute of its synchronization profile. The Oracle directory integration server uses these rules to map attributes as needed when exporting from the directory and interpreting data imported from a connected directory or file. When the Oracle directory integration server imports changes into Oracle Internet Directory, it converts the connected directory's change record into an LDAP change record following the mapping rules. Similarly, during export, the connector translates Oracle Internet Directory changes to the format understood by the connected directory.

Format of the Mapping Rules Attribute

The mapping rules attribute provides a means of specifying domain level mapping and attribute level mapping. It can be assumed to be in the format of a file as described in this section.

Mapping rules are organized in a fixed tabular format, and you must follow that format carefully. Each set of mapping rules appears between a line containing only the word DomainRules and a line containing only the characters ###. The fields within each rule are delimited by a colon (:).

DomainRules
srcDomainName1: [dstDomainName1]: [DomainMappingRule1]
srcDomainName2: [dstDomainName2]: [DomainMappingRule2]
AttributeRules
srcAttrName1:[ReqAttrSeq]:[SrcAttrType]:[SrcObjectClass]:

[dstAttrName1]:[DstAttrType]:[DstObjectClass]:

[AttrMappingRule1]
srcAttrName2: [ReqAttrSeq]:[SrcAttrType]: 
[SrcObjectClass]:[dstAttrName2]:[DstAttrType]:

[DstObjectClass]:[AttrMappingRule2]
###

where the expansion of each srcAttrName1 and srcAttrName2 would be a single, unfolded long line.

The domain rule specifications appear after a line containing only the keyword DomainRules. Each domain rule is represented with the components, separated by colons, that are described in Table 28-2.

Table 28-2  DomainRule Components

Component Name	Description
SrcDomainName	Name of the domain or container of interest. Specify NONLDAP for sources other than LDAP and LDIF.
DstDomainName	Name of the domain of interest in the destination. It is optional, and if not specified, takes the value of SrcDomainName under valid conditions. For destinations other than LDAP and LDIF, specify NONLDAP. Because "import" and "export" always refer to Oracle Internet Directory, a combination of NONLDAP:NONLDAP is not allowed.
DomainMappingRule	This field is meaningful only when importing to Oracle Internet Directory, or when exporting to an LDIF file or another external LDAP-compliant directory. This rule is used to construct the destination DN from the source domain name, from the attribute given in AttributeRules,, or both. This field is typically of the form cn=%,l=%,o=oracle,dc=com. Such specifications are used to put entries under different domains or containers in the directory. In case of non-LDAP sources, this rule indicates the way the target DN needs to be formed to place the entries in the directory. This component is optional in LDAP-to-LDIF, LDAP-to-LDAP, or LDIF-to-LDAP. If not specified, the source domain and destination domain names are considered to be the same.

The attribute rule specifications appear after a line containing only the keyword AttributeRules. Each attribute rule is represented with the components, separated by colons, and described in Table 28-3. The attribute rule specifications end with a line containing only the characters ###.

Table 28-3  Components in Attribute Rules

Component Name	Description
SrcAttrName	For LDAP-compliant directory repositories, this parameter refers to the name of the attribute to be translated. For Oracle9i Database Server repositories, it refers to the ColumnName in the table specified by the SrcClassName. For other repositories this parameter can be appropriately interpreted.
ReqAttrSeq	Indicator of whether the source attribute must always be passed to the destination. When entries are synchronized between the Oracle Internet Directory and the connected directory, some attributes need to be used as synchronization keys. This field indicates whether the specified attribute is being used as a key. If so, regardless of whether the attribute has changed or not, the value of the attribute is always extracted from the source. A nonzero integer value should be placed in this field if the attribute needs to be always passed on to the other end.
SrcAttrType	This parameter refers to the attribute type--for example, integer, string, binary--that validates the mapping rules. It validates the equivalency of the source and destination attribute types. In Release 9.2, this field is ignored.
SrcObjectClass	If the source of the attribute being shared is an LDAP-compliant directory, then this parameter names the object class to which the attribute belongs. If the source of the shared attribute is an Oracle9i Database Server repository, then this parameter refers to the TableName and is is mandatory. For other repositories, this parameter may be ignored.
DstAttrName	Optional attribute. If it is not specified, then the SrcAttrName is assumed. For LDAP-compliant directories, this parameter refers to the name of the attribute at the destination. For Oracle9i Database Server repositories, it refers to the ColumnName in the table specified by the SrcClassName. For other repositories, this parameter can be appropriately interpreted.
DstAttrType	This parameter refers to the attribute type--for example, integer, string, binary--that validates the mapping rules. It validates the equivalency of the source and destination attribute types. In Release 9.2, this field is ignored.
DstObjectClass	For LDAP-compliant directories, this parameter refers to the object class to which the attribute belongs, and is optional. For Oracle9i Database Server repositories, it refers to the TableName, and is mandatory. For other repositories this parameter may be ignored.
AttrMapping Rule	Optional arithmetic expression with operators: +, functions: toUpper (string) , toLower(String), trunc (string,char). If nothing is specified, then the source attribute value is copied as the value of the destination attribute.

In a newly created synchronization profile, mapping rules are empty. To enter mapping rules, edit a file that strictly follows the correct format.

Example: A Mapping File

Here is an example of a mapping file for importing from the Oracle Human Resources database tables by using the tagged-file interface. This example of a file is supplied during installation, at
$ORACLE_HOME/ldap/odi/conf/oraclehragent.map.master.

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

###

As described earlier, the mapping file consists of keywords and a set of domain and attribute mapping rule entries. The mapping file in this example contains the domain rule NONLDAP:dc=metaagt,dc=com:cn=%,dc=metaagt,dc=com. This rule implies that the source domain is NonLDAP--that is, there is no source domain.

The destination domain (:dc=metaagt,dc=com) implies that all the directory entries this profile deals with are in the domain dc=metaagt,dc=com.

The DomainMappingRule (:uid=%,dc=metaagt,dc=com) implies that the data from the source should refer to the entry in the directory with the DN, which is constructed using this domain mapping rule. In this case, uid must be one of the destination attributes which should always have a non-null value. If any data corresponding to an entry to be synchronized has a null value, then the mapping engine assumes that the entry is invalid and proceeds to the next entry. To identify the entry correctly in the directory, it is also necessary that uid should be a single-valued attribute.

In some cases, the RDN of the DN needs to be constructed by using the name of a multivalued attribute. For example, to construct an entry with the DN of cn=%,l=%,dc=metaagt,dc=com, where cn is a multivalued attribute, the DomainMappingRule can be of this form: rdn,l=%,dc=metaagt,dc=com where rdn is one of the destination attributes having a non-null value. A typical mapping file supporting this could have the following form:

DomainRules
NONLDAP:dc=metaagt,dc=com:rdn,l=%,dc=metaagt,dc=com
AttributeRules
firstname: : : :cn: :person
email : : : :cn: :person: trunc(email,'@')
email : : : :rdn: :person: 'cn='+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
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
###

In the attribute mapping rule, firstname: : : :cn: : person, these explanations apply:

SrcAttrName - firstname (Name of the original attribute )

ReqAttrSeq : empty (If the attr is not found, you can still continue with mapping )

SrcAttrType: empty (Not required )

SrcObjectClass: empty (Not required)

DstAttrName : cn (Name of the attr as it appears in Oracle Internet Directory )

DstAttrType: empty (Not required)

DstObjectClass : person. Object class to which the attribute belongs to - it is mandatory while using a Import with Tagged File interface.

Similarly, the rule e-mail: : : :cn: : person: trunc(email,'@')implies applying the mapping rule of truncating all the characters off of e-mail and get the remaining as cn.

You can customize mapping rules by adding new ones, modifying the existing ones or deleting the existing ones by modifying the file. If the mapping rules are not available in a file, the attribute value can be downloaded to the file by using ldapsearch as described in "ldapsearch Syntax". The entry to be searched for is orclodipagentname=ProfileName,cn=subscriber profile,cn=changelog subscriber,cn=oracle internet directory for the attribute orclodipattributemappingrules.

Mapping rules are flexible: They can include both one-to-many and many-to-one mappings.

• One-to-many

  One attribute in a connected directory can map to many attributes in Oracle Internet Directory. For example, suppose an attribute in the connected directory is Address:123 Main Street/MyTown, MyState 12345. You can map this attribute in Oracle Internet Directory to both the LDAP attribute homeAddress and the LDAP attribute postalAddress.

• Many-to-one

  Multiple attributes in a connected directory can map to one attribute in Oracle Internet Directory. For example, suppose that the Oracle Human Resources directory represents Anne Smith by using two attributes: firstname=Anne and lastname=Smith. You can map these two attributes to one attribute in Oracle Internet Directory: cn=Anne Smith.

  See Also: "Default Oracle Human Resources Connector Mapping Rules" for an example of mapping rules

Updating Mapping Rules

You can customize mapping rules by adding new ones, modifying existing ones, or deleting some from the mapping rule set specified in the orclodipAttributeMappingRules attribute. In general, to perform any of these operations, you identify the file containing the mapping rules, or store the value of the attribute for a file by using an ldapsearch command as described in "ldapsearch Syntax".

OrclodipAttributeMappingRules is a single valued attribute in the directory and it must follow a fixed format. You cannot edit the mapping rules in Oracle Directory Manager. Instead, mapping rules are stored in a file that you upload to the directory as a value of the attribute. To upload the mapping file, use the utility oidmuplf.sh. Once you have created and uploaded the mapping file, you can maintain a copy of it in the $ORACLE_HOME/ldap/odi/conf directory, and upload it again after any future update.

Adding an Entry to the Mapping Rules File

To add a new entry to the mapping rules file, edit this file and add a record to it. To do this:

1. Identify the connected directory attribute name that needs to be mapped to Oracle Internet Directory.
2. Identify the corresponding attribute name in Oracle Internet Directory to which it can be mapped.
3. Generate the mapping rule elements indicating the conversion that needs to be done on the attribute values.
4. Load the attribute mapping rule file to the synchronization profile by using the oidmuplf.sh tool.

Modifying an Entry in the Mapping Rules File

After you identify an entry to be modified in the mapping rules file, generate the mapping rule element for the desired conversion of attribute values. Then use the oidmuplf.sh tool to load the attribute mapping rule file into the synchronization profile.

Deleting an Entry from the Mapping Rules File

After you identify an entry to be deleted in the mapping rules file, you can either delete the entry from the file or comment it out by putting a hash mark (#) in front of it. Then use the oidmuplf.sh tool to load the attribute mapping rule file into the synchronization profile.

Location and Naming of Files

Table 28-4 tells you where to find the various files and what names to use:

Table 28-4  Location and Names of Files

File	File Name
Import DataFile	$ORACLE_HOME/ldap/odi/data/import/Profile_Name.dat
Export Data File	$ORACLE_HOME/ldap/odi/data/export/Profile_Name.dat
TraceFile	$ORACLE_HOME/ldap/odi/log/Profile_Name.trc
Additional Configuration Info	$ORACLE_HOME/ldap/odi/conf /Profile_Name.cfg
Mapping Rules	$ORACLE_HOME/ldap/odi/conf /Profile_Name.map

For example, the datafile name of the Oracle Human Resources agent is oraclehrprofile.dat.

Managing Synchronization Profiles

This section contains these topics:

• Managing Profiles by Using Oracle Directory Manager
• Managing Synchronization Profiles by Using Command-Line Tools

Managing Profiles by Using Oracle Directory Manager

This section tells you how to register and deregister a profile by using Oracle Directory Manager.

Registering a Profile by Using Oracle Directory Manager

Oracle Directory Manager enables you to register a profile in one of two ways:

• By creating a new configuration set entry, then adding a profile to it
• By selecting an existing configuration set entry, then adding a profile to it

To register a profile:

1. In the navigator pane, expand Oracle Internet Directory Servers > directory_server_instance > Server Management, then select Directory Integration Server. The Active Processes box appears in the right pane.
2. On the toolbar, click Create. The Configuration Sets dialog box appears.
3. In the Configuration Sets dialog box, click Create. The Integration Profiles dialog box appears. You have two options:
   • To create an integration profile by copying an existing one, select the Oracle Directory Integration Platform profile you want to copy, then click Create Like. The Integration Profile dialog box displays the General tab page.
   • To create an integration profile without copying an existing one, click Create New. The Integration Profile dialog box displays the General tab page.
4. In the General tab page, fill in the fields as explained in Table 28-5.

   Table 28-5  Description of Fields on the General Tab Page in Oracle Directory Manager

   Field	Description
   Profile Name	Specify the name of the Profile. The name you enter is used as the RDN component of the DN for this integration profile. For example, specifying a profile name MSAccess creates an integration profile named orclodipagentname=MSAccess,cn=subscriber profile, cn=changelog subscriber, cn=oracle internet directory. This field is mandatory. There is no default.
   Synchronization Mode	Specify whether this is an import or an export operation. An import operation pulls changes from a connected directory into Oracle Internet Directory. An export operation pushes changes from Oracle Internet Directory into a connected directory. This field is mandatory. The default is IMPORT.
   ProfileStatus	Specify whether the profile is enabled or disabled. This field is mandatory. The default is ENABLE.
   Number of Retries	Specify the maximum number of times the directory integration server is to attempt synchronization before it disables synchronization. This field is mandatory. The default is 5. The first retry takes place 1 minute after the first failure. The 2nd retry happens 2 minutes after the 2nd failure, and subsequently the n-th retry takes place n minutes after the n-th failure.
   Scheduling Interval	Specify the number of seconds between synchronization attempts between a connected directory and Oracle Internet Directory. This field is mandatory. The default is 60.

5. Select the Execution tab and fill in the fields as explained in Table 28-6.

   Table 28-6  Description of Fields on the Execution Tab in Oracle Directory Manager

   Field	Description
   Execution Command	Specify the agent executable name and the arguments used by the directory integration server to execute the agent. This field is optional. There is no default. A typical execution command is of the form, odicmd user=%orclodipcondirAccessAccount pass=%orclodipcondiraccesspassword Where odicmd is the command to be executed (available in the PATH or specified as a complete path name), and user=%orclodipcondirAccessAccount pass=%orclodipcondiraccesspassword are the command-line arguments. The value to be passed for the user is derived from the attribute orclodipcondiraccessaccount, and the value to be passed for pass is derived from the attribute orclodipcondiraccesspassword. A typical example is given in the Oracle Human Resources agent.
   Connected Directory Account	Specify the account to be used by the connector/agent for accessing the connected directory. For example, if the connected directory is a database, the account might be Scott. If the connected directory is another LDAP-compliant directory, then the account might be cn=Directory Manager. This field is optional. There is no default.
   Connected Directory Account Password	Specify the password the connector/agent is to use when accessing the connected directory. This field is optional. There is no default.
   Additional Config Info	This field displays additional information that the directory integration server passes to an agent. You cannot modify this field through ODM. The only way to modify it is to use oidmuplf.sh. There is no default.
   Connected Directory URL	The URL of the connected directory, if available.
   Data Interface Type	The format used by the import or export file. Valid values are LDIF, DB, LDAP, or TAGGED. This field is optional. The default is TAGGED.

6. Select the Mapping tab and fill in the fields as explained in Table 28-7.

   Table 28-7  Description of Fields on the Mapping Tab in Oracle Directory Manager

   Field	Description
   Mapping Rules	This field displays the mapping rules for converting data between a connected directory and Oracle Internet Directory. There is no default. Note: You cannot edit the mapping rules file by using Oracle Directory Manager. You edit the mapping rules in a file manually and then upload it to the profile by using the provided script, oidmuplf.sh. See Appendix A, "Syntax for LDIF and Command-Line Tools"
   OIDMatchingRule	Specify the attribute that uniquely identifies records in Oracle Internet Directory. This attribute is used as a key to synchronize Oracle Internet Directory and the connected directory. This field is optional.
   ConnectedDirectorymatchingRule	Specify the attribute that uniquely identifies an entry in the connected directory.

7. Select the Status tab and fill in the fields as explained in Table 28-8. Since this shows the execution status of the connectors, most of the fields are not editable.

   Table 28-8  Description of Fields on the Status Tab in Oracle Directory Manager

   Field	Description
   OID Last Applied Change Number	For export operations, specify the identifier of the last change from Oracle Internet Directory that has been applied to the connected directory. The default is 0. The field can be consciously modified by the end user whenever appropriate. The profile should be in the disabled mode. If the number is increased, then any Change Log entries numbered between the original value and the new value will not be applied.
   Last Execution Time	The most recent absolute time that the agent was executed. The default is the time at which the connector is created. Modifying this field will be misleading.
   Last Successful Execution Time	The most recent absolute time that the agent succeeded. The default is the time at which the connector is created. Modifying this field will be misleading.
   Synchronization Status	Synchronization success/failure.
   Synchronization Errors	The last error message. You cannot modify this field. There is no default.
   ConnectedDirectory Last AppliedChangeNumber	The number of the Change Log entry that was most recently applied successfully to the connected directory. The field can be consciously modified by the end user whenever appropriate. The profile should be in the disabled mode. If the number is increased, then any Change Log entries numbered between the original value and the new value will not be applied.

8. When all edits under every tab of the Integration Profile dialog box are completed, click OK. This returns you to the Configuration Sets dialog box, which now lists the integration profile you just created.
9. Click OK to exit the Configuration Sets dialog box. The agent you created is now registered with Oracle Internet Directory.

Deregistering a Profile by Using Oracle Directory Manager

To delete a connector:

1. In the navigator pane, expand Oracle Internet Directory Servers > directory_server_instance> Server Management > Directory Integration Server.
2. Select the Configuration Set from which to delete the agent. The Integration Profiles tab page appears in the right pane.
3. In the Integration Profiles tab page, select the agent you want to deregister, then click Delete.

Managing Synchronization Profiles by Using Command-Line Tools

This section tells you how to register and deregister profiles. It contains these topics:

• Creating a Synchronization Profile by Using oidmcrep.sh
• Deregistering a Synchronization Profile Using oidmdelp.sh

Creating a Synchronization Profile by Using oidmcrep.sh

You can create a synchronization profile by using the command-line tool oidmcrep.sh. This tool is in the directory $ORACLE_HOME/ldap/admin/.

Deregistering a Synchronization Profile Using oidmdelp.sh

You can deregister a synchronization profile by using the command-line tool oidmdelp.sh. This tool is in the directory $ORACLE_HOME/ldap/admin/.