> For the complete documentation index, see [llms.txt](https://docs.onum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onum.com/the-workspace/pipelines/actions/transformation/flat-json.md).

# Flat JSON

{% hint style="info" %}
See the changelog of this Action type [here](/actions/flat-json.md).
{% endhint %}

{% hint style="warning" %}
**Deprecated operation**

This operation has been deprecated and is no longer supported. We recommend using the [JSON Transformation](/the-workspace/pipelines/actions/transformation/json-transformation.md) operation as its replacement.
{% endhint %}

## Overview

The **Flat JSON** Action converts a nested JSON into a new, flattened JSON field with only one layer of key/value pairs.

<figure><picture><source srcset="/files/B3DKa34VDASHObovYXld" media="(prefers-color-scheme: dark)"><img src="/files/dTCyMO2nVyNxLUcSGHvU" 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.

</details>

## Configuration

{% stepper %}
{% step %}
Find **Flat JSON** 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 that holds the JSON</strong><mark style="color:red;"><strong>*</strong></mark></td><td>Select the field that contains the JSON values from the incoming data.</td><td></td></tr><tr><td><strong>Field where the flatten JSON will be stored</strong><mark style="color:red;"><strong>*</strong></mark></td><td>Give a name to the field that will store the flattened JSON values.</td><td></td></tr><tr><td><strong>Flatten level</strong> </td><td>Set the number of levels to flatten to.</td><td></td></tr><tr><td><strong>Separator</strong></td><td>Choose to separate values with <em><code>_</code></em> or <em><code>.</code></em> (<em><code>_</code></em> by default).</td><td></td></tr></tbody></table>
{% endstep %}

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

## Example

You wish to flatten a JSON to level 3 hierarchy.

{% stepper %}
{% step %}

### Raw JSON

Your input data contains the following raw JSON file:

```
[
  {
    "username": "user_1",
    "method": "POST",
    "endpoint": "breach log",
    "ip": "10.XXX.XX.XX",
    "description": "[Role] User performed an action on breach log",
    "viewport": [1920, 955],
    "usage": true
  },
  {
    "username": "user_1",
    "method": "POST",
    "endpoint": "event log",
    "ip": "10.XXX.XX.XX",
    "description": "[Role] User performed an action on event log from breach log",
    "viewport": [1920, 955],
    "usage": true
  },
  {
    "username": "service_user",
    "method": "POST",
    "endpoint": "/admin/age",
    "ip": "127.0.0.1",
    "status": 400
  },
  {
    "username": "user_2",
    "method": "POST",
    "endpoint": "/sso/login",
    "ip": "10.XXX.XX.XX",
    "status": 302
  }
]
```

You can add a [Parser](/the-workspace/pipelines/actions/transformation/parser.md) and paste this data as raw data to generate the event.
{% endstep %}

{% step %}

### Flat JSON

Add the **Flat JSON** Action to the canvas and enter the following:

* **Field that holds the JSON -** `msg`
* **Field where the flatten JSON will be stored** - give your new field a name e.g. `Flattened`
* **Flatten level** - `3`
  {% endstep %}

{% step %}

### Results

The **Flat JSON** Action now has an output field that will send the JSON flattened to a level 3 hierarchy:

```
[
  {
    "username": "user_1",
    "method": "POST",
    "endpoint": "breach log",
    "ip": "10.XXX.XX.XX",
    "description": "[Role] User performed an action on breach log",
    "usage": true,
    "viewport_dimensions": {
      "width": 1920,
      "height": 955
    }
  },
  {
    "username": "user_1",
    "method": "POST",
    "endpoint": "event log",
    "ip": "10.XXX.XX.XX",
    "description": "[Role] User performed an action on event log from breach log",
    "usage": true,
    "viewport_dimensions": {
      "width": 1920,
      "height": 955
    }
  },
  {
    "username": "service_user",
    "method": "POST",
    "endpoint": "/admin/age",
    "ip": "127.0.0.1",
    "status": 400
  },
  {
    "username": "user_2",
    "method": "POST",
    "endpoint": "/sso/login",
    "ip": "10.XXX.XX.XX",
    "status": 302
  }
]
```

{% endstep %}
{% endstepper %}