> 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/pipelines/actions/formatting/message-builder.md).

# Message Builder

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

## Overview

The **Message Builder** Action allows users to define new messages by combining different input fields.

{% hint style="warning" %}
In order to configure this Action, you must first link it to a Listener. Go to [Building a Pipeline ](/pipelines/building-a-pipeline.md)to learn how to link.
{% endhint %}

## Ports <a href="#ports" id="ports"></a>

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 **Message Builder** in the **Actions** tab (under the **Formatting** group) and drag it onto the canvas. Link it to the required [Listener](https://docs.onum.com/the-workspace/listeners) and [Data sink](https://docs.onum.com/the-workspace/pipelines/data-sinks).
{% 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="179.5">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Fields</strong></td><td><p>This is where you specify the fields you wish to include in your message, <a href="/pages/GigDqk7hAxltMMo8kSKl">color coded</a> by type.</p><p></p><p>Fields beginning with <code>_</code> are internal fields.</p></td></tr><tr><td><strong>Destination Field Name</strong></td><td>Give your message a name to identify it by in the end destination.</td></tr><tr><td><strong>Output format</strong> </td><td>Choose <em>how</em> to send your message from the following formats: <strong>CSV, JSON, Key Value, Free Mode.</strong> See the tabs below for the settings specific to each one.</td></tr></tbody></table>
{% endstep %}

{% step %}

### Save

Click save when you have composed your message.
{% endstep %}
{% endstepper %}

{% tabs %}
{% tab title="CSV" %}
To include a field in your message, drag it from the **Fields** area and drop it into the **Message** are&#x61;**.**

You can add a **Field** **Delimiter** to separate the fields in your message string. Choose between `:` , `,` , `|` , `;` .

<figure><img src="/files/5VtSLzKc2iPDrqYHW2cl" alt=""><figcaption></figcaption></figure>

This will generate an output CSV.
{% endtab %}

{% tab title="JSON" %}
You can generate a JSON file.&#x20;

To include a field in your message, drag it from the **Fields** area and drop it into the **Message** are&#x61;**.**

This will automatically add the field value separated by : followed by the source action and field. A comma separates each JSON value.

Click **New Register** to manually type the values and fields.

<figure><img src="/files/4ekCtUxRHa1u9qmwatdk" alt=""><figcaption></figcaption></figure>

In JSON mode, when adding a **literal** **value** you may select the **JSON type** of that literal: string, number or boolean. Literals are a **string** type by default.

<figure><img src="/files/Cp2WJC0SaDSsj3AZliWj" alt=""><figcaption></figcaption></figure>

This will generate a JSON file.
{% endtab %}

{% tab title="Key-Value" %}
Create a key-value file.

To include a field in your message, drag it from the **Fields** area and drop it into the **Message** are&#x61;**.**

This will automatically add the field value separated by `:` followed by the source action and field. A `:`separates each key-value pair.

To change the Value and Pair separators, use the drop-down menus and choose between `:` , `;` , and `|`

Click **New Register** to manually type the values and fields.

<figure><img src="/files/X3j74xppVBJp3hzJpeaP" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Free mode" %}
To include a field in your message, drag it from the **Fields** area and drop it into the **Message** are&#x61;**.**

The expressions should be strings that, optionally, may contain field names. For example:

```
this is an example with the value: ${myField}
```

where `${myField}` will be replaced with the actual value in the event.

The action provides the following features depending on the argument *delimiter behavior* and the given *delimiter* and *replacement* values:

* `REPLACE`: replaces `delimiter` with `replacement` on each event field.
* `DELETE`: deletes `delimiter` on each event field.
* `QUOTE`: adds double quotes surrounding an event field if it contains `delimiter`.
* `ESCAPE`: adds a backslash (`\`) before each `delimiter` on each event field.

To select more than one at once, click a field in the **Fields** area and select the checkboxes next to the name, then select **Add fields.**
{% endtab %}
{% endtabs %}

## Example

Let's say you have received raw data in JSON format and wish to extract the fields and format them as a CSV.

{% stepper %}
{% step %}

### Raw data

```
[
  {
    "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
  }
]
```

{% endstep %}

{% step %}

### Parse the JSON

Add a Parser to the canvas and extract the fields using the automatic parsing.

<figure><img src="/files/cKeIbs4vHNKiTce32RAc" alt=""><figcaption></figcaption></figure>

You have extracted the **endpoint, ip, method, status** and **username** into separate fields.
{% endstep %}

{% step %}

### Build the message

Now use the **Message Builder** to create a CSV containing these fields as one message.

Drag the following fields to the **Message** area:

* method
* description
* object
* endpoint
* ip
* status
* username
* port

**Fields delimiter:** *,*

**if delimiter matches:** *Put "" in quotes.*
{% endstep %}
{% endstepper %}