Hintergrund
Chains interagiert mit einer Vielzahl von Systemen von Drittanbietern sowie mit der Workiva-Plattform, indem es die REST-API des Systems nutzt, mit dem es integriert ist. Viele REST-API-Antworten liegen im JSON-Format vor, darunter auch die verschiedenen Workiva APIs. Während eine JSON-Antwort gut dokumentiert und einheitlich strukturiert sein kann, ist es schwierig, mit Daten in diesem Format zu arbeiten. Der Array to CSV Befehl im JSON Connector ist ein nützlicher Weg, um JSON Daten in ein tabellarisches Format (Zeilen und Spalten) zu konvertieren und in der Workiva Plattform zu verwenden.
In diesem Artikel wird untersucht, wie die Filterfunktionen dieses Befehls genutzt werden können, um nur die benötigten Ergebnisse aus der JSON-Nutzlast zurückzugeben. Dies kann notwendig sein, da eine REST-API-Antwort oft mehr Informationen als nötig enthält, da die Nutzlast im Allgemeinen von den Entwicklern festgelegt wird und die Endbenutzer des Endpunkts oft nicht die Möglichkeit haben, den Umfang der zurückgegebenen Daten zu begrenzen.
Als Beispiel verwendet der List Files Command des Workiva Connectors den Retrieve a List of Files Endpunkt von der Workiva Wdata API, um eine Liste aller Dateien, die mit einer Wdata Tabelle verbunden sind, zurückzugeben. Die JSON-Antwort für diesen Endpunkt enthält die folgenden Informationen:
[
{
"created": "2024-01-24T12:01:53.000Z",
"id": "89b34ac927fe499abf944571ded77983",
"metadata": {
"column1": {},
"column2": {}
},
"name": "executions_2024-01.csv",
"numRecords": 108808,
"originalFileSize": 26226080,
"status": "IMPORTED",
"tableId": "bafe350ebff74a2dbc11262245483dee",
"updated": "2024-01-24T12:02:03.000Z",
"userId": "HzU1OTQwMTMxODMzMTE4NzI",
"version": 1
},
{
"created": "2023-12-18T15:06:56.000Z",
"id": "62f3d0b79b724776a4fae8bf25f711f1",
"metadata": {
"column1": {},
"column2": {}
},
"name": "executions_2023-12.csv",
"numRecords": 101789,
"originalFileSize": 24226080,
"status": "IMPORTED",
"tableId": "bafe350ebff74a2dbc11262245483dee",
"updated": "2023-12-18T15:06:56.000Z",
"userId": "HzU1OTQwMTMxODMzMTE4NzI",
"version": 1
}
]
Der Befehl Array to CSV ermöglicht es uns, nur die Felder auszuwählen, die wir aus der JSON-Antwort abrufen können. Wir können zum Beispiel die Felder id, name und status auswählen, indem wir diese im Eingabeabschnitt Spalten des Befehls angeben. Der Befehl extrahiert jede Datei-ID, jeden Namen und jeden Status aus der JSON-Antwort und erstellt eine Zeile für jede Datei in der JSON-Antwort.
Ein häufiger Anwendungsfall innerhalb der Workiva-Plattform ist die Aktualisierung von Daten (Dateien) in einer Wdata-Tabelle, wie im obigen Beispiel der List Files. Um einen aktualisierten Datensatz (Datei) zu importieren, muss der bestehende Datensatz aus der Tabelle entfernt werden, da Wdata nicht mehrere Dateien mit demselben Namen zulässt. Um eine bestehende Datei zu löschen, müssen die ID und der Status (Staged oder Imported) der bestehenden Datei abgefragt werden.
Eine Möglichkeit, diese Informationen abzurufen, besteht darin, die JSON-Nutzdaten der Listendateien mithilfe des Befehls Array to CSV in ein Tabellenformat zu konvertieren. Als Nächstes verwenden Sie den Befehl Tabellarische Transformation Smart Filter Rows, um die einzelne Zeile mit den Dateiinformationen zu isolieren. Dann verwenden Sie den Befehl Tabellarische Transformation Wert extrahieren, um die Datei-ID und den Status abzurufen. Für die Zwecke dieses Artikels bezeichnen wir dies als den Legacy-Ansatz.
Verwendung von Filtern
Mit dem Filter-Eingang kann eine JSON-Antwort nicht nur hinsichtlich der auszuwählenden Felder (Spalten) gefiltert werden, sondern auch hinsichtlich der Elemente (Zeilen), die aus der JSON-Nutzlast abgerufen werden sollen. Dies ist ein leistungsfähiger Mechanismus zur Auswahl der benötigten spezifischen Daten, der die Effizienz des Integrationsprozesses verbessert. Der Filter ermöglicht es, ein oder mehrere Elemente in der JSON-Nutzlast zu verwenden, um die Anzahl der abgerufenen Elemente (Zeilen) zu begrenzen.
Ein Filterkriterium hat 3 Komponenten - Elementpfad, Vergleichswert und einen Operator. Die Kriterien müssen zu einem wahren oder falschen Wert führen. Wenn die Filterkriterien einen wahren Wert ergeben, wird der Datensatz aus der JSON-Nutzlast entsprechend der Definition der Befehlsspalten extrahiert und als Zeile in der resultierenden CSV-Ausgabe erstellt. Zum Beispiel:
- Ist der Dateistatus gleich Staged?
In diesem Beispiel ist der Dateistatus der Elementpfad, equal ist der Operator und Staged ist der Vergleichswert. Für jeden Datensatz in der JSON-Nutzlast, dessen Dateistatus "Staged" lautet, wird eine Zeile in der CSV-Datei erstellt, die die in der Befehlskonfiguration definierten Spalten enthält. In diesem Beispiel sind dies ID, Name und Status.
Element Pfad
Um einen Filter anzugeben, muss der Pfad zum Element bekannt sein. In der Antwort "List Files" lautet der Pfad zum Element "Status" beispielsweise:
@.status
Der dem Element zugeordnete Wert wird bei der Ausführung des Befehls abgerufen. Im obigen Payload-Beispiel wäre dies der Wert IMPORTED für das Element status .
Hinweis: Ein Elementpfad muss mit dem Symbol bei (@) beginnen.
Vergleichswert
Der Vergleichswert ist der Wert, mit dem der Elementpfadwert verglichen wird. Der Vergleichswert kann ein statischer Wert sein, der in der Befehlskonfiguration definiert ist, oder er kann eine Variable oder einen Ausgabewert verwenden, der bei der Ausführung bestimmt wird.
Operator
Der Operator bestimmt die Art der Auswertung, die zum Filtern der Daten durchgeführt wird.
Hinweis: Zwischen dem Element Pfad und dem Operator sowie zwischen dem Operator und dem Vergleichswert ist ein Leerzeichen erforderlich.
Unterstützte Operatoren
| Operatortyp | Operator | Verwenden Sie |
| Numerisch | < | Auswerten, ob der Elementwert kleiner ist als der Vergleichswert |
| Numerisch | <= | Auswerten, ob der Elementwert kleiner oder gleich dem Vergleichswert ist |
| Numerisch | > | Auswerten, ob der Elementwert größer ist als der Vergleichswert |
| Numerisch | >= | Auswerten, ob der Elementwert größer oder gleich dem Vergleichswert ist |
| Logisch / Text | == |
Auswerten, ob der Elementwert gleich (identisch) mit dem Vergleichswert ist. Der Auswertungswert muss in doppelte Anführungszeichen ("") eingeschlossen werden Groß- und Kleinschreibung werden unterschieden. Wildcards werden NICHT unterstützt. |
| Logisch / Text | != |
Auswerten, ob der Elementwert nicht gleich dem Vergleichswert ist. Der Auswertungswert muss in doppelte Anführungszeichen ("") eingeschlossen werden Groß- und Kleinschreibung werden unterschieden. Wildcards werden NICHT unterstützt. |
| Logisch / Text | && | Der AND Operator, mit dem mehrere Filterpfade und/oder Kriterien ausgewertet werden können. Die Verwendung dieses Operators gibt nur die Datensätze zurück, bei denen alle Bedingungen als wahr ausgewertet werden. |
| Logisch / Text | || | Der OR Operator, mit dem mehrere Filterpfade und/oder Kriterien ausgewertet werden können. Die Verwendung dieses Operators gibt alle Datensätze zurück, bei denen eine oder mehrere der Bedingungen den Wert "wahr" ergeben. |
Es ist wichtig, bei der Angabe des Operators die Art der Werte zu berücksichtigen, die für den Elementpfad existieren. So würde beispielsweise die Verwendung des Operators größer als (>) bei der Auswertung eines Elements, das Textwerte enthält, möglicherweise eine leere Ausgabe erzeugen, da eine numerische Auswertung eines Textwerts unlogisch ist.
Filter-Syntax & Beispiel-Filter
Alle Filter müssen mit einem Fragezeichen (?) beginnen und in Klammern gesetzt werden.
Einzelnes Kriterium
Für ein einzelnes Filterkriterium wird die folgende Syntax verwendet:
?(Element_Path Operator Comparison_Value)
?(@.name == "executions_2023-12.csv")
Dieser Filter gibt alle Datensätze zurück, bei denen das Element name gleich executions_2023-12.csv ist.
Mehrere Kriterien
Ein Filter mit mehreren Kriterien verwendet die folgende Syntax:
?(Element_Path Operator Comparison_Value Logical_Operator Element_Path Operator Comparison_Value)
?(@.name == "executions_2023-12.csv" && @.status == "IMPORTED")
Dieser Filter gibt alle Datensätze zurück, bei denen das Element name gleich executions_2023-12.csv und das Element status gleich IMPORTED ist.
Beispiel einer Befehlskonfiguration
In diesem Beispiel ist der Filtereingang so konfiguriert, dass er das Element name in der JSON-Nutzlast auswertet. Der Filter verwendet Variablen für das Jahr und den Monat, die in diesem Beispiel Laufzeit-Eingabewerte sind. Dadurch kann der Filter dynamisch das Jahr und den Monat berücksichtigen, die bei der Ausführung der Kette angegeben werden.
Der Wert von Filtern
Filter ermöglichen es, dass nur die erforderlichen Zeilen aus einer JSON-Antwort abgerufen werden. Dadurch kann die Größe der vom Befehl erzeugten Ausgabedatei verringert werden, was die Leistung der Kette verbessern kann.
Beim Versuch, eine einzelne Zeile aus einer JSON-Antwort zu isolieren, kann Dynamic Outputs verwendet werden, um diese spezifischen Werte aus der gefilterten Nutzlast zu extrahieren und sie für die Verwendung in nachfolgenden Knoten der Kette verfügbar zu machen.
Die folgende Abbildung zeigt ein Beispiel für die Definition einer dynamischen Ausgabe.
Die sich daraus ergebende Kette ist schlanker, da ein einziger Knoten (Array zu CSV) die Operationen von vier Knoten ausführt, die bei einem herkömmlichen Ansatz erforderlich sind. Diese schlankere Kette arbeitet auch effizienter, da weniger Befehle ausgeführt werden und die resultierenden Ausgaben kleiner sind.