Flow rule

A flow rule (hereafter called a rule) is a description of how, and maybe under what conditions, information should flow from a source to a target attribute - and even perhaps how the source value(s) should transform in the process. Depending on the flow direction, the source and target can be either a connector space attribute or a metaverse attribute.

During transition from source to target, source values are converted to strings to be able to apply any transforms. It is the responsibility of the transform rules to make sure that the value handed to the target value corresponds to the datatype (or can be converted to the target datatype).

You can have several rules with the same name and use [conditions|Conditions] to determine which rule is applied to specific objects.

Each rule consists of the following elements -

• Conditions (optional)
• SourceExpression (contains one or more source)
• Target

A typical rule looks like this

<FlowRule Name="AccountName" Direction="Export" xsi:type="FlowRule">
  <Conditions Operator="Or">
    <Condition></Condition>
    ...
  </Conditions>
  <SourceExpression>
    <Source Name="AccountName">
      <Transforms>
        <Transform xsi:type="Trim"/>
        <Transform xsi:type="ToUpper"/>
        ...
      </Transforms>
    </Source>
  </SourceExpression>
  <Target Name="sAMAccountName" ActionOnNullSource="None" />
</FlowRule>

Each rule is linked to a Management Agent and you can have many rules under each MA. Each rule must have these attributes -

• Name (required: used as the name of the flow rule specified in the Synchronization Service Manager)
• Direction (required: must be either 'Import' or 'Export')
• xsi:type (required: see below)

Rule type is specified using the 'xsi:type' attribute and can be one of the following -

• FlowRule (this)
• FlowRuleCode

Each rule has one or more 'Source' attributes and a 'Target' attribute. Values flow from the source attributes to the target attribute and can be transformed after being read and before being written.

SourceExpression element

The SourceExpression element holds a list of one or more source elements. This element is required under each flow rule. If you configure more than one source then the values from the source (after transforms) are concatenated. This means that you can use this to construct, i.e. a DisplayName from several attributes like FirstName and LastName, like below where a DisplayName is constructed to be GRANFELDT, Soeren and the LastName is uppercased by the transform 'ToUpper'.

<SourceExpression>
  <Source Name="LastName" xsi:type="Attribute">
    <Transforms>
      <Transform xsi:type="ToUpper"/>
    </Transforms>
  </Source>
  <Source Value=" ," xsi:type="Constant"/>
  <Source Name="FirstName" xsi:type="Attribute"/>
</SourceExpression>

Source element

A source describes a source value to use for flowing information to a target attribute. A source value can be one of the following -

• Values from one or more CS or MV attributes (depending of flow direction)
• A constant value - a source value can be transformed before being handed to the target attribute for further processing. For more information on transforming a value have a look at the possible transforms that can be used.

On each source element, you must specify type using the attribute 'xsi:type' attribute. Possible values are -

• Attribute - for CSEntry/imports rules: The name of the source attribute can be either the name of the actual attribute or one of the following special values, [DN], [RDN], [ObjectType] or [ConnectionChangeTime]. For MVEntry/exports rules: The name of the source attribute can be either the name of the actual attribute or one of the following special values, [DN], [ObjectType]
• MultiValueAttribute
• Constant

A typical attribute source value is specified like this -

<Source Name="displayName" xsi:type="Attribute">
  <Transforms>
    <Transform xsi:type="ToUpper"/>
  </Transforms>
</Source>

and a typical constant source value looks like this -

<Source xsi:type="Constant" Value=" <text or number> "/>

You can also specify the attribute 'RetrieveFrom' (use values CS or MV) on the Source element to be able to get an attribute value from the Connectorspace (CS) for export flow rules or to get an attribute value from the Metaverse (MV) on import rules. This can be interesting if you only want to change a single bit in an existing CS value (i.e. userAccountControl). If you want to do this, a source element could look like this -

<Source Name="userAccountControl" xsi:type="Attribute" RetrieveFrom="CS">

Please note that transforms cannot be applied to constants, only to attribute values.

Target element

A target describes a target attribute that should receive the [source value|Source]. A target value should be a CS or MV attribute (depending of flow direction of the rule)

A target value received from a [source|Source] can be [transformed|Transforms] before actually being applied to a target attribute value. For more information on transforming a value have a look at the possible [transforms|Transforms] that can be used.

No source value

On target attributes, you can specify what action should be taken by supplying a value for the 'ActionOnNullSource' attribute, if no source value is present or the source value is blank. Possible actions are -

• None (this is the default and will throw an DeclineMapping exception)
• Delete
• SetDefault (use value from DefaultValue attribute) A typical target attribute is specified like this -

<Target Name="description" ActionOnNullSource="Delete" DefaultValue="Default description" />

You can have a look at some samples rules to maybe give you a better idea of the flexibility of the flow rules.