Microsoft Identity Integration Server 2003 graphic

Attribute flow rules

Attribute flow is the process of pushing changes to an object's attributes into and out of a connector space. Attribute flow rules are defined by the attribute mappings in the management agent. The following table lists the different kinds of mappings that you can specify.

Mapping type	Description
Direct	Defines a direct relationship between a single source attribute and a single destination attribute. The destination attribute is assigned the value of the source attribute and cannot be modified by a rules extension. The attribute might have different names in the management agent schema and the metaverse schema. For example, you can map employeeID to userID.
Rules extension	Defines a direct relationship between one or many source attributes and a single destination attribute. For example, you can map two source attributes such as firstName and lastName to create a single destination attribute fullName.
Constant	Defines a single destination attribute and the constant value that the attribute will have. A source attribute does not exist. For example, you can set the value of the destination attribute OU to Contoso, Ltd for all objects.
Distinguished name	Defines a mapping between a component of the source distinguished name and a single destination attribute. For example, you might want to assign a username value that does not contain the complete distinguished name (also known as DN) from the hierarchical directory. For the user CN=MikeD,CN=Users,OU=MIIS,O=Microsoft you can map component 1 of the distinguished name to the destination attribute username. The value of username would then be MikeD.

The following illustration shows examples of the four possible attribute mapping types.

Examples of attribute mapping.

When changes to an object's attributes are sent from the connector space to the metaverse or from the metaverse to the connector space, the attributes flow according to their mappings and precedence. Import attribute flow rules (from the connector space to the metaverse) are applied when the connector space flows a change to the metaverse, and export attribute flow rules (from the metaverse to the connector space) are applied when the metaverse flows a change to the connector space.

Export attribute flow

It is important to understand how export attribute flow rules are called. Export attribute flow rules are called in the following situations:

When a source metaverse object is synchronized with a newly connected destination connector space object or when any run profile that reevaluates the rules is run. In these cases, a full export synchronization is run.
When a source metaverse object has previously been synchronized to the destination connector space object. In this case, a delta synchronization is run; that is, only values that have changed are flowed from the metaverse to the connector space.
When a reference attribute on the source metaverse object references another metaverse object that has had a connector space object (in the destination connector space) connected or disconnected. This changes the possible values that can be flowed to the destination connector space object, as only values that reference a metaverse object with connectors in the destination connector space can be flowed. In this case, the references are flowed from the metaverse to the connector space.
When a synchronization runs from the connector space to the metaverse out to another connector space. Export attribute rules are called here to flow values from the metaverse object back to the connector space object that initiated, that is, was the source of, the operation. This is done to revert imported changes on the connector space attributes as governed by the export precedence rules.
Important
- Export attribute flow rules are always called after provisioning rules have been run. Be aware that export attribute flow rules could modify attributes that were set by the provisioning rules. For this reason, any "one-time" operations, such as setting an initial password, should be done in the provisioning rules, not the export attribute flow rules.

The following illustration is an example of attribute flow. In step 1, import attribute flow pushes attribute values from the connector space object to the metaverse object by using the attribute mappings defined in the DataSource1 management agent. In step 2, export attribute flow pushes attribute values from the metaverse object to the connector space object by using the attribute mappings defined in the DataSource2 management agent.

Example of import and export attribute flow.

The following flow chart shows the sequence in which management agent rules are applied.

Flow chart of management agent rules.

Allow Nulls

When the last source attribute of an export attribute flow mapping has been deleted, then by default, the export attribute flow rules are not called and the target attribute is not modified or deleted. If you want to allow attribute deletions to flow to the target connector space, you can specify the Allow Nulls option on the Configure Attribute Flow page of Management Agent Designer. The behavior described here for source attribute deletions also applies to scenarios where the value of the source attribute is modified to NULL.

If the export attribute flow mapping is a direct mapping, the Allow Nulls option works in the manner described in the following table.

Source attribute status	Allow Nulls check box	Result of export attribute flow
Source attribute has been deleted	Clear	Target attribute is not deleted
Source attribute has been deleted	Selected	Target attribute is deleted

If the export attribute flow mapping is a rules extension, then the Allow Nulls option works in the manner described in the following table.

Source attribute status	Allow Nulls check box	Result of export attribute flow
All source attributes have been deleted	Clear	The rules extension is not called, and the target attribute is not deleted
All source attributes have been deleted	Selected	The rules extension is not called, and the target attribute is deleted

When you are exporting attribute values to a target reference attribute, it is recommended that you select Allow Nulls for the mapping. If the Allow Nulls check box is not selected, it is possible for a target reference attribute to end up referencing a deleted object.

The following table contains some examples of how reference attributes work with the Allow Nulls option.

Source attribute status	Allow Nulls check box	Result of export attribute flow
The source reference attribute has been deleted	Clear	The target reference attribute value does not change (that is, it still references the old value)
The source reference attribute has been deleted	Selected	The target reference attribute is deleted
The object referenced by the source reference attribute is not exposed to the target connector space. This can happen if there are no connectors to the object in the metaverse from the target connect space.	Clear	The target reference attribute value does not change (that is, it still references the old value)
The object referenced by the source reference attribute is not exposed to the target connector space. This can happen if there are no connectors to the object in the metaverse from the target connect space.	Selected	The target reference attribute is deleted

For more information, see Configure attribute flow rules.

Attribute precedence

When a single management agent or multiple management agents define different attribute mappings into the same destination metaverse attribute, it is recommended that you define one data source as having precedence so that you maintain data integrity. You can set attribute flow precedence per attribute for each object type by using Metaverse Designer. The precedence list is a configurable ordered list that displays each source attribute and management agent that flows data to that metaverse attribute. If an attribute is defined as having primary precedence, and a flow is attempted but the source attribute is missing, then processing continues by using the next import flow in the precedence list. For more information about Metaverse Designer, see Using Metaverse Designer.

In some cases, you want to disable attribute precedence for a particular attribute. In these cases, you can configure an attribute to use manual precedence. Manual precedence is only available for attribute flows that use a rules extension. For example, if you have multiple management agents that all need to contribute values to a multi-value attribute in the metaverse, attribute precedence would, by default, force one of the management agents to have precedence and the others would be unable to update the attribute. By configuring the attribute to use manual precedence, the rules extension can accumulate the values from all the management agents and write them all to the multi-value attribute. For more information, open the Microsoft Identity Integration Server 2003 Developer Reference.

Export precedence

Export precedence is a set of built-in rules that keep attribute values from lower-precedence connected data sources from flowing out to higher precedence connected data sources. To configure effective attribute flow, it is important to understand how export precedence is applied.

Export precedence rules are applied to export attribute flows that overlap an import attribute flow. An export attribute flow and import attribute flow are said to overlap if:

The flows refer to the same management agent, connector space object type, and metaverse object type.
The export attribute flow has at least one source attribute, which is also the destination attribute for the import attribute flow.
The destination attribute of the export attribute flow is one of the source attributes of the import attribute flow.

Export precedence rules are not applied in the following cases:

When the export attribute flow has no source attributes, that is, if it is a constant or rules extension mapping. In these cases, export attribute flow rules always run. This behavior should be kept in mind when you design attribute flow rules.
When the import flow for the attribute is configured for manual precedence. When manual precedence is configured for an attribute, normal attribute precedence rules are ignored, and the precedence is handled by the manual precedence rules extension.
When there is no overlap between any export and import attribute mappings.

If an overlap mapping is determined:

The overlap ranking is determined for the source, or metaverse attribute. The overlap ranking is the precedence ranking of the highest-precedence overlapping import attribute flow mapping from the destination connector space.
The populator ranking is determined for the source, or metaverse attribute. The populator ranking is the precedence ranking of the mapping that populated the source, or metaverse attribute.
- If the lineage on the source attribute is not recognized, that is, if it refers to an import attribute flow that has been deleted, the rank is set to the lowest precedence.
- If there are no values on the source attribute, a rank cannot be determined and the export attribute flow mapping does not run. This is to prevent behavior that might lead to unintended data loss.
The overlap ranking and the populator ranking are then compared. If the populator rank is greater than the overlap rank, that is, if the mapping that populated the export flow's source attribute has lower precedence than the import attribute flow mapping from the destination connector space, then the export attribute flow rules does not run. Otherwise, the export attribute flow rules run as configured.