Workiva-ondersteuningscentrum

Achtergrond

Chains communiceert met verschillende systemen van derden en met het Workiva platform door gebruik te maken van de REST API van het systeem waarmee het integreert. Veel REST API responses zijn in JSON formaat, inclusief de verschillende Workiva APIs. Hoewel een JSON-antwoord goed gedocumenteerd en consistent gestructureerd kan zijn, is het moeilijk om met gegevens in dit formaat te werken. De opdracht Array to CSV in de JSON Connector is een handige manier om een JSON payload te converteren naar een tabelformaat (rijen & kolommen) voor gebruik binnen het Workiva platform. 

In dit artikel onderzoeken we hoe we de filtermogelijkheden van dit commando kunnen gebruiken om alleen de resultaten van de JSON payload te retourneren die nodig zijn. Dit kan nodig zijn omdat een REST API respons vaak meer informatie bevat dan nodig is, omdat de payload over het algemeen bepaald wordt door ontwikkelaars en eindgebruikers van het eindpunt vaak niet de mogelijkheid hebben om de omvang van de geretourneerde gegevens te beperken. 

Als voorbeeld, de List Files Command van de Workiva Connector gebruikt de Retrieve a List of Files endpoint van de Workiva Wdata API om een lijst terug te sturen van alle bestanden die geassocieerd zijn met een Wdata tabel. Het JSON antwoord voor dit eindpunt bevat de volgende informatie:

 [ 
 { 
 "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": {}, 
 "kolom2": {}
 }, 
 "name": "executions_2023-12.csv", 
 "numRecords": 101789, 
 "originalFileSize": 24226080, 
 "status": "IMPORTED", 
 "tableId": "bafe350ebff74a2dbc11262245483dee", 
 "updated": "2023-12-18T15:06:56.000Z", 
 "userId": "HzU1OTQwMTMxODMzMTE4NzI", 
 "version": 1 
 }
]

Met de opdracht Array to CSV kunnen we alleen de velden selecteren die we uit het JSON-antwoord kunnen ophalen. We kunnen er bijvoorbeeld voor kiezen om de velden id, name en status te selecteren door deze op te geven in het invoergedeelte Columns van de opdracht. De opdracht haalt elke bestands-ID, naam en status uit het JSON-antwoord en maakt een rij voor elk bestand in het JSON-antwoord.  

Voortbordurend op het bovenstaande voorbeeld van Lijstbestanden, is een veelvoorkomend gebruik binnen het Workiva platform het bijwerken van de gegevens (bestand) in een Wdatatabel. Om een bijgewerkte dataset (bestand) te importeren, moet de bestaande dataset uit de tabel worden verwijderd, omdat Wdata niet toestaat dat meerdere bestanden dezelfde naam hebben. Om een bestaand bestand te verwijderen, moeten ID en status (Staged of Imported) van het bestaande bestand worden opgehaald. 

Een manier om deze informatie op te halen is door de JSON-belading van List Files te converteren naar een tabelformaat met de opdracht Array to CSV. Vervolgens gebruikt u de opdracht Tabular Transformation Smart Filter Rows om de individuele rij met de bestandsinformatie te isoleren. Vervolgens gebruikt u de opdracht Tabular Transformation Extract Value om de bestands-ID en status op te halen. In dit artikel noemen we dit de Legacy-aanpak.   

Filters gebruiken

Met de filteringang kan een JSON-antwoord niet alleen worden gefilterd op de velden (kolommen) die moeten worden geselecteerd, maar ook op welke items (rijen) zullen worden opgehaald uit de JSON payload. Dit is een krachtig mechanisme om de specifieke gegevens te selecteren die nodig zijn, wat de efficiëntie van het integratieproces verbetert. Met de Filter kunnen één of meer elementen in de JSON payload gebruikt worden om het aantal opgehaalde items (rijen) te beperken. 

Een filtercriterium heeft 3 componenten - elementpad, vergelijkingswaarde en een operator. De criteria moeten resulteren in een waar of onwaar waarde. Als de filtercriteria een ware waarde opleveren, wordt de record uit de JSON payload gehaald volgens de opdrachtkolomdefinitie en als rij aangemaakt in de resulterende CSV-uitvoer. Bijvoorbeeld:

• Is de bestandsstatus gelijk aan Staged?

In dit voorbeeld is Bestandsstatus het pad van het element, Gelijk is de operator en Opgevoerd is de Vergelijkingswaarde. Voor elke record in de JSON payload waarvan de bestandsstatus Staged (Gefaseerd) is, wordt een rij gemaakt in de CSV die de kolommen bevat die in Command configuration (Opdrachtconfiguratie) zijn gedefinieerd. Voor dit voorbeeld zijn dat ID, naam en status.

Element Pad

Om een filter op te geven, moet het pad naar het element bekend zijn. In het antwoord List Files is het pad naar het Status-element bijvoorbeeld:

@.status

De waarde die bij het element hoort, wordt opgehaald tijdens het uitvoeren van de opdracht. In het bovenstaande voorbeeld van de payload zou dit de waarde IMPORTED zijn voor het status element. 

Opmerking: Een elementpad moet beginnen met het op (@) symbool.

Vergelijkingswaarde

De Vergelijkingswaarde is de waarde waarmee de elementpadwaarde vergeleken wordt. De vergelijkingswaarde kan een statische waarde zijn die in de opdrachtconfiguratie is gedefinieerd of kan een variabele of uitvoerwaarde gebruiken die tijdens de uitvoering wordt bepaald.  

Exploitant

De operator bepaalt het type evaluatie dat wordt uitgevoerd om de gegevens te filteren. 

Opmerking: Er is een spatie vereist tussen de Element Path en de Operator evenals tussen de Operator en de Vergelijkingswaarde.

Ondersteunde operatoren

Het is belangrijk om bij het specificeren van de operator rekening te houden met het type waarden dat voor het elementpad bestaat. Het gebruik van de greater than (>) operator zou bijvoorbeeld een lege uitvoer kunnen opleveren bij het evalueren van een element dat tekstwaarden bevat, aangezien een numerieke evaluatie van een tekstwaarde onlogisch is.

Filtersyntaxis & voorbeeldfilters

Alle filters moeten beginnen met een vraagteken (?) en tussen haakjes staan.  

Enkele criteria

Een enkelvoudig criteriafilter gebruikt de volgende syntaxis:

?(Element_Path Operator Vergelijking_Waarde)

?(@.name == "executions_2023-12.csv")

Dit filter retourneert alle records waarvan het naamelement gelijk is aan executions_2023-12.csv.

Meerdere criteria

Een filter met meerdere criteria gebruikt de volgende syntaxis:

?(Element_Path Operator Comparison_Value Logical_Operator Element_Path Operator Comparison_Value)

?(@.name == "executions_2023-12.csv" && @.status == "IMPORTED")

Dit filter retourneert alle records waarvan het element name gelijk is aan executions_2023-12.csv en het element status gelijk is aan IMPORTED.

Voorbeeld opdrachtconfiguratie

In dit voorbeeld is de filteringang geconfigureerd om het element name in de JSON payload te evalueren. Het filter gebruikt variabelen voor het Jaar en de Maand, die in dit voorbeeld Runtime Input-waarden zijn. Hierdoor kan het filter dynamisch rekening houden met het jaar en de maand die opgegeven zijn wanneer de ketting wordt uitgevoerd.  

De waarde van filters

Filters zorgen ervoor dat alleen de vereiste rijen uit een JSON antwoord worden opgehaald. Dit kan de grootte van het uitvoerbestand verkleinen dat door het commando wordt gegenereerd, wat de prestaties van de keten kan verbeteren. 

Als u bovendien een enkele rij uit een JSON-respons probeert te isoleren, kunt u Dynamic Outputs gebruiken om die specifieke waarden uit de gefilterde payload te halen en ze beschikbaar te maken voor gebruik in volgende knooppunten van de Chain. 

Hieronder ziet u een voorbeeld van dynamische uitvoerdefinities.

De resulterende keten is meer gestroomlijnd, met een enkel knooppunt (Array naar CSV) dat de bewerkingen uitvoert van vier knooppunten die nodig zijn bij een legacy-aanpak. Deze gestroomlijnde keten presteert ook efficiënter omdat er minder opdrachten worden uitgevoerd en de resulterende uitgangen kleiner zijn.