| Previous Contents Index Next |
| iPlanet Meta-Directory Configuration and Administration Guide |
Chapter 2 Meta-Directory Principles at Work
This chapter uses an example to show how to configure Meta-Directory to integrate three different external data sources into one unified meta view. In order to make this example compliant with the Windows NT or Solaris operating system, the sample uses data sources that work with both. These include an LDIF data file imported into a Directory Server, a CSV data file using the Universal Text Parser (UTP), and an Oracle database using the Database Connector. These data samples are small but the principles of working with them using Meta-Directory are the same as they would be for large bodies of data. This chapter includes the following sections:
The LDIF Data File
The LDIF Data File
An LDIF file is a text version of LDAP data. The following LDIF data is what will be imported into Directory Server. Once it is imported, the LDAP data sub-tree is directly accessible by Meta-Directory and would be considered a direct connection.
The CSV Data File
A CSV (comma-separated values) file is a text file format that can be output by a standard spreadsheet program. (Its name is derived from the fact that each record is stored in a single line with the individual items of data separated by commas.) The following CSV data will be imported into Meta-Directory via the UTP. (The UTP is considered an indirect connector as it is necessary to map the CSV file data to the Directory Server's LDAP schema before it can be read by Meta-Directory.)
The Oracle Database
Data stored in an Oracle database can be viewed in Meta-Directory with a Database Connector. The following data will be accessed from an Oracle 8 database via Structured Query Language (SQL). The Database Connector is considered a direct connector because it plugs directly into the join engine.
Employee ID
First Name
Last Name
Salary
Department ID
Background Information
Siroe, Inc. is a small company that outsources services. It currently has ten employees on its payroll. Personal and employment information on their employees is divided among three data sources. Siroe's Directory Server contains names and email addresses of five employees. Similar information for five consultants is in an Excel spreadsheet program. An Oracle database contains the salary information, employee numbers, and departments of all ten employees. Siroe needs to integrate all three of these sources and identify the employees by job function: four writers, three designers, and three accountants.The example assumes that iPlanet Directory Server and Meta-Directory have been installed and a join engine has been created.
Configuration of Connectors and Join Process Rules
Siroe, Inc. has hired a systems administrator, Tracy, to help with the integration of their data. Tracy decides to flow the data on Siroe's Directory Server first. The next steps are integrating the CSV file exported from Excel and then syncing the Oracle tables into Siroe's unified employee database.
Flowing LDIF Data to the Connector View
Siroe has two directory servers: one is an iPlanet Directory Server and the other is Netscape Directory Server 1.0. The Directory Server 1.0 is not completely compatible with Meta-Directory so Tracy exports its LDAP data to an LDIF file in order to import it into the newer iPlanet Directory Server. (The Netscape Directory Server will no longer be used; its place is taken by the iPlanet Directory Server.) Tracy creates an instance of the Universal Connector (UTC) from iPlanet Console which also adds a connector view for the data on the newer iPlanet Directory Server by:
Naming the instance: firstgroup
When Tracy refreshes the Directory Server and Meta-Directory consoles, the o=firstgroup LDAP sub-tree is visible in the navigation tree of the Directory Server and the firstgroup connector and connector view are visible in the navigation tree of Meta-Directory.Naming the base dn: o=firstgroup
Entering the LDAP URL of the Directory Server on which the data will be stored
- The LDIF file is already configured as uid=variable,o=firstgroup therefore, the base DN of our connector is input as o=firstgroup.
Once the connector view is created, Tracy imports the LDIF file into the connector view sub-tree via the iPlanet Directory Server by using the Import Database command from the Directory Server console.
Flowing LDAP Data to the Meta View
The LDIF data is now written to a LDAP Directory Server that is directly connected to the join engine. Therefore, Tracy can begin configuring the join process to flow the LDAP data through the join engine and into the meta view.by creating the rules to define how Siroe would like the data to flow.
Constructing an Attribute
destinationIndicator is an allowed attribute of the organizationalPerson object class so Siroe will use this attribute to keep track of an employee's off-site locations. Tracy, therefore, needs to put a value to this attribute. One way to do this is to take a value that is already present and break it into sub-tokens, enabling the use of these sub-tokens for other attributes. As their personnel's email address changes with each job, Tracy constructs an attribute with a value by:
Naming the constructed attribute: constructeddestinationIndicator
With this rule, Tracy deconstructs the email address field, variable@company.com into three tokens: variable, company and com. From these fields, %company% is chosen as the value for constructeddestinationIndicator that will sync with the LDAP destinationIndicator attribute indicating the employee's off-site location.
Mapping Attribute Flow Rules
After constructing the attribute, Tracy configures flow tables to match up the attributes from the LDIF/LDAP data to the attributes in Meta-Directory's schema. Attribute flow rules can be configured for two directions: from the connector view to the meta view and from the meta view back to the connector view. The LDIF/LDAP data contains the following attributes: objectclass, cn, sn, mail, title, uid, and givenname; in addition, Tracy needs to flow the constructed attribute constructeddestinationIndicator. Tracy creates attribute flow rules by:
Naming the rule: fg2mv
All attributes from the LDIF/LDAP data will flow to the same-titled attribute in the meta view (although Tracy could flow them differently if Siroe wanted different mappings). The constructed attributes are visible when Constructed Attributes is chosen from the source objectclass drop-down list. In this case, Tracy maps the constructeddestinationIndicator constructed attribute to the schema attribute destinationIndicator.Choosing the direction: To Meta View
Entering selection criteria: (%objectclass%==person)
Adding attribute mappings
- This specification means that any entry with an %objectclass%==person attribute/value pair will be selected and allowed to map its attributes.
- objectclass, cn, sn, mail, title, uid, givenname and constructeddestinationIndicator map respectively to objectclass, cn, sn, mail, title, uid, givenname and destinationIndicator
When the attribute mappings are complete, Tracy needs to create a rule set entitled affg2mvset and add the fg2mv rule to it. Since attribute flow rule sets can not contain rules configured for data that flows in opposite directions, Tracy must also make a separate rule and rule set to map the attributes from the meta view back to the connector view. He names them fg2cv and affg2cvset, respectively. (The difference between the two rules is that, in the latter case, Tracy does not want the constructed attribute to be flowed back to the connector view from the meta view and therefore does not map it.)
Creating the Entry's Distinguished Name
Tracy needs to configure the distinguished name (DN) for each entry. DN mapping rules create a place for each entry in the destination view. The first entry in the LDIF/LDAP data has as its source DN uid=aquinn,o=firstgroup. Tracy wants the meta view DN of this entry to be uid=aquinn,ou=Writers,o=firstgroup. The DN mapping rule is created by:
Naming the rule: fgwriter2mv
Tracy must now configure a rule for Accountants and Designers. The three completed rules, fgaccountant2mv, fgdesigner2mv and fgwriter2mv, are then added to one rule set that Tracy calls DNrulesfg2mv because they are all for flowing data to the meta view.Entering the selection criteria: ((%objectclass%==person) AND (%title%==Writer))
Constructing the DN: uid=%uid%,ou=Writers
- This specification means that any entry with %objectclass%==person and %title%==Writer attribute/value pairs will be selected and assigned the following DN.
- Tracy wants the unique identifier (in this case, aquinn) to be the unique name of each partial DN relative to the base DN. This DN construction creates the organization unit Writers in which all entries with title=Writer and objectclass=person will be placed.
Tracy then makes three more rules which flow the information back to the connector view, using as selection criteria cn in ou=Writers, ou=Accountants, and ou=Designers and constructing a DN of uid=%uid%, o=firstgroup. Tracy puts them in a rule set entitled DNrulesfg2cv. The two rule sets DNrulesfg2mv and DNrulesfg2cv will flow the LDAP data into and out of the meta view. Next, Tracy flows the CSV data into the meta view.
Mapping CSV Data to LDAP Using the UTP
The CSV data must be flowed into the connector view using the Universal Text Parser (UTP), so Tracy configures an instance of the Universal Connector (UTC) from iPlanet Console by:
Naming the instance: secondgroup
Tracy refreshes both consoles so that the o=secondgroup sub-tree is visible in the navigation tree of the Directory Server and the secondgroup connector view is visible in the navigation tree of Meta-Directory. Now, Tracy needs to convert the data in the CSV file into LDAP data using the Universal Text Parser's csv.cfg file.Naming the base dn: o=secondgroup
Entering the LDAP URL of the Directory Server on which the data will be stored
Entering an authenticating Distinguished Name and password
Entering the path name to the template.pl script included with Meta-Directory: NETSITE_ROOT/md50/utc-secondgroup/utp/template.pl
- The template.pl file is part of the UTP. It is a Perl script that tells the UTC what to do. It must be moved to the configured UTC's directory (entered in the path name above) from its default location at NETSITE_ROOT/bin/utc50/install/templates/universalparser/template.pl.
Mapping CSV Data to LDAP Attributes
The csv.cfg text file is used to map comma-separated values to LDAP attributes. Tracy finds the file and the task.cfg file in NETSITE_ROOT/bin/utc50/install/templates/universalparser. Tracy first copies the csv.cfg file to the task.cfg file. (task.cfg is called by template.pl but it needs to be configured specifically for CSV conversion into LDIF using the csv.cfg file.) Tracy edits the new version of task.cfg by editing the LineFormat and ImportLineFormat sections to map the CSV data attributes REALNAME, LASTNAME, EMAIL, PHONE, BUILDING, JOBTITLE, ALTERNATIVENAME and NICKNAME to the LDAP attributes cn, sn, mail, telephoneNumber, l, title, uid and givenName, respectively. Tracy also changes the InputFile section of csv.cfg to %ScriptBase%csv.data. Tracy then places the csv.data file and the modified task.cfg file in the directory with template.pl located at NETSITE_ROOT/md50/utc-secondgroup/utp/.
Mapping LDAP Attributes to the Connector View
Once the CSV data has been mapped to LDAP-recognized attributes within the csv.cfg file, these LDAP attributes need to be mapped to the LDAP attributes in the connector view using indirect connector rules. First, Tracy specifies the attributes defined in csv.cfg as attributes that are available to the connector. For this, each attribute name is entered on the connector's External Available Attributes panel. Once defined, the attributes are accessible for mapping data to and from the connector view attributes. Tracy can now create attribute flow rules for the indirect connector by:
Naming the rule: secondgroupflow
Tracy can now apply the indirect connector rule by selecting the utc-secondgroup indirect connector and its corresponding secondgroupflow rule.Choosing the mapping type: Mappings for Locally Owned Objects
Match the external attributes cn, sn, mail, telephoneNumber, l, title, uid and givenName To Connector View attributes cn, sn, mail, telephoneNumber, l, title, uid and givenName
- This choice identifies the rule as applying to data flow from the external source to the connector view.
Match the external attributes cn, sn, mail, telephoneNumber, l, title, uid and givenName From Connector View attributes cn, sn, mail, telephoneNumber, l, title, uid and givenName
Choosing the mapping type: Mappings for Connector View Owned Objects
Match the external attributes cn, sn, mail, telephoneNumber, l, title, uid and givenName To Connector View attributes cn, sn, mail, telephoneNumber, l, title, uid and givenName
- This choice identifies the rule as applying to data flow from the connector view to the external data source.
Match the external attributes cn, sn, mail, telephoneNumber, l, title, uid and givenName From Connector View attributes cn, sn, mail, telephoneNumber, l, title, uid and givenName
Note Again, in order to flow data in both directions, the attributes need to be mapped in both directions AND under each mapping type.
Flowing LDAP-configured CSV Data to the Meta View
From this point, Tracy follows the same procedure established for the LDIF/LDAP data. First, DN mapping rules are configured, selecting the entries and linking them to the DN as laid out in the table below.
Select entries that contain
Link entries to DN constructed as
Tracy names the rules sgwriters2mv, sgdesigners2mv and sgaccountants2mv and puts them in a rule set called DNrulessg2mvset. Whereas the LDIF file had employees identified by job title, the CSV data has them identified by building location with each building occupied by accountants, writers, or designers exclusively. These DN mapping rules place people in the correct sub-trees based on their building location.
Mapping LDAP-configured CSV Data to the Meta View
Attribute flow rules are needed to map the CSV/LDAP attributes in the connector view to the LDAP attributes in the join engine's meta view. Tracy creates attribute flow rules by:
Naming the rule: sg2mv
Tracy also creates a separate rule to map the attributes from the meta view back to the connector view; this is called sg2cv. Rule sets are created (afsg2mvset and afsg2cvset)to hold the two configured rules. With that done, all the rules needed to manage the flow of data from the CSV file are complete.Choosing the direction: To Meta View
Entering the selection criteria: (%objectclass%==person)
Adding attribute mappings
- This specification means that any entry with an %objectclass%==person attribute/value pair will be selected and assigned the following mappings.
- uid, objectclass, telephoneNumber, sn, mail, title, givenName and l map respectively to uid, objectclass, telephonenumber, sn, mail, title, givenname and l
Flowing Oracle Data to the Meta View
Tracy must now flow the Oracle data to the meta view. This data includes salary information and employee identification numbers. To make the flow possible, Tracy needs to configure the Oracle database as a Data Server that can be recognized by the Meta-Directory's join engine.
Note In order to bring Oracle data into Meta-Directory, the OCI libraries, available from Oracle, must be installed on the same machine in which the join engine is installed.
Configuring the Oracle Database as a Recognizable Data Server
In order to configure the Oracle database as a recognizable Data Server, Tracy accesses the Data Server panel from Meta-Directory console and completes the general information by:
Entering a name for the data server
Next, Tracy selects the tables and columns that will participate in the data flow by:Entering an alias for the data server
Entering a user name that does not already exist within the Oracle database
- This is the Oracle connect string.
Entering the path name to where the OCI libraries are installed
- This name will be used by Meta-Directory's Database Connector as the privileged user.
Choosing the Oracle columns for syncing
The name and location for the change log tables and triggers are also chosen. (Tuning and DCNS schedule use the default option.) When these selections are saved, a script is generated which, when applied to the database, enables change detection on the selected tables and columns. Tracy then runs the script on the command line via SQLplus (part of Oracle client software) and creates both the connector view and participating view from Meta-Directory console.
Choosing (or nominating) a primary key for Meta-Directory's use
- The Uninstrumented Columns are the full list of Oracle columns that Tracy will choose from. The Instrumented Columns are the ones Tracy has selected: EMPLOYEE_ID, FIRST_NAME, LAST_NAME, SALARY and DEPARTMENT_ID.
- The primary key is unique and not null among all the entries. Tracy chooses EMPLOYEE_ID.
Note The Oracle table data can never be seen through the Meta-Directory console. Only when the data is synced in the meta view can it be viewed.
Constructing an Attribute for the Oracle Database
When flowing data from an Oracle database, the objectclass attribute must always be constructed and flowed with the data as Oracle does not use object classes. Tracy creates an objectclass attribute by:
Naming the constructed attribute: dbobjectclass
Tracy also constructs a commonname attribute by:No selection criteria is necessary
Entering attribute construction: top;person;organizationalperson;inetorgperson
Naming the constructed attribute: dbcommonname
To complete the constructed attributes, Tracy puts each rule in a separate constructed attribute rule set entitled dbobjectclass and dbcommonname, respectively.Entering selection criteria: (%cv.FIRST_NAME%=@)
Entering attribute construction: %cv.FIRST_NAME% %cv.LAST_NAME%
- This specification means that any entry with a connector view value of FIRST_NAME will be selected.
- The dbcommonname will be made from the connector view's FIRST_NAME and LAST_NAME attributes.
Creating Attribute Flow Rules for the Oracle Database
Tracy can now create the attribute flow rules to map the Oracle columns to their counterpart LDAP attributes. This is done by:
Naming the rule: oracle2mv
This attribute flow rule is then put in an attribute flow rule set entitled oracle2mvset. An attribute flow rule going back to the Oracle column is also created (using the selection criteria %uid%=@) and put in a rule set entitled oracle2cvset.Choosing the direction: To Meta View
Entering the selection criteria: (%cv.EMPLOYEE_ID%=@)
Adding attribute mappings
- This specification means that any entry with a connector view value of EMPLOYEE_ID will be selected for these mappings.
- EMPLOYEE_ID, FIRST_NAME, LAST_NAME, SALARY, DEPARTMENT_ID, dbobjectclass and dbcommonname map respectively to uid, givenName, sn, description, departmentnumber, objectclass and cn.
Creating DN Mapping Rules for the Oracle Database
Tracy can now configure rules that will create DNs for the Oracle data. Three rules are needed to flow the data into the meta view's three organizational units. A DN rule for Writers is created by:
Naming the rule: oraclewriter2mv
This DN rule creates the organizational unit Writers in which all entries with an employee ID and a department ID of 10 will be placed. Tracy must now configure a different rule for accountants and designers. The three completed rules that apply to data flowing into the meta view are put into one rule set entitled DNrulesoracle2mvset.Entering the selection criteria: ((%cv.EMPLOYEE_ID%=@) AND (%cv.DEPARTMENT_ID%==10))
Constructing an DN: %cv.EMPLOYEE_ID%, ou=Writers
- This specification means that any entry with a connector view value of EMPLOYEE_ID and a department ID of 10 will be selected for this DN.
Tracy then makes three more rules which flow the information back to the connector view, using as selection criteria %mv.EMPLOYEE_ID%=@ and constructing a DN of %mv.EMPLOYEE_ID%. Tracy puts them in a rule set entitled DNrulesoracle2cv. The two rule sets DNrulesoracle2mv and DNrulesoracle2cv will flow the LDAP data into and out of the meta view.
Integration of the Data With Join Rules
With the bulk of the rules configured for the three data sources, Tracy is now able to flow the data into the meta view. Join rules need to be configured to synchronize the data correctly as each data source has different information flowing to the same meta view entry. Tracy needs to configure join rules that look at all source entries and link only those that have passed certain criteria. Tracy creates a join rule for the Oracle database by:
Naming the rule: oraclecv2mv
Tracy puts the Oracle join rule into a join rule set called oraclejrcv2mvset. For the LDIF data source the join rule is configured by:Entering the selection criteria: (%cv.EMPLOYEE_ID%=@)
Constructing the join filter: cn=%cv.FIRST_NAME% %cv.LAST_NAME%
- This specification means that any entry with a connector view value of EMPLOYEE_ID will be selected for joining.
Naming the rule: ldifcv2mv
Tracy creates a join rule set called ldifjrcv2mvset and the LDIF join rule is put into it. Tracy then realizes that the join rule created for LDIF data will also work for the CSV data source because they both have been converted into LDAP. Now Tracy is ready to apply the join process rules.Entering the selection criteria: (%objectclass%==person)
Constructing the join filter: cn=%cn%
- This specification means that any entry with an object class equal to person will be selected for joining.
Applying Rules to the Participating View
Tracy applies the join process rules to the correct participating views. (The participating view allows the connector view to `participate' in the join process.) From Meta-Directory console, a participating view for the firstgroup, secondgroup and oracle connector views is added. It is here that the join process rules are applied as follows:
Participating View
Join Process Rule
Rule Set Name
Once the join engine is started, the connectors are enabled and the views are refreshed, Siroe's LDIF data, CSV data and Oracle data will flow to the meta view forming one complete source of employee information.
At this point, Tracy checks the Meta-Directory error logs to see if any of the data has failed to flow or link. He does this by issuing the following grep command in the log directory:
Had any errors been found, Tracy could use the Fix-It Tool to manually link the orphaned entries. Fortunately for him no errors were found so Tracy steps outside for lunch.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated April 08, 2002