Chapter 5   Configuring The Join Engine

This chapter provides information on the join engine, the core component of Meta-Directory. The primary purpose of the join engine is to link data and manage the flow of information from the connector view, into the meta view and back to the connector view. This chapter includes the following sections:

• What is the Join Engine?
• Creating the Join Engine Instance
• What is the Join Process?
• Configuring the Join Process

• Join Rules
• Constructed Attributes
• Attribute Flow Rules
• Filters
• Distinguished Name Mapping Rules
• Data Servers
• Enabling UTF8 Character Flow Support
• Operational Configuration for the Join Engine

What is the Join Engine?

---

The join engine is responsible for directing the flow and synchronization of data between one or more connector views and the meta view. It allows data to flow in either direction, monitoring the connector views for changes and incorporating these changes into the meta view as well as monitoring the meta view for changes and incorporating these changes back into 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, the join engine relays the change to the meta view. The change will be made in the address attribute of the user's meta view entry as well as flow back to reflect the change in other connector views the entry might also be linked with.

Creating the Join Engine Instance

---

You create one instance of the join engine within 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 Administration Server.) The instance is created from Sun ONE Console. General server information, such as the base DN of the meta view and Directory Server URL, is needed to create the instance. It also requires enabling the Directory Server change log as well as loading the schema into the Directory Server. (The schema should be loaded into any new Directory Server introduced into the system.) Once the join engine instance is created, Directory Server should be restarted and Meta-Directory console can be accessed.

To Create a Join Engine Instance

1. In Sun ONE Console, right-click the Server Group.

A context menu appears.

2. Select Create Instance Of, then select Meta-Directory Join Engine.

The New Instance Creation dialog box appears.





3. Enter values for all of the following fields:

Fields	Values
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 within 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 on the Directory Server before instantiating the join engine is recommended.
Data Server URL	Select a Directory Server on which the meta view will be stored from the drop-down list, or type in a new one.
Data Server Bind DN	Enter a DN with which the join engine will authenticate to the Directory Server.
Data Server Bind Password	Enter the password associated with the authenticating DN.

4. Click OK.

A pop-up window appears with change log options. A change log is a file that summarizes changes made to a server. Directory Server writes the change logs in a subtree (cn=changelog).

5. Select one of the following options concerning the change log:

• Enable Changelog NOW.

The Enable Changelog dialog box will appear. Enter the directory path where you want to store the change log and accept the default Changelog Suffix or provide your own. Click OK. (You will be reminded to restart the Directory Server. For information on how to do this, see the Deployment Guide.)

• Enable Changelog LATER.

It is recommended that you enable the change log now. The process for doing this in Directory Servers 4.1x and 5.x is different. Please see iPlanet Directory Server documentation for enabling the change log after the instance has been created.

• Abort Instance Creation.

This option will stop the instance creation process.




---

Note

In the Solaris operating environment, Directory Server is normally installed as root. Because of this, the permissions of the directory need to be changed to allow console to create the change log directory. Apply a command of chmod -R 777 against the directory where you wish to create the change log.

---




6. Click Yes to load the schema into the Directory Server.

Loading the schema requires several minutes. After it is loaded, the message "Instance Creation Succeeded" appears.




---

Note	Meta-Directory cannot detect if the schema has been loaded into Directory Server so it asks whether to load the schema every time an instance is created. Every Directory Server should have the schema loaded at least once. Loading it more than once does not harm the configuration.

---

To Remove a Join Engine Instance

1. In Sun ONE Console, right-click the join engine instance.

A context menu appears.

2. Select Remove Server and click Yes in the message box.

The join engine instance is deleted.

What is the Join Process?

---

The join process is the movement of data through a sequence of rules and filters, configured by the administrator 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 a 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:

• An individual rule identifies an entry
• All rules fail and the entry is not passed

It is important to remember that each rule set should be made up of rules that search through entries flowing in one direction. In other words, 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:

• Optional Token Assignments (Format Operator)
• Selection Criteria (Requirements Operator)
• Distinguished Name Construction/Join Filter/Attribute Construction (Substitution Operator)

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 "The 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 configures 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 synchronize.

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

• Entry Conditions

The Entry type enables you to compose criteria that would select or not select entire entries.

• Attribute Conditions

The Attribute type allows you to compose conditions that would define your selection criteria as the value of an attribute.

• Language Tagged Attribute Conditions

The Language Tagged Attribute type enables language subtype support. If you specify a language subtype for an attribute, the entry allows searches based on a secondary, specified language.

The following sections explain how to configure each type of condition.

To Compose Entry Conditions

1. In the Compose Selection Criteria dialog box, select Entry as the Type.

This figure shows the available fields for the Entry conditions.





2. Provide values for the following fields:

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 drop-down list contains two choices: Equal and Does Not Equal.
Value	Provide a value to complete the expression.

3. Click Insert. Your composition appears in the Conditions list window above.
4. Optional: Add other conditions as necessary.
5. Optional: Modify the conditions using the buttons at the right as described in "Combining Conditions".
6. Click OK to save the conditions and return to the previous dialog box.

To Compose Attribute Conditions

1. Select Attribute as the Type.

This figure shows the available fields for the Attribute conditions.





2. Provide values for the following fields:

Source	Choose the source for the attribute from the drop-down list. 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 drop-down list 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 drop-down lists. (When using this option, be aware of your use of the space bar.)
Value	Provide a value to complete the expression, if applicable.

3. Click Insert. Your composition appears in the Conditions list window above.
4. Optional: Add other conditions as necessary.
5. Optional: Modify the conditions using the buttons at the right as described in "Combining Conditions".
6. Click OK to save the conditions and return to the previous dialog box.

To Compose Language Tagged Attribute Conditions

1. Select Language Tagged Attribute as the Type.

This figure shows the available fields for the Language Tagged Attribute conditions.





2. Provide values for the following fields:

Source	Choose the source for the attribute from the drop-down list. 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 drop-down list 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 drop-down lists. (When using this option, be aware of your use of the space bar.)
Value	Provide 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	Click this checkbox 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.

3. Click Insert.

Your composition appears in the Conditions list window above.

4. Optional: Add other conditions as necessary.
5. Optional: Modify the conditions using the buttons at the right as described in "Combining Conditions".
6. Click OK to save the conditions and return to the previous dialog box.

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.

The system would respond as shown:

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, i.e.: all requirements must evaluate to TRUE for the entry.

---

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

The final operator string is the substitution operator. The substitution operator contains the conditions that the join engine applies to the target view in order to find one entry with which to link the source entry. This is the required entry when defining rules. The join engine will apply the substitution operator criteria to the data in the destination source and join the entry flowing to that source with the one entry in the destination source that matches the criteria. For example, an entry flowing from the connector view has a uid=agreen. A substitution operator of uid=%uid% will join this entry with the one entry in the destination source that also has a uid=agreen. The substitution operator will find only one unique entry to match or else the rule will fail. The rule will also fail if this field is left empty.

---

Note	See "The Join Process Operators" to learn more about this syntax.

---

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 finished, the rules are placed in rule sets and applied to the data. Based on the rule configurations, the join engine can allow one or more of the following:

• Entry creation in the meta view or in the external data sources
• Entry deletion from the meta view, and subsequently, from the external data sources in which the entry originated or to which it is connected
• Entry modification in the meta view and the corresponding entry in any number of external data sources
• Incremental updates in the external data sources as modifications occur

Once the join process rules are configured they need to be applied to the participating view in order to modulate the process. Information and procedures on how to apply these rules can be found in "Configuring a Participating View" of "Views in Meta-Directory."

Join Rules

A join rule is one of the join process rules. To successfully join entries from different connector views into one meta view entry, join rules are specified. Join rules identify which values and attributes in the source entry will be used to search the destination view for one entry with which to join it. 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 which define the order in which the rules are applied. The join engine applies the rules sequentially within the rule set until either a rule identifies a single entry or all rules fail. If a match is made, the join engine moves on to 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 can leave the source entry unlinked and the entry can be manually joined using The Fix-It Tool as described in "Administration Tools."

Working With Join Rules

1. From the Meta-Directory console, choose the Configuration tab.
2. Select Meta-Directory in the navigation tree.
3. Click the Join Rules tab.

The join rules window appears.

To Create New Rules

1. Click New Rule.

The New Join Rule dialog box appears.





2. Provide values for the following fields:

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

3. Click OK.

The new rule and its type appear in the Rules list box.

4. Repeat the steps above to add other join rules.
5. Click Save from the Join Rules window when you are finished.

Example:

In order to join entries that have the same values for the attribute uid, you would tell 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 you want to edit from the Rules list box and click Open Rule.
2. Alter the fields in the Edit Join Rule dialog box as described in "To Create New Rules".
3. Click OK to save your changes and return to the Join Rules window.
4. Edit other rules following steps 1 - 3.
5. Click Save from the Join Rules window when you are finished editing rules.

To Delete Rules

1. Select the rule you want to delete.
2. Click Delete Rule.

The rule disappears from the Rules list box.

3. Click Save.

To Create A New Rule Set Name

1. Click New Set.

The New Set dialog box appears.

2. Enter the new rule set name and click OK.

The new name appears in the Rule Sets list box.

3. 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 you want to add from the Rules list box.
3. Click Add Member.

The rule you add appears in the Members list box.

4. Repeat steps 1 - 3 to add more rules to the set
5. Click Save when you are finished.

To Delete Members from a Rule Set

1. Select the rule set name from the Rule Sets list box.
2. Select the member you want to delete from the Members list box and click Remove Member.
3. Repeat step 2 to delete other members.
4. Click Save when you are finished removing members.

To Delete a Rule Set

1. Select the set you want to delete.
2. Click Delete Set.

The set disappears from the Rule Sets list box.

3. Click Save when you are finished.

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 check that the join engine has been started.

1. Click Rule Tester.

The Join Rule Tester dialog box appears.





2. Choose the Entry To Test Against:

• To test the rule on a meta view entry, click the Browse button next to the Meta View drop-down list. The Select An Entry dialog box appears from which you can select the entry within the meta view you want to test on and click OK. The entry's location appears 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 click the adjacent Browse button. The Select An Entry dialog box appears. Select an entry within the connector view you want to test on and click OK. The entry's location appears 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 drop-down list. 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 to receive detailed test results, including which rule or rule set (along with the rules within the rule set) were tested. Deselect Verbose to receive final results only.
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 will show up 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 pieces of information (department, job title, and phone extension), this information can be broken 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 into the meta view.

---

Working With Constructed Attributes

1. From the Meta-Directory console, choose the Configuration tab.
2. Select Meta-Directory in the navigation tree.
3. Click the Attribute Construction tab.

The Attribute Construction panel appears.

To Name a New Constructed Attribute

1. Click New Attribute.

The Constructed Attribute dialog box appears.





2. Provide a name and description for the new attribute.
3. Click OK.

The new attribute appears in the Attributes list.

To Create a Rule for a New Constructed Attribute

1. Select the attribute, then click New Rule.

The New Constructed Attribute Rule dialog box appears.





2. Provide values for the following fields:

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%@sun.com is a combination of attributes and hard-coded values. For more information, see "Distinguished Name Construction/Join Filter/Attribute Construction (Substitution Operator)".

3. Click OK.

The new rule for this attribute appears in the Rules list box.

4. Repeat the steps above to add more rules.
5. Click Save when you are finished.

Example:

In order to construct an objectclass attribute for use with an Oracle database, you might name it 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 you want to edit.
2. Click Edit Rule.

The Edit Constructed Attribute Rule dialog box appears.

3. Alter the fields as necessary, and click OK.

The Attribute Construction window reappears.

4. Click Save when you are finished editing rules.

To Delete a Rule

1. Select the rule to be deleted.
2. Click Delete Rule.

The rule disappears from the Rules column.

3. Click Save when you are finished deleting rules.

To Delete an Attribute

1. Select the attribute you want to delete.
2. Click Delete Attribute.

The attribute disappears from the Attributes list.

3. Click Save when you are finished deleting attributes.

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.

---

Working With Attribute Flow

1. From the Meta-Directory console, choose the Configuration tab.
2. Select Meta-Directory in the navigation tree.
3. Click the Attribute Flow tab.

The Attribute Flow panel appears.

To Add a New Rule

1. Click New Rule.

The New Attribute Flow Configuration dialog box appears.





2. Provide values for the following fields:

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 "Views in Meta-Directory.")

3. Click OK from the New Attribute Flow Configuration dialog box.

The new rule appears in the Rules section of the Attribute Flow window.

4. Click Save when you are finished adding new rules.

To Add Attribute Mappings

1. From the New Attribute Flow Configuration dialog box, click Add to configure attribute mappings for this rule.

The Add Attribute Mappings dialog box appears.





2. Select your choices from the following fields:

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.

3. Select an attribute from the source view and one from the destination view and click Insert.

The mapping appears in the lower half of the New Attribute Flow Configuration dialog box under the Type, Source, and Destination columns.

4. Repeat Step 2 and Step 3 to add additional mappings to the configuration.
5. Click Close when you are finished.

To Edit a Rule

1. Select the rule you want to edit.
2. Click Open Rule.

The Edit Attribute Flow Configuration dialog box appears.

3. Change information in the fields as necessary. You can add or remove attribute mappings by using the buttons at the bottom of the dialog box.

• To add a mapping, see "To Add Attribute Mappings" on page 96.
• To delete a mapping, select the mapping you want to delete and click Remove.
4. Click OK to return to the Attribute Flow window.
5. Click Save when you are finished editing rules.

To Delete a Rule

1. Select the rule you want to delete.
2. Click Delete Rule.

The rule disappears from the Rules list.

3. Click Save when you are finished.

To Create a New Rule Set

1. Click New Set.

The New Set dialog box appears.

2. Provide a name for the new set and click OK.

The new name appears in the Sets list box.

3. Click Save when you are finished.

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 appears in the Members list box.

4. Repeat steps 2 and 3 to add additional rules to the set as desired.
5. Click Save when you are finished.




---

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 you want to delete.
2. Click Remove Member.

The member disappears from the Members list box.

3. Click Save when you are finished.

To Delete a Rule Set

1. Select the rule set you want to delete.
2. Click Delete Set.

The rule set disappears from the Sets list box.

3. Click Save when you are finished.

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. In Meta-Directory console, right-click on the join engine.
2. Select Attribute Flow Summary from the context menu.

The Attribute Flow Summary dialog box appears.

To Configure an Attribute Flow Summary

1. Provide values for the following fields:

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.

2. Click Filter to display attribute mappings based on your choices.

Alternatively, you can display all attribute flow mappings by clicking Show All.

3. The summary is divided into four columns of information:

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 5-1    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:

"NoSubtreesExcept" o=siroe,c=us

"AllEntriesExcept" cn=John Smith cn=Fred Jones

This means that the only subtree to be processed is o=siroe, 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, choose the Configuration tab.
2. Select Meta-Directory in the navigation tree.
3. Click the Filters tab.

The Filters panel appears.

To Create a New Filter

1. In the Filters window, click New Filter.

The Filter Name dialog box appears.

2. Enter a name and click OK.

The new name appears in the Filter Name list box.

To Add a Subtree Filter

1. In the Filters window, select a filter name, then click Add Subtree.

The Subtree DN dialog box appears.

2. Enter a DN for the subtree and click OK.

The DN appears in the list box.

3. Select All Subtrees Except or No Subtrees Except from the drop-down list.
4. Repeat steps 1-3 to add other subtree filters.
5. Click Save when you are finished.

To Add an Entry Filter to the Subtree

1. Select a filter name and then select the subtree DN to which you want to add an entry filter.
2. Click Add Entry.

The Entry RDN dialog box appears.

3. Enter a relative distinguished name and click OK.

The RDN appears in the list box.

4. Select either All Entries Except, or No Entries Except from the drop-down list.
5. Repeat steps 1-4 to add other entry filters.
6. Click Save when you are finished.

To Remove a Subtree Filter

1. Select the DN you want to remove.
2. Click Remove Subtree.
3. Click Save when you are finished.




---

Note	This action removes all entry filters associated with this subtree.

---

To Remove an Entry Filter

1. Select the entry you want to remove.
2. Click Remove Entry.
3. Click Save when you are finished.

To Delete a Filter

1. Select the filter name you want to delete from the Filter Name list box.
2. Click Delete Filter.

The filter and its associated subtrees and entries disappear from the window.

3. Click Save when you are finished.

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 within the target view for the replicated entry. You can create your own 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 even though 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=sunone.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 into a DN mapping rule set to allow for ordered testing. You can also define rules differently 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, choose the Configuration tab.
2. Select Meta-Directory in the navigation tree.
3. Click the DN Rules tab.

The DN Rules panel appears.

To Add a New Rule

1. Click New Rule.

The New DN Mapping Rule dialog box appears.





2. Provide values for the following fields:

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 optional 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.
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)".

3. Click OK.

The new rule for this DN mapping appears in the Rules list box.

4. Repeat steps 1-3 to add more DN mapping rules.
5. Click Save when you are finished.

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. The DN Construction might be: uid=%uid%,ou=users,ou=internal,o=MV

To Edit a Rule

1. Select the rule you want to edit.
2. Click Open Rule.

The Edit DN Mapping Rule dialog box appears.

3. Alter the fields as necessary, then click OK.

The DN Rules window reappears.

4. Click Save when you are finished.

To Delete a Rule

1. Highlight the rule you want to delete.
2. Click Delete Rule.

The rule disappears from the Rules list.

3. Click Save when you are finished.

To Create a New Rule Set

1. Click New Set.

The New Set dialog box appears.

2. Enter the new rule set name and click OK.

The new name appears 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 you want to add to the rule set, and click Add Member.

The rule you add appears in the Members list.

3. Repeat steps 1-2 to add more rules to the rule set.
4. Click Save when you are finished.

To Edit a Rule Set

1. Select the set you want to edit.
2. Add or remove a member by doing one of the following:

• To add a member, select the name of the member you want to add from the Rules menu and click Add Member. The added member appears in the Members list. Click Save when you are finished adding members.
• To remove a member, select the member you want to remove from the Members list and click Remove Member. Repeat or click Save when you are finished.

To Delete a Rule Set

1. Select the set you want to delete.
2. Click Delete Set.

The set disappears from the Sets list.

3. Click Save when you are finished.

Data Servers

Meta Directory has the ability to connect to a number of data servers for a number of functions. For instance, these servers can be added and used as external data sources or as space to hold connector views or meta views. Currently, Meta-Directory can connect to two types of data servers: iPlanet Directory Server and Oracle. For information on how to connect to and manage these data servers, see "Managing Servers and Permissions."

Enabling UTF8 Character Flow Support

Earlier versions of the Meta-Directory only consistently supported ASCII characters. Sun ONE Meta-Directory 5.1 synchronizes attribute values which contain UTF-8 encoded Unicode characters as well.

From the Directory Server Console

1. Select the Directory tab
2. Select Meta-Directory
3. Select 5
4. Select System
5. Select Shared Configuration and the following screen should appear
   
   

6. Right Click Shared Configuration and Select Properties
   
   

In order to enable the UTF-8 character flow support the following configuration parameters must be modified:

1. mdsgeneralConfiguration: Charset

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

2. mdsgeneralConfiguration: Lang

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

where

- Admin Domain is a value like india.sun.com and

- Native Charset is one of the following values

ISO88591

ISO885915

WINDOWS1252

US-ASCII

Charset	UTF8	Operating System
ISO88591	Yes	Solaris
ISO885915	Yes	Solaris
WINDOWS1252	Yes	Windows
US-ASCII	No	Solaris or Windows

The following table illustrates the supported charactersets:

Note that if the Charset has a value US-ASCII, it indicates no UTF-8 support. WINDOWS1252 and US-ASCII are the supported charsets in Windows. ISO88591, ISO885915 and US-ASCII are the supported charsets in Solaris. Euro is supported by WINDOWS1252 and ISO885915 charsets only. The default charset is US-ASCII.

- Native Lang is typically the value that the setlocale function would take. In Windows the value is of the format lang_country ( for instance English_United States) and in 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 in Windows and en_US in Solaris systems.

7. Note that when the join engine is not installed, these configuration parameters are not present. Under such circumstances 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 the "Add attribute" button.
8. This throws a popup window containing all the attributes. 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

In order to enable the Oracle database server handle UTF-8 data, select the database CHARACTERSET as UTF8 during the database setup. This setting can be checked 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 "testuser".

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 and the following screen will appear

The following default values are configured at the time of instance creation (See Meta-Directory Connectors of this manual on how to create an instance of each individual connectors):

1. Active Directory Connector

AttributesToBeEscapedLikeDn=member,uniqueMember,mdsAdMember

2. NT Domain Connector

AttributesToBeEscapedLikeDn=member,uniqueMember

3. Universal Connector

AttributesToBeEscapedLikeDn=

4. Microsoft Exchange Connector

AttributesToBeEscapedLikeDn=member,uniqueMember

In case of Universal Connector, it is the responsibility of the external application creating input file, to provide values for such attributes in \xx notation. This is also true for the reverse direction. It is also the responsibility of the external application processing the output file to unescape \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 the Meta view entries are updated with attributes associated with the Join entry (mds* attributes):

• mdsEntityOwner identifies the owner of the entry within the context of the single Meta directory.
• mdsCVMembership or mdsMVMembership identifies CV or MV membership. If we are looking at a Meta View entry, we see only mdsMVMembership attribute and a value of the connector view to indicate that this entry is a linked entry for this Meta view
• mdsCVLinktype or mdsMVLinktype identifies the link type within the context of the connector or the Meta view as either automatic/Join Engine (A) or manual/Operator (M)

• mdslinkToCV or mdslinktoMV identifies the RDN of the linked entry. The linked entry in the connector view would have the RDN in this field pointing back to the Meta view. The mdslinkToCV describes the link to the connector view entry within the context of the MV. The mdslinktoMV describes the link to an MV entry within the context of the CV.