29
Directory Synchronization

This chapter discusses synchronization, which uses the first of the two types of integration profiles: 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 the following topics:

• About Connectors and Directory Integration Profiles

• Managing Synchronization Profiles

• Managing Connectors from the Command Line

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

About Connectors and Directory Integration Profiles

This section contains these topics:

• Connectors

• Directory Synchronization Profiles

• Directories with Unique Formats

• Synchronization Scenarios

• 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 Directory Integration Profile, which contains all the configuration information required for synchronizing data between Oracle Internet Directory and a connected directory. This is all that one needs for synchronizing between Oracle Internet Directory and a connected directory if the connected directory can support one of the interfaces supported by DIP for exchanging data. One example is the iPlanet Connector that is shipped with the Oracle Internet Directory product. The iPlanet connector consists of just a pre-packaged Integration profile, because the data between Oracle Internet Directory and iPlanet Directory can be synchronized using the LDAP interface supported by Oracle Directory Integration platform.

A connector may also include an agent. This is required if the connected directory can not directly support the interface supported by DIP for exchanging data. The agent would transform the data from one of the data formats supported by DIP into a format supported by the connected directory. An example is the Oracle HR Connector, which consists of a prepackaged Integration profile and an HR agent. This agent uses the "Tagged File" format supported by DIP to communicate data with Oracle Internet Directory, and it uses SQL (through OCI interface) to communicate with the Oracle Human Resources system.

Directory Synchronization Profiles

A directory integration profile for synchronization is called a directory synchronization profile. It contains all the configuration information required for synchronization--for example, the name and type of an agent, how and when to invoke it, the mapping information required for synchronizing entries and attributes.

Some connected directories only receive data from Oracle Internet Directory, and do not supply data to Oracle Internet Directory. Others supply data to Oracle Internet Directory but do not receive data from Oracle Internet Directory. Some directories both supply data to and receive data from Oracle Internet Directory. A separate profile is used for each direction, that is, for information coming into Oracle Internet Directory and for information going from Oracle Internet Directory to the connected directories.

Some connected directories can receive data in any of the interfaces built into Oracle Internet Directory for synchronization. These interfaces currently include the PL/SQL, LDAP, tagged, and LDIF interfaces. For these connected directories, the Directory Synchronization Service performs the synchronization itself, directly, using the information stored in the profile.

Changes requiring synchronization can occur in Oracle Internet Directory or in a connected directory. The Directory Synchronization Service (DSS) 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 DSS 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 use of an agent, that need is specified in the profile and the agent is automatically invoked.

Directories with Unique Formats

Some connected directories cannot receive data using any of those interfaces. The profiles for this type of directory contain an attribute identifying a separate program to be used to accomplish the 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 Directory Synchronization Service invokes the agent identified in the profile to perform the synchronization.

When exporting synchronization data from the Oracle Internet Directory for import into this type of connected directory, the 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 synchronization data from this type of connected directory for import into the Oracle Internet Directory, the agent creates the necessary tagged or LDIF format file. The Directory Synchronization Service then uses this file of connected directory data to update the Oracle Internet Directory.

Synchronization Scenarios

Synchronization can occur in either direction, i.e., from a connected directory to Oracle Internet Directory or 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 Directory Synchronization Service processes a synchronization profile, it retrieves the number of the Change Log entry last used to update the corresponding connected directory. Checking each Change Log entry after (more recent than) that number, the Service 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, identifying 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 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 Directory Synchronization Service then uses this file of connected directory data to update the Oracle Internet Directory.

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 in the directory. This synchronization profile is stored as an LDAP 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 accountname, password, hostname, portnumber--is stored in the synchronization profile. However, if the connector execution requires any additional information, it can be stored in the orclOdipAgentConfigInfo attribute discussed in the section "Additional Connector Configuration Information" later in this chapter.

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

The Object ID prefix 2.16.840.1.113894.7 is assigned to platform-related classes and attributes. The following table lists all the attributes in the Oracle Directory Integration platform profile.

Table 29-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)	IMPORT/EXPORT. Import implies changes from the connected directory are imported to Oracle Internet Directory. Export implies changes from the Oracle Internet Directory are extracted and given to the connected directory.
SchedulingInterval (orclOdipSchedulingInterval)	The interval with which the connector has to synchronize.
Number of Retries (orclodipSyncRetryCount)	Maximum number of times the agent or synchronization will be attempted in case of failure. By default, the Directory Integration Server tries the synchronization a maximum of 5 times. The first retry takes place 1 minute after the first failure, 2nd retry happens 2 minutes after the 2nd failure and subsequently the n-th retry takes place after n minutes after the n-th failure.
ProfileVersion (orclVersion)	Identifier indicating the Integration Profile version. It has a value 1.0. If this field has a value other than 1.0, the profile will not be 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. Typical usage of passing it in the command-line is illustrated in Chapter 33, "Synchronization with Oracle Human Resources".
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 id in the HR database. For other connectors, it can be passed as a commandline argument when the connector is invoked. Typical usage of passing it in the commandline is illustrated in Chapter 33, "Synchronization with Oracle Human Resources".
ConnectedDirectory AccountPassword (orclOdipConDirAccessPassword)	Password to be used by the userid specified by 'ConnectedDrectoryAccount' to connect to the connected directory. For instance, for the Iplanet Synchronization Connector, it is the valid bindpassword in the iPlanet directory. For Hragent, it is the HR 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 hostname and portnumber as, "host:port". Similarly for DB this can be used in the form of 'Host:port:oraclesid'.
Interface Type (orclodipDataInterfaceType)	The data format or protocol used in synchronization. The four supported values are: 1. LDIF - Import/Export from a LDIF File 2. Tagged - Import/Export from a Tagged File - a proprietary format supported by the Integration server, similar to LDIF format The details are discussed in Appendix A, "Syntax for LDIF and Command-Line Tools". 3. LDAP - Import/Export of the data from/to a LDAP compliant directory. 4. DB - Import/Export of the data from/to a RDBMS 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/profilename.cfg' which 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. Mapping rules are discussed in greater detail in Mapping Rules and Formats on . See Also: "Default Oracle Human Resources Connector Mapping Rules" for an example of mapping rules.
ConnectedDirectoryMatchingFilter (orclOdipConDirMatchingFilter)	Attribute used to filter changes made to Oracle Internet Directory to select those to be applied to the connected directory.
OIDMatchingFilter (orclOdipOIDMatchingFilter)	Attribute used to filter changes made to the connected directory to select those 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 a 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/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 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

While the synchronization profile stores most of the information needed by a connector to synchronize Oracle Internet Directory data with connected directories, some connectors may need more. 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: 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 using the script named ldapUploadAgentFile.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 or to the connected directory or both. Oracle Internet Directory and the Oracle directory integration server do not read or modify this information. When the connector is invoked, the Oracle Directory Integration Server simply passes to it the information in this attribute, as a temporary file.

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/

See Also: "Location and Naming of Files" for the names of these files

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 govern the conversion of attributes between a connected directory and the Oracle Internet Directory. Each connector has a set of mapping rules stored in the orclodipAttributeMappingRules attribute of its synchronization profile.

The the Oracle directory integration server uses these rules to map attributes as needed when exporting data from the directory and interpreting the data imported from a connected directory or file. When the Directory Integration Server imports changes into the 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.

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 below:

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 "###" (without the quotes). 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]:[AttrMapping Rule2]
  ###

  where the expansion of each <srcAttrName1> and <srcAttrName2> would each 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 29-2, "DomainRule Components".

Table 29-2 DomainRule Components

Component Name	Meaning and Use
SrcDomainName	This entry gives the name of the domain/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. Since import/export always refers to Oracle Internet Directory, a combination of NONLDAP:NONLDAP is not allowed.
DomainMappingRule	This field is meaningful only in import to Oracle Internet Directory, or in export to LDIF file or to another external LDAP directory. This rule is used for constructing the destination dn from the source domain name and/or the attribute given in AttributeRules. 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) that are described in Table 29-3, "Components in Attribute Rules". The attribute rule specifications end with a line containing only the characters "###" (without the quotes).

Table 29-3 Components in Attribute Rules

Component	Discussion
SrcAttrName	For LDAP directory repositories, this parameter refers to the name of the attribute to be translated. For RDBMS repositories, it refers to the ColumnName in the table specified by the SrcClassName. For other repositories this parameter can be appropriately interpreted.
ReqAttrSeq	This field indicates whether the source attribute must always be passed on to the destination. When entries are synchronized between the directory and the connected directory, some attributes need to be used as synchronization keys. This field is to indicate whether the specified attribute is being used as a key. If so, irrespective of whether the attribute has changed or not, the value of the attribute is always extracted from the source. A non-zero 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 (integer, String, binary, etc.), which will be helpful in validating the mapping rules, i.e., validating the equivalency of the Source and Destination attribute types. (In the current Release, this field is ignored.)
SrcObjectClass	If the source of the attribute being shared is an LDAP directory, this parameter names the object class to which the attribute belongs. If the source of the attribute being shared is an RDBMS repository, this parameter refers to the TableName. (This specification is mandatory for LDAP or RDBMS.) For other repositories, this parameter may be ignored.
DstAttrName	This is optional. If it is not specified, the SrcAttrName will be assumed. For LDAP directory repositories, this parameter refers to the name of the attribute at the destination. For RDBMS 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 (integer, String, binary, etc.), which will be helpful in validating the mapping rules, i.e., validating the equivalency of the Source and Destination attribute types. (In the current Release, this field is ignored.)
DstObjectClass	For LDAP directory repositories, this parameter refers to the object class to which the attribute belongs, and is optional. For RDBMS 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, the source attribute value is copied as the value of the destination attribute.

OrclodipAttributeMappingRules is a single valued attribute in the directory. It needs to follow a fixed format. Therefore, editing the mapping rules in ODM is not feasible.

To overcome this, mapping rules are stored in a file, and the file is uploaded to the directory as a value of the attribute. The utility ldapUploadAgentFile.sh can be used for uploading the mapping file.

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/

In a newly created synchronization profile, mapping rules will be empty. To enter mapping rules, edit a file which strictly follows the format given in the previous section.

Here is a sample mapping file that can be used to import HR data from the Oracle HR Database tables using TaggedFile Interface. (This 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 following explanations may help you understand the sample file. It contains the domain rule NONLDAP:dc=metaagt,dc=com:cn=%,dc=metaagt,dc=com. This rule implies that the source domain is NonLDAP, indicating 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 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 multi-valued 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. Objectclass to which the attribute belongs to - it is mandatory while using a Import with Tagged File interface.

Similarly, the rule email: : : :cn: : person: trunc(email,'@')

implies applying the mapping rule of truncating all the characters off of `email' 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 using ldapsearch. For usage of the ldapsearch command, see Appendix A. The entry to be searched for is `orclodipagentname=<ProfileName>,cn=subscriber profile,cn=changelog subscriber,cn=oracle internet directory' for the attribute `orclodipattributemappingrules'.

The Oracle Directory Integration platform supports both one-to-many and many-to-one mappings.

• One-to-many mapping

  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 mapping

  Multiple attributes in a connected directory may map to one attribute in Oracle Internet Directory. For example, suppose that the 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 using an ldapsearch command as described in Appendix A, "Syntax for LDIF and Command-Line Tools".

orclodipAttributeMappingRules is a single-valued attribute in the directory, which needs to follow a fixed format. Hence editing the mapping rules in ODM is not feasible. To overcome this, mapping rules are stored in a file that is uploaded to the directory as a value of the attribute. The utility ldapUploadAgentFile.sh can be used to do this. Once the mapping file is created and uploaded, a copy of the file can be maintained in the $ORACLE_HOME/ldap/odi/conf directory, and uploaded again after any future update.

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/

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 ldapUploadAgentFile.sh tool.

   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/

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 ldapUploadAgentFile.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 ldapUploadAgentFile.sh tool to load the attribute mapping rule file into the synchronization profile.

Location and Naming of Files

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

Table 29-4 Location and Names of Files

File	File Name
Import DataFile	$ORACLE_HOME/ldap/odi/data/import/ProfileName.dat
Export Data File	$ORACLE_HOME/ldap/odi/data/export/ProfileName.dat
TraceFile	$ORACLE_HOME/ldap/odi/log/ProfileName.trc
Additional Configuration Info	$ORACLE_HOME/ldap/odi/conf /ProfileName.cfg
Mapping Rules	$ORACLE_HOME/ldap/odi/conf /ProfileName.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 Connectors from the Command Line

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 29-5.

   Table 29-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.
   Agent Execution Host	The host on which the agent is to be executed.

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

   Table 29-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 pathname), and user=%orclodipcondirAccessAccount pass=%orclodipcondiraccesspassword are the commandline 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 HR 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 ldapuploadagentfile.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 29-7.

   Table 29-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, ldapUploadAgentFile.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 29-8. Since this shows the execution status of the connectors, most of the fields are not editable.

   Table 29-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 Connectors from the Command Line

This section tells you how to register and deregister agents by using the script ldapcreateConn.sh.

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/

Creating a Synchronization Profile with the Command-Line Tool

You can create a synchronization profile by using the command-line tool ldapcreateConn.sh. This tool is in the directory $ORACLE_HOME/ldap/admin/. The lines below show the syntax for this tool; Table 29-9 explains its arguments.

LdapcreateConn.sh -name <Agent Name> \
[ -type <IMPORT | EXPORT > ] [ -agentpwd < Agent Password> ] \
[ -config <which configset to associate to > ] \
[ -LDAPhost <LDAP server host> ] \
[ -LDAPport <LDAP server port> ] \
[ -binddn SuperUserDN (default cn=orcladmin ) ] \
[ -bindpass Bindpassword (default=welcome) ] \
[ -retry <Max Retry Count on synchronization Errors > ]\
[ -poll < Polling Interval For Synchronization> ] \
[ -host < Host on which to run Agent> ]
[ -conndirurl < Connected Directory URL > ] \
[ -conndiracct < Connected Directory Acct Info > ]\
[ -conndirpwd < Connected Directory Acc Pwd> ] \
[ -execmd < Command Line for the Agent > ]\
[ -iftype < Interface Type > ] \
[ -condirfilter < Connected Directory Matching Filter> ]\
[ -oidfilter < OID Matching Filter > ] \
[ -U <SSL Authentication Mode> ]\
[ -W <Wallet location> ] [ -P <Wallet password> ]

Table 29-9 Arguments for ldapcreateConn.sh to Register a Partner Agent

Argument	Description
Name	The Name of the Integration Profile.This has to be unique.
Type	IMPORT/EXPORT. The default is IMPORT/
Agentpwd	The password to protect the profile. The default is `welcome'.
Config	The configuration set number. The default is 1.
LDAPhost	The LDAP Server host. The default is the current host.
LDAPport	The LDAP server port The default is port 389.
Binddn	The BIND DN of the Directory user which has the privileges to create Integration profile. The default is `cn=orcladmin'
Bindpass	The BIND password. The default is `welcome'
Retry	Maximum number of retries to be done by the server on encountering a synchronization error. The default is `5'.
Poll	The scheduling interval of the profile. The default is `60' seconds.
Host	This is currently used. For the time being, it should be set to the machine name on which the DIP server is executing.
Conndirurl	The Connected Directory access Information.
Conndiracct	The Connected Directory account.
Conndirpwd	The Connected Directory account password
Execmd	The OS command line to execute the partner agent.
Iftype	The Interface Type. The default is TAGGED.
Condirfilter	The Connected Directory Matching Filter
Oidfilter	The Oracle Internet Directory Matching Filter.

When the integration server is invoked with configuration set 2 in this command line argument, this agent is run. You can see a full description by invoking ldapCreateConn.sh with the -help argument.

Deregistering a Profile Using ldapdeleteConn.sh

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

The following example deregisters an agent entry and dissociates it from the configuration set 2 (config 2) entry:

ldapdeleteconn.sh name HRMS config 2