Attribute Transformers

An Attribute Transformer is used to transform a set of data, or attributes, into a possibly different set of data.

It can be used to add, change or remove attributes.

The following s Attribute Transformer types are supported:

All Attribute Transformers have the following common properties:

  • id: the ID of the Attribute Transformer.
  • excluded-attributes: list of attributes to filter out.
  • transformer-type: one of the types mentioned above.

In the following sections, more details are given about each different Attribute Transformer type.

Regex Transformer

The Regex Transformer can be used to perform substitutions in the values of a set of attributes, dependent on whether the attribute values match a predefined regular expression.

The Regex Transformer specifies only one property:

  • attributes: List of attributes to be transformed. At least one element must be provided.

Each entry must specify the following:

  • attribute-base-path: the path to the attribute, or “$root” if the attribute is under the attributes tree root.
  • attribute-name: name of the attribute to be transformed.
  • transformed-attribute-name: the name of the attribute after it is transformed. This is optional.
  • matching-regex: the regular expression to use to match against the attribute value.
  • replacement-value: the transformed attribute value.

The base path of the attribute is specified using the dot notation. For example, to transform the email of an user account, the attribute-base-path would have the value emails.email, and in this case, the attribute-name would be simply value.

If the base path of the attribute is the root itself, attribute-base-path must be set to “$root”. In all other cases, explicitly declaring the root is optional, hence $root.emails.email is equivalent to emails.email.

attribute-name is the simple name of the attribute, not including its path, as seen above.

If provided, transformed-attribute-name is the new name of the attribute after the transformation is applied. If not provided, the attribute’s name is kept unchanged.

The value of matching-regex is the regular expression that will be used to match against the value of the attribute being transformed. If the regex matches, the value is transformed using the provided replacement-value, otherwise the value is kept unchanged.

Notice that the replacement-value may contain parts of the original value by referring to the matching regex groups (see the examples below).

Note

If an empty replacement-value is provided, the attribute will be removed rather than transformed in case it is single-valued, or the items matching the regex will be removed in case it is multi-valued (and if all items are removed, the attribute itself gets removed). Only String values can be replaced using the Regex Transformer.

Regex transformation examples

The following examples should make it clear how you can use regular expressions effectively to transform attributes.

Given the following attributes, in JSON format:

Listing 6 Example of original user attributes
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "name": { "givenName": "Joe", "familyName": "Doe" },
  "subject": "joe_doe",
  "emails": [
    {
      "value": "joe@acme.com",
      "type": "work",
      "primary": true
    },
    {
      "value": "joe@doe.com",
      "type": "home"
    }
  ]
}

Example 1. A Regex Transformer that removes the name attribute and replaces the value of the subject attribute when a value matches the simple joe_doe regex:

Listing 7 simple attribute-transformer configuration example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<attribute-transformer>
  <id>regexTransformer1</id>
  <excluded-attributes>name</excluded-attributes>
  <regex-transformer>
    <attributes>
      <attribute-base-path>$root</attribute-base-path>
      <attribute-name>subject</attribute-name>
      <matching-regex>joe_doe</matching-regex>
      <replacement-value>Joe_Doe</replacement-value>
    </attributes>
  </regex-transformer>
<attribute-transformer>

Result:

Listing 8 Example 1 transformed attributes
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "subject": "Joe_Doe",
  "emails": [
    {
      "value": "joe@acme.com",
      "type": "work",
      "primary": true
    },
    {
      "value": "joe@doe.com",
      "type": "home"
    }
  ]
}

Example 2. A Regex Transformer that replaces all email attribute values ending with @acme.com to a value ending with @foo.org instead:

Listing 9 Example regex transformer that uses a regex group to replace part of an attribute value
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<attribute-transformer>
  <id>regexTransformer1</id>
  <regex-transformer>
    <attributes>
      <attribute-base-path>emails</attribute-base-path>
      <attribute-name>value</attribute-name>
      <matching-regex>(*.@)acme\.com</matching-regex>
      <replacement-value>$1foo.org</replacement-value>
    </attributes>
  </regex-transformer>
<attribute-transformer>

Result:

Listing 10 Example 2 transformed attributes
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "name": { "givenName": "Joe", "familyName": "Doe" },
  "subject": "joe_doe",
  "emails": [
    {
      "value": "joe@foo.org",
      "type": "work",
      "primary": true
    },
    {
      "value": "joe@doe.com",
      "type": "home"
    }
  ]
}

Data Source Transformer

The Data Source Transformer uses a Data Source to lookup new values for pre-defined attributes. If for some reason the result of the data source lookup doesn’t contain the attribute, the original value is used.

Only attributes defined in the attribute list are replaced with data source values. Other attributes are passed through without change.

The Data Source Transformer only uses the first record returned by the data source.

The following properties may be set:

  • attribute-data-source: The data-source to use to lookup attributes.
  • attributes: The list of attributes to perform the transformation on.

Note

Some data sources can be customized by configuring a custom-attribute-query, which is used for this lookup.

Each attribute entry may specify the following:

  • attribute-name: name of the attribute to be transformed.
  • transformed-attribute-name: The name of the resulting attribute after the transformation is applied. If not set the name will be the same as the original attribute.
  • use-value-of-attribute-named: The name of the attribute (eg. column) that contains the replacement value for the attribute.
  • additional-attributes-to-include: This is a whitelist of attributes that if returned by the data source, will be added to the transformation response.

Data Source Transformation example

Listing 11 Example data source transformer that adds extra information to a set of attributes and replaces the subject attribute value with the data source-provided account_id.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<attribute-transformer>
  <id>dsTransformerSqlForSecondaryDomain</id>
  <excluded-attributes>accountid</excluded-attributes>
  <data-source-transformer>
    <attribute-data-source>DefaultHSQLDBAttributeNameLookupSecondaryDomain</attribute-data-source>
    <attributes>
      <attribute-name>subject</attribute-name>
      <use-value-of-attribute-named>account_id</use-value-of-attribute-named>
    </attributes>
    <additional-attributes-to-include>linked_account_domain_name</additional-attributes-to-include>
    <additional-attributes-to-include>linked_account_id</additional-attributes-to-include>
  </data-source-transformer>
</attribute-transformer>

Script Transformer

The Script Transformer simply invokes a transformation procedure script to transform attributes.

The only property that is specific to the Script Transformer is:

  • transformation-procedure: the ID of the transformation procedure to use.

This is the most powerful attribute transformer, as it allows any change at all to be performed on the original attributes. But in most cases, the other, simpler to maintain transformers, might be a better fit.