# JSON Unroll

{% hint style="info" %}
See the changelog of this Action type [here](https://app.gitbook.com/s/IXj83By4f20oCrZZ0gyP/json-unroll).
{% endhint %}

## Overview

The **JSON** **Unroll** Action unrolls (explodes) an array of objects into individual events, while also inheriting top-level fields.

<figure><picture><source srcset="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FLl8E7MTDYorMAreag6zq%2Fkkkg.png?alt=media&#x26;token=6234f23e-9273-4041-b877-1637004015b1" media="(prefers-color-scheme: dark)"><img src="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FEKcm7zSkhDFwpgtl7sXr%2Fgsgsgs.png?alt=media&#x26;token=4a7246f4-32ca-4bd3-a587-2079e1f6498e" alt=""></picture><figcaption></figcaption></figure>

{% hint style="warning" %}
In order to configure this action, you must first link it to a Listener. Go to [Building a Pipeline ](https://docs.onum.com/the-workspace/pipelines/building-a-pipeline)to learn how to link.
{% endhint %}

## Ports

These are the input and output ports of this Action:

<details>

<summary>Input ports</summary>

* **Default port** - All the events to be processed by this Action enter through this port.

</details>

<details>

<summary>Output ports</summary>

* **Default port** - Events are sent through this port if no error occurs while processing them.
* **Error port** - Events are sent through this port if an error occurs while processing them.
* **Unroll port** - This port will output the unrolled array values.

</details>

## Configuration

{% stepper %}
{% step %}
Find **JSON Unroll** in the **Actions** tab (under the **Transformation** group) and drag it onto the canvas.
{% endstep %}

{% step %}
To open the configuration, click the Action in the canvas and select **Configuration**.
{% endstep %}

{% step %}
Enter the required parameters:

<table><thead><tr><th width="218">Parameter</th><th>Description</th><th data-hidden></th></tr></thead><tbody><tr><td><strong>Field to transform</strong><mark style="color:red;"><strong>*</strong></mark></td><td>Select the JSON input event that holds the array to be unrolled.</td><td></td></tr><tr><td><strong>Path</strong><mark style="color:red;"><strong>*</strong></mark></td><td>Inidicate the JSON array name you want to unroll.</td><td></td></tr><tr><td><strong>Output field</strong><mark style="color:red;"><strong>*</strong></mark></td><td>The name that the exploded array element will receive in each new event.</td><td></td></tr></tbody></table>
{% endstep %}

{% step %}
Click **Save** to complete the process.
{% endstep %}
{% endstepper %}

## Example

Suppose you wish to unroll a JSON that comes in an input value called `JSONdata`

{% stepper %}
{% step %}

### Input JSON

Your input data contains the following raw JSON file:

```
{
  "timestamp": "2024-03-18T12:45:00Z",
  "user": "Alice",
  "allPurchases": [
    {
      "item": "Laptop",
      "price": 1200,
      "payment_method": "Credit Card"
    },
    {
      "item": "Headphones",
      "price": 150,
      "payment_method": "PayPal"
    },
    {
      "item": "Smartphone",
      "price": 900,
      "payment_method": "Debit Card"
    }
  ]
}
```

{% endstep %}

{% step %}

### Configuration

Add the **JSON Unroll** Action to the canvas and enter the following:&#x20;

<table><thead><tr><th width="218">Parameter</th><th>Value</th><th data-hidden></th></tr></thead><tbody><tr><td><strong>Field to transform</strong></td><td>Select the <code>JSONdata</code> field.</td><td></td></tr><tr><td><strong>Path</strong></td><td>We need to unroll the array <code>allPurchases</code>.</td><td></td></tr><tr><td><strong>Output field</strong></td><td>We'll name the new field with the unrolled array <code>purchases</code>.</td><td></td></tr></tbody></table>
{% endstep %}

{% step %}

### Result

These will be the output events. Each element under the original `allPurchases` array is now placed in a `purchases` field in its event:

```
Event 1:
{"JSONdata":"{"timestamp":"2024-03-18T12:45:00Z","user":"Alice","purchases":{"item":"Laptop","price":"1200","payment_method":"Credit Card"}

Event 2:
{""JSONdata":"{"timestamp":"2024-03-18T12:45:00Z","user":"Alice","purchases":{"item":"Headphones","price":"150","payment_method":"Paypal"}

Event 3:
{""JSONdata":"{"timestamp":"2024-03-18T12:45:00Z","user":"Alice","purchases":{"item":"Smartphone","price":"900","payment_method":"Smartphone"}

```

{% endstep %}
{% endstepper %}