Überblick

Transformationen passen die Struktur ausgehender Datenpakete an die Anforderungen von Drittsystemen an — etwa für Abrechnung, Energiemanagement oder nachgelagerte APIs. Sie werden im Integrationsflow als Schritt zwischen Filter und ausgehendem Konnektor eingesetzt; zu Datenfluss und Auslösern siehe dort.

Eingehende Datenpakete werden nicht im Integrationsflow transformiert, sondern über das Transformations-Template im eingehenden Konnektor. Details dazu sind im Kapitel Konnektoren im Abschnitt Eingehende Konnektoren beschrieben.

Datenmodell und Beispiel-Payloads

Die Eingabe für eine Transformation ist typischerweise ein JSON-Objekt mit den Feldern meta und value. Welche Felder in meta gesetzt sind, hängt vom Auslöser des Integrationsflows und vom Datenpunkt ab.

Vollständige Beispiel-Payloads und Felderklärungen finden sich im Kapitel Integrationsflows:

Diese Beispiele können als Beispiel-Eingabe im Transformations-Editor übernommen oder angepasst werden (siehe Transformation im UI testen).

Zugriff & Navigation

Unter Integrationen > Transformationen lassen sich Transformationen anlegen und bearbeiten. Beim Anlegen oder Bearbeiten stehen zwei Reiter zur Verfügung:

• Metadaten — Name, Konto, Beschreibung
• Transformation — Ausgabeformat, Transformationstyp, Editor, Testbereich und Schnellreferenz

Konfiguration

• Name: Eindeutiger Name der Transformation.
• Konto: Konto, für das die Transformation gilt (bei neuen Einträgen nach dem Anlegen nicht mehr änderbar).
• Beschreibung: Optionale Zusatzinformationen.
• Ausgabeformat: Gewünschtes Format der transformierten Ausgabe, passend zum ausgehenden Konnektor bzw. Zielsystem — z. B. application/json, text/plain oder generic (siehe auch den Hinweis zu JSON und generic im Integrationsflow-Kapitel).
• Typ der Transformation:
  • JSONata — Ausdruck gegen das gesamte Eingabeobjekt (Root), Zugriff z. B. mit $.meta… und $.value.
  • JavaScript — Funktionsrumpf: Der Editor enthält nur den Code innerhalb der Funktion; die Plattform umschließt ihn zu einer Funktion module.exports = (x) => { … }. Das Argument x ist das Eingabeobjekt (meta / value). Es muss ein Rückgabewert geliefert werden, der der neuen Nutzlast entspricht (siehe nächster Abschnitt).

Verhalten im Integrationsflow: Das Ergebnis der Transformation ersetzt den bisherigen Inhalt von value im Payload; meta wird vom System weitergeführt, soweit zutreffend. Entsprechend sollte die Transformation genau die Struktur liefern, die das Zielsystem in value erwartet.

JSONata- und JavaScript-Transformation

Die folgenden Beispiele beziehen sich auf typische AFTER STATE HANDLING-Pakete (mit dtwin_id in meta). Für BEFORE STATE-HANDLING oder ALARMLOG-Auslöser die Felder an die jeweiligen Objekte aus den verlinkten Abschnitten anpassen.

JSONata

Ausdruck liefert das neue Wertobjekt. Beispiel: Messwert und ausgewählte Metadaten für ein schlankes JSON-Zielformat:

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

JavaScript

Es wird nur der Funktionsrumpf eingetragen (der Code innerhalb von (x) => { … }). Die Oberfläche setzt module.exports = (x) => { und die schließende Klammer; eine eigene module.exports-Deklaration ist nicht nötig. Beispiel:

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

Bedingung und abweichendes Format:

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 };

Transformation im UI testen und Schnellreferenz

Auf dem Reiter Transformation sind drei Bereiche nummeriert:

1. Ausgabeformat definieren — Ausgabeformat wählen (Voraussetzung für den Test).
2. Transformation schreiben — JSONata- oder JavaScript-Code bearbeiten.
3. Transformation testen — Im Feld Beispiel Eingabe gültiges JSON einfügen (z. B. aus den Integrationsflows-Beispielen). Mit dem „Transformer testen“-Button wird die Transformation serverseitig ausgeführt; das Ergebnis erscheint unter Ausgabe nach Transformation.

Ohne gültige Beispieldaten, ohne gewähltes Konto oder ohne Ausgabeformat ist der Test deaktiviert; beim Überfahren des Buttons zeigt ein Hinweis das jeweils fehlende Feld an.

Schnellreferenz: Unterhalb des Editors befindet sich ein aufklappbarer Bereich „Schnellreferenz (Metawerte und Beispiel)“. Dort sind die typischerweise verfügbaren Meta-Attribute aufgelistet (einschließlich Hinweis, dass einige Felder nur nach Zuweisung an Virtuelles Gerät oder Digitalen Zwilling vorkommen, vergleichbar AFTER STATE HANDLING). Außerdem enthält die Schnellreferenz ein kompaktes JSONata-Beispiel: Original-Payload, Transformationsausdruck und erwartete Ausgabe — analog zur Darstellung in der Oberfläche.

Verwandte Seiten

• Integrationsflows — Auslöser, Datenobjekte, Konnektor-Schritt
• Konnektoren — eingehende und ausgehende Konnektoren
• Filter — JSONata/JavaScript-Filter in der Kette