Process

Tag and transform incoming sensor data using JSONPath rules.

IoTMan takes an opinionated approach to data processing: since every datapoint coming in is JSON and every datapoint going out is JSON, the same language — JSONPath (RFC 9535) — handles all processing logic. IoTMan uses the PostgreSQL implementation of JSONPath, which is largely compatible with that specification and adds extensions such as the object constructor syntax used in transformations.

Data processing happens in two steps: tagging and transformation.

Tagging

Tags are key-value labels attached to each incoming datapoint, identified by a key:value pair. They are used for filtering and grouping. A tag category is a named rule — its name becomes the tag key (except for the Source method, where the key is the source name), and the rule defines how the tag value is derived from each datapoint.

Creating a tag rule

  1. Click + New tag rule.
  2. Enter a name — this becomes the tag key.
  3. Select a method and configure it (see methods below). When a JSONPath or regex method is selected, an inline tester appears so you can validate the expression before saving.
  4. Click Save. The rule applies to all new incoming datapoints.

Requires Editor or Admin role.

There are five ways to produce tags:

JSONPath field detection

Evaluates a JSONPath expression against the payload. If the field exists, the datapoint receives a fixed tag value of 1.

Use this to classify datapoints by the presence of a field. For example, a category named has_temperature with expression $.temperature tags all payloads containing a temperature key as has_temperature:1.

JSONPath value capture

Evaluates a JSONPath expression and uses the returned value as the tag. This produces as many distinct tag values as there are distinct values in your data.

Example: a category named device_type with expression $.device_type on {"device_type":"thermostat","value":21} produces device_type:thermostat.

Source

Tags the datapoint with the name of the HTTP endpoint or MQTT connector it arrived on. The tag key is the source name and the value is 1.

Example: a datapoint arriving on the "Field sensors" endpoint gets tag Field sensors:1.

Regex match on MQTT topic

Applies a regular expression to the MQTT topic path. If the topic matches, the datapoint receives a fixed tag value of 1. Only applies to data received via MQTT connectors.

Example: a category named has_sensor_data with regex sensors/.+/data on topic sensors/node-42/data produces has_sensor_data:1.

Regex capture on MQTT topic

Applies a regular expression with a capture group to the MQTT topic path and uses the captured value as the tag. Only applies to data received via MQTT connectors.

Example: a category named device with regex sensors/([^/]+)/data on topic sensors/node-42/data captures node-42, producing device:node-42.

Deleting a tag rule

Click the delete button on a tag rule row. Existing tags on already-ingested datapoints are not affected.

Requires Editor or Admin role.

Transformation

A transformation selects a subset of datapoints and reshapes them into a new JSON structure. Each transformation definition is called an output.

How an output is defined

  1. Tag — a key:value pair (from the Tagging step above) that selects which datapoints the transformation applies to.
  2. JSON constructor — a JSONPath expression using PostgreSQL's object constructor syntax that builds a new JSON object from the matched payload. Example: {"id": $.device_id, "temp": $.value}.

Only datapoints carrying the exact tag are passed through the constructor. The result is stored as the output value.

Creating an output

  1. Click + New output.
  2. Enter a name for the output.
  3. Enter the tag (key:value) that selects which datapoints this output applies to. Example: has_temperature:1 or Field sensors:1. The field offers suggestions based on your existing tag rules.
  4. Write the JSON constructor expression. Use the Test constructor button to validate it against a sample payload before saving.
  5. Click Save.

Requires Editor or Admin role.

Deleting an output

Click the delete button on an output row.

Requires Editor or Admin role.

Using outputs

Outputs appear in the Export tab, where each output can be exposed as its own API endpoint. This lets consumers query a clean, pre-shaped version of your data without needing to know the raw payload structure.