Mappings

open class Mappings

The Mappings builder is used to build up key/destination mappings that are applied on top of the full Dispatch payload before it is sent to a given Dispatcher.

Keys that are not mapped to are kept as they are, while a mapped destination replaces any existing value. The only exception is the root “command_name” key, where mapped values (constants or variables) are appended to any value already there, flattening arrays one level, so that multiple commands can be collected (e.g. an existing ["a"] with a mapped ["b", ["c"]] gives ["a", "b", ["c"]]). If a parent along the destination path holds a value of a different type (e.g. a string where an object is needed, or an object where an array is needed), it is replaced. Sources are always read from the original payload, so mappings don’t chain. Derived values should be computed with a dispatcher-scoped transformation, which runs before mappings.

Use the mapFrom method to supply the required source “key” and “destination” key, as well as any optional “path” entries required to access keys in nested object.

Using the following payload DataObject as an example (shown as JSON)

 {
      "source" : "value",
      "path": {
          "to" : [{
              "source": "nested value",
          }]
      }
 }

Simple usage for keys in the top level DataObject would look like so:

 mappings.mapFrom("source", to: "destination")

More complex versions requiring accessing keys that exist in nested objects and arrays would look like so:

 mappings.mapFrom(JSONPath["path"]["to"][0]["source"],
                  to: JSONPath["path"]["to"]["destination"])

The mapFrom method returns a VariableOptions that allows for setting optional properties relevant to a mapping like a ifValueEquals(:), to only perform the mapping if the value is equal to some specific string.

Use the mapConstant method to supply a constant “value” and “destination” key.

 mappings.mapConstant("value", to: "destination")

More complex versions requiring accessing keys that exist in nested objects would look like so:

 mappings.mapConstant(value, to: JSONPath["path"]["to"]["destination"])

The mapConstant method returns a ConstantOptions that allows for setting optional properties relevant to a mapping like a ifValueIn(:equals:), to only perform the mapping if a value at the given key is equal to the given target.