Matrix42: Verschachtelte JSON-Objekte ohne PowerShell erstellen

Die Anbindung externer Dienste über REST-APIs ist eine Kernaufgabe in der modernen IT-Administration mit Matrix42. Häufig müssen dafür JSON-Payloads (JavaScript Object Notation) direkt in den Workflows erzeugt werden. Der Griff zur “Invoke PowerShell“-Aktivität ist dabei ein verbreiteter, aber suboptimaler Ansatz.

Die Ausführung von PowerShell-Skripten erzeugt unnötigen Overhead, verlangsamt den Workflow, reduziert die Transparenz der Prozesslogik und kann im schlimmsten Fall zu Ressourcenproblemen führen. Das muss nicht sein.

Dieser Guide zeigt Ihnen Schritt für Schritt, wie Sie komplexe JSON-Strukturen ausschliesslich mit den Bordmitteln von Matrix42 im Low-Code- & No-Code-Ansatz erstellen. Im Gegensatz zur PowerShell-Ausführung arbeitet die native Methode direkt im Prozess des Matrix42 Workers. Es wird kein neuer Prozess gestartet und keine zusätzliche Ressourcen-Allokation benötigt. Die Logik wird “in-process” ausgeführt, was sie signifikant schneller und ressourcenschonender macht.

Kriterium	PowerShell-Ansatz	Nativer Ansatz
Performanz	Schlechte Performanz durch PowerShell-Overhead	Verbesserte Performanz durch Wegfall externer Prozessaufrufe
Ressourcennutzung	Hohe Ressourcennutzung durch Belastung der PS-Runspaces	Minimale Ressourcennutzung durch Ausführung im Worker-Prozess
Abhängigkeiten	Abhängigkeiten zur PowerShell-Version und -Konfiguration	Keine externen Abhängigkeiten, geringere Total Cost of Ownership (TCO)
Wartbarkeit	Intransparente Logik, die im Skript verborgen ist	Bessere Wartbarkeit durch direkt im Workflow sichtbare Logik

Die Herausforderung: JSON-Limitierungen im Workflow-Studio

Das Matrix42 Workflow-Studio bietet mit “Set JSON” und “HTTP Send” zwar Werkzeuge für die API-Kommunikation, doch bei fortgeschrittenen Anforderungen stösst man schnell an Grenzen. Bei genauerer Betrachtung der verfügbaren Datentypen in der “Set JSON”-Aktivität werden die Limitierungen klar:

• Keine verschachtelten Objekte: Es ist nicht möglich, den Datentyp $JObject$ für eine Eigenschaft auszuwählen.
• Keine Arrays: Ebenso fehlt die Möglichkeit, den Datentyp $JArray$ auszuwählen.
• Keine Dezimalzahlen: Der verfügbare numerische Typ ist $Integer$. Ein Preis wie 19.99 würde zu 19 trunkiert, was zu Datenverlust führt.
• Keine reinen Datums-Typen: Der Typ $DateTime$ enthält immer eine Zeitkomponente, was bei APIs, die nur ein Datum im Format JJJJ-MM-TT erwarten, ungeeignet ist.

Die Lösung: Schritt für Schritt zum verschachtelten JSON

Die folgende Anleitung zeigt, wie ein komplexes JSON-Objekt ausschließlich mit nativen Mitteln des Matrix42 Workflow-Studios erstellt wird. Als Beispiel dient das im Video verwendete Szenario: die Erstellung eines Produktdatensatzes mit verschachtelten Eigenschaften und einer Liste von Bewertungen.

{
  "title": "PowerShell Scripting Pen",
  "category": "Stationery",
  "description": "Ein wunderschöner Stift",
  "price": 19.99,
  "specs": {
    "inkColor": "Blue",
    "tipSize": "0.7mm",
    "refillable": true
  },
  "reviews": [
    {
      "rating": 5,
      "comment": "Der tollste Artikel aller Zeiten",
      "date": "2025-07-18T09:15:00Z",
      "reviewerName": "Torben Soennecken",
      "reviewerEmail": "torben.soennecken@rootitup.de"
    }
  ]
}

Die Werkzeuge: Vorstellung der Bordmittel

Für diese Aufgabe werden hauptsächlich drei Aktivitäten aus dem “General”-Tab des Workflow-Studios benötigt:

Aktivität	Zweck im Workflow	Wichtige Konfiguration
Set JSON	Erstellen und Modifizieren von JSON-Objekten, primär für flache Attribute.	Properties, ResultJObject, JObject
Assign	Zuweisen von Werten zu Variablen. Wird hier genutzt, um komplexe Objekte via VB.NET zu initialisieren.	To, Value
HTTP Send	Senden von Daten (z. B. dem erstellten JSON-String) an eine REST-API.	RequestData, Method, Endpoint, ContentType

Die Set JSON-Aktivität ist der grundlegende Baustein. Sie erzeugt ein JSON-Objekt (JObject) und füllt es mit Schlüssel-Wert-Paaren. Ein oft übersehenes Feld ist das Eingabefeld JObject, das es erlaubt, ein bereits existierendes JSON-Objekt zu modifizieren.

1️⃣ Das Fundament – Flache JSON-Objekte für Unterdaten erstellen

Die Strategie besteht darin, von innen nach außen zu arbeiten. Zuerst werden die untergeordneten JSON-Objekte (specs und review) erstellt, die später in das Hauptobjekt eingebettet werden.

Erstellen des Product-Specs-Objekts

• Eine Set JSON-Aktivität in den Workflow ziehen.
• Einen aussagekräftigen Namen vergeben, z. B. “Set Specs”.
• Im Feld Result JObject eine neue Variable vom Typ JObject erstellen oder auswählen, z. B. ProductSpecs.
• Den Properties-Editor öffnen und drei Eigenschaften hinzufügen:
  • Name: inkColor, Typ: String, Wert: "Blue"
  • Name: tipSize, Typ: String, Wert: "0.7mm"
  • Name: refillable, Typ: Boolean, Wert: True

Erstellen des Product-Review-Objekts

• Eine weitere Set JSON-Aktivität hinzufügen und “Set Review” nennen.
• Eine neue Variable ProductReview (Typ JObject) im Feld Result JObject anlegen oder auswählen.
• Fünf Eigenschaften im Properties-Editor definieren:
  • Name: rating, Typ: Integer, Wert: 5
  • Name: comment, Typ: String, Wert: "Der tollste Artikel aller Zeiten"
  • Name: date, Typ: DateTime, Wert (Expression): DateTime.UtcNow
  • Name: reviewerName, Typ: String, Wert: "Torben"
  • Name: reviewerMail, Typ: String, Wert: "torben.soennecken@rootitup.de"

Nach diesem Schritt existieren zwei separate JObject-Variablen (ProductSpecs und ProductReview).

Hinweis zur Case Sensitivity: Die Schreibweise der Attributnamen kann entscheidend sein. Einige APIs sind “Case-Sensitive”. Wenn die Zielschnittstelle das Attribut inkColor (CamelCase) erwartet, muss es exakt so benannt werden. Ein Fehler hier führt unweigerlich zu Problemen bei der API-Verarbeitung.

2️⃣ Der Trick – Komplexe Strukturen mit “Assign” initialisieren

Anstatt einer weiteren Set JSON-Aktivität wird eine Assign-Aktivität genutzt, um die Limitierungen zu umgehen. Die Verwendung einer dedizierten Assign-Aktivität ist eine Best Practice für die Lesbarkeit. Sie signalisiert anderen Fachkräften sofort: “Hier wird eine Struktur programmatisch initialisiert.”

• Eine Assign-Aktivität in den Workflow ziehen und “Init Body” nennen.
• Im Feld To eine neue Variable für das finale Objekt erstellen, z. B. ProductDetailsBody (Typ JObject).
• Das Feld Value öffnen und den VB.NET-Ausdruck eingeben, der das Hauptobjekt initialisiert.

New Json.JsonObject From {
    ' 1. Korrekte Definition einer Dezimalzahl (Suffix "D").
    {"price", 19.99D},

    ' 2. Einbetten des zuvor erstellten JObject.
    {"specs", ProductSpecs},

    ' 3. Erstellen eines JSON-Arrays "on the fly".
    {"reviews", New Json.JsonArray From {ProductReview}}
}

Zum Kopieren (einzeilig):

New Json.JsonObject From { {"price", 19.99D}, {"specs", ProductSpecs}, {"reviews", New Json.JsonArray From {ProductReview}} }

3️⃣ Vervollständigung – Das finale JSON-Objekt anreichern

Das ProductDetailsBody-Objekt enthält nun die komplexe Struktur. Die restlichen Attribute auf der obersten Ebene (title, category, description) werden mit einer letzten Set JSON-Aktivität hinzugefügt.

1. Eine Set JSON-Aktivität hinzufügen und “Set Body” nennen.
2. Wichtig: Die Variable ProductDetailsBody sowohl in das Eingabefeld JObject als auch in das Ausgabefeld Result JObject ziehen. Dies weist die Aktivität an, das bestehende Objekt zu modifizieren.
3. Im Properties-Editor die restlichen Attribute hinzufügen:
   • Name: title, Typ: String, Wert: "PowerShell Scripting Pen"
   • Name: category, Typ: String, Wert: "Stationery"
   • Name: description, Typ: String, Wert: "Ein wunderschöner Stift"

Das JObject in der Variable ProductDetailsBody ist nun vollständig.

4️⃣ Objekt via “HTTP Send” senden

Der letzte Schritt ist das Senden des fertigen Objekts an die API.

1. “HTTP Send”-Aktivität konfigurieren:
   • Wählen Sie die HTTP-Methode (POST, PUT etc.).
   • Setzen Sie den ContentType auf JSON. Die Aktivität setzt den korrekten Header automatisch.
   • Geben Sie die Endpunkt-URL an.
2. Request-Daten übergeben:
   • Wandeln Sie im Feld RequestData das Objekt mit folgendem Ausdruck in einen String um: ProductDetailsBody.ToString()

5️⃣ Test & Verifizierung

Prüfen Sie das Ergebnis im Debug-Modus. Im RequestData-Feld der Call API-Aktivität sehen Sie den finalen JSON-String. Verifizieren Sie dort die korrekte Struktur mit Dezimalwert, verschachteltem Objekt und Array.

Vom Prototyp zur produktionsreifen Automatisierung

Der gezeigte Workflow ist ein Prototyp. Für den produktiven Einsatz müssen weitere Aspekte für eine robuste Automatisierung berücksichtigt werden:

• Authentifizierung: Die HTTP Send-Aktivität unterstützt verschiedene Methoden, von API-Schlüsseln bis zu OAuth-Flows.
• Fehlerbehandlung: Ein produktiver Workflow muss auf den Response Status Code reagieren und entsprechende Logik ausführen (z. B. Benachrichtigung, Logging).
• Retry-Logik: Die HTTP Send-Aktivität bietet eine Retry Condition, um bei temporärer Nichterreichbarkeit der API einen erneuten Versuch zu starten.

Ergebnis & Business-Value

Die Annahme, PowerShell sei für komplexe JSON-Objekte in Matrix42-Workflows notwendig, ist ein Irrtum. Das Workflow-Studio bietet alle Werkzeuge für native API-Integrationen. Der Schlüssel ist die Kombination der “Set JSON”- und “Assign”-Aktivitäten. Diese Methode schafft technisch saubere, schnelle und robuste Automatisierungslösungen, die die Performance steigern und die Wartbarkeit verbessern.