Sun logo      Previous      Contents      Index      Next     

Sun ONE Meta-Directory 5.1.1 Administration Guide

Chapter 1
Configuring the Join Engine

This chapter contains information about the Join Engine, the core component of Meta-Directory. Join Engine links data and manages the flow of information from the Connector View to the Meta View, and back to the Connector View.

This chapter includes the following sections:


Join Engine Overview

The Join Engine is the central component of the Sun ONE Meta-Directory system. It directs the synchronization of data between one or more Connector Views and the Meta View. It can be configured to allow data to flow to either the MetaView or Connector View. The Join Engine monitors the changelog in the Connector Views for changes and then, based on the configuration acts on the changes; this includes flowing these changes to the Meta View. In addition, the Join Engine also monitors the Meta View changelog for changes and can be configured to incorporate the changes back to the Connector Views.

For example, if information from a Human Resources database that contains a change in an employee’s address enters the Join Engine, then, the Join Engine relays this change to the Meta View. The change is then made in the address attribute of the user’s Meta View entry and flows back to reflect this change in other Connector Views where the entry could also be linked too.


Creating the Join Engine Instance

You can create a single instance of the Join Engine in a server group. (A server group consists of one or more servers that share a root directory and are managed by a common instance of the Administration Server.) The instance is created from the Sun ONE Console. General server information, such as the base DN of the Meta View and Directory Server URL, is required to create the instance.

It also requires enabling the Directory Server retro-changelog plug-in; you must restart the Directory Server before this change becomes active.

    To create a Join Engine instance
  1. From the Sun ONE Console, right-click Server Group.
  2. Choose Create Instance Of > Meta-Directory Join Engine.
  3. The ‘New Instance Creation’ dialog box displays.
    Figure shows the options available in the ’New Instance Creation’ dialog box.

  4. Enter appropriate values for fields as described:
  5. Table 1-1  Description of the options and the tasks to perform for each option

    Field

    Do This

    View Name

    Enter a name for the Meta View associated with this Join Engine.

    View ID

    Enter no more than five characters to represent a view ID that is unique in the system. The default is MV.

    View Base DN

    Enter the base DN under which the view’s information will be stored. If this suffix does not exist, the default created is o=MV. Creating the root suffix in the Directory Server before initiating the Join Engine is recommended.

    Data Server URL

    Select a Directory Server from the list box or type in a new one on which the Meta View will be stored.

    Data Server Bind DN

    Enter a DN that the Join Engine will authenticate to the Directory Server.

    Data Server Bind Password

    Enter the password associated with the authenticating DN.

  6. Click OK. A message is displayed with changelog options.
  7. Changelog is a file that summarizes changes made to a server. Directory Server retro-changelog writes the changelogs in a subtree (cn=changelog). This is a separate (backend) database in the Directory Server.

  8. Select one of the following options:
    • Enable Changelog NOW.
    • The ‘Enable Changelog’ dialog box displays. Enter the directory path to store the changelog and accept the default Changelog Suffix or enter an appropriate value. Click OK. (A message suggesting that you must restart the Directory Server is displayed. For more information, see the Meta-Directory Deployment Guide.)

    • Enable Changelog LATER.
    • It is recommended that you enable the changelog now. For details on enabling the changelog after the instance is created, see Sun ONE Directory Server documentation. The process for doing this in Directory Servers 4.1x and 5.x is different.

    • Abort Instance Creation.
    • Stops the instance creation process.


      Note

      In the Solaris Operating System, Directory Server is normally installed as root. Thus, the permissions of the directory must be changed to allow the Console to create the changelog directory. Execute the chmod -R 777 command against the directory (location of the changelog).


  9. Click ‘Yes’ when prompted, if this Directory is a new data server in Meta-Directory. This loads the Meta-Directory schema extensions into the Directory hosting the Meta View suffix.
    To remove a Join Engine instance
  1. From the Sun ONE Console, right-click the Join Engine instance.
  2. Click Remove Server, and then click Yes.
  3. The Join Engine instance is deleted.


    Note

    Flow rules defined for the Join Engine are stored in the o=netscapeRoot suffix in the Configuration Directory. Thus, flow rules are not deleted if the Join Engine instance is deleted.



About the Join Process

The join process is the transfer of data, through a sequence of configured rules and filters and administered by the Join Engine, to determine how Connector View entries will be linked in the Meta View. To successfully join Connector View entries, the Join Engine must match each Connector View value with atleast one corresponding value in the Meta View. To do this, rules containing values and attributes are used as criteria for finding and creating links. The rules include join rules, attribute construction definitions, attribute flow rules, filters, and DN mapping rules.

Join Process Rules and Rule Sets

Before beginning configuration, you should be familiar with the concept of join process rules and rule sets. Join process rules contain values and attributes that are used as criteria for moving data through the Join Engine and linking the data in the Meta View. For the join process, rules are configured and then placed in rule sets. These sets are applied when setting up the Participating View. After they are applied, the rules are used by the Join Engine to steer the join process.

Rule Sets

A rule set contains an ordered group of configured rules which are sequentially tested until either one of two things occur:

It is important to remember that each rule set should be made up of rules that search through entries flowing in one direction. Thus, do not add a rule that searches through entries flowing to the Meta View to a rule set that already contains a rule that searches through entries flowing to a Connector View.

Join Process Rules

A configured rule consists of one or more of these three operator strings:

The operators are executed in the order stated. The Format Operator is recognized first so that sub-tokens can be created. The entries are then checked by the Requirements Operator. The entries that contain the proper selection criteria are then searched by the Substitution Operator for those that match the query. For additional information regarding these operators, see Appendix A, "Join Process Operators."

Optional Token Assignments (Format Operator)

The format operator string is an optional field that specifies the format for attributes which consist of multiple values. It is used to break up an attribute’s value into separate, more specific values. Values can be divided into sub-tokens for use in the configuration of other rules. For example, the value of the attribute {cn}=%last,first% can be separated into two values by entering {cn}=%last%,%first% in the optional token assignment field.These sub-tokens (%last% or %first%) are then used as attributes for placement in other rules. (When this field is left empty, all pairs default to their entire source value.)

Selection Criteria (Requirements Operator)

The requirements operator string specifies conditions that are applied to a source entry; the conditions must evaluate to TRUE for the entry to pass to the next operator. Join rules, DN mapping rules, constructed attributes and attribute flow rules include the Selection Criteria option. The ‘Compose Selection Criteria’ dialog box helps you to configure the specifications which are used to determine if the particular rule for which they are configured should be applied against the entry being flowed. If the entry does not meet the required condition (for instance, objectclass==person), the entry will not be synchronized.

Figure displays ’ComposeSelection Criteria’ dialog with specifications which are used to determine a particular rule.

Selecting the option to make a new rule from the join rules, DN mapping rules, constructed attributes or attribute flow rules screens and clicking the (...) button displays ‘Compose Selection Criteria’ dialog box. This helps you to set conditions against entries or attributes:

    To compose entry conditions
  1. From the ‘Compose Selection Criteria’ dialog box, select Entry as the Type.
  2. The available fields for the Entry conditions.
    Figure displays the options for ’Entry’ conditions.

  3. Enter appropriate values as described in the following table:
  4. Table 1-2  Description of the options and the tasks to perform for each option

    Field

    Do This

    Property

    Select Operation and the condition selects entries based on whether or not the join, add, update, or delete action is true or false. Select CV or MV and the condition selects entries based on where the entry will flow from or to. The entry will synchronize if the value ID is equal or not equal to the property ID.

    Expression

    Select an expression to describe the relationship between the Property and the Value. The Expression list box contains two choices: Equal and Does Not Equal.

    Value

    Provide a value to complete the expression.

  5. Click Insert. The composition is displayed in the Conditions list window.
  6. Optional: Add other conditions if required.
  7. Optional: Modify the conditions using the options at the right as described in "Combining conditions".
  8. Click OK to save the conditions.
    To compose attribute conditions
  1. Select Attribute as the Type.
  2. The available fields for the Attribute conditions:
    Figure shows the options for ’Attribute’ conditions.

  3. Enter appropriate values in the fields as described in the following table:
  4. Table 1-3  Description of the options and the tasks to perform for each option

    Field

    Do This

    Source

    Choose the source for the attribute from the list box. The list includes all configured connector and Meta Views plus Default. Choose Default if you want all sources.

    Attribute

    Choose an attribute used in the source schema.

    Expression

    Select an expression that describes the relationship between the attribute and the value. The expressions in the list box are self-explanatory except for these two:

    • Constructed From is for use with constructed attributes. As an example, the following constructed attribute is defined
      description = %title%,%telephonenumber%
      To specify an attribute telephonenumber, an Expression of Constructed From, and a value of description would be used. When the Join Engine applies the selection criteria, it searches for description to specify telephonenumber
    • Free Format appends to anything you type in the Value field. Do not use Free Format to type description @ AND cn @ in the Value field. These values should be selected using the list boxes. (When using this option, be aware of your use of the space bar.)

    Value

    Provide a value to complete the expression, if applicable.

  5. Click Insert. The composition is displayed in the Conditions list window.
  6. Optional: Add other conditions if required.
  7. Optional: Modify the conditions using the options at the right as described in "Combining conditions".
  8. Click OK to save the conditions.
    To compose language-tagged attribute conditions
  1. Select Language Tagged Attribute as the Type.
  2. The available fields for the Language Tagged Attribute conditions:
    Figure shows the options for the Language Tagged Attribute conditions.

  3. Enter appropriate values in the fields as described in the following table:
  4. Table 1-4  Description of the options and the tasks to perform for each option

    Field

    Do This

    Source

    Select the source for the attribute from the list box. The list includes all configured connector and Meta Views and the default values. Select Default if you want all sources.

    Attribute

    Select an attribute used in the source schema.

    Expression

    Select an expression that describes the relationship between the attribute and the value. The expressions in the list box are self-explanatory except for these two:

    • Constructed From is for use with constructed attributes. As an example, the following constructed attribute is defined
      description = %title%,%telephonenumber%
      To specify an attribute telephonenumber, an Expression of Constructed From, and a value of description would be used. When the Join Engine applies the selection criteria, it searches for description to specify telephonenumber.
    • Free Format appends to anything you type in the Value field. Do not use Free Format to type description @ AND cn @ in the Value field. These values should be selected using the list boxes. (When using this option, be aware of your use of the space bar.)

    Value

    Enter a value to complete the expression, if applicable.

    Supported Language Subtypes

    Select a language subtype. For more information, see "Language Subtype Tagged Attributes".

    Add Phonetic Subtype

    Select to indicate that the attribute value is a phonetic representation. For example, givenname;lang-ja;phonetic indicates that the attribute value is the phonetic version of the entry's Japanese name.

  5. Click Insert. The composition is displayed in the Conditions list window.
  6. Perform Step 1 through Step 3 to add other conditions - if required.
  7. Optional: Modify the conditions using the options at the right as described in "Combining conditions".
  8. Click OK to save the conditions.
    Combining conditions

You can combine configured conditions at any time using one or more of the operator buttons on the right side of the window. For instance, to combine the first two of the following conditions with an AND operator, you would select them and click AND.

Figure shows the ’AND’ condition.

The system would respond as shown:

Figure shows the result of the ’AND’ condition.

To add the third condition with an AND operator and nest the first two, you would select the already combined conditions and the third condition and click AND. The system would respond as shown:

For definitions of the combining operator buttons, see "Combining Requirements Operators".


Note

If single requirements are inserted without the use of the logical operator buttons, the requirements appear in the Selection Criteria box delineated by a semi-colon. The semi-colon is treated as a logical AND, that is, all requirements must evaluate to TRUE for the entry.


Distinguished Name Construction/Join Filter/Attribute Construction (Substitution Operator)

The substitution operator contains the conditions that the Join Engine applies to the target view to find one entry to link the source entry with. This is a required entry when defining rules. The Join Engine applies the substitution operator criteria to the data in the destination source and, joins the entry flowing to the source with a single entry in the destination source that matches the criteria.

For example, an entry flowing from the Connector View has uid=agreen. A substitution operator of uid=%uid% joins this entry with a single entry in the destination source that also has uid=agreen. The substitution operator finds only one unique entry to match with, else, the rule fails. In addition, the rule would fail if this field is left empty.


Note

For more information about this syntax, see Appendix A, "Join Process Operators."



Configuring the Join Process

The configuration of the join rules, attribute construction definitions, attribute flow rules, filters, and DN mapping rules is the basis of the join process. After these configurations are completed, the rules are placed in rule sets and applied to the data. Based on the rule configurations, the Join Engine allows one or more of the following:

Once the join process rules are configured they need to be applied to the Participating View to modulate the process. For information on applying these rules, see "Configuring a Participating View" in Chapter 2, "Working with Views."

Join Rules

A join rule is one of the join process rules. Join rules are specified to join entries from different Connector Views to one Meta View entry. It also identifies the values and attributes in the source entry, that is used to search the destination view, for one entry to which it joins to. When a matching value is found in the destination view, a join between the two entries is created.

After join rules are configured, they are placed in rule sets that define the order of applying the rules. The Join Engine applies the rules sequentially from the rule set until either a rule identifies a single entry or all the rules fail. If a match is made, the Join Engine executes the next rule set in the join process. If the entire search fails, the Join Engine may still add the source entry to the destination view, depending on the configuration of the other rules. Alternatively, the Join Engine does not link the source entry. It can then be manually joined using the "Using the Fix-It Tool". For more information on this, see Chapter 14, "Administration Tools."

    Working with join rules
  1. From the Meta-Directory console, select the Configuration tab.
  2. Select Meta-Directory from the navigation tree.
  3. Select the Join Rules tab. The ‘Join Rules’ window displays.
    To create new rules
  1. From the Join Rules window, click New Rule.
  2. The ‘New Join Rule’ dialog box displays.
    Figure shows the ’New Join Rule’ dialog box.

  3. Enter appropriate values in the fields as described in the following table:
  4. Table 1-5  Description of the options and the tasks to perform for each option

    Field

    Do This

    Name

    Enter a name for the join rule. Restrict the name to the following characters: A-Z a-z 0-9 _ - <space>

    Description

    Optional. Enter a description.

    Type

    The default rule type is Grammar. (The Join Engine provides condition and substitution statements that are based on attribute names and values.) Additional script-based rule options may be available through Sun ONE Professional Services.

    Optional Token Assignments

    This field is used to break up an attribute’s value into specific values. These sub-tokens can then be used as attributes. For example, the attribute {cn}=%last,first% can be sliced into two attributes by entering {cn}=%last%,%first%.To compose token assignments, see "Optional Token Assignments (Format Operator)" for instructions.

    Selection Criteria

    Optional. This field determines the conditions that must be met by an entry before a rule is applied. For instance, you can choose to flow only those entries that contain (%objectclass%=person); using this field parses the entries using that standard. To compose selection criteria, see "Selection Criteria (Requirements Operator)" for instructions.

    Join Filter

    This required field is the search filter used to join entries. The Join Engine will apply the rule to the destination data and join the source entry with the one destination entry that matches the criteria. For example, a join filter of uid=%uid% will join a Connector View entry and a Meta View entry whose unique ID match. To compose join filters, see "Distinguished Name Construction/Join Filter/Attribute Construction (Substitution Operator)" for instructions.

  5. Click OK. The new rule and its type is displayed in the Rules list box.
  6. Perform Step 1 through Step 3 to add other join rules.
  7. Once complete, click Save.

Example:

To join entries that have the same values for the attribute uid, you would specify, the Join Engine, to select all entries with the attribute uid [(%uid%=@) in the Selection Criteria field] and join those that have an identical user ID [(uid=%uid%) in Join Filter field].

    To edit rules
  1. Select the rule to edit from the Rules list box, and then click Open Rule.
  2. Modify the values as required in the ‘Edit Join Rule’ dialog box. For details, see "To create new rules".
  3. Click OK to save the changes. The ‘Join Rules’ window.
  4. Perform Step 1 through Step 3 to edit other rules.
  5. Once complete, click Save.
    To delete rules
  1. Select the rule to delete, and the click Delete Rule.
  2. The rule is removed from the Rules list box.

  3. Once complete, click Save.
    To create a new rule set name
  1. Click New Set. The ‘New Set’ dialog box displays.
  2. Enter the new rule set name and click OK.
  3. The new name is displayed in the Rule Sets list box.

  4. Once complete, click Save.
    To assign members to a rule set
  1. Select the rule set name from the Rule Sets list box.
  2. Select the rule to add from the Rules list box.
  3. Click Add Member. The rule is displayed in the Members list box.
  4. Perform Step 1 through Step 3 to add other rules to this set.
  5. Once complete, click Save.
    To delete members from a rule set
  1. Select the rule set name from the Rule Sets list box.
  2. Select the member to delete from the Members list box, and then click Remove Member.
  3. Perform Step 2 again to delete other members.
  4. Once complete, click Save.
    To delete a rule set
  1. Select the set to delete.
  2. Click Delete Set. The set is removed from the Rule Sets list box.
  3. Once complete, click Save.
    To test a rule

Before a rule can be tested, a Connector View with at least one entry must be configured and added as a Participating View. Also, verify that the Join Engine has started.

  1. Click Rule Tester. The ‘Join Rule Tester’ dialog box displays:
    Figure shows the ’Join Rule Tester’ dialog box.
  2. Choose the ‘Entry To Test Against’:
    • To test the rule on a Meta View entry, click Browse next. The ‘Select An Entry’ dialog box displays. Select the entry from the Meta View to test and then click OK. The location of entry is displayed in the Entry to Test Against field.
    • To test the rule on a Connector View entry, select the desired Connector View from the Connector View list, and then click Browse. The ‘Select An Entry’ dialog box displays. Select an entry from the Connector View to test, and then click OK. The location of the entry is displays in the Entry to Test Against field.
  3. Select the Rule/Rule Set To Test:
    • Test Using Connector View Settings uses the join rule set employed by the Connector View selected from the list box. This option is available whether you are testing an entry from a Connector View or from a Meta View. Select the rule set name in the Rule Set field.
    • Test Using Rule Set uses a join rule set. Select the rule set from the Rule Set field.
    • Test Using Rule uses a join rule. Select the rule from the Rule field.
  4. Select Verbose for a detailed test result. This would contain information on rule or rule set (with the rules from the rule set) that was tested.
  5. Click Test to execute the test.

Constructed Attributes

A constructed attribute is an attribute name and its value created from information in a source entry. Once created, the constructed attribute appears as an attribute choice during the creation of attribute flow rules.

For example, if a data source’s entries have a Comments field that contains three parts of information (department, job title, and phone extension), this information can be separated into three constructed attributes.

Conversely, there may be three separate attributes that list a car type, a car color, and a transmission type that can be consolidated into a single constructed attribute. The final value of the attribute can be static (a telephone number which remains the same) or dynamic (a value based on an entry’s attributes or culled from sub-token assignments).


Note

One common use of constructed attributes is defining objectclasses for data flowing from Oracle tables to the Meta View.


    Working with constructed attributes
  1. From the Meta-Directory console, select the Configuration tab.
  2. Select Meta-Directory from the navigation tree.
  3. Select the Attribute Construction tab. The ‘Attribute Construction’ window displays.
    To name a new constructed attribute
  1. Click New Attribute. The ‘Constructed Attribute’ dialog box displays.
  2. Enter a name and description, and then click OK. The attribute is displayed in the Attributes list.
    To create a rule for a new constructed attribute
  1. Select the attribute, and then click New Rule.
  2. The ‘New Constructed Attribute Rule’ dialog box displays:
    Figure shows the ’New Constructed Attribute Rule’ dialog box.

  3. Enter appropriate values in the fields as described in the following table:
  4. Table 1-6  Description of the options and the tasks to perform for each option

    Field

    Do This

    Name

    Enter a name for the constructed attribute. Restrict the name to the following characters: A-Z a-z 0-9 _ - Spaces are not allowed in constructed attribute names.

    Description

    Optional. Enter a description.

    Type

    The default rule type is Grammar (Join Engine provides condition and substitution statements that are based on attribute names and values). Additional script-based rule options may be available through Sun ONE Professional Services.

    Optional Token Assignments

    This field is used to break up an attribute’s value into separate, more specific values. These sub-tokens can then be used as attributes. For example, the attribute {cn}=%last,first% can be sliced into two attributes by entering {cn}=%last%,%first%.To compose token assignments, see "Optional Token Assignments (Format Operator)" for instructions.

    Selection Criteria

    Optional. This field determines the conditions that must be met by an entry before a rule is applied. For instance, you can choose to flow only those entries that contain (%objectclass%=person); using this field parses the entries using that standard. To compose selection criteria, see "Selection Criteria (Requirements Operator)" for instructions.

    Attribute Construction

    This required field carries the value of the constructed attribute. A hard-coded value, the entry’s attribute, token assignments or a combination are acceptable. For example, %givenname%.%sn%@madisonparc.com is a combination of attributes and hard-coded values. For more information, see "Distinguished Name Construction/Join Filter/Attribute Construction (Substitution Operator)".

  5. Click OK. The new rule for this attribute is displayed in the Rules list box.
  6. Perform Step 1 through Step 3 to add more rules.
  7. Once complete, click Save.

Example:

To construct an objectclass attribute for use with an Oracle database, you could name it as ‘dbobjectclass’ and add the objectclasses to be defined in the Attribute Construction field. Depending on the attributes in the database, top;person;organizationalPerson;inetOrgPerson is recommended.

    To edit a rule
  1. Select the rule to edit.
  2. Click Edit Rule. The ‘Edit Constructed Attribute Rule’ dialog box displays.
  3. Modify the values as required, and click OK. The ‘Attribute Construction window’ is displayed.
  4. Once complete, click Save.
    To delete a rule
  1. Select the rule to delete, and then click Delete Rule. The rule is removed from the ‘Rules’ column.
  2. Once complete, click Save.
    To delete an attribute
  1. Select the attribute to delete, and then click Delete Attribute. The attribute is removed from the Attributes list.
  2. Once complete, click Save.

Attribute Flow Rules

An attribute flow rule allows you to map attributes between a Connector View and a Meta View. Attribute flow tables define matching attributes; they consist of a single source attribute and one destination attribute. When a new entry appears in a Connector View, attribute flow rules determine which attributes will be flowed and how to map the attribute names between the connector and Meta View.


Note

Default attribute flow rules, referred to as Atomic, can also be used. When the Join Engine applies atomic attribute flow, attributes in both views flow one-to-one while attributes in the destination entry that are not present in the source entry are deleted. Custom attribute flow rules should be defined for selective attributes to flow.


    Working with Attribute Flow
  1. From the Meta-Directory console, select the Configuration tab.
  2. Select Meta-Directory from the navigation tree.
  3. Select the Attribute Flow tab. The ‘Attribute Flow’ window displays.
    To add a new rule
  1. Click New Rule. The ‘New Attribute Flow Configuration’ dialog box displays:
    Figure ’New Attribute Flow Configuration’ dialog box.
  2. Enter appropriate values in the fields as described in the following table:
  3. Table 1-7  Description of the options and the tasks to perform for each option

    Field

      Do This

    Name

    Enter a name for the attribute flow rule. Restrict the name to the following characters: A-Z a-z 0-9 _ - <space>

    Description

    Optional. Enter a description of the rule.

    Direction

    Specify whether you want the new rule to map entries that flow to the Meta View or to the Connector View.

    Selection Criteria

    Optional. This field determines the conditions that must be met by an entry before a rule is applied. For instance, you can choose to flow only those entries that contain (%objectclass%=person); using this field parses the entries using that standard. To compose selection criteria, see "Selection Criteria (Requirements Operator)" for instructions.

    Attribute Mappings

    See To add attribute mappings for instructions. (The Meta View and at least one Connector View must be configured before moving on to this step. For those procedures, see Chapter 2, "Working with Views.")

  4. Click OK. The new rule is displayed in the ‘Rules’ area of the Attribute Flow window.
  5. Once complete, click Save.
    To add attribute mappings
  1. From the ‘New Attribute Flow Configuration’ dialog box, click Add to configure attribute mappings for this rule.
  2. The ‘Add Attribute Mappings’ dialog box displays:
    Figure shows ’Add Attribute Mappings’ dialog box.

  3. Select the appropriate options. The following table describes the options:
  4. Table 1-8  Description of the options and the tasks to perform for each option

    Field

    Do This

    Source View and Destination View

    The object class choices shown are based on the view chosen.

    Source Objectclass and Destination Objectclass

    Choose one of the following to define the Attribute field below:

    • All Attributes to list attributes in the chosen view’s schema.
    • All Language Tagged Attributes to list attributes with an associated language tag.
    • Constructed Attributes to list attributes created as constructed attributes.

    Supported Language Subtypes for Source and Supported Language Subtypes for Destination

    To define an attribute with a language subtype, choose All Language Tagged Attributes and select the language subtype for the attribute desired. A language subtype allows searches in other languages. For more information, see "Language Subtype Tagged Attributes".

    Add Phonetic Subtype checkbox

    Select to indicate that the attribute value is a phonetic representation. For example, givenname;lang-ja;phonetic indicates that the attribute value is the phonetic version of the entry's Japanese name.

    Treat Attribute as Group

    Select if the selected attribute applies to a number of entries. Your choice is reflected in the Type column of the New Attribute Flow Configuration dialog box after you click Insert.

  5. Select an attribute from the source view and one from the destination view and click Insert. The mapping is displayed.
  6. Perform Step 2 and Step 3 to add additional mappings to the configuration.
  7. Once complete, click Close.
    To edit a rule
  1. Select the rule to edit.
  2. Click Open Rule. The ‘Edit Attribute Flow Configuration’ dialog box displays.
  3. Modify the values as required. You can add or remove attribute mappings by using the buttons at the bottom of the dialog box.
  4. Click OK. The ‘Attribute Flow’ window displays.
  5. Once complete, click Save.
    To delete a rule
  1. Select the rule to delete.
  2. Click Delete Rule. The rule is removed from the Rules list.
  3. Once complete, click Save.
    To create a new rule set
  1. Click New Set. The ‘New Set’ dialog box displays.
  2. Enter a name for the new set and click OK.
  3. The new name is displayed in the Sets list box.

  4. Once complete, click Save.
    To assign a rule to the new rule set
  1. Select the name of the new rule set from the Rule Sets list box.
  2. Select a rule in the Rules list.
  3. Click Add Member. The rule is displayed in the Members list box.
  4. Perform Step 2 and Step 3 to add additional rules to the set.
  5. Once complete, click Save.

  6. Caution

    When defining attribute flow rule sets, each rule set must contain rules defined for the same direction only. Rule members flowing to the Meta View or flowing to the Connector View should be set up in rule sets flowing to the Meta View or flowing to the Connector View, respectively. If the same rule set is used for rules flowing in both directions, an objectclass violation will be encountered and entries will not flow.


    To delete a rule from a rule set
  1. Select the rule member to delete.
  2. Click Remove Member. The member is removed from the Members list box.
  3. Once complete, click Save.
    To delete a rule set
  1. Select the rule set to delete.
  2. Click Delete Set. The rule set is removed from the Sets list box.
  3. Once complete, click Save.

Attribute Flow Summary

After you have configured attribute flow rules and rule sets, and specified attribute flow for each Connector View or Meta View relationship, you can view a summary of attribute flow rules. The Attribute Flow Summary dialog box displays all mappings for a particular attribute, all mappings for a particular Meta or Connector View, or limits the display by using a filter.

    To view an attribute flow summary
  1. From the Meta-Directory console, right-click the Join Engine.
  2. Select Attribute Flow Summary.
  3. The ‘Attribute Flow Summary’ dialog box displays.

    To configure an attribute flow summary
  1. Enter appropriate values in the fields as described in the following table:
  2. Table 1-9  Description of the options and the tasks to perform for each option

    Field

    Do This

    Attribute

    Select an attribute to limit the display to the mappings that contain the attribute. This can be a Connector View attribute or a Meta View attribute.

    Source/Destination

    Select a Meta View or Connector View ID to limit the display to mappings that include attributes from the corresponding Connector View or Meta View.

    Rule Name

    Select an attribute flow rule name to limit the display to mappings that use a particular attribute flow rule.

  3. Click Filter to display the attribute mappings.
  4. Alternatively, click Show ALL to display all the attribute flow mappings.

  5. Summary information description:
  6. Table 1-10  Description of the options and the tasks to perform for each option

    Field

    Do This

    Source Attribute

    The attribute that is native to the source chosen.The source attribute coupled with the destination attribute is the attribute flow rule.

    Destination Attribute

    The attribute that is not native to the source chosen. The source attribute flows to the destination attribute.

    Rule Name

    The name of the attribute flow rule that includes the attribute mapping.

    Selection Criteria

    The selection criteria configuration used by the attribute flow rule that contains this attribute mapping.

Language Subtype Tagged Attributes

A language subtype can be added to any attribute using the attribute flow rules. By choosing a language other than the default (English), users are offered the option of searching in that language. For example, Noriko prefers that her name be represented by Japanese characters as well as English. Selecting Japanese as a language subtype for the givenname attribute allows other users to search for her Japanese name.

If a language subtype is specified for an attribute, it takes the form attribute;lang-subtype where subtype is the two character abbreviation for the specified language. You can assign only one language subtype per attribute instance in an entry. To assign multiple language subtypes, add another attribute instance to the entry and then assign the second language subtype. For example, the following is invalid: cn;lang-ja;lang-en-GB:Smith. Instead, use:

cn;lang-ja:ja_value together with cn;lang-en-GB:en-GB_value.

The following table contains the list of supported language subtypes.

Table 1-11  Supported Language Subtypes 

Language Tag

Language

af

Afrikaans

be

Byelorussian

bg

Bulgarian

ca

Catalan

cs

Czechoslovakian

da

Danish

de

German

el

Greek

en

English

es

Spanish

eu

Basque

fi

Finnish

fo

Faroese

fr

French

ga

Irish

gl

Galician

hr

Croatian

hu

Hungarian

id

Indonesian

is

Icelandic

it

Italian

ja

Japanese

ko

Korean

nl

Dutch

no

Norwegian

pl

Polish

pt

Portuguese

ro

Romanian

ru

Russian

sk

Slovakian

sl

Slovenian

sq

Albanian

sr

Serbian

sv

Swedish

tr

Turkish

uk

Ukraianian

zh

Chinese

Filters

By default, the Join Engine includes all entries in the join process. However, filters can be configured to prevent particular subtrees or entries or both from participating. These filters are based on the DNs of the entries and not the attributes. They do not support random inclusions and exclusions.

Example

To filter out all organizations except one, as well as exclude two users from the organization during processing, the filter might appear as follows:

‘No Subtrees Except’ o=madisonparc,c=us

‘Exceptions to Above Rule’ cn=John Smith cn=Fred Jones

This means that the only subtree to be processed is o=madisonparc, c=us. Within this subtree, the connector is interested in all entries except cn=John Smith and cn=Fred Jones. All entries beneath the subtree will pass the filter except the ones with the names John Smith and Fred Jones.

    Working with Filters
  1. From the Meta-Directory console, select the Configuration tab.
  2. Select Meta-Directory from the navigation tree.
  3. Click the Filters tab. The Filters panel displays.
    To create a new filter
  1. From the Filters window, click New Filter. The Filter Name dialog box displays.
  2. Enter a name and click OK.
  3. The new name is displayed in the Filter Name list box.

    To add a subtree filter
  1. In the Filters window, select a filter name, and then click Add Subtree.
  2. The Subtree DN dialog box displays.

  3. Enter a DN for the subtree and click OK. The DN is displayed in the list box.
  4. Select All Subtrees Except or No Subtress Except from list box.
  5. Perform Step 1 through Step 3 to add other subtree filters.
  6. Once complete, click Save.
    To add an entry filter to the subtree
  1. Select a filter name and then select the subtree DN to add an entry filter.
  2. Click Add Entry. The ‘Entry RDN’ dialog box displays.
  3. Enter a relative distinguished name, and then click OK.
  4. The RDN is displayed in the list box.

  5. Select Exceptions to Above Rule.
  6. Perform Step 1 through Step 4 to add other entry filters.
  7. Once complete, click Save.
    To remove a subtree filter
  1. Select the DN to remove.
  2. Click Remove Subtree.
  3. Once complete, click Save.

  4. Note

    This action removes all entry filters associated with this subtree.


    To remove an entry filter
  1. Select the entry to remove.
  2. Click Remove Entry.
  3. Once complete, click Save.
    To delete a filter
  1. Select the filter name to delete from the Filter Name list box.
  2. Click Delete Filter. The filter and its associated subtrees and entries are removed.
  3. Once complete, click Save.

Distinguished Name Mapping Rules

If join rules cannot identify a suitable entry in the target view to link to the source entry, the Join Engine will create such an entry. Distinguished Name (DN) mapping rules are used as guidelines to compose a DN in the target view for the replicated entry. You can create your DN mapping rules or use the Atomic (default) rules provided with the Join Engine.


Note

When the Join Engine applies an atomic DN mapping rule, the RDN of the source entry is appended to the destination view’s base DN although the partial DN (relative to the source’s base DN) may be different. For instance, an RDN of user1 in an assigned Connector View of cn=user1,ou=cv1,o=madisonparc.com would remain the same when atomic rules are applied to the Meta View as cn=user1,o=mv.


You can group multiple DN mapping rules to a DN mapping rule set to allow ordered testing. You can also define different rules for entries originating from different Connector Views.


Note

The DN Mapping only specifies the partial DN, relative to the view’s base DN.


    Working With DN Mapping Rules
  1. From the Meta-Directory console, select the Configuration tab.
  2. Select Meta-Directory from the navigation tree.
  3. Select the DN Rules tab.
  4. The DN Rules panel displays.

    To add a new rule
  1. Click New Rule. The ‘New DN Mapping Rule’ dialog box displays:
    Figure shows the ’New DN Mapping Rule’ dialog box.
  2. Enter appropriate values as described in the following table:
  3. Table 1-12  Description of the options and the tasks to perform for each option

    Field

    To This

    Name

    Enter a name for the DN mapping rule. Restrict the name to the following characters: A-Z a-z 0-9 _ - <space>

    Description

    Enter an description. Optional.

    Type

    The default rule type is Grammar (Join Engine provides condition and substitution statements that are based on attribute names and values). Additional script-based rule options may be available through Sun ONE Professional Services.

    Optional Token Assignments

    This field is used to break up an attribute’s value into separate, more specific values. These sub-tokens can then be used as attributes. For example, the attribute {cn}=%last,first% can be sliced into two attributes by entering {cn}=%last%,%first%.To compose token assignments, see "Optional Token Assignments (Format Operator)" for instructions.

    Selection Criteria

    Optional. This field determines the conditions that must be met by an entry before a rule is applied. For instance, you can choose to flow only those entries that contain (%objectclass%=person); using this field parses the entries using that standard. To compose selection criteria, see "Selection Criteria (Requirements Operator)" for instructions.

    Distinguished Name Construction

    This required field carries the value of the entry’s RDN. Be certain that the attributes used have corresponding attributes in the Directory Server schema. For more information, see "Distinguished Name Construction/Join Filter/Attribute Construction (Substitution Operator)".

  4. Click OK. The new rule for this DN mapping is displayed in the Rules list box.
  5. Perform Step 1 though Step 3 to add more DN mapping rules.
  6. Once complete, click Save.
Example

A connector with user information at ou=users,o=MD flows to a Meta View with user information at ou=users,ou=internal,o=MV. DN Construction could be: uid=%uid%,ou=users,ou=internal,o=MV.

    To edit a rule
  1. Select the rule to edit.
  2. Click Open Rule. The ‘Edit DN Mapping Rule’ dialog box displays.
  3. Modify the values as required, and then click OK. The DN Rules window displays.
  4. Once completed, click Save.
    To delete a rule
  1. Select the rule to delete.
  2. Click Delete Rule. The rule is removed from the Rules list.
  3. Once complete, click Save.
    To create a new rule set
  1. Click New Set. The ‘New Set’ dialog box displays.
  2. Enter the new rule set name and click OK.
  3. The new name is displayed in the Sets list.

    To assign a rule to a rule set
  1. Select the rule set name from the Sets list.
  2. From the Rules list, select a rule to add to the rule set, and click Add Member.
  3. The rule is added to the Members list.

  4. Perform Step 1 through Step 2 to add more rules to the rule set.
  5. Once complete, click Save.
    To edit a rule set
  1. Select the set to edit.
  2. Do one of the following to add or remove a member:
    • To add a member, select the name of the member to add from the Rules menu and click Add Member. The added member appears in the Members list. Click Save to complete adding members.

      - Or -

    • To remove a member, select the member to remove from the Members list and click Remove Member. Repeat or click Save to complete.
    To delete a rule set
  1. Select the set to delete.
  2. Click Delete Set. The set is removed from the Sets list.
  3. Once complete, click Save.

Data Servers

Meta Directory can connect to many data servers to perform several functions. For instance, servers can be added and used as external data sources (to hold Connector Views or Meta Views). Currently, Meta-Directory connects to these data servers: Sun ONE Directory Server and Oracle. For information on connecting to and managing the data servers, see Chapter 16, "Managing Servers and Permissions."

Enabling UTF8 Character Flow Support

Meta-Directory synchronizes attribute values that contain UTF-8 encoded Unicode characters.

  1. From the Directory Server Console, select the Directory tab.
  2. Select Meta-Directory.
  3. Select 5.
  4. Select System.
  5. Select Shared Configuration and right-click Shared Configuration, and then select Properties.
    Figure shows the properties of the Shared Configuration.
  6. To enable the UTF-8 character flow support, the following configuration parameters must be modified:

    1. mdsgeneralConfiguration: Charset
    2. cn=Shared Configuration, cn=System, ou=5, ou=Meta-Directory, ou=Global Preferences, ou=<Admin Domain>, o=NetscapeRoot mdsgeneralConfiguration: Charset=<Native Charset>

    3. mdsgeneralConfiguration: Lang
    4. n=Shared Configuration, cn=System, ou=5, ou=Meta-Directory, ou=Global Preferences, ou=<Admin Domain>, o=NetscapeRoot mdsgeneralConfiguration: Lang=<Native Lang>

      where:

    5. Admin Domain is a value such as: restaurants.madisonparc.com
    6. Native character set (Native Charset) is one of the following values:
      • ISO88591
      • ISO885915
      • WINDOWS1252
      • US-ASCII
      • This table describes the supported character sets (charset):

        Character Set

        UTF8

        Operating System

        ISO88591

        Yes

        Solaris

        ISO885915

        Yes

        Solaris

        WINDOWS1252

        Yes

        Windows

        US-ASCII

        No

        Solaris or Windows

        Note that if the character set has a value US-ASCII, it indicates no UTF-8 support. WINDOWS1252 and US-ASCII are the supported character sets on Microsoft Windows. ISO88591, ISO885915, and US-ASCII are the supported character sets on Solaris. Euro is supported by WINDOWS1252 and ISO885915 character sets only. The default character set is US-ASCII.

        Native Language (Native Lang) is typically the value that the setlocale function would take. On Windows, the value is of the format lang_country (for instance English_United States) and on Solaris it is one of the values of the result of command locale -a (for instance en_US). By default, this parameter is not set to any value and English_United States is assumed on Windows and en_US on Solaris.

  7. Note that when the Join Engine is not installed, these configuration parameters are not present. For such scenarios, you must manually add them. From the Directory Console:
    1. Select the Directory tab.
    2. Select Meta-Directory.
    3. Select 5.
    4. Select System.
    5. Select Shared Configuration.
    6. Right-click Shared Configuration, and select Properties.
    7. Click Add attribute. This displays a dialog that contains all the attributes.
    8. Select mdsgeneralconfiguration, and click OK.
    9. Add the configuration parameters (for instance Charset=WINDOWS1252 and Lang=English_United States), and click OK.

Enabling UTF8 in the Oracle Database Connector

To enable the Oracle database server to handle UTF-8 data, select the database CHARACTERSET as UTF8 during the database setup. This setting can be selected from NLS_CHARACTERSET parameter present in the view NLS_DATABASE_PARAMETERS.

Enabling UTF8 in Indirect Connectors

Some objects may have an attribute whose value is the DN of some other object. For example, in a group-member kind of relationship, member attribute of the Group object has a value that is actually a DN of some User or Group object. For instance, a group object ‘testgroup’ has ‘uniquemember’ attribute that has the value of ‘uid=testuser, o=testcv’, that is the DN value for the user object ‘estuser’.

dn: cn=testgroup, o=testcv
cn: testgroup
objectclass: top
objectclass: groupOfNames
uniquemember: uid=testuser, o=testcv

If this kind of attribute values contain UTF-8 data, those are escaped/unescaped the same way the DN is escaped/unescaped (using \xx notation - RFC 2253). Such attributes to be escaped like DN have to be specified using the following configuration parameter for each connector instance.

cn=<connector instancename>,cn=connectors,cn=system,ou=5,ou=meta-directory,ou=global preferences,ou=xyz,o=netscaperoot mdsgeneralconfiguration: AttributesToBeEscapedLikeDn= <comma separated attribute list>.

  1. Select Directory Server.
  2. Select the Directory tab.
  3. Select Meta-Directory.
  4. Select 5.
  5. Select System.
  6. Select Connectors.
  7. Select Connector Instance and right click and select properties.

The following default values are configured when the instance is created (to create an instance of individual connectors, see "Meta-Directory Connectors"):

    1. Active Directory Connector
    2. AttributesToBeEscapedLikeDn=member,uniqueMember,mdsAdMember

    3. NT Domain Connector
    4. AttributesToBeEscapedLikeDn=member,uniqueMember

    5. Universal Connector
    6. AttributesToBeEscapedLikeDn=

    7. Microsoft Exchange Connector
    8. AttributesToBeEscapedLikeDn=member,uniqueMember

In case of the Universal Connector, the external application creating input file must provide values for such attributes in \xx notation. This applies for the reverse direction too. The external application processing the output file, must unescape the \xx escaped values of such attributes before providing the data to external data source.

Enabling UTF8 for Direct Connectors

No further attributes need be changed.


Operational Configuration for the Join Engine

When an entry is joined to the Meta View, both the Connector View and Meta View entries are updated with attributes associated with the join entry (mds* attributes):



Previous      Contents      Index      Next     


Copyright 2004 Sun Microsystems, Inc. All rights reserved.