Rule Reference

Each rule in the JSON mapping file is an object that defines how a target field is populated.

Rule Properties

Property	Required	Description
target	Yes	Path in the output structure where the value is written (e.g., data/userName, data/emails[0]/value)
source	No*	Field name from the incoming JSON object (e.g., MSKEYVALUE). Can also be a list for multi-source. Supports prefixes: header:name or prop:name
constant	No*	A fixed value to set (string, number, or boolean)
header	No*	Name of a message header to read the value from
property	No*	Name of a message property to read the value from
transform	No	Transform to apply: template, appendExisting, toString, conditional (see Transformations)
template	No	Template string with placeholders or , , etc.
prefix	No	String prepended to the resolved value
separator	No	Separator used for multi-source joins or appendExisting

INFO

At least one value source (source, constant, header, or property) is required unless using transform: "conditional".

Path Syntax

The target (and source for nested reads) uses / as a path separator with array index support:

• data/userName — nested object field
• data/emails[0]/value — first element of the emails array, then its value field
• data/name/givenName — deeply nested field

Value Source Resolution Order

When a rule specifies its value source, the engine resolves it in this order:

1. header — reads from message headers
2. property — reads from message properties
3. source — reads from the incoming JSON object (supports path syntax and list for multi-source)
4. constant — uses the literal value provided

Only the first matching source type is used per rule.

Source Path Prefixes

Within source strings (including inside when.field), headers and properties can be referenced directly:

• header:roiam_customer_system_name — reads the header value
• prop:SomeProperty — reads the property value
• MX_FIRSTNAME — reads from the current source JSON object
• data/nested/field — reads a nested path from the source object

Transformations

Direct (no transform specified)

Copies the resolved value of the source field directly to the target.

{
  "source": "MX_FIRSTNAME",
  "target": "data/name/givenName"
}

toString

Converts the resolved value to a string (useful when the source is numeric).

{
  "source": "MSKEY",
  "target": "data/externalId",
  "transform": "toString"
}

template

Builds a string from a template with placeholders replaced by source values.

Single source — use :

{
  "source": "MSKEYVALUE",
  "target": "data/description",
  "transform": "template",
  "template": "Identity unique identifier: {{VALUE}}"
}

Multiple sources — use , , etc.:

{
  "source": ["MX_FIRSTNAME", "MX_LASTNAME"],
  "target": "data/displayName",
  "transform": "template",
  "template": "{{VALUE1}} {{VALUE2}}"
}

Sources in a template can also reference headers/properties using path prefixes:

{
  "source": ["MSKEYVALUE", "header:roiam_customer_system_name"],
  "target": "data/description",
  "transform": "template",
  "template": "User {{VALUE1}} from system {{VALUE2}}"
}

appendExisting

Appends the resolved value to whatever already exists in the template at that target path. If the value already contains the incoming string, it is not duplicated.

{
  "source": "MSKEYVALUE",
  "target": "bulkId",
  "transform": "appendExisting",
  "separator": ":"
}

conditional

Selects which source and transformation to apply based on runtime conditions. First matching condition wins; if none match, the default branch is used.

{
  "target": "data/userName",
  "transform": "conditional",
  "conditions": [
    {
      "when": {
        "field": "MX_FS_IDENTITY_TYPE",
        "operator": "equals",
        "value": "Employee"
      },
      "source": "MX_MAIL_PRIMARY"
    },
    {
      "when": {
        "field": "MX_FS_IDENTITY_TYPE",
        "operator": "startsWith",
        "value": "Ext"
      },
      "source": "MSKEYVALUE",
      "transform": "template",
      "template": "C_{{VALUE}}"
    }
  ],
  "default": { "source": "DISPLAYNAME" }
}

Condition Structure

Each condition entry has:

Property	Description
when.field	The field to evaluate. Can be a source JSON field name, header:headerName, or prop:propertyName
when.operator	Comparison operator (see table below)
when.value	The value to compare against (not required for exists)

Plus any standard rule properties (source, constant, header, property, transform, template, prefix, separator) that define what to do when the condition matches.

Available Operators

Operator	Description	Example
equals	Exact string match	"value": "Employee"
notEquals	Does not equal	"value": "Inactive"
contains	Field value contains substring	"value": "admin"
startsWith	Field value starts with string	"value": "EXT_"
endsWith	Field value ends with string	"value": "@company.com"
exists	Field is non-null and non-empty (no value needed)	—

Default Branch

The default object uses the same properties as a condition entry (minus the when block). It is applied when no condition matches. If omitted and no condition matches, nothing is written to the target.

See also

• Examples — complete worked examples covering all transform types