4. use

Last updated: Sep 11, 2025

DEVELOPER

IMPLEMENTATION

HEALTH TECH VENDOR

Definition

In a config modifier schema, use use to:

indicate which payload to act upon; or
grant access to an input payload beyond the selector’s initial scope.

This is helpful if you want to access variables or values outside the scope provided by the selector. For example, you could modify something at the selector path based on the presence or value of another path. Review available variables below this section.

This keyword is typically a sub-keyword of references, but may be used in other cases. Learn about the references keyword.

Available variables

initialPayload

The initialPayload variable refers to the first payload Redox receives either from the source or as a response from the destination.

This is the payload before a Redox base config is applied. Learn about base configs.

Example

Let’s say you want to map the value from GT1[0].6 to a PatientAdmin message under Visit.Guarantor.

The initialPayload is the entire payload that’s originally sent. In this example, the initialPayload is an HL7 ADT message. Since the base config doesn’t map the Visit.Guarantor.PhoneNumber you still need the initial data.

Example: HL7v2 ADT message

json

1
{
2
 ...
3
  "GT1": [
4
    {
5
      ...
6
      "5": [
7
        {
8
          "1": {
9
            "1": "2011 N SOTO ST"
10
          },
11
          "2": "",
12
          "3": "LOS ANGELES",
13
          "4": "CA",
14
          "5": "900323628",
15
          "6": "USA",
16
          "7": "HOME",
17
          "8": "",
18
          "9": "Los Angeles"
19
        }
20
      ],
21
      "6": [
22
        {
23
          "1": "",
24
          "2": "HOME",
25
          "3": "TEL",
26
          "4": "",
27
          "5": "",
28
          "6": "",
29
          "7": "",
30
          "8": "",
31
          "9": "",
32
          "10": "",
33
          "11": "",
34
          "12": "3234324342"
35
        },
36
        {
37
          "1": "",
38
          "2": "PAGER PERS",
39
          "3": "",
40
          "4": "",
41
          "5": "",
42
          "6": "",
43
          "7": "",
44
          "8": "",
45
          "9": "",
46
          "10": "",
47
          "11": "",
48
          "12": "3234324342"
49
        },
50
        {
51
          "1": "",
52
          "2": "MOBILE",
53
          "3": "TEL",
54
          "4": "",
55
          "5": "",
56
          "6": "",
57
          "7": "",
58
          "8": "",
59
          "9": "",
60
          "10": "",
61
          "11": "",
62
          "12": "3234324342"
63
        },
64
        {
65
          "1": "",
66
          "2": "EMAIL"
67
        }
68
      ],
69
      "8": {
70
        "1": "19820202"
71
      },
72
      "11": {
73
        "1": "SELF",
74
        "2": "SELF"
75
      },
76
      "36": {
77
        "1": "ENGLISH",
78
        "2": "English"
79
      }
80
    }
81
  ],
82
  ...
83
}

The input at the time this config modifier processes, though, would be:

Example: initialPayload input

json

1
{
2
  ...
3
  "Visit": {
4
    "AccountNumber": "80160443",
5
    "AdditionalStaff": [
6
    ],
7
    ...
8
    "DiagnosisRelatedGroup": null,
9
    "DiagnosisRelatedGroupType": null,
10
    "Duration": null,
11
    "Guarantor": {
12
      ...
13
      "PhoneNumber": {
14
        "Business": null,
15
        "Home": null,
16
        "Mobile": null
17
      },
18
      ...
19
    },
20
    "VisitDateTime": "2025-09-10T18:52:28.000Z",
21
    "VisitNumber": null
22
  }
23
}

This means, you’d need this selector:

Example: initialPayload selector

json

1
$.Visit.Guarantor

In the config modifier schema, we first store the corresponding array of GT1[0].6 into a reference of guarantorTelecom. We then create additional references where we search for the array that corresponds to the HOME number, grab the HOME number, and store it as a reference of home. We do the same thing for reference mobile. For email, this will map to Visit.Guarantor.EmailAddresses, so we look for all EMAIL objects under GT1[0].6.

Example: Config modifier with initialPayload variable

yaml

1
references:
2
  guarantorTelecom:
3
    use: initialPayload
4
    get: GT1[0].6
5
comment: check if Visit.Guarantor exists. If not, do nothing
6
if:
7
  operator: all
8
  terms:
9
    - {}
10
  then:
11
    merge:
12
      - {}
13
      - references:
14
          home:
15
            pipe:
16
              - use: guarantorTelecom
17
                plugin:
18
                  name: array
19
                  action: find
20
                  parameters:
21
                    match:
22
                      '2': HOME
23
              - get: 12
24
                plugin:
25
                  name: phone-number
26
                  action: format
27
          mobile:
28
            pipe:
29
              - use: guarantorTelecom
30
                plugin:
31
                  name: array
32
                  action: find
33
                  parameters:
34
                    match:
35
                      '2': MOBILE
36
              - get: 12
37
                plugin:
38
                  name: phone-number
39
                  action: format
40
          email:
41
            pipe:
42
              - use: guarantorTelecom
43
                plugin:
44
                  name: array
45
                  action: filter
46
                  parameters:
47
                    match:
48
                      '2': EMAIL
49
              - items:
50
                  get: 12
51
        properties:
52
          PhoneNumber:
53
            properties:
54
              Home:
55
                use: home
56
              Mobile:
57
                use: mobile
58
          EmailAddresses:
59
            use: email
60
      - if:
61
          operator: some
62
          terms:
63
            - get: FirstName
64
            - get: LastName
65
          then:
66
            properties:
67
              FirstName:
68
                get: FirstName
69
                plugin:
70
                  name: text
71
                  action: upper-case
72
              LastName:
73
                get: LastName
74
                plugin:
75
                  name: text
76
                  action: upper-case
77
          else:
78
            omit: true            
79
  else:
80
    omit: true

Given that, your output would be:

Example: initialPayload output

json

1
{
2
  ...
3
  "Visit": {
4
    "VisitNumber": null,
5
    "AccountNumber": "80160443",
6
    "PatientClass": null,
7
    "VisitDateTime": "2025-09-10T18:52:28.000Z",
8
    ...
9
    "Guarantor": {
10
      ...
11
      "PhoneNumber": {
12
        "Home": "+13234324342",
13
        "Business": null,
14
        "Mobile": "+13234324342"
15
      },
16
      ...
17
    }
18
  }
19
}

processedPayload

@parent

The @parent variable refers to the parent object or array of a property. Use this variable to access a unique value in the parent object to guarantee that the schema is applied to the right element in an array.

Example

Let’s say you want to go through every observation and convert each date-time value to UTC. The time zone in the initial payload is set to America/New_York, which means the date-times in OBX.3.1 are also America/New_York. But the destination expects the time to be in UTC.

You can use @parent.@parent to match the unique OBX property (3.1) so that the schema is applied to the correct observation.

The selector is OBX.14.1, and we want to match on OBX.3.1.

Example: Parent input from initial payload

json

1
{
2
  ...,
3
  "PATIENT_RESULT": [
4
    {
5
      "ORDER_OBSERVATION": [
6
        {
7
          "OBR": {
8
            "1": 1,
9
            ...
10
          },
11
          "OBSERVATION": [
12
            {
13
              "OBX": {
14
                "1": 1,
15
                "11": "F",
16
                "14": {
17
                  "1": "20250812200000"
18
                },
19
                "2": "ST",
20
                "3": {
21
                  "1": "PROMISHEALTHPAIN"
22
                },
23
                "5": [
24
                  "8"
25
                ]
26
              }
27
            },
28
            {
29
              "OBX": {
30
                "1": 2,
31
                "11": "F",
32
                "14": {
33
                  "1": "20250812200000"
34
                },
35
                "2": "ST",
36
                "3": {
37
                  "1": "KOOSJRS1L"
38
                },
39
                "5": [
40
                  "3"
41
                ]
42
              }
43
            },
44
            {
45
              "OBX": {
46
                "1": 3,
47
                "11": "F",
48
                "14": {
49
                  "1": "20250812200000"
50
                },
51
                "2": "ST",
52
                "3": {
53
                  "1": "HOOSJRP1R"
54
                },
55
                "5": [
56
                  "3"
57
                ]
58
              }
59
            },
60
            ...
61
          ],
62
          "ORC": {
63
            "1": "RE"
64
          }
65
        }
66
      ],
67
      ...
68
    }
69
  ]
70
}

Example: Parent selector

json

1
$.PATIENT_RESULT[*].ORDER_OBSERVATION[*].OBSERVATION[*].OBX.14.1

Example: Config modifier with parent variable

yaml

1
references:
2
  code:
3
    use: '@parent.@parent'
4
    get: 3.1
5
  observationResources:
6
    use: initialPayload
7
    get: entry
8
    plugin:
9
      name: array
10
      action: filter
11
      parameters:
12
        match:
13
          resource.resourceType: Observation
14
pipe:
15
  - references:
16
      originalTime:
17
        pipe:
18
          - use: observationResources
19
            items:
20
              if:
21
                operator: all
22
                terms:
23
                  - get: resource.code.coding
24
                    plugin:
25
                      name: array
26
                      action: find
27
                      parametersIsProperty: true
28
                      parameters:
29
                        properties:
30
                          match:
31
                            properties:
32
                              code:
33
                                use: code
34
                then: {}
35
                else:
36
                  omit: true
37
          - get: '0'
38
          - get: resource.effectiveDateTime
39
    use: originalTime
40
    plugin:
41
      name: date-time
42
      action: render
43
      parameters:
44
        standard: HL7

During processing, the request checks and converts the time zones in the initial payload.

Example: Parent output

json

1
{
2
  ...,
3
  "PATIENT_RESULT": [
4
    {
5
      "ORDER_OBSERVATION": [
6
        {
7
          "OBR": {
8
            "1": 1,
9
            ...
10
          },
11
          "OBSERVATION": [
12
            {
13
              "OBX": {
14
                "1": 1,
15
                "11": "F",
16
                "14": {
17
                  "1": "20250813000000"
18
                },
19
                "2": "ST",
20
                "3": {
21
                  "1": "PROMISHEALTHPAIN"
22
                },
23
                "5": [
24
                  "8"
25
                ]
26
              }
27
            },
28
            {
29
              "OBX": {
30
                "1": 2,
31
                "11": "F",
32
                "14": {
33
                  "1": "20250813000000"
34
                },
35
                "2": "ST",
36
                "3": {
37
                  "1": "KOOSJRS1L"
38
                },
39
                "5": [
40
                  "3"
41
                ]
42
              }
43
            },
44
            {
45
              "OBX": {
46
                "1": 3,
47
                "11": "F",
48
                "14": {
49
                  "1": "20250813000000"
50
                },
51
                "2": "ST",
52
                "3": {
53
                  "1": "HOOSJRP1R"
54
                },
55
                "5": [
56
                  "3"
57
                ]
58
              }
59
            },
60
            ...
61
          ],
62
          "ORC": {
63
            "1": "RE"
64
          }
65
        }
66
      ],
67
      ...
68
    }
69
  ]
70
}

Nesting level

This keyword executes at the following nesting level:

omit
constant
references
use
get
properties or if or concat or switch or pipe or merge
default
plugin

Example

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

Example: Use input from initial payload

json

1
{
2
  "favorites": {
3
      "dessert": "Cheesecake"
4
      "appetizer": "Buffalo wings"
5
  }
6
}

Example: Config modifier with use keyword

yaml

1
use: initialPayload
2
get: favorites.dessert

Example: Use output

json

1
"Cheesecake"

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