Data Sync Server Documentation Index
Configuration Reference Home

Constructed Attribute Mapping

A Constructed Attribute Mapping is used when a destination attribute's values are constructed from static text and multiple source attribute values.

These source attribute values can optionally be modified using regular expressions and replacement values. A constructed attribute mapping can be used to provide a fixed set of values for an attribute or to augment attribute values with some additional fixed values. For instance, "dsconfig create-attribute-mapping --map-name ObjectClass-Map --mapping-name objectClass --type constructed --set value-pattern:ubidPersonAux --set value-pattern:{objectClass}" will add the ubidPersonAux objectClass value to the existing objectClass values from the source. To exclude certain values from synchronizing use the exclude-value property.

↓Parent Component
↓Properties
↓dsconfig Usage

Parent Component

The Constructed Attribute Mapping component inherits from the Attribute Mapping

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
↓ to-attribute ↓ also-depends-on-src-attribute
↓ description ↓ sync-on-every-update
↓ exclude-value
↓ value-pattern
↓ conditional-value-pattern

Basic Properties

to-attribute (Read-Only)

Description
Specifies the name of the attribute whose values are constructed by this attribute mapping.
Default Value
None
Allowed Values
The name of the destination attribute
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

description

Description
A description for this Attribute Mapping
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

exclude-value

Description
Specifies a list of values that will be excluded from the destination attribute after applying any other mapping or transformation.
Default Value
None
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

value-pattern

Description
Specifies a pattern for constructing the destination attribute value using fixed text and attribute values from the source entry. By default, any text provided in the value-pattern is copied verbatim into the target value with the exception of source attribute names embedded in '{}'s. Attributes are substituted using their source value, e.g. {uid} will select the uid attribute from the source entry and use that value in place of {uid} in the value-pattern. At most one attribute may be multivalued. If one attribute is multivalued then the target value will be multivalued with the same number of values minus any duplicates. For example a mapping of '{givenName} {sn}' would produce values ['Jim Smith', 'James Smith'] if givenName had values of ['Jim', 'James'] and sn had a value of 'Smith'. If the source entry has no value or if there are multiple multivalued attributes, the attribute value construction will fail. To include a '{' in the constructed value use '{{' in the value-pattern. Likewise, '}}' will result in '}' in the value pattern.

Furthermore, a regular expression with a substitution pattern can be used to further manipulate an individual attribute value. The java.util.regex.Pattern and java.util.regex.Matcher classes are used to perform the substitution. The regular expression with replacement value uses this syntax '{attr-name:/regex/replacement/flags}'.

'attr-name' is an attribute name such as 'cn'.

'regex' is a regular expression using the syntax described in the java.util.regex.Pattern javadoc. The optional flags value can also be used to change how this regular expression is interpreted.

'replacement' is a replacement value that is passed to the java.util.regex.Matcher#replaceFirst or java.util.regex.Matcher#replaceAll method to perform the replacement. The 'g' (global) flag controls whether replaceFirst or replaceAll is called.

'flags' is an optional set of single character flags that control how the regular expression is interpreted and how the replacement is performed. The flags are:

  • 'g' : Matcher#replaceAll is called instead of Matcher#replaceFirst to replace all matching values instead of just the first one.
  • 'i' : the regex pattern is compiled with Pattern.CASE_INSENSITIVE.
  • 'x' : the regex pattern is compiled with Pattern.COMMENTS.
  • 's' : the regex pattern is compiled with Pattern.DOTALL.
  • 'm' : the regex pattern is compiled with Pattern.MULTILINE.
  • 'u' : the regex pattern is compiled with Pattern.UNICODE_CASE.
  • 'd' : the regex pattern is compiled with Pattern.UNIX_LINES.
The substitution value is constructed using Java code equivalent to:

Pattern pattern = Pattern.compile(regex, flagsMask);
Matcher matcher = pattern.matcher(attributeValueInput);
String substitutionValueOutput = matcher.replaceFirst(replacement);

To extract JSON fields within JSON attributes append '.' and then the JSON field to extract to the attribute name. For example, if 'ubidEmailJSON' is a JSON attribute and the 'value' field is to be extracted then 'ubidEmailJSON.value' could be specified for the attribute name resulting in '{ubidEmailJSON.value}' or '{ubidEmailJSON.value:/regex/replacement/flags}' if a regular expression is to be used.

To apply modifiers to the values extracted append ':' and then the name of the modifier to apply. For example, if attribute 'mail' is to be included in a constructed JSON value then modifier 'jsonEscape' could be specified resulting in '{{ "userMail":"{mail:jsonEscape}" }}' or '{{ "userMail":"{mail:/regex/replacement/flags:jsonEscape}" }}' if a regular expression is to be used. Note that '{{' expands to '{' and '}}' to '}'. The modifiers are:

  • 'jsonEscape' : Escape text for use in a JSON value.
  • 'lowerCase' : Convert text to lower case.
  • 'trim' : Remove leading and trailing whitespace.
  • 'upperCase' : Convert text to upper case.
Here is an example to summarize these points. Suppose, the 'uid' field of the target entry needs to be populated with the initials of the first and last name followed by the user's employee number which is stored in the 'eid' attribute. For example, 'John Smith' with an employee id of 12345, would get a uid of 'js12345'. The value-pattern would be '{givenname:/^(.)(.*)/$1/s:lowerCase}{sn:/^(.)(.*)/$1/s:lowerCase}{eid}'. The employee's initials are extracted from the 'givenname' and 'sn' attributes. The '^(.).*' regular expression used for these attributes matches the entire value and stores the initial character in the $1 variable, which used for the replacement. (The 's' flag is used to guard against the unlikely event that the user's 'givenname' or 'sn' attribute includes a newline character.) The lowerCase modifier converts the character to lowercase. The mapping will fail if the givenname or sn attributes are not present on an entry or if both attributes have multiple values.
Default Value
None
Allowed Values
The pattern to use to construct the attribute value.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

conditional-value-pattern

Description
Specifies a pattern for conditionally constructing the destination attribute value using fixed text and attribute values from the source entry. The destination attributed is only constructed if the specified LDAP filter matches the source entry. The value specified is an LDAP filter and pattern combination for constructing the destination attribute value using fixed text and attribute values from the source entry if the LDAP filter matches the source entry. The value has this form (the ":" is literal):

LDAP-filter : pattern

The LDAP filter is similar to what can be passed to the "ldapsearch" command. For example, if the "admin-user-name" attribute is to be selected from the source if and only if the "is-admin" attributed is "true" a value like the following could be used:

(is-admin=true) : {admin-user-name}

Note that surrounding the LDAP filter with parenthesis as shown in the example above is recommended, but not required, as it reduces ambiguity.

Conditional value patterns can also be used to map attribute values. For instance, to map a source attribute 'status=inactive' to a destination attribute of 'account-disabled=true', the to-attribute would be set to account-disabled, and conditional-value-pattern would have values '(status=inactive):true' and '(!(status=inactive)):false'.

The conditional value patterns are evaluated in the order specified. The first one with a LDAP filter that matches the source entry is used. If none of the LDAP filters evaluate to true then the "value-pattern" property is used as a default, if it is specified.

See the "value-pattern" property for information about the pattern portion of the value.

Default Value
None
Allowed Values
The pattern used to construct the attribute value.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action


Advanced Properties

also-depends-on-src-attribute (Advanced Property)

Description
Changes to the specified source attribute will trigger an update to the destination attribute independent of any changes to the attributes that this mapping directly depends on. This property is very rarely needed. Any change detected at the source to the specified attribute will force the attribute value to be recomputed and updated at the destination (if it was out-of-sync). This property is only needed when the Data Sync Server cannot directly detect changes to an attribute. For instance in some environments, a Directory Server plugin might introduce attribute changes that do not show up in the LDAP change log, so a separate attribute is watched for changes even though its value does not directly contribute to the synchronized value.

This property does not need to be set except in very unusual situations.

Default Value
None
Allowed Values
A string
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

sync-on-every-update (Advanced Property)

Description
This property will cause the attribute specified in this mapping (the 'to-attribute') to get synchronized on any detected change of any attribute. This is useful when an attribute may change without any indication in the changelog. This property is very rarely needed. Any change detected at the source to any attribute will force this attribute value to be recomputed and updated at the destination (if it was out-of-sync). This property is only needed when the Data Sync Server cannot directly detect changes to an attribute. For instance in some environments, a Directory Server plugin might introduce attribute changes that do not show up in the LDAP change log.

This property does not need to be set except in very unusual situations.

Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured Attribute Mappings:

dsconfig list-attribute-mappings
     [--property {propertyName}] ...

To view the configuration for an existing Attribute Mapping:

dsconfig get-attribute-mapping-prop
     --mapping-name {name}
     --map-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing Attribute Mapping:

dsconfig set-attribute-mapping-prop
     --mapping-name {name}
     --map-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...

To create a new Constructed Attribute Mapping:

dsconfig create-attribute-mapping
     --mapping-name {name}
     --map-name {name}
     --type constructed
     [--set {propertyName}:{propertyValue}] ...

To delete an existing Attribute Mapping:

dsconfig delete-attribute-mapping
     --mapping-name {name}
     --map-name {name}