Overview

Transformations adapt the structure of outgoing data packets to the requirements of third-party systems — for example billing, energy management, or downstream APIs. They are used in an integration flow as a step between filter and outgoing connector; see that chapter for data flow and triggers.

Incoming data packets are not transformed in the integration flow; they are handled via the transformation template on the incoming connector. Details are described in the Connectors chapter under Incoming connectors.

Data model and example payloads

The input to a transformation is typically a JSON object with meta and value fields. Which fields are set in meta depends on the integration flow trigger and the data point.

Full example payloads and field descriptions are in the Integration flows chapter:

These examples can be copied or adapted as Example input in the transformation editor (see Testing in the UI and quick reference).

Access & navigation

Under Integrations > Transformations, transformations can be created and edited. When creating or editing, two tabs are available:

• Metadata — name, account, description
• Transformation — output format, transformation type, editor, test area, and quick reference

Configuration

• Name: A unique name for the transformation.
• Account: The account the transformation applies to (cannot be changed after creation for new records).
• Description: Optional additional information.
• Output format: The desired format of the transformed output, matching the outgoing connector or target system — e.g. application/json, text/plain, or generic (see also the note on JSON and generic in the Integration flows chapter).
• Transformation type:
  • JSONata — expression against the entire input object (root), e.g. $.meta… and $.value.
  • JavaScript — function body: the editor only contains the code inside the function; the platform wraps it as module.exports = (x) => { … }. The argument x is the input object (meta / value). A return value must be supplied that matches the new payload (see next section).

Behavior in the integration flow: The transformation result replaces the previous contents of value in the payload; meta is carried forward by the system where applicable. The transformation should therefore produce exactly the structure the target system expects in value.

JSONata and JavaScript transformation

The examples below refer to typical AFTER STATE HANDLING packets (with dtwin_id in meta). For BEFORE STATE-HANDLING or ALARMLOG triggers, adjust the fields to match the objects in the linked sections.

JSONata

The expression yields the new value object. Example: measurement and selected metadata in a compact JSON target format:

{
  "timestamp": $.meta.timestamp,
  "deviceId": $.meta.dtwin_id,
  "deviceTitle": $.meta.dtwin_title,
  "reading": $.value
}

JavaScript

Only the function body is entered (the code inside (x) => { … }). The UI adds module.exports = (x) => { and the closing brace; a separate module.exports declaration is not required. Example:

return {
  ts: x.meta.timestamp,
  twin: x.meta.dtwin_id,
  tags: x.meta.twin_tags,
  v: x.value
};

Conditional logic and a different shape:

if (x.meta.state_type === "number" && x.value > 100) {
  return { alert: true, value: x.value, unit: x.meta.unit };
}
return { alert: false, value: x.value };

Testing in the UI and quick reference

On the Transformation tab there are three numbered areas:

1. Define output type — select the output format (required for the test).
2. Write your transformation — edit the JSONata or JavaScript code.
3. Test your transformation — paste valid JSON in the Example input field (e.g. from the Integration flows examples). The Test transformer button runs the transformation on the server; the result appears under Output after transformation.

Without valid sample data, a selected account, or an output format, the test is disabled; hovering the button shows a hint for the missing item.

Quick reference: Below the editor there is an expandable section “Quick reference (meta values & example)”. It lists the meta attributes that are typically available (including a note that some fields only appear after assignment to a Virtual Device or Digital Twin, comparable to AFTER STATE HANDLING). The quick reference also includes a compact JSONata example: original payload, transformation expression, and expected output — similar to the UI.

Related pages

• Integration flows — triggers, data objects, connector step
• Connectors — incoming and outgoing connectors
• Filters — JSONata/JavaScript filters in the chain