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, 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.

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.