Sfondo
Catene interagisce con una serie di sistemi di terze parti e con la piattaforma Workiva sfruttando le API REST del sistema con cui si sta integrando.Molte risposte delle API REST sono in formato JSON, comprese le varie API di Workiva.Sebbene una risposta JSON possa essere ben documentata e strutturata in modo coerente, è difficile lavorare con i dati in questo formato.Il comando Array a CSV nel connettore JSON è un modo utile per convertire un payload JSON in un formato tabellare (righe e colonne) da utilizzare nella piattaforma Workiva.
In questo articolo vedremo come utilizzare le capacità di filtraggio di questo comando per restituire solo i risultati del payload JSON necessari.Questo può essere necessario perché la risposta di un'API REST spesso contiene più informazioni del necessario, poiché il payload è generalmente determinato dagli sviluppatori e gli utenti finali dell'endpoint spesso non hanno la possibilità di limitare lo scope dei dati restituiti.
Ad esempio, il comando Elenca file del connettore Workiva utilizza l'endpoint Recupera un elenco di file dell'API Wdata di Workiva per restituire un elenco di tutti i file associati a una tabella Wdata.La risposta JSON per questo endpoint contiene le seguenti informazioni:
[
{
"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
}
]
Il comando Array a CSV ci permette di selezionare solo i campi che possiamo recuperare dalla risposta JSON.Ad esempio, possiamo scegliere di selezionare i campi id, nome e stato specificandoli nella sezione Colonne del comando.Il comando estrarrà ogni ID, Nome e Stato del file dalla risposta JSON e creerà una riga per ogni file nella risposta JSON.
Continuando con l'esempio dei file elenco di cui sopra, un caso d'uso comune all'interno della piattaforma Workiva è la necessità di aggiornare i dati (file) in una tabella Wdata.Per importare un set di dati (file) aggiornato, il set di dati esistente deve essere rimosso dalla tabella perché Wdata non consente di importare più file con lo stesso nome.Per cancellare un file esistente, è necessario recuperare l'ID e lo stato (Graduale o Importato) del file esistente.
Un approccio per recuperare queste informazioni è quello di convertire il payload JSON di Elenca file in un formato tabellare utilizzando il comando Array a CSV.Successivamente dovresti utilizzare il comando Filtro intelligente righe della Trasformazione tabellare per isolare la singola riga con le informazioni sul file.Poi dovresti utilizzare il comando Estrai valore della Trasformazione tabellare per recuperare l'ID e lo stato del file.Ai fini di questo articolo, chiameremo questo approccio Legacy.
Utilizzo dei filtri
L'input Filtro permette di filtrare una risposta JSON non solo in termini di campi (colonne) da selezionare ma anche di quali elementi (righe) saranno recuperati dal payload JSON.Si tratta di un potente meccanismo per selezionare i dati specifici necessari che migliora l'efficienza del processo di integrazione.Il Filtro permette di utilizzare uno o più elementi nel payload JSON per limitare il numero di elementi (righe) recuperati.
Un criterio di filtro ha 3 componenti: il percorso dell'elemento, il valore di confronto e un operatore.I criteri devono avere come risultato un valore vero o falso.Quando i criteri del filtro restituiscono un valore vero, il record viene estratto dal payload JSON in base alla definizione delle colonne del comando e creato come riga nell'output CSV risultante.Ad esempio:
- Lo stato del file è uguale a Graduale?
In questo esempio, lo stato del file è il percorso dell'elemento, equal è l'operatore e Graduale è il valore di confronto.Ogni record nel payload JSON in cui lo stato del file è Graduale, viene creata una riga nel CSV contenente le colonne definite nella configurazione del comando.In questo esempio sono ID, nome e stato.
Percorso dell'elemento
Per specificare un filtro, è necessario conoscere il percorso dell'elemento.Ad esempio nella risposta Elenca file, il percorso dell'elemento Stato è:
@.status
Il valore associato all'elemento viene recuperato durante l'esecuzione del comando.Nell'esempio di payload sopra riportato, questo sarebbe il valore IMPORTATO per l'elemento stato .
Nota: il percorso di un elemento deve iniziare con il simbolo a (@).
Valore di confronto
Il valore di confronto è il valore con cui viene confrontato il valore del Percorso dell'elemento.Il valore di confronto può essere un valore statico definito nella configurazione del comando oppure può utilizzare una variabile o un valore di output che viene determinato al momento dell'esecuzione.
Operatore
L'operatore determina il tipo di valutazione che verrà eseguita per filtrare i dati.
Nota: è necessario uno spazio tra il percorso dell'elemento e l'operatore e tra l'operatore e il valore di confronto.
Operatori supportati
| Tipo di operatore | Operatore | Utilizzo |
| Numerico | < | Valuta se il valore dell'elemento è inferiore al valore di confronto |
| Numerico | <= | Valuta se il valore dell'elemento è inferiore o uguale al valore di confronto |
| Numerico | > | Valuta se il valore dell'elemento è maggiore del valore di confronto |
| Numerico | >= | Valuta se il valore dell'elemento è maggiore o uguale al valore di confronto |
| Logico / Testo | == |
Valuta se il valore dell'elemento è uguale (identico) al valore di confronto.Il valore di valutazione deve essere racchiuso tra doppi apici ("") ed è MAIUSCOLO O MINUSCOLO. I caratteri jolly NON sono supportati. |
| Logico / Testo | != |
Valuta se il valore dell'elemento non è uguale al valore di confronto. Il valore di valutazione deve essere racchiuso tra doppi apici ("") ed è MAIUSCOLO O MINUSCOLO. I caratteri jolly NON sono supportati. |
| Logico / Testo | && | L'operatore AND che permette di valutare più percorsi di filtro e/o criteri.L'uso di questo operatore restituisce solo i record in cui tutte le condizioni sono valutate come vere. |
| Logico / Testo | || | L'operatore OR che permette di valutare più percorsi di filtro e/o criteri.L'uso di questo operatore restituisce tutti i record in cui una o più condizioni sono valutate come vere. |
È importante considerare il tipo di valori che esistono per il percorso dell'elemento quando si specifica l'operatore.Ad esempio, l'uso dell'operatore maggiore di (>) produrrebbe potenzialmente un output vuoto quando si valuta un elemento che contiene valori di testo, poiché una valutazione numerica di un valore di testo è illogica.
Sintassi ed esempi di filtri
Tutti i filtri devono iniziare con un punto interrogativo (?) ed essere contenuti tra parentesi.
Criteri singoli
Un singolo criterio di filtro utilizza la seguente sintassi:
?(Element_Path Operator Comparison_Value)
?(@.name == "executions_2023-12.csv")
Questo filtro restituisce tutti i record in cui l'elemento nome è uguale a executions_2023-12.csv.
Criteri multipli
Un filtro a criteri multipli utilizza la seguente sintassi:
?(Element_Path Operator Comparison_Value Logical_Operator Element_Path Operator Comparison_Value)
?(@.name == "executions_2023-12.csv" && @.status == "IMPORTED")
Questo filtro restituisce tutti i record in cui l'elemento nome è uguale a executions_2023-12.csv e l'elemento stato è uguale a IMPORTATO.
Esempio di configurazione dei comandi
In questo esempio, l'input Filtro è configurato per valutare l'elemento nome nel payload JSON.Il filtro utilizza le variabili per l'anno e il mese, che in questo esempio sono valori di input del runtime.Questo permette al filtro di tenere conto dinamicamente dell'anno e del mese specificati al momento dell'esecuzione della catena.
Il valore dei filtri
I filtri permettono di recuperare solo le righe richieste da una risposta JSON.Questo può ridurre le dimensioni del file di output generato dal comando, migliorando le prestazioni della catena.
Inoltre, quando si cerca di isolare una singola riga da una risposta JSON, è possibile utilizzare Output dinamici per estrarre quei valori specifici dal payload filtrato e renderli disponibili per l'uso nei nodi successivi della catena.
Di seguito viene mostrato un esempio di definizioni di Output dinamico.
La catena risultante è semplificata: un singolo nodo (Array a CSV) esegue le operazioni di quattro nodi richieste dall'approccio tradizionale.Questa catena semplificata funziona anche in modo più efficiente, poiché vengono eseguiti meno comandi e gli output risultanti sono più piccoli.