# use

## 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](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/references). 

### Available variables

| **Variable** | **Notes** |
| --- | --- |
| `initialPayload` | 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](https://docs.redoxengine.com/permalink/Wxms74JvgjSCtaPnJdNFD/#base-configs). |
| `processedPayload` | Refers to the output payload after applying a Redox base config.  This payload is either in Redox FHIR, Redox data model, or external format, depending on where in log processing the base config is applied. This payload will be updated with either the `Delete` or `Write` config modifier flavor. |
| `@parent` | 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. |

## Order of execution

This keyword executes in the following order:  

1. `omit`
2. `constant`
3. `references`
4. **`use`**
5. `get`
6. Mutually exclusive keywords at this level:
   - `properties` 
   - `if` 
   - `concat` 
   - `switch` 
   - `pipe` 
   - `merge` 
   - `prefer` 
   - `items`
7. `default`
8. `plugin`

## Example 1: use initialPayload

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

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
{
 ...
  "GT1": [
    {
      ...
      "5": [
        {
          "1": {
            "1": "2011 N SOTO ST"
          },
          "2": "",
          "3": "LOS ANGELES",
          "4": "CA",
          "5": "900323628",
          "6": "USA",
          "7": "HOME",
          "8": "",
          "9": "Los Angeles"
        }
      ],
      "6": [
        {
          "1": "",
          "2": "HOME",
          "3": "TEL",
          "4": "",
          "5": "",
          "6": "",
          "7": "",
          "8": "",
          "9": "",
          "10": "",
          "11": "",
          "12": "3234324342"
        },
        {
          "1": "",
          "2": "PAGER PERS",
          "3": "",
          "4": "",
          "5": "",
          "6": "",
          "7": "",
          "8": "",
          "9": "",
          "10": "",
          "11": "",
          "12": "3234324342"
        },
        {
          "1": "",
          "2": "MOBILE",
          "3": "TEL",
          "4": "",
          "5": "",
          "6": "",
          "7": "",
          "8": "",
          "9": "",
          "10": "",
          "11": "",
          "12": "3234324342"
        },
        {
          "1": "",
          "2": "EMAIL"
        }
      ],
      "8": {
        "1": "19820202"
      },
      "11": {
        "1": "SELF",
        "2": "SELF"
      },
      "36": {
        "1": "ENGLISH",
        "2": "English"
      }
    }
  ],
  ...
}
```

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

**Example: initialPayload input**

```json
{
  ...
  "Visit": {
    "AccountNumber": "80160443",
    "AdditionalStaff": [
    ],
    ...
    "DiagnosisRelatedGroup": null,
    "DiagnosisRelatedGroupType": null,
    "Duration": null,
    "Guarantor": {
      ...
      "PhoneNumber": {
        "Business": null,
        "Home": null,
        "Mobile": null
      },
      ...
    },
    "VisitDateTime": "2025-09-10T18:52:28.000Z",
    "VisitNumber": null
  }
}
```

This means you’d need this selector:

**Example: initialPayload selector**

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

references:
  guarantorTelecom:
    use: initialPayload
    get: GT1[0].6
comment: check if Visit.Guarantor exists. If not, do nothing
if:
  operator: all
  terms:
    - {}
  then:
    merge:
      - {}
      - references:
          home:
            pipe:
              - use: guarantorTelecom
                plugin:
                  name: array
                  action: find
                  parameters:
                    match:
                      '2': HOME
              - get: 12
                plugin:
                  name: phone-number
                  action: format
          mobile:
            pipe:
              - use: guarantorTelecom
                plugin:
                  name: array
                  action: find
                  parameters:
                    match:
                      '2': MOBILE
              - get: 12
                plugin:
                  name: phone-number
                  action: format
          email:
            pipe:
              - use: guarantorTelecom
                plugin:
                  name: array
                  action: filter
                  parameters:
                    match:
                      '2': EMAIL
              - items:
                  get: 12
        properties:
          PhoneNumber:
            properties:
              Home:
                use: home
              Mobile:
                use: mobile
          EmailAddresses:
            use: email
      - if:
          operator: some
          terms:
            - get: FirstName
            - get: LastName
          then:
            properties:
              FirstName:
                get: FirstName
                plugin:
                  name: text
                  action: upper-case
              LastName:
                get: LastName
                plugin:
                  name: text
                  action: upper-case
          else:
            omit: true            
  else:
    omit: true
```

Given that, your output would be:

**Example: initialPayload output**

```json
{
  ...
  "Visit": {
    "VisitNumber": null,
    "AccountNumber": "80160443",
    "PatientClass": null,
    "VisitDateTime": "2025-09-10T18:52:28.000Z",
    ...
    "Guarantor": {
      ...
      "PhoneNumber": {
        "Home": "+13234324342",
        "Business": null,
        "Mobile": "+13234324342"
      },
      ...
    }
  }
}
```

## Example 2: use processedPayload

In this scenario, `TXA.4.1` is missing from the HL7v2 output. This is because the initial FHIR message’s `DocumentReference` resource is missing a field that indicates an Activity Date/Time or any time at all. 

You want to map the value from `EVN.2.1` to `TXA.4.1`. Since you can get this from the existing HL7v2 message, we can use the `processedPayload` to retrieve the value at `EVN.2.1`.

**Example: processedPayload input**

```json
{
  "EVN": {
    "1": "T02",
    "2": {
      "1": "20250919165623"
    }
  },
  ...
  "TXA": {
    "1": 1,
    "12": {
      "1": "fab71b57-d565-4cda-8ed9-b694c2a737c2",
      "2": "urn:uuid:fab71b57-d565-4cda-8ed9-b694c2a737c2"
    },
    "19": "AV",
    "2": "ASSESSMENTS",
    "3": "TX"
  }
}
```

This means you’d need this selector:

**Example: processedPayload selector**

```json
$.TXA.4.1
```

**Example: Config modifier with processedPayload variable**

```yaml
use: processedPayload
get: EVN.2.1
```

Given that, your output would be:

**Example: processedPayload output**

```json
{
  "EVN": {
    "1": "T02",
    "2": {
      "1": "20250919165623"
    }
  },
  ...
  "TXA": {
    "1": 1,
    "12": {
      "1": "fab71b57-d565-4cda-8ed9-b694c2a737c2",
      "2": "urn:uuid:fab71b57-d565-4cda-8ed9-b694c2a737c2"
    },
    "19": "AV",
    "2": "ASSESSMENTS",
    "3": "TX",
    "4": {
      "1": "20250919165623"
    },
    ...
  }
}
```

## Example 3: use @parent

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.

**Example: Parent input from initial payload**

```json
{
  ...,
  "PATIENT_RESULT": [
    {
      "ORDER_OBSERVATION": [
        {
          "OBR": {
            "1": 1,
            ...
          },
          "OBSERVATION": [
            {
              "OBX": {
                "1": 1,
                "11": "F",
                "14": {
                  "1": "20250812200000"
                },
                "2": "ST",
                "3": {
                  "1": "PROMISHEALTHPAIN"
                },
                "5": [
                  "8"
                ]
              }
            },
            {
              "OBX": {
                "1": 2,
                "11": "F",
                "14": {
                  "1": "20250812200000"
                },
                "2": "ST",
                "3": {
                  "1": "KOOSJRS1L"
                },
                "5": [
                  "3"
                ]
              }
            },
            {
              "OBX": {
                "1": 3,
                "11": "F",
                "14": {
                  "1": "20250812200000"
                },
                "2": "ST",
                "3": {
                  "1": "HOOSJRP1R"
                },
                "5": [
                  "3"
                ]
              }
            },
            ...
          ],
          "ORC": {
            "1": "RE"
          }
        }
      ],
      ...
    }
  ]
}
```

**Example: Parent selector**

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

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`. Because the selector targets `14.1`, the first `@parent` navigates up to `14` and the second `@parent` navigates up to `OBX`. From there, we can `get: 3.1`.

**Example: Config modifier with parent variable**

```yaml
references:
  code:
    use: '@parent.@parent'
    get: 3.1
  observationResources:
    use: initialPayload
    get: entry
    plugin:
      name: array
      action: filter
      parameters:
        match:
          resource.resourceType: Observation
pipe:
  - references:
      originalTime:
        pipe:
          - use: observationResources
            items:
              if:
                operator: all
                terms:
                  - get: resource.code.coding
                    plugin:
                      name: array
                      action: find
                      parametersIsProperty: true
                      parameters:
                        properties:
                          match:
                            properties:
                              code:
                                use: code
                then: {}
                else:
                  omit: true
          - get: '0'
          - get: resource.effectiveDateTime
    use: originalTime
    plugin:
      name: date-time
      action: render
      parameters:
        standard: HL7
```

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

**Example: Parent output**

```json
{
  ...,
  "PATIENT_RESULT": [
    {
      "ORDER_OBSERVATION": [
        {
          "OBR": {
            "1": 1,
            ...
          },
          "OBSERVATION": [
            {
              "OBX": {
                "1": 1,
                "11": "F",
                "14": {
                  "1": "20250813000000"
                },
                "2": "ST",
                "3": {
                  "1": "PROMISHEALTHPAIN"
                },
                "5": [
                  "8"
                ]
              }
            },
            {
              "OBX": {
                "1": 2,
                "11": "F",
                "14": {
                  "1": "20250813000000"
                },
                "2": "ST",
                "3": {
                  "1": "KOOSJRS1L"
                },
                "5": [
                  "3"
                ]
              }
            },
            {
              "OBX": {
                "1": 3,
                "11": "F",
                "14": {
                  "1": "20250813000000"
                },
                "2": "ST",
                "3": {
                  "1": "HOOSJRP1R"
                },
                "5": [
                  "3"
                ]
              }
            },
            ...
          ],
          "ORC": {
            "1": "RE"
          }
        }
      ],
      ...
    }
  ]
}
```