> For the complete documentation index, see [llms.txt](https://docs.informationhub.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.informationhub.io/project/sensors/parsers.md).

# Parsers

A parser decides how a raw sensor payload is turned into the fields that get written into your tables. When you register a device you pick a parser by name in the metadata table's `parser` column. Alongside the [built-in parsers](/project/sensors.md#built-in-parsers), you can build your own **custom parsers** - entirely through configuration, with no code.

Custom parsers are managed on the **Parsers** tab of the Sensors module.

## When to build a custom parser

Use a custom parser when your device's payload does not match one of the built-in parsers - for example, when the readings are nested inside the payload, use field names you want to rename, or need simple conversions such as rounding or multiplying a value.

A custom parser maps fields from an incoming payload to output fields. You reference it by its name in the `parser` column of your metadata table.

## The Parsers tab

* If there are no parsers yet, you see **There are no parsers currently** and a **Create parser** button.
* Otherwise, each parser is listed with **Edit** and **Delete** buttons, plus a **Create parser** button at the top.
* The **?** (help) icon opens a short in-app explanation of how parsers work.

## Create or edit a parser

Click **Create parser** (or **Edit** on an existing one) to open the parser editor.

* **Parser name** - a name up to 64 characters, for example `sensecap_parser`. This is the name you put in the `parser` column of your metadata table.
* **Include envelope keys (received\_at, gateway\_id, rssi)** - turn this on to automatically include those common top-level values from the incoming message in the output, on top of your field mappings.

### Field mappings

Add one mapping row for each output field you want:

* **Output field** - the name of the field in the result (for example `temperature`).
* **Source path** - where to read the value from in the incoming payload, using dot notation. For example `uplink_message.decoded_payload.temperature`. Use a number to pick an item from a list - for example `readings.0.value` reads the first reading. If the path is not found, that field is simply skipped.
* **Transform** - an optional conversion applied to the value:

  | Transform      | Effect                                       |
  | -------------- | -------------------------------------------- |
  | **None**       | Use the value as-is.                         |
  | **Multiply**   | Multiply by a **Factor** you enter.          |
  | **Round**      | Round to a number of **Decimals** you enter. |
  | **To number**  | Convert the value to a number.               |
  | **To string**  | Convert the value to text.                   |
  | **To boolean** | Convert the value to true/false.             |

Use **Add field** to add another mapping, and the **remove** button on a row to delete it.

### Preview before you save

1. Paste an example payload into the **Sample payload (JSON)** editor.
2. Click **Run preview**.
3. The result of applying your mappings appears below, or an error message if the sample or a mapping is not valid.

The preview runs entirely in your browser, so you can safely try mappings against a real payload before saving. No code is executed - mappings are pure configuration.

When you are happy, click **Save** (or **Update** when editing). Use **Reset** to clear your changes.

{% hint style="info" %}
After saving a custom parser, put its **name** in the `parser` column of the device's row in your metadata table. From then on, that device's readings are decoded with your parser.
{% endhint %}