# concat

## Definition

In a config modifier schema, use `concat` to create an array by linking defined elements together. Each element under the `concat` keyword can be composed of any other valid config modifier keywords. Essentially, this creates an array list for a property in the output or a list to be checked during processing.

> **Exclusive keywords**
>
> If `properties`, `if`, `concat`,  `switch`, `pipe`, `merge`, `prefer`, or `items` are present at the same nesting level, only the first keyword listed will run. We recommend not listing these keywords together at the same nesting level. 

> **Useful expressions for concat**
>
> There are a couple of expressions that you should know about when using `concat`.
>
> - `-` : Indicates an array or list item in standard YAML and can still be used that way generally with config modifiers. However, in the context of `concat`, a hyphen (`-`) can also indicate one independent value that should be present in an array. Each element in the array should be designated with a `-` before the key-value pair.
> - `{}`: Refers to a current value in an array within the initial payload. Use this to retain an original value rather than deleting or overwriting it. To make sure the value appears in a processed payload as-is, add this expression on its own line in the `concat` object as `- {}`. 

## 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: Join items in one list

You can use `concat` and `-` to check for items in an array then joining them in one list rather than checking each item individually.

**Example: Observations input from initial payload**

```json
"Observations": [
    {
      "AbnormalFlag": null,
      "Code": "93246-7",
      ...
      "Status": "Final",
      "Units": null,
      "Value": "1",
      "ValueType": "Coded Entry"
    },
    {
      "AbnormalFlag": null,
      "Code": "93247-5",
      ...
      "Status": "Final",
      "Units": null,
      "Value": "1",
      "ValueType": "Coded Entry"
    },
    {
      "AbnormalFlag": null,
      "Code": "NF1570400181",
      ...
      "Status": "Final",
      "Units": null,
      "Value": "High Risk",
      "ValueType": "String"
    },
    {
      "AbnormalFlag": null,
      "Code": "93267-3",
      ...
      "Status": "Final",
      "Units": null,
      "Value": "1",
      "ValueType": "Coded Entry"
    },
    {
      "AbnormalFlag": null,
      "Code": "93269-9",
      ...
      "Status": "Final",
      "Units": null,
      "Value": "0",
      "ValueType": "Coded Entry"
    },
    {
      "AbnormalFlag": null,
      "Code": "NF1570400504",
      ...
      "Status": "Final",
      "Units": null,
      "Value": "Putting my notes here",
      "ValueType": "String"
    }
  ]
```

**Example: Observations selector**

```json
$.Observations
```

**Example: Config modifier with concat and include keywords**

```yaml
items:
  if:
   operator: includes
   terms:
      - concat:
        - constant: NF1570400504
        - constant: NF1570400181
        - constant: 93374-7
      - get: Code
   then:
     omit: true
   else:
     comment: pass observation through
```

**Example: Observations output**

```json
"Observations": [
    {
      "AbnormalFlag": null,
      "Code": "93246-7",
      ...
      "Status": "Final",
      "Units": null,
      "Value": "1",
      "ValueType": "Coded Entry"
    },
    {
      "AbnormalFlag": null,
      "Code": "93247-5",
      ...
      "Status": "Final",
      "Units": null,
      "Value": "1",
      "ValueType": "Coded Entry"
    },
    {
      "AbnormalFlag": null,
      "Code": "93267-3",
      ...
      "Status": "Final",
      "Units": null,
      "Value": "1",
      "ValueType": "Coded Entry"
    },
    {
      "AbnormalFlag": null,
      "Code": "93269-9",
      ...
      "Status": "Final",
      "Units": null,
      "Value": "0",
      "ValueType": "Coded Entry"
    }
  ],
```

## Example 2: Add a new item in an array

You can use `concat` and `{}` to add a new item to an array that already exists in the payload, rather than replacing it entirely.

**Example 2: Concat input**

```json
{
  "Patient": {
    "Roles": ["PC"]
  }
}
```

**Example 2: Concat selector**

```json
$.Patient.Roles
```

**Example 2: Config modifier with concat keyword and {}**

```yaml
concat:
  - {}
  - constant: SC
```

**Example 2: Concat output**

```json
{
  "Patient": {
    "Roles": ["PC", "SC"]
  }
}
```