Skip to main content

Configuration

Connhex Mapper is configured through a toml file, where you can specify all the mapping details. Next, we'll discuss all the configuration sections in detail, concluding with a concrete example of a configuration file.

Subscriber (optional)​

The subscriber section specifies all the subjects (aka topics) from which Connhex Mapper will listen for incoming messages. If no subscriber is listed, Connhex Mapper will listen to all available subjects.

Format (optional)​

Format of the incoming messages.

Supported formats

Currently, Connhex Mapper only supports JSON format.

Validate (optional)​

Whether to validate the message payload or not. For example, with format set to JSON Connhex Mapper will check if the payload contains a valid JSON.

Mappers​

The mappers section is the core of the service configuration, where all the mapping details are expressed. It consists of an array of tables where each table represents a specific map. Each map includes three keys:

  • a filter (optional),
  • a query
  • a subtopic (optional).

Filter​

The filter to apply to the incoming message. It is mainly used to extract a specific attribute, or a set of attributes, from the message subject to the mapping operation.

Query​

The query key can be thought of as a DSL that expresses the transformations to be applied to the incoming message payload.

Allowed transformations​

@flatten​

This transformation is used to flatten nested objects or arrays in the input data. It takes an object or an array as input and returns a flattened version of it.

@flatten
input: ["el0" ["el1"], "el2"]
output: ["el0", "el1", "el2"]
@keys​

This transformation is used to extract the keys from an object and return them as an array. It takes an object as input and returns an array containing all the keys of the object.

@keys
input: {"key0": "value0", "key0": "value1"}
output: ["key0", "key1"]

@values​

This transformation is used to extract values from an object and return them as an array. It takes an object as input and returns an array containing all the object's values.

@values
input: {"key0": "value0", "key0": "value1"}
output: ["value0", "value1"]
@tostring​

This transformation is used to convert a value into its string representation.

@tostring
input: 23
output: "23"
@tonumber​

This transformation is used to convert a value into its number representation.

@tonumber
input: "23.3"
output: 23.3
@fill​

This transformation is used to fill an array with values from another array or object.

@fill
input: [{"fillK":"fillV"}, [{"aK":"aV"}]]
output: [{"fillK":"fillV","aK":"aV"}]
@fill
input: [{"fillK1":"fillV1","fillK2":"fillV2"}, [[{"aK":"aV"}]]]
output: [[{"fillK1":"fillV1","fillK2":"fillV2","aK":"aV"}]]
@toentries​

This transformation is used to convert the input into an array of key-value pairs. It takes an object as input and returns an array where each element is a key-value pair representing a property of the input object.

@toentries
input: {"aK":"aV"}
output: [{"key":"aK","value":"aV"}]
@toentries:k:v
input: {"aK":"aV"}
output: [{"k":"aK","v":"aV"}]
@toentries:k k:v v
input: {"aK":"aV"}
output: [{"k k":"aK","v v":"aV"}]
@zip​

This transformation is used to zip arrays together, combining corresponding elements into subarrays.

@zip
input: [[1,2], ["a","b"]]
output: [[1,"a"],[2,"b"]]
@zip
input: [[{"1":"1"},{"2":"2"}], [{"a":"a"},{"b":"b"}]]
output: [[{"1":"1"},{"a":"a"}],[{"2":"2"},{"b":"b"}]]
[arr1,arr2]|@zip
input: {"arr1":[1,2], "arr2":["a","b"]}
output: [[1,"a"],[2,"b"]]
@template​

This transformation is used to apply a template to an incoming message. The transformation returns a modified version of the message where the template placeholders are replaced with the correponding values from the input message.

@template:"num is: %num%"
input: {"num": 123}
output: "num is: 123"
{"label":@template:"num is: %num%"}
input: {"num": 123}
output: {"label":"num is: 123"}

Composition of transformations​

The available transformations are composable, so they can be used together:

@zip:flatten
input: [[[1],[2]], [["a"],["b"]]]
output: [[1,"a"],[2,"b"]]

Subtopic​

Used to reassign the incoming message to a different topic. For example, if a message arrives from the messages/topic0 topic, and the subtopic is set to sub0, after the mapping the message will be redirected to the messages/topic0/sub0 topic.

Example configuration file​

format = "JSON"
validate = true

[[mappers]]
filter = "attr0"
query = "@toentries"
subtopic = "sub0"

[[mappers]]
filter = "attr1"
query = "@tonumber"