Workiva kundestøttesenter

Bakgrunn

Chains samhandler med en rekke tredjepartssystemer samt Workiva-plattformen ved å utnytte REST API-et til systemet som det integreres med. Mange REST API-svar er i JSON-format, inkludert de ulike Workiva API-ene. Selv om et JSON-svar kan være veldokumentert og konsekvent strukturert, er det vanskelig å arbeide med data i dette formatet. Kommandoen Array to CSV i JSON Connector er en nyttig måte å konvertere en JSON-nyttelast til et tabellformat (rader og kolonner) for bruk i Workiva-plattformen. 

I denne artikkelen skal vi se hvordan du kan bruke filtreringsmulighetene i denne kommandoen til å returnere bare de resultatene fra JSON-nyttelasten som du trenger. Dette kan være nødvendig fordi et REST API-svar ofte inneholder mer informasjon enn nødvendig, siden nyttelasten som regel bestemmes av utviklere og sluttbrukerne av endepunktet ofte ikke har mulighet til å begrense omfanget av dataene som returneres. 

For eksempel bruker List Files Command i Workiva Connector endepunktet Retrieve a List of Files fra Workiva Wdata API til å returnere en liste over alle filene som er knyttet til en Wdata-tabell. JSON-svaret for dette endepunktet inneholder følgende informasjon:

 [ 
 { 
 "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 Array to CSV-kommandoen kan vi velge bare de feltene vi kan hente fra JSON-svaret. Vi kan for eksempel velge å velge feltene id, navn, og status ved å angi disse i inndatadelen Kolonner i kommandoen. Kommandoen trekker ut hver fil-ID, navn og status fra JSON-svaret og oppretter en rad for hver fil i JSON-svaret.  

Hvis vi fortsetter med eksemplet med listefiler ovenfor, er et vanlig bruksområde i Workiva-plattformen å oppdatere dataene (filen) i en Wdata-tabell. For å importere et oppdatert datasett (fil) må det eksisterende datasettet fjernes fra tabellen, fordi Wdata ikke tillater flere filer med samme navn. For å slette en eksisterende fil må ID og status (Staged eller Imported) for den eksisterende filen hentes inn. 

En måte å hente denne informasjonen på er å konvertere List Files JSON-nyttelasten til et tabellformat ved hjelp av Array to CSV-kommandoen. Deretter bruker du Tabular Transformation Smart Filter Rows Kommando for å isolere den enkelte raden med filinformasjonen. Deretter bruker du kommandoen Tabular Transformation Extract Value til å hente ut fil-ID og status. I denne artikkelen kaller vi dette for Legacy-tilnærmingen.   

Bruk av filtre

Med Filter-inngangen kan et JSON-svar filtreres, ikke bare med hensyn til hvilke felt (kolonner) som skal velges, men også hvilke elementer (rader) som skal hentes fra JSON-nyttelasten. Dette er en effektiv mekanisme som gjør det mulig å velge ut de spesifikke dataene som trengs, noe som forbedrer effektiviteten i integrasjonsprosessen. Filteret gjør det mulig å bruke ett eller flere elementer i JSON-nyttelasten til å begrense antallet elementer (rader) som hentes. 

Et filterkriterium består av tre komponenter - elementbane, sammenligningsverdi og en operator. Kriteriene må resultere i en sann eller falsk verdi. Når filterkriteriene returnerer en sann verdi, trekkes posten ut fra JSON-nyttelasten i henhold til Command Columns-definisjonen og opprettes som en rad i den resulterende CSV-utdataen. For eksempel:

• Er filstatusen lik Staged?

I dette eksempelet er filstatus elementbanen, equal er operatøren og Staged er sammenligningsverdien. For alle poster i JSON-nyttelasten der filstatusen er Staged, opprettes det en rad i CSV-filen som inneholder kolonnedefinisjonen i kommandokonfigurasjonen. I dette eksemplet er de ID, navn og status.

Elementbane

For å angi et filter må banen til elementet være kjent. I List Files-svaret er for eksempel banen til Status-elementet:

@.status

Verdien som er knyttet til elementet, hentes under utførelsen av kommandoen. I eksemplet på nyttelast ovenfor vil dette være verdien IMPORTED for elementet status . 

Merk: En elementbane må begynne på på (@)-symbolet.

Sammenligningsverdi

Sammenligningsverdien er den verdien som verdien for elementstien sammenlignes med. Sammenligningsverdien kan være en statisk verdi som er definert i kommandokonfigurasjonen, eller den kan bruke en variabel eller utgangsverdi som bestemmes ved kjøring.  

Operatør

Operatøren bestemmer hvilken type evaluering som skal utføres for å filtrere dataene. 

Merk: Det kreves et mellomrom mellom Element Path og operatøren samt mellom operatøren og Comparison-verdien.

Operatører som støttes

Det er viktig å ta hensyn til hvilke typer verdier som finnes for elementbanen når du spesifiserer operatøren. For eksempel vil bruk av operatoren større enn (>) potensielt gi en tom utdata når du evaluerer et element som inneholder tekstverdier, siden en numerisk evaluering av en tekstverdi er ulogisk.

Filtersyntaks og eksempler på filtre

Alle filtre må begynne med et spørsmålstegn (?) og stå innenfor parenteser.  

Enkeltkriterier

Et enkelt filterkriterium bruker følgende syntaks:

?(Element_Path Operator Comparison_Value)

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

Dette filteret returnerer alle poster der name-elementet er lik executions_2023-12.csv.

Flere kriterier

Et filter med flere kriterier bruker følgende syntaks:

?(Element_Path Operator Comparison_Value Logical_Operator Element_Path Operator Comparison_Value)

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

Dette filteret returnerer alle poster der name-elementet er lik executions_2023-12.csv og status-elementet er lik IMPORTED.

Eksempel på kommandokonfigurasjon

I dette eksempelet er Filter-inndataene konfigurert til å evaluere name -elementet i JSON-nyttelasten. Filteret bruker variabler for år og måned, som i dette eksempelet er Runtime Input-verdier. Dette gjør at filteret dynamisk tar hensyn til året og måneden som er angitt når kjeden kjøres.  

Verdien av filtre

Filtre gjør at bare de nødvendige radene kan hentes fra et JSON-svar. Dette kan redusere størrelsen på utdatafilen som genereres av kommandoen, noe som kan forbedre kjedens ytelse. 

I tillegg kan Dynamic Outputs brukes til å trekke ut de spesifikke verdiene fra den filtrerte nyttelasten og gjøre dem tilgjengelige for bruk i påfølgende noder i kjeden når du prøver å isolere en enkelt rad fra et JSON-svar. 

Nedenfor vises et eksempel på dynamiske utdatadefinisjoner.

Den resulterende kjeden er mer strømlinjeformet, med én enkelt node (Array til CSV) som utfører operasjonene til fire noder som kreves med en eldre tilnærming. Denne strømlinjeformede kjeden er også mer effektiv, siden færre kommandoer kjøres og de resulterende utdataene blir mindre.