Build a config modifier

Last updated: Aug 5, 2024
DEVELOPER
IMPLEMENTATION

A config modifier is an operation that applies a set of custom instructions for processing incoming or outgoing data. Learn about operations.

Creating a config modifier may sound intimidating. This reference guide breaks down the Redox-specific syntax you should use to build a config modifier schema.

You build a config modifier schema with keywords, which specify what action to take on the payload at a given point in time. If keywords exist at the same nesting level in a schema, they execute according to this listed execution order, not the order they appear in the schema itself:

  1. omit
  2. constant
  3. use
  4. get
  5. properties or if or concat
  6. default
  7. plugin

For example, if you add get above use in the schema, use still executes first.

Keywords build on each other, so each one uses the previous keyword's output as its input. For example, the output of use is the input of get.

Review the requirements and notes about each keyword below.

1. omit

Denotes an intentionally omitted output from the processed payload. Though it's the first keyword in order of execution, we recommend using it in the context of a conditional if keyword.

Examples for omit

For example, you could specify that a processed payload should omit a particular field if its value doesn't equal the term you define.

Example: Omit input
json
1
{
2
"favoriteAppetizer": "Buffalo wings",
3
"favoriteDessert": "Cheesecake"
4
}

If the term value matches what you define, the output returns the then constant value. If the value doesn't match, the field is omitted altogether.

Example: Config modifier with omit keyword
yaml
1
if:
2
operator: equals
3
terms:
4
- get: favoriteAppetizer
5
- constant: veggies & dip
6
then:
7
constant: yum
8
else:
9
omit: true
Example: Omit output
json
1
{
2
"favoriteDessert": "Cheesecake"
3
}

2. constant

Specifies a value to always return. This value can be a primitive value or an object.

A constant in the config modifier schema means that all work stops at that point, which negates any other keywords at the same nesting level or below it.

Examples for constant

For example, you could define the value to always return at a given selector.

Example: Constant selector
json
1
"$.greeting"
Example: Constant value
yaml
1
constant: Hello world
Example: Constant output
json
1
{
2
"greeting": "Hello world"
3
}

3. use

Indicates which payload to act upon.

Available values

Value
Notes
initialPayload
The first payload Redox receives either from the source or as a response from the destination. This is the payload before a Redox base config is applied.
processedPayload
The output payload after applying a Redox base config operation. This payload is either in Redox FHIR® or data model formats, or in an external format, depending on where in log processing the base config is applied. This payload will be updated with either the Delete or Write config modifier flavor.

Examples for use

For example, you could indicate that you always want to use the value at a given selector from the initial payload.

Example: Use input from initial payload
json
1
{
2
"favorites": {
3
"dessert": "Cheesecake"
4
"appetizer": "Buffalo wings"
5
}
6
}
Example: Config modifier with use keyword
yaml
1
use: initialPayload
2
get: favorites.dessert
Example: Use output
json
1
"Cheesecake"

4. get

Retrieves a value at a given path. To retrieve a nested property value, use dot.notation; a prefix . isn't required. Additionally, we support an array[index] notation (e.g., get: someArray[0].someProperty).

This value can either be simply returned or used as a starting point for other keywords at the same level or nested below.

Examples for get

For example, you could indicate which value in an array to return.

Example: Get input from initial payload
json
1
{
2
"favorites": {
3
"dessert": "Cheesecake"
4
"appetizer": "Buffalo wings"
5
}
6
}
Example: Config modifier with get keyword
yaml
1
use: initialPayload
2
get: favorites.dessert
Example: Get output
json
1
"Cheesecake"

5. properties

Defines individual properties to construct an object in the output payload.

Examples for properties

For example, you could define which fields to use to build an object.

Example: Properties selector
json
1
"$.guests"
Example: Config modifier with properties keyword
yaml
1
properties:
2
host:
3
constant: Eva
4
guestOfHonor:
5
constant: Phil
Example: Properties output
json
1
{
2
"guests": {
3
"host": "Eva"
4
"guestOfHonor": "Phil"
5
}
6
}

5. if

Defines a conditional state to run a given action or not.

A conditional allows you to determine how to construct an output value by conditionally executing different keywords, based on the evaluation of a set of values.

You can use one of these sub-keywords to construct a conditional statement:

  • operator
  • terms
  • then
  • else

operator

Determines what action to take based on one of the following operators. The config modifier defines what should happen if a value exists and meets the criteria of any of these operators.

terms

Defines a sequential array of keywords to execute on. All terms are evaluated in sequence, then the related operator performs the appropriate action. You can review the requirements for terms based on the operator used.

then

Defines the keyword(s) to execute when the operator resolves to a true state.

else

Defines the keyword(s) to execute when the operator resolves to a false state.

5. concat

Creates an array by linking defined elements together. Each element under the concat keyword can be composed of any other valid config modifier keywords.

Examples for concat

For example, you could create an array list for a property in the output.

Example: Concat input from initial payload
json
1
{
2
"guests": {
3
"host": "Eva"
4
"guestOfHonor": "Phil"
5
"otherGuests": "Robby"
6
}
7
}
Example: Concat selector
json
1
"$.guests.otherGuests"
Example: Config modifier with concat keyword
yaml
1
concat:
2
- {}
3
- constant: Aisha
4
- constant: Dominic
5
- constant: Jin
6
- constant: Monique
Example: Concat output
json
1
{
2
"guests": {
3
"host": "Eva"
4
"guestOfHonor": "Phil"
5
"otherGuests": [
6
Robby,
7
Aisha,
8
Dominic,
9
Jin,
10
Monique
11
]
12
}
13
}

6. default

Specifies a value to return if any of the previous keywords result in a non-existent value. This value can be a primitive value or an object.

Examples for default

For example, you could set a default value for a specific value if it doesn't exist in the input.

Example: Default input
json
1
{
2
"favoriteAppetizer": "buffalo wings"
3
"favoriteDessert": "cheesecake"
4
"favoriteBeverage": "soda"
5
}
Example: Config modifier with default keyword
yaml
1
use: initialPayload
2
get: favorites.beverage
3
default: soda
Example: Default output
json
1
"soda"

7. plugin

Defines a bundle of functionality to produce a value. You can use one of these sub-keywords to construct a plugin:

Sub-keyword
Notes
name
Defines the name of the plugin to apply.
action
Specifies the action to perform with this plugin.
parameters
Lists individual operations for a given plugin.action.

Common plugins

Accepted formats

Several of our plugins require you to specify a format. These are valid formats for various plugins.