plugin

Last updated: Feb 23, 2026

DEVELOPER

IMPLEMENTATION

HEALTH TECH VENDOR

Definition

In a config modifier schema, use plugin to define 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.

Order of execution

This keyword executes in the following order:

omit
constant
references
use
get
Mutually exclusive keywords at this level:
- properties
- if
- concat
- switch
- pipe
- merge
- prefer
- items
default
plugin

Common plugins

Plugin: Dates with time

Bundles functionality for handling date values with time. This is referenced as name: date-time.

The array options are:

now
parse
render

Review examples for each below.

now

Generates the current DateTime and then renders the output.

Required parameters

Parameter	Notes
standard: string (mutually exclusive with custom)	A named identifier for the format of the input. The default is ISO. Learn about accepted formats.
custom: string (mutually exclusive with standard)	A custom-defined format for how to parse the input (ex: yyyy MM/dd HH:mm:ss). Learn about accepted formats.

Optional parameters

Parameter	Notes
timeZone: string	The time zone of the input. See possible time zone values. The default is UTC. If the input already includes an offset or time zone information then this parameter is unused.

Example

You have a Notes message that doesn’t populate Note.ServiceDateTime, which usually maps to TXA.4.1. Instead you can map either from Note.DocumentationDateTime if it exists, and if not, Redox can generate the current time into a string with the date-time plugin and now action.

Example: Now input

json

1
{
2
  "Note": {
3
      ...
4
      "DocumentationDateTime": "2025-11-26T06:25:46.868381Z"
5
  },
6
}

Example: Now selector for date-time plugin

json

1
$.TXA.4.1

Example: Now in config modifier for date-time plugin

yaml

1
prefer:
2
- use: initialPayload
3
  get: Note.DocumentationDateTime
4
  plugin:
5
    name: date-time
6
    action: render
7
    parameters:
8
      standard: HL7
9
      timeZone: America/Los_Angeles
10
- plugin:
11
    name: date-time
12
    action: now
13
    parameters:
14
      standard: HL7
15
      timeZone: America/Los_Angeles

Example: Now output for date-time plugin

json

1
{
2
  "TXA": {
3
    "2": "Behavioral Health Response Service Outreach",
4
    "4": {
5
      "1": "20251125222546"
6
    },
7
    ....
8
  },
9
}

parse

Identifies how to read an incoming date-time value; outputs an ISO-8601 string.

Optional parameters

Parameter	Notes
standard: string (mutually exclusive with custom)	A named identifier for the format of the input. The default is ISO. Learn about accepted formats.
custom: string (mutually exclusive with standard)	A custom-defined format for how to parse the input (ex: yyyy MM/dd HH:mm:ss). Learn about accepted formats.
timeZone: string	The time zone of the input. See possible time zone values. The default is UTC. If the input already includes an offset or time zone information then this parameter is unused.
outputTimeZone: string	The time zone of the output. The default is UTC.

Example

You need to map either OBR.7.1 or OBR.6.1 to the Order.CollectionDateTime in an Order.New message (review the Redox Order schema). However, the OBR.7.1 and OBR.6.1 date-times are in HL7v2 format and we need them to be converted into ISO format. You can do this with the date-time plugin and the parse action. You can pass a standard parameter of HL7 to indicate that the input format is HL7.

Example: Parse input for date-time plugin

json

1
{
2
  "ORDER": [
3
    {
4
      ...,
5
      "ORDER_DETAIL": {
6
        "OBRRQDRQ1RXOODSODT_SUPPGRP": {
7
          "OBR": {
8
            "1": "1",
9
            "2": {
10
              "1": "7502027492",
11
              "2": "EPC"
12
            },
13
            "3": {
14
              "1": "1070331"
15
            },
16
            "4": {
17
              "1": "CAR755",
18
              "2": "HOLTER MONITOR (BARDY) 3 TO 7 DAYS MAIL OUT",
19
              "3": "BARDYEAP"
20
            },
21
            "5": "R",
22
            "6": {
23
              "1": "20250625090558"
24
            },
25
            ...
26
          }
27
        }
28
      }
29
    }
30
  ]
31
}

Example: Parse selector for date-time plugin

json

1
$.Order.CollectionDateTime

Example: Parse in config modifier for date-time plugin

yaml

1
use: initialPayload
2
if:
3
  operator: none
4
  terms:
5
    - get: ORDER[0].ORDER_DETAIL.OBRRQDRQ1RXOODSODT_SUPPGRP.OBR.7.1
6
  then:
7
    get: ORDER[0].ORDER_DETAIL.OBRRQDRQ1RXOODSODT_SUPPGRP.OBR.6.1
8
  else:
9
    get: ORDER[0].ORDER_DETAIL.OBRRQDRQ1RXOODSODT_SUPPGRP.OBR.7.1
10
plugin:
11
  name: date-time
12
  action: parse
13
  parameters:
14
    standard: HL7

Example: Parse output for date-time plugin

json

1
{
2
  "Order": {
3
    ...
4
    "CollectionDateTime": "2025-06-25T09:05:58.000Z"
5
  }
6
}

render

Reads an ISO-8601 string and outputs into the specified format.

Required parameters

Parameter	Notes
standard: string (mutually exclusive with custom)	A named identifier for the format of the input. The default is ISO. Learn about accepted formats.
custom: string (mutually exclusive with standard)	A custom-defined format for how to parse the input (ex: yyyy MM/dd HH:mm:ss). Learn about accepted formats.

Optional parameters

Parameter	Notes
timeZone: string	The time zone of the input. See possible time zone values. The default is UTC. If the input already includes an offset or time zone information then this parameter is unused.

Example

You need to map the authoredOn property in the ServiceRequest resource in a FHIR® message to OBR.7.1. Since FHIR® date-times are in ISO, you need to change the format that HL7v2 specs format. You can do this with the date-time plugin and the render action, which takes in an ISO input and outputs it to your desired format.

For this case, you should set the parameter standard to HL7. You also pass a parameter of timeZone to indicate what time zone offset you’d like to apply since the input is in UTC time.

Example: Render input for date-time plugin

json

1
{
2
      "fullUrl": "https://fhir.redoxengine.com/fhir-sandbox/ServiceRequest/47842e584c94471c8c2de382b4c3ce9f",
3
      "resource": {
4
        "resourceType": "ServiceRequest",
5
        "identifier": {
6
          "value": "HAI_ISRN_20251124184000189",
7
          "system": "urn:oid:1.2.840.114350.1.13.12345.1.7.2.798268"
8
        },
9
        "requester": {
10
          "type": "Practitioner",
11
          "reference": "https://fhir.redoxengine.com/fhir-sandbox/Practitioner/35ce589e33c9431fa0a85304e0aedf90"
12
        },
13
        "authoredOn": "2025-11-24T18:40:00Z",
14
        "note": [
15
          {
16
            "text": "TVT"
17
          }
18
        ]
19
      }
20
    },

Example: Render selector for date-time plugin

json

1
$.PATIENT_RESULT[0].ORDER_OBSERVATION[0].OBR.7.1

Example: Render in config modifier for date-time plugin

yaml

1
references:
2
  authoredOn:
3
    use: initialPayload
4
    get: entry
5
    plugin:
6
      name: array
7
      action: find
8
      parameters:
9
        match:
10
          resource.resourceType: ServiceRequest
11
use: authoredOn
12
get: resource.authoredOn
13
plugin:
14
  name: date-time
15
  action: render
16
  parameters:
17
    standard: HL7
18
    timeZone: America/New_York

Example: Render output for date-time plugin

json

1
{
2
  "PATIENT_RESULT": [
3
    {
4
      "ORDER_OBSERVATION": [
5
        {
6
          "NTE": [
7
            {
8
              "3": [
9
                "TVT"
10
              ]
11
            }
12
          ],
13
          "OBR": {
14
            ...,
15
            "7": {
16
              "1": "20251124134000"
17
            }
18
          },
19
          ...
20
        }
21
       }
22
      ]
23
    }
24
  ]
25
}

Plugin: Dates

Bundles functionality for handling date values. This is referenced as name: date.

The array options are:

now
parse
render

Review examples for each below.

now

Generates the current date and then renders the output.

Required parameters

Parameter	Notes
standard: string (mutually exclusive with custom)	A named identifier for the format of the input. Learn about accepted formats.
custom: string (mutually exclusive with standard)	A custom-defined format for how to parse the input (ex: yyyy MM/dd). Learn about accepted formats.

Example

Example: Now input

json

1
{
2
  "Note": {
3
      ...
4
      "DocumentationDateTime": "2025-11-26T06:25:46.868381Z"
5
  },
6
}

Example: Now in config modifier for date plugin

yaml

1
plugin:
2
  name: date
3
  action: now
4
  parameters:
5
    standard: HL7

Example: Now output for date plugin

json

1
"20220729"

parse

Identifies how to read an incoming date value.

Optional parameters

Parameter	Notes
standard: string (mutually exclusive with custom)	A named identifier for the format of the input. The default is ISO. Learn about accepted formats.
custom: string (mutually exclusive with standard)	A custom-defined format for how to parse the input (ex: yyyy MM/dd). Learn about accepted formats.

Example

You want to map the Guarantor’s date of birth from the HL7v2 message. Since the input format is in HL7, you need to use the date plugin with the parse action while passing in the parameter of standard and setting it to HL7. The parse action outputs the input similar to the output of date-time without timestamps.

Example: Parse input for date plugin

json

1
{
2
  "PATIENT": {
3
    ...
4
    "INSURANCE": [
5
      {
6
        ...
7
        "GT1": [
8
          {
9
            ...
10
            "8": {
11
              "1": "19460228"
12
            },
13
            "9": "female",
14
            "11": {
15
              "1": "1"
16
            }
17
          }
18
        ]
19
      },
20
      ...
21
    }
22
  }
23
}

Example: Parse selector for date plugin

json

1
$.Visit.Insurances[*].Insured.DOB

Example: Parse in config modifier for date plugin

yaml

1
use: initialPayload
2
get: PATIENT.INSURANCE[0].GT1[0].8.1
3
plugin:
4
  name: date
5
  action: parse
6
  parameters:
7
    standard: HL7

Example: Parse output for date plugin

json

1
{
2
  ...
3
  "Visit": {
4
    ...
5
    "Insurances": [
6
      {
7
        ...
8
        "Insured": {
9
          ...,
10
          "DOB": "1946-02-28"
11
        }
12
      }
13
    ]
14
  }
15
}

render

Identifies how to create an output date value.

Required parameters

Parameter	Notes
standard: string (mutually exclusive with custom)	A named identifier for the format of the input. Learn about accepted formats.
custom: string (mutually exclusive with standard)	A custom-defined format for how to render the input (ex: yyyy MM/dd). Learn about accepted formats.

Example

You might have an incoming message with a Clinical Info object with the date formatted like yyyyMMdd, but you need the output to be formatted to MM/dd/yyyy. The date is associated with the Clinical Info object with a Description of Start date. You can find the object that matches, then convert the Value into the expected date format.

Example: Render input for date plugin

json

1
{
2
  ...
3
  "Order": {
4
    "ApplicationOrderID": "534-120225",
5
    "ClinicalInfo": [
6
      ...
7
      {
8
        "Abbreviation": null,
9
        "Code": "RECSTDTC1",
10
        "Codeset": null,
11
        "Description": "Start date",
12
        "Notes": [
13
        ],
14
        "Units": null,
15
        "Value": "20251202"
16
      }
17
    ]
18
    ...
19
  }
20
}

Example: Render selector for date plugin

json

1
$.Order.ClinicalInfo[*]

Example: Render in config modifier for date plugin

yaml

1
if:
2
  operator: equals
3
  terms:
4
    - get: Description
5
    - constant: Start date
6
  then:
7
    merge:
8
      - {}
9
      - properties:
10
          Value:
11
            get: Value
12
            plugin:
13
              name: date
14
              action: render
15
              parameters:
16
                custom: MM/dd/yyyy
17
  else:
18
    comment: do nothing

Example: Render output for date plugin

json

1
{
2
  ...
3
  "Order": {
4
    "ApplicationOrderID": "534-120225",
5
    "ClinicalInfo": [
6
      ...
7
      {
8
        "Abbreviation": null,
9
        "Code": "RECSTDTC1",
10
        "Codeset": null,
11
        "Description": "Start date",
12
        "Notes": [
13
        ],
14
        "Units": null,
15
        "Value": "12/02/2025"
16
      }
17
    ],
18
    ...
19
  }
20
}

Parameter	Notes
dashes: boolean	Controls if the output is rendered with or without dashes. If not specified, the default is true.

Plugin: Phone numbers

Parameter	Notes
renderFormat: string	Specifies the output to render. If not specified, the default is e164. Learn about accepted formats.

Plugin: Text formatting

Bundles functionality for manipulating text values. This is referenced as name: text.

The text options are:

lower-case
replace
split
trim
upper-case

lower-case

Converts an input string to lower case.

There aren’t any required or optional parameters for lower-case.

Example

Example: Lower-case input for text plugin

json

1
"Extensions": {
2
    "gender-identity": {
3
      "string": "Male",
4
      "url": "https://api.redoxengine.com/extensions/gender-identity"
5
    }
6
  }

Example: Lower-case selector for text plugin

json

1
$.Patient.Demographics.Extensions.gender-identity.string

Example: Lower-case in config modifier for text plugin

yaml

1
plugin:
2
  name: text
3
  action: lower-case

Example: Lower-case output for text plugin

json

1
"Extensions": {
2
    "gender-identity": {
3
      "string": "male",
4
      "url": "https://api.redoxengine.com/extensions/gender-identity"
5
    },

replace

Identifies an input string value and replaces occurrences of a given search value with a new value.

Global replace

This is a global replace operation. All occurrences of the search value are replaced with the new value.

There's no attempt to trim or normalize whitespace. If you require that functionality, you'll first need to sanitize your input value with the trim operator.

Required parameters

Parameter	Notes
newValue: string	A string value that serves as the replacement value. If not specified, the plugin returns an undefined value.

Optional parameters

Parameter	Notes
searchValue: string	The value that newValue replaces. If not specified, this defaults to a single whitespace.

Example

Example: Replace input for text plugin

json

1
"identifier": [
2
  {
3
    "system": "urn:redox:1a359110-47eb-40f6-924c-1e67079574a4:wshmrn",
4
    "type": {
5
      "text": "WSHMRN"
6
    },
7
    "value": "050050184"
8
  },
9
  ...
10
],

Example: Text plugin selector

json

1
$.entry[?(@.resource.resourceType=="Patient")].resource.identifier[*]

Example: Replace in config modifier for text plugin

yaml

1
if:
2
  operator: all
3
  terms:
4
    - get: type.text
5
  then:
6
    if:
7
      operator: equals
8
      terms:
9
        - get: type.text
10
        - constant: WSHMRN
11
      then:
12
        merge:
13
          - {}
14
          - properties:
15
              type:
16
                properties:
17
                  text:
18
                    constant: MR
19
              system:
20
                get: system
21
                plugin:
22
                  name: text
23
                  action: replace
24
                  parameters:
25
                    newValue: mr
26
                    searchValue: wshmrn
27
      else:
28
        comment: do nothing
29
  else:
30
    comment: type.text does not exist, do nothing

Example: Replace output for text plugin

json

1
"identifier": [
2
  {
3
    "system": "urn:redox:1a359110-47eb-40f6-924c-1e67079574a4:mr",
4
    "type": {
5
      "text": "MR"
6
    },
7
    "value": "050050184"
8
  },
9
  ...
10
],

split

Splits a string value on a supplied separator and returns the resulting string array. This optionally allows retrieving a specific value by index, returning only the string.

Required parameters

Parameter	Notes
separator: string	A string value used to split the input string.

Optional parameters

Parameter	Notes
getIndex: number	A number that'll be used to retrieve a specific value using a zero-based index.
fromEnd: boolean	If true, the start index begins from the end of the array and retrieves the last value first. If specified, getIndex is required. If not specified, the default is false.

Example

A good use case for split is if an HL7v2 message includes a string with -> in the initial payload. For example, component 3 of each note in ORDER_DETAIL.NTE[x]. You can map the left value to the Code of a ClinicalInfo object and the right value to the Value of a ClinicalInfo object.

Example: Split input for text plugin

json

1
"ORDER_DETAIL": {
2
        "OBRRQDRQ1RXOODSODT_SUPPGRP": {
3
         ...
4
        },
5
        "NTE": [
6
          {
7
            "1": "1"
8
          },
9
          {
10
            "1": "2"
11
          },
12
          {
13
            "1": "3",
14
            "3": [
15
              "------------"
16
            ]
17
          },
18
          {
19
            "1": "4",
20
            "3": [
21
              "Do not delete - Department info for vendor: "
22
            ]
23
          },
24
          {
25
            "1": "5",
26
            "3": [
27
              "MERCY MEDICAL CENTER"
28
            ]
29
          },
30
          {
31
            "1": "6",
32
            "3": [
33
              "MERCY NONINVASIVE CARDIOLOGY"
34
            ]
35
          },
36
          {
37
            "1": "7",
38
            "3": [
39
              "701 10TH ST SE"
40
            ]
41
          },
42
          {
43
            "1": "8",
44
            "3": [
45
              "CEDAR RAPIDS IA 52403-1251"
46
            ]
47
          },
48
          {
49
            "1": "9",
50
            "3": [
51
              "Dept: 319-221-8500"
52
            ]
53
          },
54
          {
55
            "1": "10",
56
            "3": [
57
              "Loc: 319-398-6011"
58
            ]
59
          },
60
          {
61
            "1": "11",
62
            "3": [
63
              "------------"
64
            ]
65
          },
66
          {
67
            "1": "12",
68
            "3": [
69
              "Duration (days):->3"
70
            ]
71
          },
72
          {
73
            "1": "13",
74
            "3": [
75
              "Cardiac implant:->None"
76
            ]
77
          },
78
          {
79
            "1": "14",
80
            "3": [
81
              "Placement:->In Clinic"
82
            ]
83
          },
84
          {
85
            "1": "15",
86
            "3": [
87
              "Reason for exam:->CP"
88
            ]
89
          },
90
          {
91
            "1": "16",
92
            "3": [
93
              "Wear start date:->9/26/25"
94
            ]
95
          },
96
          {
97
            "1": "17",
98
            "3": [
99
              "Device applied by:->COLEMAN, DAVID T"
100
            ]
101
          },
102
          {
103
            "1": "18",
104
            "3": [
105
              "Vendor:->CAM - BardyDX"
106
            ]
107
          },
108
          {
109
            "1": "19",
110
            "3": [
111
              "Device serial number:->123"
112
            ]
113
          }
114
        ],
115
        "DG1": [
116
          {
117
            "1": "1",
118
            "2": "I10",
119
            "3": {
120
              "1": "R94.31",
121
              "2": "Abnormal electrocardiogram (ECG) (EKG)",
122
              "3": "I10"
123
            },
124
            "4": "Abnormal electrocardiogram (ECG) (EKG)"
125
          }
126
        ]
127
      }

Example: Split in config modifier for text plugin

yaml

1
use: initialPayload
2
get: ORDER[0].ORDER_DETAIL.NTE
3
items:
4
  if:
5
    operator: includes
6
    terms:
7
      - get: 3[0]
8
      - constant: '->'
9
    then:
10
      pipe:
11
        - get: 3[0]
12
          plugin:
13
            name: text
14
            action: split
15
            parameters:
16
              separator: '->'
17
        - properties:
18
            Code:
19
              get: '0'
20
            Value:
21
              get: 1
22
    else:
23
      omit: true

Example: Split output for text plugin

json

1
"ClinicalInfo": [
2
      {
3
        "Code": "Duration (days):",
4
        "Value": "3"
5
      },
6
      {
7
        "Code": "Cardiac implant:",
8
        "Value": "None"
9
      },
10
      {
11
        "Code": "Placement:",
12
        "Value": "In Clinic"
13
      },
14
      {
15
        "Code": "Reason for exam:",
16
        "Value": "CP"
17
      },
18
      {
19
        "Code": "Wear start date:",
20
        "Value": "9/26/25"
21
      },
22
      {
23
        "Code": "Device applied by:",
24
        "Value": "COLEMAN, DAVID T"
25
      },
26
      {
27
        "Code": "Vendor:",
28
        "Value": "CAM - BardyDX"
29
      },
30
      {
31
        "Code": "Device serial number:",
32
        "Value": "123"
33
      }
34
    ]

trim

Removes leading and trailing whitespace from the input string.

Optional parameters

Parameter	Notes
normalizeWhitespace: boolean	Indicates whether whitespace is converted. The default is true, which converts any whitespace within the input string to one character whitespace. For example, Bob Smith becomes Bob Smith. The false value doesn’t convert whitespace within the input string. For example, Bob Smith stays the same.

Example

In a FHIR® message, the Patient resource contains telecom phone values that include the extension number and the word ext.. You only care about the 7-digit phone number, so you can use the text plugin with split to grab everything before ext.. However, you’re left with some whitespaces. Using the text plugin again with trim eliminates the trailing (and any leading) whitespace.

Example: Trim input for text plugin

json

1
{
2
      "fullUrl": "urn:uuid:3186e100-8de6-448a-b869-ea8ad2d444df",
3
      "resource": {
4
        "resourceType": "Patient",
5
        ...
6
        "telecom": [
7
          {
8
            "value": "(608) 833-1557 ext. 432",
9
            "use": "home",
10
            "system": "phone"
11
          },
12
          {
13
            "value": "(608) 630-4354 ext. 123",
14
            "use": "work",
15
            "system": "phone"
16
          }
17
        ],
18
        ...
19
      }
20
    },

Example: Trim selector

json

1
$.entry[?(@.resource.resourceType=="Patient")].resource.telecom[?(@.system=="phone")].value

Example: Trim in config modifier for text plugin

yaml

1
if:
2
  operator: includes
3
  terms:
4
    - {}
5
    - constant: ext.
6
  then:
7
    pipe:
8
      - plugin:
9
          name: text
10
          action: split
11
          parameters:
12
            separator: ext.
13
      - get: '0'
14
      - plugin:
15
          name: text
16
          action: trim
17
  else: {}

Example: Trim output for text plugin

json

1
{
2
  "fullUrl": "urn:uuid:3186e100-8de6-448a-b869-ea8ad2d444df",
3
  "resource": {
4
    "resourceType": "Patient",
5
    ...
6
    "telecom": [
7
      {
8
        "value": "(608) 833-1557",
9
        "use": "home",
10
        "system": "phone"
11
      },
12
      {
13
        "value": "(608) 630-4354",
14
        "use": "work",
15
        "system": "phone"
16
      }
17
    ],
18
    ...
19
  }
20
},

upper-case

Converts an input string to upper case.

There aren’t any required or optional parameters for upper-case.

Example

Example: Upper-case input for text plugin

json

1
"Patient": {
2
   ...
3
    "Demographics": {
4
      ...
5
      "FirstName": "Apple",
6
      "IsDeceased": null,
7
      "IsHispanic": null,
8
      "Language": "en",
9
      "LastName": "Johnny",
10
      "MaritalStatus": null,
11
      "MiddleName": null,
12
      ...
13
    },

Example: Upper-case selector

json

1
$.Patient.Demographics.FirstName

Example: Upper-case in config modifier for text plugin

yaml

1
plugin:
2
  name: text
3
  action: upper-case

Example: Upper-case output for text plugin

json

1
"Patient": {
2
   ...
3
    "Demographics": {
4
      ...
5
      "FirstName": "APPLE",
6
      "IsDeceased": null,
7
      "IsHispanic": null,
8
      "Language": "en",
9
      "LastName": "Johnny",
10
      "MaritalStatus": null,
11
      "MiddleName": null,
12
      ...
13
    },

Plugin: Arrays

Bundles functionality for handling array values. This is referenced as name: array.

The array options are:

filter
find
join
last
sort
unique
without

Review examples for each below.

filter

Returns an array of values that match the specified value.

Required parameters

Parameter	Notes
match: string	A string value used to compare to other values within an input array.

Optional parameters

Parameter	Notes
partial: boolean	The default value is false. Indicates that a partial match won’t be performed. If set to true, performs a case-sensitive partial match for the specified value(s). Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted: 1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching. 2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Parameter

Notes

partial: boolean

The default value is false. Indicates that a partial match won’t be performed.

If set to true, performs a case-sensitive partial match for the specified value(s).

Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted:

1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching.

2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Example

Example: Filter input for array plugin

json

1
[
2
      {
3
        "ID": "2000746",
4
        "IDType": "EPI"
5
      },
6
      {
7
        "ID": "TEST123",
8
        "IDType": "MR"
9
      }
10
    ]

Example: Filter in config modifier for array plugin

yaml

1
plugin:
2
  name: array
3
  action: filter
4
  parameters:
5
    match:
6
      IDType: EPI

Example: Filter output for array plugin

json

1
[
2
      {
3
        "ID": "2000746",
4
        "IDType": "EPI"
5
      }
6
  ],

find

Returns the first value that matches the specified value; otherwise, returns undefined if no match is found.

Required parameters

Parameter	Notes
match: string	A string value used to compare to other values within an input array. match is only used along with array/find (and is required).

Optional parameters

Parameter	Notes
partial: boolean	The default value is false. Indicates that a partial match won’t be performed. If set to true, performs a case-sensitive partial match for the specified value(s). Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted: 1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching. 2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Parameter

Notes

partial: boolean

The default value is false. Indicates that a partial match won’t be performed.

If set to true, performs a case-sensitive partial match for the specified value(s).

Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted:

1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching.

2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Example 1: Exact match

Example: Find input for array plugin

json

1
"Order": {
2
    ...,
3
    "ClinicalInfo": [
4
      ...,
5
      {
6
        "Code": "CAMID",
7
        "Codeset": null,
8
        "Description": "Serial number",
9
        "Value": "MTP",
10
        "Units": null,
11
        "Abbreviation": null,
12
        "Notes": []
13
      }
14
    ]
15
  }

Example: Find selector for array plugin

json

1
$.Visit.Location.Facility

Example: Find in config modifier for array plugin

yaml

1
pipe:
2
  - use: processedPayload
3
    get: Order.ClinicalInfo
4
    plugin:
5
      name: array
6
      action: find
7
      parameters:
8
        match:
9
          Code: CAMID
10
          Value: MTP
11
  - get: Value

Example: Find output for array plugin

json

1
"Visit": {
2
    ...,
3
    "Location": {
4
      "Type": null,
5
      "Facility": "MTP",
6
      "FacilityIdentifiers": [],
7
      "Department": "SNH CARDIO",
8
      "DepartmentIdentifiers": [],
9
      "Room": null,
10
      "Bed": null
11
    }
12
  },

Example 2: Partial match

You want to map DocumentReference resources that are the focus in the MessageHeader and are missing the type. You need to use find in conjunction with a partial match for DocumentReference/ to find all the DocumentReference resources in the entry. You can grab the first DocumentReference resource that has resource.content[0].attachment.title populated and map it to TXA.12.1

Example: Find / partial input for array plugin

json

1
"entry": [
2
    {
3
      "resource": {
4
        "eventUri": "https://fhir.redoxengine.com/EventDefinition/DocumentReferenceCreate",
5
        "resourceType": "MessageHeader",
6
        "id": "PatientProgressDocumentReferenceMessageHeader",
7
        "source": {
8
          "name": "LucidAct Health Inc.",
9
          "endpoint": "28020876-0c46-435e-87d1-913e72e5dd08"
10
        },
11
        "focus": [
12
          {
13
            "reference": "DocumentReference/381168-PatientProgress-2025-09-01"
14
          }
15
        ]
16
      }
17
    },
18
    {
19
      "fullUrl": "urn:uuid:3b8c99e1-c84d-4a16-a620-9dd0f91c571c",
20
      "resource": {
21
        "resourceType": "Patient",
22
        ...
23
      }
24
    },
25
    {
26
      "fullUrl": "urn:uuid:2c4eba76-cfae-4f48-83f8-1c11cf35ba73",
27
      "resource": {
28
        "resourceType": "ServiceRequest",
29
        ...
30
      }
31
    },
32
    {
33
      "fullUrl": "urn:uuid:a0acbeed-f0db-4e6c-86c9-bcc566765b36",
34
      "resource": {
35
        "resourceType": "Practitioner",
36
        ...
37
      }
38
    },
39
    {
40
      "fullUrl": "urn:uuid:de56c63b-8e4a-4d47-b088-3883dbefe407",
41
      "resource": {
42
        "resourceType": "Practitioner",
43
        ...
44
      }
45
    },
46
    {
47
      "fullUrl": "urn:uuid:3ac75f6d-d37d-41ac-bcee-4be4bc30fc30",
48
      "resource": {
49
        "resourceType": "Condition",
50
        ...
51
      }
52
    },
53
    {
54
      "fullUrl": "urn:uuid:4e4645b2-258e-4f69-9cdc-2dde035e5b83",
55
      "resource": {
56
        "resourceType": "Condition",
57
        ...
58
      }
59
    },
60
    {
61
      "fullUrl": "https://api.redoxengine.com/fhir/R4/optum-tristate/Production/DocumentReference/381168-PatientProgress-2025-09-01",
62
      "resource": {
63
        "id": "381168-PatientProgress-2025-09-01",
64
        "resourceType": "DocumentReference",
65
        ...,
66
        "content": [
67
          {
68
            "attachment": {
69
              "contentType": "application/pdf",
70
              "title": "381168_CHARLES L_SANTAMARIA_1934-06-04_1205839255_LucidAct",
71
              "data":
72
              ...
73
            }
74
          }
75
        ],
76
        "subject": {
77
          "reference": "urn:uuid:3b8c99e1-c84d-4a16-a620-9dd0f91c571c"
78
        }
79
      }
80
    }
81
  ]

Example: Find / partial selector for array plugin

json

1
$.TXA.12.1

Example: Find / partial in config modifier for array plugin

yaml

1
references:
2
  documentReferenceId:
3
    comment: >-
4
      find all DocumentReference resources that are part of the MessageHeader
5
      focus
6
    pipe:
7
      - use: initialPayload
8
      - get: entry
9
      - plugin:
10
          name: array
11
          action: find
12
          parameters:
13
            match:
14
              resource.resourceType: MessageHeader
15
      - get: resource.focus
16
      - plugin:
17
          name: array
18
          action: filter
19
          parameters:
20
            match:
21
              reference: DocumentReference/
22
            partial: true
23
      - items:
24
          get: reference
25
          plugin:
26
            name: text
27
            action: split
28
            parameters:
29
              separator: DocumentReference/
30
              getIndex: 1
31
  documentReferenceEntries:
32
    pipe:
33
      - use: initialPayload
34
      - get: entry
35
      - items:
36
          if:
37
            operator: equals
38
            terms:
39
              - constant: DocumentReference
40
              - get: resource.resourceType
41
            then: {}
42
            else:
43
              omit: true
44
pipe:
45
  - use: documentReferenceEntries
46
  - comment: >-
47
      filter the DocumentReference array list to just the ones referenced in the
48
      MessageHeader focus field
49
    items:
50
      if:
51
        operator: includes
52
        terms:
53
          - use: documentReferenceId
54
          - get: resource.id
55
        then: {}
56
        else:
57
          omit: true
58
  - comment: >-
59
      only include DocumentReference entries where there is a value in
60
      resource.content[0].attachment.title
61
    items:
62
      if:
63
        operator: all
64
        terms:
65
          - get: resource.content[0].attachment.title
66
        then: {}
67
        else:
68
          omit: true
69
  - comment: >-
70
      if there are multiple DocumentReference entries that fit this criteria,
71
      just grab the first
72
    get: '0'
73
  - get: resource.content[0].attachment.title

Example: Find / partial output for array plugin

json

1
"TXA": {
2
    "1": 1,
3
    "12": {
4
      "1": "381168_CHARLES L_SANTAMARIA_1934-06-04_1205839255_LucidAct"
5
    },
6
    ...
7
  },

join

Creates a string from the contents of the array and the separator.

Required parameters

Parameter	Notes
separator: string	A string value that’ll be inserted immediately after each element in the array, excepting the final value in the array.

Example

A good use case of join is if you want to append the facility code to the ID when the IDType is “PI”.

Example: Join input for array plugin

json

1
"Meta": {
2
    ...,
3
    "FacilityCode": "2807"
4
  },
5
  ...
6
  "Patient": {
7
  "Identifiers": [
8
      ...,
9
      {
10
        "ID": "282089_2807",
11
        "IDType": "PI"
12
      }
13
    ]
14
  ...,
15
  }

Example: Join selector for array plugin

json

1
$.Patient.Identifiers[?(@.IDType == 'PI')].ID

Example: Join in config modifier for array plugin

yaml

1
pipe:
2
  - concat:
3
      - {}
4
      - use: initialPayload
5
        get: Meta.FacilityCode
6
  - plugin:
7
      name: array
8
      action: join
9
      parameters:
10
        separator: _

Example: Join output for array plugin

json

1
"Patient": {
2
  "Identifiers": [
3
      ...,
4
      {
5
        "ID": "282089_2807",
6
        "IDType": "PI"
7
      }
8
    ]
9
  ...,
10
  }

last

Retrieves the last element in an array.

There aren’t any required or optional parameters for last.

Example: Last input for array plugin

json

1
{
2
  ...,
3
  "PV1": {
4
    "2": "O",
5
    "3": {
6
      "1": "K.PT",
7
      "2": null,
8
      "3": null,
9
      "4": {
10
        "1": "SY.K"
11
      },
12
      "6": null
13
    }
14
    ...
15
  }
16
}

Example: Last selector for array plugin

json

1
$.PV1.3.4.1

Example: Last in config modifier for array plugin

yaml

1
references:
2
  facilityId:
3
    use: processedPayload
4
    get: PV1.3.4.1
5
pipe:
6
  - comment: >-
7
      these are the facilities where we just want to return whatever comes
8
      after the first "."
9
    constant:
10
      - CD
11
      - CR
12
      - SY
13
  - items:
14
      if:
15
        operator: equals
16
        terms:
17
          - use: facilityId
18
            plugin:
19
              name: text
20
              action: split
21
              parameters:
22
                separator: .
23
                getIndex: 0
24
          - {}
25
        then: {}
26
        else:
27
          omit: true
28
  - prefer:
29
      - plugin:
30
          name: array
31
          action: last
32
      - use: facilityId

Example: Last output for array plugin

json

1
{
2
  ...
3
  "PV1": {
4
    "2": "O",
5
    "3": {
6
      "1": "K.PT",
7
      "2": null,
8
      "3": null,
9
      "4": {
10
        "1": "K"
11
      },
12
      "6": null
13
    }
14
    ...
15
  }
16
}

sort

Sorts the array as indicated.

This operator can sort both primitive and object arrays.

Optional parameters

Parameter	Notes
order: Array of Objects	Directs how to sort the input array. If not specified, a primitive array is sorted in asc order. An object array isn’t sorted. If direction isn’t specified, the array is sorted in asc order. If multiple directions are specified, they’re evaluated in order. For example, it might sort an array first by age, then by last name. If you specify any direction other than asc or desc, the order parameter is ignored and not applied. If any other directions are defined, they are also ignored. If by isn’t specified, a primitive array is sorted according to direction. An object array isn’t sorted.

Parameter

Notes

order: Array of Objects

Directs how to sort the input array.

If not specified, a primitive array is sorted in asc order. An object array isn’t sorted.

If direction isn’t specified, the array is sorted in asc order. If multiple directions are specified, they’re evaluated in order. For example, it might sort an array first by age, then by last name. If you specify any direction other than asc or desc, the order parameter is ignored and not applied. If any other directions are defined, they are also ignored.

If by isn’t specified, a primitive array is sorted according to direction. An object array isn’t sorted.

Example

A query returns a list of patients, but maybe you want the results ordered by the modifyTimestamp input field for each patient. To get this value, you should base it off the initialPayload and add a new modifyTimestamp converted to milliseconds to each PotentialMatch, since the response schema doesn’t include a timestamp. The matches can then be sorted.

Since this adds a new modifyTimestamp field to a potential match, you might want to create a delete config modifier to remove it after sorting the array of potential matches.

Example: Sort input for array plugin

json

1
[
2
    {
3
      "id": "f0b57abb-1df5-408c-8b00-b5386af54e4d",
4
      "firstName": "John",
5
      "lastName": "Smith",
6
      "middleName": "",
7
      ...,
8
      "modifyTimestamp": "2023-04-06T05:47:13.18"
9
    },
10
    {
11
      "id": "4d6c0775-1e5b-4991-81a1-461f58954a94",
12
      "firstName": "John",
13
      "lastName": "Smith",
14
      "middleName": "W",
15
      ...,
16
      "modifyTimestamp": "2016-08-18T10:29:11.127"
17
    },
18
    {
19
      "id": "2f463e9b-2a37-4803-81f0-792a8553e391",
20
      "firstName": "John",
21
      "lastName": "Smith1",
22
      "middleName": "",
23
      ...,
24
      "modifyTimestamp": "2024-02-20T16:11:09.753"
25
    },
26
    {
27
      "id": "218e5def-f320-4229-926c-ec49d6992401",
28
      "firstName": "John1",
29
      "lastName": "Smith12",
30
      "middleName": "",
31
      ...,
32
      "modifyTimestamp": "2022-12-21T01:36:20.74"
33

34
    },
35
    {
36
      "id": "bd128e19-13cd-412a-bb3c-438f1813fbcd",
37
      "firstName": "John12",
38
      "lastName": "Smith123",
39
      "middleName": "",
40
      ...,
41
      "modifyTimestamp": "2022-12-21T01:39:20.817"
42
    },
43
    {
44
      "id": "264f1937-bdf8-4adc-b209-d11eac28d41c",
45
      "firstName": "John",
46
      "lastName": "Smithson",
47
      "middleName": "",
48
      ...,
49
      "modifyTimestamp": "2024-11-04T14:33:53.023"
50
    }
51
  ]

Example: Sort selector for array plugin

json

1
$.PotentialMatches

Example: Sort in config modifier for array plugin

yaml

1
references:
2
  potentialMatchesWithModify:
3
    use: initialPayload
4
    items:
5
      pipe:
6
        - references:
7
            modifyTimestamp:
8
              get: modifyTimestamp
9
              comment: convert to milliseconds so we can sort
10
              plugin:
11
                name: date-time
12
                action: render
13
                parameters:
14
                  standard: Milliseconds
15
          merge:
16
            - {}
17
            - properties:
18
                modifyTimestamp:
19
                  use: modifyTimestamp
20
pipe:
21
  - use: potentialMatchesWithModify
22
    plugin:
23
      name: array
24
      action: sort
25
      parameters:
26
        order:
27
          - by: modifyTimestamp
28
            direction: desc

Example: Sort output for array plugin

json

1
"PotentialMatches": [
2
    {
3
      "Demographics": {
4
        "DOB": "2000-11-15",
5
        "Sex": "F",
6
        "FirstName": "John",
7
        "LastName": "Smith",
8
        ...,
9
      }
10
    },
11
    {
12
      "Demographics": {
13
        "DOB": "1987-09-03",
14
        "Sex": "M",
15
        "FirstName": "John",
16
        "LastName": "Smith",
17
        "MiddleName": "W",
18
        ...,
19
      }
20
    },
21
    {
22
      "Demographics": {
23
        "DOB": "1998-03-08",
24
        "Sex": "M",
25
        "FirstName": "John",
26
        "LastName": "Smith1",
27
        ...
28
      }
29
    },
30
    {
31
      "Demographics": {
32
        "DOB": "1998-03-08",
33
        "Sex": "M",
34
        "FirstName": "John1",
35
        "LastName": "Smith12",
36
        ...,        
37
      }
38
    },
39
    {
40
      "Demographics": {
41
        "DOB": "1998-03-08",
42
        "Sex": "M",
43
        "FirstName": "John12",
44
        "LastName": "Smith123",
45
        ...,
46
      }
47
    },
48
    {
49
      "Demographics": {
50
        "DOB": "1988-02-01",
51
        "Sex": "U",
52
        "FirstName": "John",
53
        "LastName": "Smithson",
54
        ...,
55
      }
56
    }
57
  ],

unique

Returns an array of distinct values.

Optional parameters

Parameter	Notes
match: string	A string value that’ll be used as the de-duplication key for a non-primitive array. If a primitive array, the value of match is ignored. If an object array, the value of match uses that object property value as the de-duplication key.

Example

You’re receiving telecom information for a Patient resource that has duplicate values. You can use the plugin for array and unique to deduplicate the same telecom entries.

Example: Unique input for array plugin

json

1
{
2
      "fullUrl": "urn:uuid:2b9d8eb9-168e-4052-bcf4-874614ed9869",
3
      "resource": {
4
        ...
5
        "resourceType": "Patient",
6
        "telecom": [
7
          {
8
            "system": "phone",
9
            "use": "home",
10
            "value": "+12164445555"
11
          },
12
          {
13
            "system": "email",
14
            "value": "noilya.mese+testdelete11122025stagerx01@bighealth.com"
15
          },
16
          {
17
            "system": "phone",
18
            "use": "mobile",
19
            "value": "+12139245224"
20
          },
21
          {
22
            "system": "email",
23
            "use": "work",
24
            "value": "noilya.mese+testdelete11122025stagerx01@bighealth.com"
25
          }
26
        ]
27
      }
28
    }

Example: Unique selector for array plugin

json

1
$.entry[?(@.resource.resourceType=="Patient")].resource.telecom

You need to use two plugin array actions: a) one to sort those telecom entries without a use to the bottom of the array to save the entry that has more data; and b) one to remove duplicates with the unique action.

Example: Unique in config modifier for array plugin

yaml

1
pipe:
2
  - comment: sort to move any undefined "use" keys to the end
3
    plugin:
4
      name: array
5
      action: sort
6
      parameters:
7
        order:
8
          - by: use
9
  - comment: remove any duplicate "value" values
10
    plugin:
11
      name: array
12
      action: unique
13
      parameters:
14
        match: value

Example: Unique output for array plugin

json

1
[
2
    {
3
      "system": "phone",
4
      "use": "home",
5
      "value": "+12164445555"
6
    },
7
    {
8
      "system": "phone",
9
      "use": "mobile",
10
      "value": "+12139245224"
11
    },
12
    {
13
      "system": "email",
14
      "use": "work",
15
      "value": "noilya.mese+testdelete11122025stagerx01@bighealth.com"
16
    }
17
]

without

Returns an array of values that don’t match the specified value.

Required parameters

Parameter	Notes
match: string	A string value used to compare to other values within an input array.

Optional parameters

Parameter	Notes
partial: boolean	The default value is false. Indicates that a partial match won’t be performed. If set to true, performs a case-sensitive partial match for the specified value(s). Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted: 1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching. 2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Parameter

Notes

partial: boolean

The default value is false. Indicates that a partial match won’t be performed.

If set to true, performs a case-sensitive partial match for the specified value(s).

Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted:

1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching.

2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Example

The Patient.Identifiers array contains an ID that has an IDType of TD-MR. If you don’t want this included, you can filter it out with without.

Example: Without input for array plugin

json

1
{
2
  ...
3
  "Patient": {
4
    ...,
5
    "Identifiers": [
6
      {
7
        "ID": "10605",
8
        "IDType": "TD-MR"
9
      }
10
    ],
11
    "Notes": [
12
    ]
13
  }
14
}

Example: Without selector for array plugin

json

1
$.Patient.Identifiers

Example: Without in config modifier for array plugin

yaml

1
plugin:
2
  name: array
3
  action: without
4
  parameters:
5
    match:
6
      IDType: TD-MR

Since there’s only one Identifier in the Identifiers array and that identifier has an IDType of TD-MR, Patient.Identifiers is removed.

Example: Without output for array plugin

json

1
{
2
  ...
3
  "Patient": {
4
    ...
5
    "Notes": [
6
    ]
7
  }
8
}

Plugin: Uniform Resource Identifiers (URIs)

Parameter	Notes
isComponent: boolean	Indicates whether the underlying value should be interpreted as a full URI or just a URI component.

Parameter	Notes
isComponent: boolean	Indicates whether the underlying value should be interpreted as a full URI or just a URI component.

Plugin: Universally Unique Identifiers (UUIDs)

Bundles functionality for handling UUID or GUID values. This is referenced as name: uuid.

generate

Creates a version 4 UUID. Learn about version 4.

There aren’t any required or optional parameters for generate.

Example

No input is needed for the UUID plugin. However, you could check an input payload if the generate action is conditional on whether a certain field or value is present.

Let’s say you want to create a new FHIR® Organization resource if PATIENT[0].PV1.3.4.1 exists. A new FHIR® resource should be added to the entry array. Typically, a new uuid for a FHIR® resource is the fullUrl of the associated resource. To make it easy, you can use the uuid plugin with the generate action to generate a UUID value.

Example: Generate input for uuid plugin

json

1
"PATIENT": [
2
    {
3
      ...,
4
      "PV1": {
5
        "3": {
6
          "1": "HURHO",
7
          "2": "",
8
          "3": "",
9
          "4": {
10
            "1": "1084831"
11
          },
12
          "5": "",
13
          "6": "HHP DES MOINES HOSPICE"
14
        },
15
        ...
16
      }
17
    }
18
  ],

Example: Generate selector for uuid plugin

json

1
$.entry

Example: Generate in config modifier for uuid plugin

yaml

1
references:
2
  checkPV1:
3
    use: initialPayload
4
    get: PATIENT[0].PV1.3.4.1
5
if:
6
  operator: all
7
  terms:
8
    - use: checkPV1
9
  then:
10
    concat:
11
      - comment: original entry array
12
      - properties:
13
          fullUrl:
14
            pipe:
15
              - concat:
16
                  - constant: 'urn:uuid:'
17
                  - plugin:
18
                      name: uuid
19
                      action: generate
20
              - plugin:
21
                  name: array
22
                  action: join
23
                  parameters:
24
                    separator: ''
25
          resource:
26
            properties:
27
              resourceType:
28
                constant: Organization
29
              active:
30
                constant: 'true'
31
              name:
32
                use: checkPV1
33
  else:
34
    comment: do nothing

Example: Generate output for uuid plugin

json

1
{
2
  ...
3
  "entry": [
4
    ...
5
    {
6
      "fullUrl": "urn:uuid:85b228a6-1799-4987-bc94-a56ff08401c1",
7
      "resource": {
8
        "active": "true",
9
        "name": "1084831",
10
        "resourceType": "Organization"
11
      }
12
    }
13
  ]
14
}

Plugin: Value conversions

Bundles functionality for converting from one value type to another. This is referenced as name: convert.

The array options are:

boolean-to-string
number-to-string
string-to-boolean
string-to-number

Review examples for each below.

boolean-to-string

Converts a boolean value to its string equivalent.

Supported conversions

true to 'true'
false to 'false'

If the input value isn't a boolean, then the response returns undefined.

Also note that either single or double quotes are supported for either of the string values.

There aren’t any required or optional parameters for boolean-to-string.

Example

A FHIR® message has the extension valueBoolean in the Patient Resource. You might need to change this from boolean to a string so that it can be translated properly in your translation set before mapping it to the EHR API.

Example: Boolean-to-string input

json

1
{
2
    "fullUrl": "urn:uuid:f70fad8c-2980-4e12-bfbf-23fe7ebc1f9b",
3
    "resource": {
4
      "extension": [
5
        {
6
          "url": "http://hl7.org/fhir/us/core/StructureDefinition/consent-to-call",
7
          "valueBoolean": true
8
        }
9
      ],
10
      "resourceType": "Practitioner"
11
      ...
12
    }
13
}

Example: Boolean-to-string selector

json

1
$.entry[?(@.resource.resourceType=="Practitioner")].resource.extension

Example: Boolean-to-string in config modifier

yaml

1
pipe:
2
  - plugin:
3
      name: array
4
      action: find
5
      parameters:
6
        match:
7
          url: "consent-to-call"
8
          partial: true
9
  - get: valueBoolean
10
    plugin:
11
      name: convert
12
      action: string-to-boolean

Example: Boolean-to-string output

json

1
{
2
  "fullUrl": "urn:uuid:f70fad8c-2980-4e12-bfbf-23fe7ebc1f9b",
3
  "resource": {
4
    "extension": [
5
      {
6
        "url": "http://hl7.org/fhir/us/core/StructureDefinition/consent-to-call",
7
        "valueBoolean": "true"
8
      }
9
    ],
10
    "resourceType": "Practitioner"
11
    ...
12
  }
13
}

number-to-string

Converts a numeric value to its string equivalent.

Supported conversions

123 to '123'
-100 to '-100'
123.1 to '123.1'
9007199254740992 to '9007199254740992'

If the input value isn't numeric, then the response returns undefined.

Also note that either single or double quotes are supported for either of the string values.

There aren’t any required or optional parameters for number-to-string.

Example

You want to map waitlistid from an Athena API response into the additional-identifier Extension under the Visits array of a Scheduling.Booked message (review the Redox Scheduling data model). Because it’s a number type, you need to convert it into a string since the additional-identifier schema requires value to be of string type.

Example: Number-to-string input

json

1
{
2
  "appointmenttypeid": 641,
3
  "appointmentid": 12233807,
4
  "departmentid": 599,
5
  "providerid": 432,
6
  "waitlistid": 140178,
7
  "created": "09/02/2025 18:14:51",
8
  "patientid": 2928905,
9
  "priority": "HIGH",
10
  "note": "NP - HX OF URINARY RETENTION CATH PLACED"
11
}

Example: Number-to-string selector

json

1
$.Visit.Extensions

Example: Number-to-string in config modifier

yaml

1
references:
2
  root:
3
    pipe:
4
      - use: initialPayload
5
      - {}
6
if:
7
  operator: equals
8
  terms:
9
    - use: processedPayload
10
      get: Meta.EventType
11
    - constant: Booked
12
  then:
13
    properties:
14
      additional-identifier:
15
        properties:
16
          url:
17
            constant: https://api.redoxengine.com/extensions/additional-identifier
18
          identifier:
19
            use: root
20
            properties:
21
              value:
22
                get: waitlistid
23
                plugin:
24
                  name: convert
25
                  action: number-to-string
26
              type:
27
                constant: Athena Waitlist ID
28
              period:
29
                get: created
30
                plugin:
31
                  name: date-time
32
                  action: parse
33
                  parameters:
34
                    custom: MM/dd/yyyy hh:mm:ss
35
  else:
36
    omit: true

Example: Number-to-string output

json

1
{
2
  ...
3
  "Visits": [
4
    {
5
      "Extensions": {
6
        "additional-identifier": {
7
          "identifier": {
8
            "period": "2025-09-02T18:14:51.000Z",
9
            "type": "Athena Waitlist ID",
10
            "value": "140178"
11
          },
12
          "url": "https://api.redoxengine.com/extensions/additional-identifier"
13
        }
14
      },
15
     ...
16
  ]
17
}

string-to-boolean

Converts a set of string values to their boolean equivalent.

Supported conversions

'true' to true
'yes' to true
'no' to false
'false' to false
'null' to null

If the input value isn't a string or any of the values listed above, then the response returns undefined.

Also note that either single or double quotes are supported for any of the string values.

There aren’t any required or optional parameters for string-to-boolean.

Example

Athena’s response to an Appointments query returns a property of appointments[].consenttoCall with a string value of true or false. But you need it to be a boolean value of true or false. You can convert it with the convert plugin and string-to-boolean action. You can map this to the extension of consent-to-call in the Patient resource. This is already mapped to FHIR® using Redox’s base config, but the below is an example showing how it can be appended to the extension array in addition to using the convert and string-to-boolean plugin.

Example: String-to-boolean input

json

1
{
2
  "totalcount": 3,
3
  "appointments": [
4
    {
5
      "date": "03/12/2025",
6
      "copay": 40,
7
      "patient": {
8
        ...,
9
        "consenttocall": "true"
10
      },
11
      "duration": 30,
12
      "patientid": "1890491",
13
      ...
14
    },
15
    {
16
      "date": "03/12/2025",
17
      "copay": 0,
18
      "patient": {
19
        ...,
20
        "consenttocall": "false"
21
      },
22
      "duration": 30,
23
      "patientid": "2499392"
24
      ...,
25
    },
26
    {
27
      "date": "03/12/2025",
28
      "copay": 30,
29
      "patient": {
30
        ...,
31
        "consenttocall": "true"
32
      },
33
      "duration": 30,
34
      "patientid": "2295340",
35
      ...
36
    }
37
  ]
38
}

Example: String-to-boolean selector

json

1
$.entry[?(@.resource.resourceType=="Patient")].resource.extension

Example: String-to-boolean in config modifier

yaml

1
references:
2
   patientId:
3
    use: '@parent'
4
    get: identifier[0].value
5
pipe:
6
    - references:
7
        currentPatient:
8
            use: initialPayload
9
            get: appointments
10
            plugin:
11
                name: array
12
                action: find
13
                parametersIsProperty: true
14
                parameters:
15
                    properties:
16
                        match:
17
                            properties:
18
                                patientid:
19
                                    use: patientId
20
      concat:
21
        - {}
22
        - properties:
23
            url:
24
                constant: http://hl7.org/fhir/us/core/StructureDefinition/consent-to-call
25
            valueBoolean:
26
                use: currentPatient
27
                get: patient.consenttocall
28
                plugin:
29
                    name: convert
30
                    action: string-to-boolean

Example: String-to-boolean output

json

1
"extension": [
2
  {
3
    "url": "http://hl7.org/fhir/us/core/StructureDefinition/consent-to-call",
4
    "valueBoolean": true
5
  },
6
  {
7
    "url": "http://hl7.org/fhir/us/core/StructureDefinition/consent-to-text",
8
    "valueBoolean": true
9
  },
10
  {
11
    "url": "http://hl7.org/fhir/us/core/StructureDefinition/consent-to-call",
12
    "valueBoolean": true
13
  }
14
],

string-to-number

Converts a string value to a numeric value.

Supported conversions

'123' to 123
'-100' to -100
'123.1' to 123.1
'9007199254740992' to 9007199254740992

If the input value isn't a string, then the response returns undefined.

Also note that either single or double quotes are supported for either of the string values.

There aren’t any required or optional parameters for string-to-number.

Example

The ADT message has an OBX array that might include information for a copay amount. You want to map this to the copay extension under Insurances[*].Extensions. However, the schema expects a numeric value, and you're receiving a string. Use the convert plugin with the string-to-number action to convert it to number type.

Example: String-to-number input

json

1
"OBX": [
2
    {
3
      "1": "1",
4
      "3": {
5
        "1": "Primary Co-Pay Type"
6
      },
7
      "5": [
8
        "Specialist Visit"
9
      ]
10
    },
11
    {
12
      "1": "2",
13
      "3": {
14
        "1": "TEXTS ALLOWABLE"
15
      },
16
      "5": [
17
        "Yes"
18
      ]
19
    },
20
    {
21
      "1": "3",
22
      "3": {
23
        "1": "Financial Responsibility -- Copay"
24
      },
25
      "5": [
26
        "30.00"
27
      ]
28
    }
29
  ],

Example: String-to-number selector

json

1
$.Visit.Insurances[*].Extensions

Example: String-to-number in config modifier

yaml

1
references:
2
  copayObx:
3
    use: initialPayload
4
    get: OBX
5
    plugin:
6
      name: array
7
      action: find
8
      parameters:
9
        match:
10
          '3.1': Financial Responsibility -- Copay
11
  copayTypeObx:
12
    use: initialPayload
13
    get: OBX
14
    plugin:
15
      name: array
16
      action: find
17
      parameters:
18
        match:
19
          '3.1': Primary Co-Pay Type
20
  visitInsurances:
21
    use: '@parent'
22
comment: check if Visit.Insurances exists. If not, do nothing
23
if:
24
  operator: all
25
  terms:
26
    - use: visitInsurances
27
    - use: copayObx
28
  then:
29
    merge:
30
      - {}
31
      - properties:
32
          copay:
33
            properties:
34
              url:
35
                constant: https://api.redoxengine.com/extensions/copay
36
              decimal:
37
                use: copayObx
38
                get: 5[0]
39
                plugin:
40
                  name: convert
41
                  action: string-to-number
42
              type:
43
                use: copayTypeObx
44
                get: 5[0]
45
  else:
46
    omit: true

Example: String-to-number output

json

1
{
2
  ...
3
  "Visit": {
4
    ...
5
    "Insurances": [
6
      {
7
        ...
8
        "Extensions": {
9
          "copay": {
10
            "decimal": 30,
11
            "type": "Specialist Visit",
12
            "url": "https://api.redoxengine.com/extensions/copay"
13
          }
14
        }
15
      }
16
    ]
17
  }
18
}

Accepted formats

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

Phone numbers

Identifier	Output as E.164
+18001234567	+18001234567 (stays the same)
800.123.4567	+18001234567
800-123-4567	+18001234567
800 123 4567	+18001234567
tel:+1-800-123-4567	+18001234567
8001234567	+18001234567
(800) 123-4567	+18001234567
18001234567	+18001234567
(800) 123-4567ext987	+18001234567

Identifier	Example
e164	+18001234567
international	+1 800-123-4567
national	(800) 123-4567
rfc3966	tel:+1-800-123-4567
significant	8001234567

Dates with time

Standard

Identifier	Example(s)
HL7	20220729114900 20220729114900.123 20220729114900-0600
ISO	2016-05-25T09:08:34.123 2016-05-25T09:08:34.123-06:00
HTTP	Sun, 06 Nov 1994 08:49:37 GMT Sunday, 06-Nov-94 08:49:37 GMT Sun Nov 6 08:49:37 1994
SQL We currently only render with offsets, not timezones	2017-05-15 09:12:34 2017-05-15 09:12:34.342-06:00 2017-05-15 09:12:34.342 America/Los_Angeles
milliseconds Number of milliseconds since January 1, 1979 at midnight UTC/GMT	1659095340000
seconds Number of seconds since January 1, 1979 at midnight UTC/GMT	1659095340
RFC2822 We currently only render date-times that look like Fri, 29 Jul 2022 11:49:00 +0000	25 Nov 2016 13:23:12 GMT Fri, 25 Nov 2016 13:23:12 +0600 25 Nov 2016 13:23 Z

Custom

Custom formats

A custom format is a build-your-own format. You can use commonly used tokens to build a format that suits your needs. These formats aren't recognized as industry-regulated, but the tokens are well known, all the same.

You can use either a custom or standard format, not both.

Token	Description	Example output
S	millisecond, no padding	54
SSS	millisecond, padded to three	05
s	second, no padding	4
ss	second, padded to two padding	04
m	minute, no padding	7
mm	minute, padded to two	07
h	hour in 12-hour time, no padding	1
hh	hour in 12-hour time, padded to two	01
H	hour in 24-hour time, no padding	13
HH	hour in 24-hour time, padded to two	13
Z	narrow offset	+5
ZZ	short offset	+05:00
	techie offset	+0500
z	IANA zone	America/New_York
a	meridiem	AM
d	day of the month, no padding	6
dd	day of the month, padded to two	06
EEE	day of the week, as an abbreviated localized string	Wed
EEEE	day of the week, as an unabbreviated localized string	Wednesday
M	month as an unpadded number	8
MM	month as a padded number	08
MMM	month as an abbreviated localized string	Aug
MMMM	month as an unabbreviated localized string	August
yy	two-digit year, interpreted as >1960	14
yyyy	four-digit year	2014
D	localized numeric date	9/6/2014
DD	localized date with abbreviated month	Aug 6, 2014
DDD	localized date with full month	August 6, 2014
DDDD	localized date with full month and weekday	Wednesday, August 6, 2014

Dates

Identifier	Example(s)
HL7	20220729
ISO	2016-05-25
SQL	2017-05-15

Token	Description	Example output
d	day of the month, no padding	6
dd	day of the month, padded to two	06
EEE	day of the week, as an abbreviated localized string	Wed
EEEE	day of the week, as an unabbreviated localized string	Wednesday
M	month as an unpadded number	8
MM	month as a padded number	08
MMM	month as an abbreviated localized string	Aug
MMMM	month as an unabbreviated localized string	August
yy	two-digit year, interpreted as >1960	14
yyyy	four-digit year	2014
D	localized numeric date	9/6/2014
DD	localized date with abbreviated month	Aug 6, 2014
DDD	localized date with full month	August 6, 2014
DDDD	localized date with full month and weekday	Wednesday, August 6, 2014

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.

plugin

Definition

Order of execution

Common plugins

Plugin: Dates with time

Plugin: Dates

Plugin: Social Security numbers

Plugin: Phone numbers

Plugin: Text formatting

Plugin: Arrays

Plugin: Uniform Resource Identifiers (URIs)

Plugin: Universally Unique Identifiers (UUIDs)

Plugin: Value conversions

Accepted formats

Phone numbers

Dates with time

Dates