Oracle Internet Directory Administrator's Guide Release 3.0.1 Part Number A90151-01 |
|
This chapter discusses directory integration agents and the operations they perform in the Oracle Directory Integration platform. It explains how to manage partner agents by using either Oracle Directory Manager of command-line tools. It contains these topics:
This section contains these topics:
Agents are programs that perform one or more of the following operations, each of which is discussed in this section:
The following diagram shows the direction in which the data flows in each operation between Oracle Internet Directory and a connected directory. The remainder of this section describes each operation.
An Oracle Internet Directory export operation consists of:
A connected directory import operation consists of:
A connected directory export operation consists of:
An Oracle Internet Directory import operation consists of:
Synchronization uses combinations of the import and export operations as described in the previous section.
The exact operations involved in a given synchronization depend on whether changes are being applied from Oracle Internet Directory to a connected directory or the reverse.
This synchronization involves performing these operations in the following sequence:
The following diagram illustrates the direction in which data flows in each operation, from a connected directory to Oracle Internet Directory.
This synchronization involves performing these operations in the following sequence:
The following diagram illustrates the direction in which data flows in each operation, from Oracle Internet Directory to a connected directory.
Although an agent can perform one or many of the four operations discussed earlier in this section, it typically performs only connected directory import and connected directory export operations. It relies on the directory integration server to perform the Oracle Internet Directory import and Oracle Internet Directory export operations.
To exchange data between itself and the directory integration server, an agent uses import and export files. If an agent is designed to perform a complete synchronization by using its own resources, then it can bypass these files.
The Oracle directory integration server can perform Oracle Internet Directory import and export operations, including attribute mappings. Agents do not need to perform these operations. In addition, the directory integration server can schedule the execution of agents.
Depending on how it is deployed in the Oracle Directory Integration platform,an agent is known as either a partner agent or an external agent.
Partner agents use the services of the directory integration server to perform the Oracle Internet Directory import and export operations. Moreover, the directory integration server controls their execution.
In a typical synchronization, a partner agent performs either the connected directory import operation or the connected directory export operation. The Oracle directory integration server performs the Oracle Internet Directory import and export operations. However, agents may also perform tasks that the directory integration server would otherwise do. For example, an agent may itself map attributes instead of relying on the directory integration server to do it.
Before you can use a partner agent with the Oracle Directory Integration platform, you must register it with Oracle Internet Directory. To do this, you create a directory integration profile in Oracle Internet Directory by using either Oracle Directory Manager or command-line tools.
Partner agents performing export operations do not need to worry about changes getting purged before they are consumed. Oracle Internet Directory maintains state information about changes applied by various agents and preserves that information until all partner agents have consumed the changes.
Unlike partner agents, external agents are independent of the directory integration server when they perform Oracle Internet Directory export and import operations. Such agents are, for example, those that rely on third-party metadirectory engines for the same kinds of services that the directory integration server performs for partner agents.
Typically, an external agent performs a complete import or export synchronization. An external agent synchronizing from a connected directory to Oracle Internet Directory performs both the connected directory export and the Oracle Internet Directory import operations. Similarly, when synchronizing from Oracle Internet Directory to a connected directory, it performs both the Oracle Internet Directory export and the connected directory import operations.
External agents do not use the services of the directory integration server to synchronize between Oracle Internet Directory and connected directories. You do not need to register them with Oracle Internet Directory.
In export operations, external agents must use the standard LDAP change log interface to access change information from Oracle Internet Directory. It is the responsibility of the external agents to consume the changes in Oracle Internet Directory before those changes are purged.
To synchronize changes in Oracle Internet Directory with those in connected directories, the Oracle Directory Integration platform uses agents to retrieve changes in Oracle Internet Directory. Changes in Oracle Internet Directory are available in a container, called Change Log Container
. Changes in the change log container are uniquely identified by a change log number.
There are two interfaces for retrieving changes from Oracle Internet Directory, one for partner agents and one for external agents.
For partner agents, Oracle Internet Directory and the directory integration server keep track of changes already applied by an agent and those still pending. This is done by maintaining status information for each agent indicating the point up to which it has exported changes to the connected directory. This attribute, called orcllastappliedchangenumber
, is in the integration profile for the agent.
Oracle Internet Directory purges changes only after partner agents consume them.
In an export operation, the directory integration server updates the orcllastappliedchangenumber
attribute for the agent only after it successfully runs the agent. The directory integration server performs data mappings, then writes changes from Oracle Internet Directory into the export file. Agents then consume the changes by reading the export file.
For external agents, the directory server does not maintain status information. For such agents, the attribute orcllastchangenumber
in the root directory specific entry indicates the last change generated by the directory integration server.
Oracle Internet Directory makes changes available to external agents only for a period of time, after which it purges the changes. External agents must maintain their own status information about changes they have consumed and those still pending. They must consume the changes before the changes are purged.
To access changes in Oracle Internet Directory, external agents query the Oracle Internet Directory change log container. Typically, an external agent first retrieves the orcllastchangenumber
attribute from the DSE root. Then, based on the value of orcllastchangenumber
and the number of the last change applied, the external agent pulls changes not yet applied.
To find the last change number in Oracle Internet Directory, search the Oracle Internet Directory DSE root with a required attribute of orcllastchangenumber
. Use these specifications for the search:
SCOPE : BASE BASEDN : "" FILTER: `(objectclass=*)' REQUIRED ATTRIBUTE: orcllastchangenumber
To read a change log from Oracle Internet Directory, search with these specifications:
SCOPE : BASE BASEDN : "cn=changelog" FILTER: `(&(objectclass=changelogentry)(server=server-name)(changenumber>=change#))'
Before deploying a partner agent, you register it in Oracle Internet Directory. This registration involves creating a directory integration profile in the directory. This integration profile is stored as an LDAP entry in the directory. To create it, you can use either Oracle Directory Manager or command-line tools.
Attributes in an integration profile entry belong to an object class called 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.
Attribute | Description |
---|---|
General Information |
|
Agent Name ( |
Name of the agent. This is used as an RDN component of the DN that identifies the integration profile. The name can contain only alpha-numeric characters. |
Agent Control ( |
Indicator of whether the agent is enabled or disabled. Valid values are |
Agent Password ( |
Password that the directory integration server uses to bind to Oracle Internet Directory on behalf of the agent |
Agent Host Name ( |
Host on which the agent runs |
Synchronization Mode ( |
Direction of synchronization between Oracle Internet Directory and a connected directory. |
Scheduling Interval ( |
Number of seconds after which a connected directory is synchronized with Oracle Internet Directory |
Number of Retries ( |
Maximum number of retries that the directory integration server performs before disabling synchronization. |
Execution Information |
|
Agent Execution Command ( |
Agent executable name and argument list used by the directory integration server |
Connected Directory Account ( |
Account used by the agent for accessing the connected directory. It is passed by the directory integration server to the agent specified at the command line when the agent is invoked. |
Connected Directory Account Password ( |
Password to be used by the agent when accessing the connected directory. It is passed by the directory integration server to the agent specified at the command line when the agent is invoked. |
Agent Configuration Information ( |
Any configuration information which an agent wishes to store in Oracle Internet Directory. It is passed by the directory integration server to the agent specified at the command line when the agent is invoked. This information is stored as a binary attribute. The directory integration server does not modify this attribute, but passes it directly to the specified agent. |
Datafile Format ( |
The type of the import or export file, either |
Mapping Information |
|
Subscribed Domain ( |
DN of the subtree in Oracle Internet Directory to which an agent subscribes for all the changes it is to export |
DN Construct Rule ( |
Rule for generating the DN of an entry in Oracle Internet Directory from its RDN during an import operation. For example, you could specify that, for entries of the form |
Synchronization Key ( |
Attribute that uniquely identifies records in a connected directory. This is used as a key to synchronize Oracle Internet Directory and the connected directory. |
Attribute Mapping Rules ( |
Mapping rules for converting data from a connected directory to Oracle Internet Directory. This information is stored as a binary attribute. See Also: "Default Oracle Human Resources Agent Mapping Rules" for an example of mapping rules |
Mapping Filter ( |
Filter for excluding changes in Oracle Internet Directory that a connected directory does not require |
Status Information |
|
Next Synchronization Time ( |
Time when the agent is to be executed next. Its format is |
Synchronization Status ( |
Execution status of the agent |
Synchronization Errors ( |
Error message for the last error encountered. This is a multivalued attribute. |
Con Dir Last Applied Change Time ( |
Time when the last change from the connected directory was applied to Oracle Internet Directory.Its format is
The default is This attribute is mandatory. You can modify this attribute. |
Con Dir Last Applied Change Num ( |
For agents performing import operations, indicates the last change from the connected directory that has been applied to Oracle Internet Directory. |
OID Last Applied Change Number ( |
For export agents, the last change from Oracle Internet Directory that has been applied to the connected directory |
The various integration profile entries in the directory are created under the container cn=subscriber profile, cn=changelog subscriber, cn=oracle internet directory
. For example, an agent called OracleHRAgent is stored in the directory as orclodipagentname=OracleHRAgent,
.
cn=subscriber profile,cn=changelog subscriber,cn=oracle internet directory
An agent may need some configuration information at runtime for performing various operations. For example, to make it easier for users to specify which connected directory attributes are to be synchronized with Oracle Internet Directory, you may want an agent to store a list of these attributes as part of its configuration information. This kind of information is called agent configuration information.
You can store agent configuration information wherever and however you want. However, the Oracle Directory Integration platform enables you to store it as a binary attribute, called orclODIPAgentConfigInfo
, in the integration profile. The Oracle directory integration server passes this information as a temporary file to the agent at the time of the agent's invocation.
Agent configuration information is optional. If an agent does not require such information, then the corresponding attribute in the integration profile is left empty.
This configuration information can pertain to the agent or the connected directory or both. Oracle Internet Directory and the directory integration server do not read or modify this information, but pass it directly to the agent.
See Also:
|
Mapping rules govern the conversion of attributes between a connected directory and Oracle Internet Directory. There is one set of mapping rules for each connected directory. This set is stored as a binary value in an attribute called orclODIPAttributeMappingRules
in the integration profile in Oracle Internet Directory.
The directory integration server uses these rules to map attributes, as necessary, when generating an export file or interpreting an import file. When the directory integration server imports changes into Oracle Internet Directory, it converts the connected directory change records into LDAP change records, following the mapping rules specified in the integration profile. Similarly, when the directory integration server exports changes from Oracle Internet Directory, it converts the Oracle Internet Directory change records into connected directory change records, following the mapping rules specified in the integration profile.
An agent is not required to use the mapping function of the directory integration server. This could be the case, for example, when an agent does not use the import or export file interfaces, or when it does use import or export files of type LDIF. In such cases, the agent performs its own mappings and the orclODIPAttributeMappingRules
attribute in the integration profile is left empty.
The Oracle Directory Integration platform supports both one-to-many and many-to-one mappings.
Mapping rules are organized in a fixed tabular format, and you must follow that format carefully. The fields are delimited by a colon (:). The first line consists of fixed column headers. Do not change the column names. For each conndirattrname
and oidattrname
pair, you define only one mapping.
Each record in the mapping configuration file uses the following format:
OIDCLASSNAME:OIDATTRNAME:OIDATTRTYPE:CONNDIRCLASSNAME:CONNDIRATTRNAME:CONNDIRATT RTYPE:MAPPINGRULE
Table 23-2 describes the columns.
The following table lists and describes the mapping rules for importing into Oracle Internet Directory:
These files store data extracted from either a connected directory or Oracle Internet Directory. The platform uses them to exchange data between Oracle Internet Directory and connected directories.
Import files contain changes from the connected directory. Export files contain changes from Oracle Internet Directory.
Oracle Internet Directory release 3.0.1 supports tagged and LDIF files only.
In these files, each record consists of a tag and value pair separated by a colon (:). A multivalued attribute is represented by multiple rows with the same tag.
The following example of a tagged file contains attributes of an employee record:
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
A partner agent can exchange data with the directory integration server by using an LDIF file. In this case, the agent--not the directory integration server--performs the attribute mappings.
In an import operation from a connected directory into Oracle Internet Directory, the agent can map attributes and generate the import file in LDIF for the directory integration server. In an export operation from Oracle Internet Directory into a connected directory, the directory integration server can create an export file in LDIF, leaving the agent to map the attributes.
All filenames correspond to the name of the agent, as in the following table:
File | Filename |
---|---|
Data file |
Agent_Name |
Error file |
Agent_Name |
Agent configuration file |
Agent_Name |
Mapping rules file |
Agent_Name |
For example, the datafile name of the Oracle Human Resources agent is oraclehragent.data
.
This table tells you where to find the various files:
This section contains these topics:
This section tells you how to register and deregister a partner agent by using Oracle Directory Manager.
Oracle Directory Manager enables you to register a partner agent in one of two ways:
To register an agent:
Table 23-3 Description of Fields on the General Tab Page in Oracle Directory Manager
Table 23-4 Description of Fields on the Execution Tab in Oracle Directory Manager
Table 23-5 Description of Fields on the Mapping Tab in Oracle Directory Manager
Table 23-6 Description of Fields on the Status Tab in Oracle Directory Manager
To delete an agent:
This section tells you how to register and deregister agents by using the script ldapcreateConn.sh
.
You can register an agent by using the command-line tool ldapcreateConn.sh
. This tool is in the directory $
ORACLE_HOME
/ldap/admin/
.
The following example registers an agent named HRMS
in configuration set 2 (config 2
):
ldapcreateConn.sh name HRMS [ -host MyHost] [port 389] binddn cn=orcladmin pass welcome data TST -acct apps -pwd apps -ldapctx dc=hr,dc=metadirectory,dc=com config 2
When the integration server is invoked for configuration set 2, this agent is run. You can see a full description by invoking ldapCreateConn.sh with the -help
argument.
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
|
Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|