Data Sync Server Documentation Index
Configuration Reference Home

JSON Attribute Mapping Field

A JSON Attribute Mapping Field is used to construct a value for a single JSON field as part of a JSON Attribute Mapping. The field value can be populated from either a source attribute or a constructed value pattern.

If a single value for the field cannot be constructed (either the required attributes are not present on the source entry or the resulting value has the wrong type), then the mapping does not fail, but the field will not be present in the JSON attribute.

↓Relations to This Component
↓Properties
↓dsconfig Usage

Relations to This Component

The following components have a direct composition relation to JSON Attribute Mapping Fields:

Properties

The properties supported by this managed object are as follows:


Basic Properties: Advanced Properties:
↓ description  None
↓ json-field
↓ json-type
↓ from-attribute
↓ value-pattern

Basic Properties

description

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

json-field (Read-Only)

Description
Specifies the name of the JSON field whose value will be constructed. The specified field must be at the top of the desired JSON object hierarchy. That is, the field cannot be a field within a nested object.
Default Value
None
Allowed Values
The name of the JSON field
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

json-type

Description
The type of the JSON field. This is used to validate the content of the field. Use 'raw' to avoid most validation. 'string' types are automatically enclosed in quotes and special characters escaped.
Default Value
None
Allowed Values
boolean - The value is boolean (true or false).

number - The value is a JSON number.

object - The value is a JSON object.

raw - The value is raw JSON. It could be any of the types here or an array. String values must be quoted and special characters escaped.

string - The value is a string. It will automatically enclosed in quotes and special characters escaped.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

from-attribute

Description
Specifies the name of the source attribute whose value is used to directly provide the value of the JSON field.
Default Value
None
Allowed Values
The name of the source attribute
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

value-pattern

Description
Specifies a pattern for constructing the field value using fixed text and attribute values from the source entry. If the json-type property is set to 'string', then the value will automatically be quoted and special characters escaped. By default, any text provided in the value-pattern is copied verbatim into the target value with the exception of attribute names embedded in '{}'s. Attributes are substituted using their value, e.g. {uid} will select the uid attribute from the entry and use that value in place of {uid} in the value-pattern. No attribute values may be multivalued. If the entry has no value or if there are any multivalued attributes, the field value construction will fail and no values will be constructed. The field will be omitted from the JSON attribute. 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.

In addition, a JSON object filter may be provided in parentheses after the JSON field name to indicate that the field value will only be extracted if the attribute value matches the provided filter. For example, if 'ubidEmailJSON' is a JSON attribute and the 'value' field is to be extracted only for values where the 'type' field is equal to 'work', then the value pattern that would specify this would be '{ubidEmailJSON.value({{"filterType":"equals","field":"type","value":"work"}})}' or '{ubidEmailJSON.value({{"filterType":"equals","field":"type","value":"work"}})}:/regex/replacement/flags' if a regular expression is to be used. Note that all instances of '{' and '}' need to be escaped as '{{' and '}}' within the constructed value including those in the JSON object filter.

To apply modifiers to the values extracted append ':' and then the name of the modifier to apply. For example, if field 'mail' is to be included in a nested JSON object 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. This is only required if the json-type is not 'string' but what is being included is within a string. For instance, it is part of a nested object.
  • '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' attribute 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 is 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 either attributes have multiple values.
Default Value
None
Allowed Values
The pattern to use to construct the field value.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured JSON Attribute Mapping Fields:

dsconfig list-json-attribute-mapping-fields
     [--property {propertyName}] ...

To view the configuration for an existing JSON Attribute Mapping Field:

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

To update the configuration for an existing JSON Attribute Mapping Field:

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

To create a new JSON Attribute Mapping Field:

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

To delete an existing JSON Attribute Mapping Field:

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