# Build a config modifier schema

## What is a config modifier?

A <u>config modifier</u> is an operation that applies a set of custom instructions for processing incoming or outgoing data. Review common use cases at the end of this article to see how and when to use config modifiers. 

You can [set up a config modifier in the Redox dashboard](/how-to-use-redox/change-data-with-config-modifiers/set-up-config-modifiers). But a crucial part of the config modifier is building its <u>**schema**</u>. 

## Use keywords to build a schema

You build a config modifier schema with <u>**keywords**</u>, which specify what action to take on the payload at a given point in time. 

This reference guide breaks down the Redox-specific syntax to build a config modifier schema. It’s intended to teach you how to use the coding language. 

### Execution order of keywords

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. For example, if you add `get` above `use` in the schema, `use` still executes first. 

1. [`omit`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/omit)
2. [`constant`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/constant)
3. [`references`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/references)
4. [`use`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/use)
5. [`get`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/get)
6. The following keywords execute at this level, so they’re <u>**mutually exclusive**</u>. This means only one of these keywords will execute if they’re listed at the same level.
   - [`properties`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/properties) 
   - [`if`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/if)
   - [`concat`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/concat) 
   - [`switch`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/switch) 
   - [`pipe`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/pipe) 
   - [`merge`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/merge) 
   - [`prefer`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/prefer) 
   - [`items`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/items)
7. [`default`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/default)
8. [`plugin`](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/plugin)

### Input and output of keywords

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`.

![A diagram starts with input payload, which the config modifier operates on in the execution order of keywords. The 1st keyword's output serves as the 2nd keyword's input until all keywords are operated on to produce the output payload.](https://images.ctfassets.net/cl3wt5ehhnlv/43TrqtLHhXrPnC1Kq2u7dX/114351dbd4ade9ebc1b006ccf1130790/Config-modifier-keyword-input-output.png)

*Keyword input and outputs*

### Using comments in a schema

You can use a `comment` keyword at any point in the schema. This is a free text field to add context for anyone reading the config modifier. The `comment` keyword isn’t used when processing the config modifier.

Comments may be placed anywhere in the schema.

### Config Modifier Assistant

If AI assistants are enabled in your organization, you can use our <u>**Config Modifier Assistant**</u> to help you get started building a schema. This AI assistant knows our coding language and builds a schema when you enter a natural language prompt.

![Highlights the "Help me write" button that opens Config Modifier Assistant.](https://images.ctfassets.net/cl3wt5ehhnlv/1sLhHwp9Ne6o4xkgwaJ8dr/507b4e6b1da16a3e13159a268443e40e/Config-modifier-assistant-button.png)

*Config Modifier Assistant button*

You can choose to apply the AI-generated schema or give feedback on its response. 

![A user enters a prompt and Config Modifier Assistant builds a schema. The user applies the AI-generated schema.](https://images.ctfassets.net/cl3wt5ehhnlv/5eFpt6MNkAYvqdHbb1m04S/d9eecf6d4da20778bbd0f92ab3c2a283/Config-modifier-assistant.gif)

*Using Config Modifier Assistant*

Config Modifier Assistant process things in steps. You might see a warning when the assistant has reached its step limit. If you're not finished building, simply click the **Continue** button. 

![A warning message indicates that the AI assistant has reached its step limit and has paused. ](https://images.ctfassets.net/cl3wt5ehhnlv/5JSNkpmlzlRJsb3oARv1co/db3fe43e21bfd834c455ede0bcf6e473/Config-modifier-assistant-paused.png)

*Config Modifier Assistant - Paused*

Or you might see a warning if you've reached your weekly usage limit. AI tokens reset every Sunday. You can either wait for a reset or talk to your Account Manager if you need a higher token limit.

![A warning message indicates that the user has reached their AI token usage limit the week. ](https://images.ctfassets.net/cl3wt5ehhnlv/29DWwAxkYNhEccEY7Dnolf/fa9631c8957c21450edabda921c160d7/Config-modifier-assistant-usage-limit.png)

*Config Modifier Assistant - Reached AI token limit *

## Common use cases

Here are a few use cases where config modifiers solve common data transformation problems:

<details>
<summary>Use case 1: Hardcode a specific field</summary>

Different sites expect different things. You can hardcode fields and values so that your connection always gets the required data. For example, you might expect a certain document ID type or sending facility code in every message.

<u>Scenario</u>: You’re receiving a `PatientAdmin` data model from your connection. 

<u>Problem</u>: Your connection (i.e., source system) isn’t populating the MSH.4 (i.e., `FacilityCode`) segment. Your system expects the sending facility code in `Meta.FacilityCode`. 

<u>Goal</u>: Populate the `FacilityCode` with a specific value. In this case, you know the code should always be `acme-123`.

<u>Input payload</u>: In this input payload, you see the facility code is missing from the `Meta` object.

**Example: Input payload for hardcoding a field**

```json
{
  "Meta": {
    "DataModel": "PatientAdmin",
    "EventType": "Arrival"
  }
}
```

<u>**Selector**</u>: First, define where you want the config modifier to populate a value.

**Example: Selector for hardcoding a field**

```json
$.Meta.FacilityCode
```

<u>**Schema**</u>: Next, build your schema to hardcode the `FacilityCode` value on each `PatientAdmin` message from this source feed with this keyword:

- `constant`: Since you want to output the same value on each message, you need to use the `constant` keyword. [Learn about constant](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/constant).

**Example: Config modifier schema for hardcoding a field**

```yaml
constant: acme-123
```

<u>Output payload</u>: This config modifier would result in the hardcoded `FacilityCode` value in the `Meta` object.

**Example: Output for hardcoding a field**

```json
{
  "Meta": {
    "DataModel": "PatientAdmin",
    "EventType": "Arrival",
    "FacilityCode": "acme-123"
  }
}
```

</details>

<details>
<summary>Use case 2: Populate fields with values from different segments</summary>

Different sites configure their messages differently, so data might be found in unusual places. Redox base configs account for most of these variations. But if a value is missing from the segment you expect, you could write a config modifier to pull that value from another segment. For example, your connection sends the time the visit starts in an unexpected segment.

<u>Scenario</u>: You receive a `Scheduling.New` message from your connection (i.e., the source system). 

<u>Problem</u>: Your system expects `VisitDateTime` to be populated with the time the visit starts, but in testing, you notice you’re receiving the time the visit ends. Also, the value isn’t in your preferred date-time format.

<u>Goal</u>: Populate the `VisitDateTime` from SCH 11.1 (the time the visit starts) instead of SCH.11.4 (the time the visit ends).

<u>Input payload</u>: In this input payload, the desired start time (`20240603165602`) is located at `SCH.11[0].1.1`.

**Example: Input payload for populating a field**

```json
{
  "SCH": {
    ...
    "11": [
      {
        "1": {
          "1": "20240603165602"
        },
        "2": {
          "1": ""
        },
        "3": "",
        "4": {
          "1": "20240603175602"
        }
      }
    ]
  }
}

```

<u>**Selector**</u>: First, define where you want the config modifier to populate a value.

**Example: Selector for populating a field**

```json
$.Visit.VisitDateTime
```

<u>**Schema**</u>: Next, build your schema to retrieve the value at SCH 11.1 and reformat it with these keywords: 

- `use`: You need to access the initial HL7v2 payload, which is outside the scope of the selector path. That means you need to include `use`. [Learn about use](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/use).
- `get`: You need to define where to get the value from to populate the selector path. 
- `plugin`: You need the date-time value to be in ISO-8601 format, so you need to use a plugin to reformat. [Learn about plugin](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/plugin).
  - `name`: Use the `date-time` plugin to format the value.
  - `action`: To reformat the incoming value into ISO-8601, use `parse`.
  - `parameters.standard`: Identifies the current format of the incoming value, which is in HL7 format.

**Example: Config modifier schema for populating a field**

```yaml
use: initialPayload
get: SCH.11[0].1.1
plugin:
   name: date-time
   action: parse
   parameters:
      standard: HL7
```

<u>Output payload</u>: This config modifier results in using the desired start time in the correct format.

**Example: Output payload for populating a field**

```json
{
  ...
  "Visit": {
    ...
    "VisitDateTime": "2024-06-03T16:56:02.000Z"
  }
 }

```

</details>

<details>
<summary>Use case 3: Account for inconsistent messaging</summary>

Sometimes a site is inconsistent with their own message formatting. A site might populate a value in one field in some messages but leave it blank or populate a different field for other messages. This can happen if your connection handles IDs and codes differently based on the visit or order type.

<u>Scenario</u>: Your connection sends a Visit ID in one segment for some types of visits, but in a different segment for other types of visits. 

<u>Problem</u>: Sometimes the input payload looks like Example 1, and sometimes it looks like Example 2. Redox handles the visit ID correctly for Example 1. But in Example 2, Redox uses `null` for the visit ID because it’s not where we expect.

<u>Goal</u>: Populate visit ID regardless of the visit type.

<u>Input payload</u>: These input payloads show the different locations visit ID might be. 

**Example: Input payload 1 for accounting for inconsistent messaging**

```json
{
  ...
  "PV1": {
    ...
    "19": {
      "1": "1234"
    }
  }
}
```

**Example: Input payload 2 for accounting for inconsistent messaging**

```json
{
  ...
  "PV1": {
    ...
    "50": {
      "1": "1234"
    }
  }
}
```

<u>**Selector**</u>: First, define where you want the config modifier to output a value.

**Example: Selector for accounting for inconsistent messaging**

```json
$.Visit.VisitNumber
```

<u>**Schema**</u>: Next, build your schema to look for visit ID depending on whether PV1.19.1 is populated or not with these keywords: 

- `use`: You need to access the initial HL7v2 payload, which is outside the scope of the selector path. That means you need to include `use`. [Learn about use](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/use).
- `if`: The action to take is a conditional decision. That means you need to include `if` to define the logic for each condition. [Learn about if](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/if).
  - `operator`: First, Redox should check that the value exists, so you should enter `all`. [Learn about operator](https://docs.redoxengine.com/permalink/2sG9WePgS0JG03JoQqB3BL/#operator).
  - `terms`: Next, Redox should check whether PV1.19.1 exists, so that value is our singular term. [Learn about terms](https://docs.redoxengine.com/permalink/2sG9WePgS0JG03JoQqB3BL/#terms).
    - `get`: Define where to get the value from to populate the selector path. [Learn about get](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/get).
  - `then`: Define what should happen when the `if` scenario is true. In this case, use PV1.19.1 if it exists. [Learn about then](https://docs.redoxengine.com/permalink/2sG9WePgS0JG03JoQqB3BL/#then-else).
    - `get`: If PV1.19.1. exists, retrieve its value. [Learn about get](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/get).
  - `else`: Define what should happen when the `if` scenario isn’t true. In this case, use PV1.50.1 if PV1.19.1 doesn’t exist. [Learn about else](https://docs.redoxengine.com/permalink/2sG9WePgS0JG03JoQqB3BL/#then-else). 

**Example: Config modifier schema for accounting for inconsistent messaging**

```yaml
use: initialPayload
if:
  operator: all
  terms:
    - get: PV1.19.1
  then:
    get: PV1.19.1
  else:
    get: PV1.50.1
```

<u>Output payload</u>: This config modifier results in populating the visit ID, regardless of whether PV1.19.1 is populated or not.

**Example: Output payload for accounting for inconsistent messaging**

```json
{
  ...
  "Visit": {
    ...
    "VisitNumber": "1234"
  }
}
```

</details>

<details>
<summary>Use case 4: Remove characters from a text string</summary>

Sometimes a site can’t parse or receive data you have in its existing format. If the data format is incompatible, it might return an error or the site won’t receive important data.

<u>Scenario</u>: Your connection doesn’t accept underscores for the Observation codes under `OBX.3.1`.

<u>Problem</u>: We can’t simply use the `text` plugin for `replace` where we replace all the underscores with an empty string because it will return as `undefined`.

<u>Goal</u>: Remove the underscores under every Observation code (`OBX.3.1`)

<u>Input payload</u>: In this input payload, you see the text string with extra underscore (`_`) characters. 

**Example: Input payload for removing characters from a text string**

```json
  "PATIENT_RESULT": [
    {
      "ORDER_OBSERVATION": [
        {
          ...
          "OBSERVATION": [
            {
              ...
              "OBX": {
                ...
                "3": {
                  "1": "STD_DEV_SMBG",
                  "2": "Standard deviation across SMBG values in 14 days",
                  "3": null
                }
              }
            }
          ]
        }
      ]
    }
  ]
```

<u>**Selector**</u>: First, define which text string you want to remove characters from.

**Example: Selector for removing characters from a text string**

```json
$.PATIENT_RESULT[*].ORDER_OBSERVATION[*].OBSERVATION[*].OBX.3.1
```

<u>**Schema**</u>: Next, build your schema to look for the unnecessary characters and remove from the text string with these keywords: 

- `pipe`: You need to use the output of the first keyword action as the input of the second. [Learn about pipe](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/pipe).
- `plugin:` Plugins are common actions you can leverage for your schema. 
  - `text-split`: The text plugin is for manipulating string values. The split action removes the underscore (`_`) characters. [Learn about the text plugin](https://docs.redoxengine.com/permalink/4r50wuxhs82bzn2BU9l03H/#plugin-text-formatting).
  - `array-join`: The array plugin is for manipulating array values. The join action combines the text string that was split after removing the underscore (`_`) characters. [Learn about the array plugin](https://docs.redoxengine.com/permalink/4r50wuxhs82bzn2BU9l03H/#plugin-arrays).

**Example: Config modifier schema for removing characters from a text string**

```yaml
pipe:
  - plugin:
      name: text
      action: split
      parameters:
        separator: _
  - plugin:
      name: array
      action: join
      parameters:
        separator: ''
```

<u>Output payload</u>: This config modifier results in removing the extra underscore (\_) characters from `OBX.3.1`.

**Example: Output payload for removing characters from a text string**

```json
  "PATIENT_RESULT": [
    {
      "ORDER_OBSERVATION": [
        {
          ...
          "OBSERVATION": [
            {
              ...
              "OBX": {
                ...
                "3": {
                  "1": "STDDEVSMBG",
                  "2": "Standard deviation across SMBG values in 14 days",
                  "3": null
                }
              }
            }
          ]
        }
      ]
    }
  ]

```

</details>

These are just a few use cases. During implementation, you might find other opportunities for config modifiers when you or your connection receive data you don’t expect during testing.

[Review another deep dive example](https://docs.redoxengine.com/permalink/2sG9WePgS0JG03JoQqB3BL/#greater-than) inline with the `if` keyword guidelines for how our config modifier schema works. 

### Other common use cases

Review examples throughout our building guide to solve for other common use cases:

| **Use case** | **Example(s)** |
| --- | --- |
| Check if a value exists in the initial payload. If so, set a constant value; if not, set a different constant value. | [Constant](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/constant) |
| Change a code based on whether data in the initial payload equals or includes some other text. | [Operator: equals](https://docs.redoxengine.com/permalink/2sG9WePgS0JG03JoQqB3BL/#equals) [Operator: all](https://docs.redoxengine.com/permalink/2sG9WePgS0JG03JoQqB3BL/#all) |
| Remove an observation from the `Observations` array in a Flowsheet when the code from that observation matches. | [Omit](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/omit) [Concat](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/concat) |

## Use config modifiers

See common ways config modifiers can resolve unexpected data to or from your connections. 

[Learn more](/how-to-use-redox/change-data-with-config-modifiers)

## Set up in the dashboard

Get step-by-step instructions for setting up a config modifier in the Redox dashboard.

[Learn more](/how-to-use-redox/change-data-with-config-modifiers/set-up-config-modifiers)

## Helpful articles

### What are selectors?

Selectors point to where config modifier processing should happen. Learn how to choose or write one.

[Learn more](/how-to-use-redox/change-data-with-config-modifiers/choose-or-write-config-modifier-selectors)

### Config modifiers basics

Learn how a config modifier changes data in process. 

[Learn more](/how-to-use-redox/change-data-with-config-modifiers)

### Operation types

Learn what each data operation does in Redox processing.

[Learn more](/basics/data-exchange-with-redox/operations-for-data-processing)

## Articles in this section

Dive into our reference guide for how to use keywords to build a config modifier schema.

- [omit](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/omit)
- [constant](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/constant)
- [references](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/references)
- [use](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/use)
- [get](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/get)
- [properties](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/properties)
- [if](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/if)
- [concat](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/concat)
- [switch](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/switch)
- [pipe](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/pipe)
- [merge](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/merge)
- [prefer](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/prefer)
- [items](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/items)
- [default](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/default)
- [plugin](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/plugin)
