Workiva supportcenter

Bakgrund

Chains interagerar med en mängd olika tredjepartssystem samt Workiva-plattformen genom att utnyttja REST API för det system som det integreras med.  Många REST API-svar är i JSON-format, inklusive de olika Workiva API:erna.  Även om ett JSON-svar kan vara väldokumenterat och konsekvent strukturerat är det svårt att arbeta med data i det här formatet.  Kommandot Array to CSV i JSON Connector är ett användbart sätt att konvertera en JSON-nyttolast till ett tabellformat (rader och kolumner) för användning i Workiva-plattformen. 

I den här artikeln undersöker vi hur du kan använda filtreringsfunktionerna i detta kommando för att bara returnera de resultat från JSON-nyttolasten som behövs.  Detta kan vara nödvändigt eftersom ett REST API-svar ofta innehåller mer information än vad som behövs eftersom nyttolasten i allmänhet bestäms av utvecklare och slutanvändare av slutpunkten ofta inte har möjlighet att begränsa omfattningen av de data som returneras. 

Exempelvis använder kommandot List Files Command i Workiva Connector slutpunkten Retrieve a List of Files från Workiva Wdata API för att returnera en lista över alla filer som är associerade med en Wdata-tabell.  JSON-svaret för denna endpoint innehåller följande information:

 [ 
 { 
 "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 
 }
]

Med kommandot Array to CSV kan vi välja ut endast de fält som vi kan hämta från JSON-svaret.  Vi kan t.ex. välja att välja fälten id, name och status genom att ange dem i avsnittet Columns input i kommandot.  Kommandot extraherar varje fil-ID, namn och status från JSON-svaret och skapar en rad för varje fil i JSON-svaret.  

Om vi fortsätter med exemplet med listfiler ovan är ett vanligt användningsfall inom Workiva-plattformen att behöva uppdatera data (filen) i en Wdata-tabell.  För att importera ett uppdaterat dataset (arkivering) måste det befintliga datasetet tas bort från tabellen eftersom Wdata inte tillåter flera filer med samma namn.  För att ta bort en befintlig arkivering måste ID och status (Staged eller Imported) för den befintliga arkiveringen hämtas. 

Ett sätt att hämta den här informationen är att konvertera List Files JSON-payloaden till ett tabellformat med hjälp av kommandot Array to CSV.  Därefter skulle du använda Tabular Transformation Smart Filter Rows Kommando för att isolera den enskilda raden med filinformationen.  Sedan använder du Tabular Transformation Extract Value Command för att hämta fil-ID och status.  I den här artikeln kallar vi detta för "Legacy"-metoden.   

Använda filter

Med inmatningen Filter kan ett JSON-svar filtreras inte bara när det gäller de fält (kolumner) som ska väljas utan också vilka objekt (rader) som ska hämtas från JSON-nyttolasten.  Detta är en kraftfull mekanism för att välja de specifika data som behövs, vilket förbättrar effektiviteten i integrationsprocessen.  Filtret gör att ett eller flera element i JSON-nyttolasten kan användas för att begränsa antalet objekt (rader) som hämtas. 

Ett filterkriterium har 3 komponenter - elementväg, jämförelsevärde och en operatör.  Kriterierna måste resultera i ett sant eller falskt värde.  När filterkriterierna returnerar ett sant värde extraheras posten från JSON-nyttolasten enligt Command Columns-definitionen och skapas som en rad i den resulterande CSV-utdata.  Till exempel:

• Är filstatusen lika med Staged?

I det här exemplet är arkivering elementets sökväg, lika är operatorn och Staged är jämförelsevärdet.  För alla poster i JSON-nyttolasten där filstatusen är Staged skapas en rad i CSV-filen som innehåller de kolumner som definieras i Command configuration.  I det här exemplet är det ID, namn och status.

Elementets väg

För att specificera ett filter måste vägen till elementet vara känd.  Till exempel i svaret List Files är sökvägen till Status-elementet:

@.status

Det värde som är kopplat till elementet hämtas under exekveringen av kommandot.  I exemplet med nyttolasten ovan skulle detta vara värdet IMPORTED för elementet status . 

Obs: En elementväg måste börja med symbolen på (@).

Jämförelsevärde

Jämförelsevärdet är det värde som värdet för elementbanan jämförs med.  Jämförelsevärdet kan vara ett statiskt värde som definieras i kommandokonfigurationen eller så kan det använda ett variabel- eller utgångsvärde som bestäms vid körningen.  

Operatör

Operatören bestämmer vilken typ av utvärdering som ska utföras för att filtrera data. 

Obs: Det krävs ett mellanslag mellan Element Path och Operator samt mellan Operator och Comparison value.

Operatorer som stöds

Det är viktigt att ta hänsyn till vilken typ av värden som finns för elementbanan när operatören specificeras.  Om man t.ex. använder operatorn större än (>) kan det leda till en tom utdata när man utvärderar ett element som innehåller textvärden, eftersom en numerisk utvärdering av ett textvärde är ologisk.

Filtersyntax & exempel på filter

Alla filter måste inledas med ett frågetecken (?) och vara inom parentes.  

Enstaka kriterier

Ett filterkriterium med ett enda kriterium använder följande syntax:

?(Element_Path Operator Comparison_Value)

?(@.name == "avrättningar_2023-12.csv")

Detta filter returnerar alla poster där namnelementet är lika med executions_2023-12.csv.

Flera kriterier

Ett filter med flera kriterier använder följande syntax:

?(Element_Path Operator Comparison_Value Logical_Operator Element_Path Operator Comparison_Value)

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

Detta filter returnerar alla poster där namnelementet är lika med executions_2023-12.csv och statuselementet är lika med IMPORTED.

Exempel på kommandokonfiguration

I det här exemplet är Filter-ingången konfigurerad för att utvärdera elementet name i JSON-payloaden.  Filtret använder variabler för år och månad, som i det här exemplet är inmatningsvärden för exekvering.  Detta gör att filtret dynamiskt kan ta hänsyn till det år och den månad som anges när kedjan körs.  

Värdet av filter

Filter gör att endast de rader som krävs kan hämtas från ett JSON-svar.  Detta kan minska storleken på den utdatafil som genereras av kommandot, vilket kan förbättra kedjans prestanda. 

Vid försök att isolera en enda rad från ett JSON-svar kan Dynamic Outputs dessutom användas för att extrahera dessa specifika värden från den filtrerade nyttolasten och göra dem tillgängliga för användning i efterföljande noder i kedjan. 

Nedan visas ett exempel på definitioner av Dynamic Output.

Den resulterande kedjan är mer strömlinjeformad med en enda nod (Array till CSV) som utför de operationer som krävs av fyra noder med en äldre metod.  Denna strömlinjeformade kedja fungerar också mer effektivt eftersom färre kommandon utförs och de resulterande utdata är mindre.