Choose or write a selector for config modifiers

In a config modifier, a selector is the JSON path of the field that the modifier should act upon. In other words, the selector determines where a config modifier's defined processing should happen within a payload.

By designating the path and using config modifier keywords, you can choose which action should happen on the specified selector. There's intentionally a lot of flexibility. You can overwrite existing values and arrays, add to existing arrays, or build new arrays altogether.

This article contains guidelines for writing your selectors and config modifiers based on what action you want to occur on the payload.

There are different ways to choose or write a selector for a config modifier. It largely depends on which format the data is in.

For Redox data models or FHIR® resources, follow the guidelines for choosing a selector from a drop-down list.

For all other formats, follow the guidelines for writing a selector.

Because of format differences, you might use paths like any of these for different formats:

If you're targeting a field path from a Redox data model or FHIR® resource, select the field path from a drop-down list. The drop-down list is comprehensive for data models but not for FHIR® paths (there are too many possibilities with FHIR® to show all the options).

You can manually edit the field path after you've chosen it from the drop-down.

If you're targeting a field path for any other format (i.e., not a Redox data model or FHIR® resource), you must write the JSON path from scratch. If needed, find the field path in the input payload snapshot for reference.

Then, review a help article and refer to these JSONPath expressions to help write your JSON path correctly:

An asterisk (*) indicates that all objects or elements should be included, regardless of their name. You can use asterisks in selectors to indicate that all items within an array should be acted upon.

Use an asterisk (*) at the end of an array path name to operate on all elements within an array.

Let's say you have this initial payload:

1
{
2
  "My": {
3
    "ArrayPath": [{
4
      "PropertyName": "value-1"
5
    }, {
6
      "PropertyName": "value-2"
7
    }]
8
  }
9
}

You want to replace everything inside ArrayPath. So you would write this selector:

1
Selector: $.My.ArrayPath[*]

And build a config modifier schema with a keyword like this:

1
constant: 'new-value'

These would produce this output payload:

1
{
2
  "My": {
3
    "ArrayPath": [
4
      "new-value",
5
      "new-value"
6
    ]
7
  }
8
}

Since they original values in the array are replaced, you'd end up with the same number of values that existed in the input. However, they'd be replaced with the new values indicated in the config modifier schema.

Use an asterisk (*) at the end of the array path name to operate on all elements within an array. However, if you only want to operate on specific elements within the array, add the element name without an asterisk.

Let's say you have this initial payload:

1
{
2
  "My": {
3
    "ArrayPath": [{
4
      "PropertyA": "old-value-1",
5
      "PropertyB": "value-will-not-change"
6
    }, {
7
      "PropertyA": "original-value-2",
8
      "PropertyB": "value-will-not-change"
9
    }]
10
  }
11
}

You want to modify a specific element within ArrayPath. So you would write this selector:

1
Selector: $.My.ArrayPath[*].PropertyA

And build a config modifier schema with a keyword like this:

1
constant: 'new-value'

These would produce this output payload:

1
{
2
  "My": {
3
    "ArrayPath": [{
4
      "PropertyA": "new-value",
5
      "PropertyB": "value-will-not-change"
6
    }, {
7
      "PropertyA": "new-value",
8
      "PropertyB": "value-will-not-change"
9
    }]
10
  }
11
}

So all items with the same property name would change.

To overwrite an existing value, enter the specific element name without an asterisk (*). If you enter a specific array name, this means that the new value will overwrite the entire array.

For example, let's say you have this initial payload:

1
{
2
  "My": {
3
    "ArrayPath": [{
4
      "PropertyName": "value-1"
5
    }, {
6
      "PropertyName": "value-2"
7
    }]
8
  }
9
}

You want to overwrite all the values within ArrayPath. So you would write this selector:

1
Selector: $.My.ArrayPath

And build a config modifier schema with a keyword like this:

1
constant: 'new-value'

These would produce this output payload:

1
{
2
  "My": {
3
    "ArrayPath": "new-value"
4
  }
5
}

Use the concat keyword to build elements into a new array within a payload.

Let's say you have this initial payload:

1
{
2
  "My": {
3
    "Property": "value-1"
4
  }
5
}

You want to build an entirely new array. So you would write this selector:

1
$.My.NewArray

And build a config modifier schema with a keyword like this:

1
concat:
2
  - constant: new-value

These would produce this output payload:

1
{
2
  "My": {
3
    "Property": "value-1",
4
    "NewArray": [
5
      "new-value"
6
    ]
7
  }
8
}

Use the concat keyword to add values to an existing array within a payload, while retaining any initial values.

Let's say you have this initial payload:

1
{
2
  "My": {
3
    "ArrayPath": [{
4
      "PropertyName": "value-1"
5
    }, {
6
      "PropertyName": "value-2"
7
    }],
8
    "Property": "value-3"
9
  }
10
}

You want to add new values along with existing values at My.Property. So you would write this selector:

1
Selector: $.My.Property

And build a config modifier schema with a keyword like this:

1
concat:
2
  - {}
3
  - constant: new-value

These would produce this output payload:

1
{
2
  "My": {
3
    "ArrayPath": [{
4
      "PropertyName": "value-1"
5
    }, {
6
      "PropertyName": "value-2"
7
    }]
8
    "Property": [
9
      "value-3"
10
      "new-value"
11
    ]
12
  }
13
}

So you would retain original values while adding new values to the array.

Specify a particular value in an array that should change based on your selector.

Let's say you have this initial payload:

1
{
2
  "MyProperty": [{
3
    "id": "some-id",
4
    "value": "some-value"
5
  }, {
6
    "id": "specific-id",
7
    "value": "specific-value"
8
  }]
9
}

You want to change the id value within the array at My.Property, but you only want to change the value where id is currently equal to specific-id:

1
$.MyProperty[?(@.id==="specific-id")].id

And build a config modifier schema with a keyword like this:

1
constant: new-id

These would produce this output payload:

1
{
2
  "MyProperty": [{
3
    "id": "wrong-id",
4
    "value": "wrong-value"
5
  }, {
6
    "id": "new-id",
7
    "value": "specific-value"
8
  }]
9
}

So only one value in an array would change based on the conditions you defined.