# JSON Unroll

{% hint style="info" %}
See the changelog of this Action type [here](/actions/json-unroll.md).
{% 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="/files/674ZEl6iiR0bWEuhuSZj" media="(prefers-color-scheme: dark)"><img src="/files/crxny9H2FWOes0XMz3Kt" 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 ](/the-workspace/pipelines/building-a-pipeline.md)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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.onum.com/the-workspace/pipelines/actions/transformation/json-unroll.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.