Mapping 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 {{VALUE}} or {{VALUE1}}, {{VALUE2}}, etc.
prefix	No	String prepended to the resolved value
separator	No	Separator used for multi-source joins or appendExisting
requires	No	Gate that decides whether the rule runs at all. If the gate fails, the rule is skipped entirely (nothing is written to its target). See Conditional Execution with requires below.

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

See also

• Transformations — available transform types and their behavior
• Examples — complete worked examples

Conditional Execution with requires

requires controls whether a rule runs at all, independently of how its value is resolved. If the gate is not satisfied, the engine skips the rule and writes nothing to its target.

This is the primary tool for avoiding orphan objects — partially-populated array entries or nested objects that appear in the output even when their main value is missing. A typical case: a constant like type: "work" should only be written if the corresponding emails[0]/value was actually provided.

Accepted shapes

1. String shorthand — single field must be non-null and non-empty:

{
  "constant": "work",
  "target": "data/emails[0]/type",
  "requires": "MX_MAIL_PRIMARY"
}

Equivalent to a single exists check on that field.

2. Object with any — OR semantic, at least one entry must pass:

{
  "constant": "true",
  "target": "data/emails[0]/primary",
  "requires": {
    "any": ["MX_MAIL_PRIMARY", "MX_MAIL_SECONDARY"]
  }
}

3. Object with all — AND semantic, every entry must pass:

{
  "constant": "internal",
  "target": "data/userType",
  "requires": {
    "all": [
      {
        "field": "MX_FS_IDENTITY_TYPE",
        "operator": "equals",
        "value": "EMPLOYEE"
      },
      { "field": "MX_FS_PERSONNEL_NUMBER", "operator": "exists" }
    ]
  }
}

4. Both any and all — both groups must pass (logical AND between groups).

Entry forms inside any / all

Each entry in an any or all array can be either:

• A plain string — shorthand for { field: "<string>", operator: "exists" }. Use this when you only need a "field is present" check.
• A condition object with field, operator, and (when applicable) value — same shape and operators as when blocks in transform: "conditional". See Available Operators.

The two forms can be mixed in the same array:

"requires": {
  "any": [
    "MX_MAIL_PRIMARY",
    { "field": "MX_FS_IDENTITY_TYPE", "operator": "equals", "value": "EMPLOYEE" }
  ]
}

Edge cases

Situation	Behavior
"any": [] (empty array)	Treated as false — nothing to satisfy, so the rule is skipped.
"all": [] (empty array)	Treated as true (vacuously satisfied) — the rule runs.
Object with neither any nor all	Treated as a malformed gate — the rule is skipped (fail-safe).
requires omitted	The rule always runs (existing behavior, fully backwards compatible).

When to use requires vs transform: "conditional"

• Use requires when the question is "should this rule fire at all?" — typical for constants and headers attached to an array slot or nested object.
• Use transform: "conditional" when the rule will always fire and you only need to choose which source or template to use.

The two can be combined: a conditional rule may also have a requires gate, in which case the gate is evaluated first.

See also

• Transformations — available transform types and their behavior
• Examples — complete worked examples