Portail de support Workiva

Arrière-plan

Chains interagit avec une variété de systèmes tiers ainsi qu'avec la plateforme Workiva en exploitant l'API REST du système avec lequel il s'intègre.  De nombreuses réponses de l'API REST sont au format JSON, y compris les différentes API de Workiva.  Bien qu'une réponse JSON puisse être bien documentée et structurée de manière cohérente, il est difficile de travailler avec des données dans ce format.  La commande Array to CSV du connecteur JSON est un moyen utile de convertir une charge utile JSON en un format tabulaire (lignes et colonnes) à utiliser dans la plateforme Workiva. 

Dans cet article, nous verrons comment utiliser les capacités de filtrage de cette commande pour ne renvoyer que les résultats de la charge utile JSON dont on a besoin.  Cela peut s'avérer nécessaire car une réponse d'API REST contient souvent plus d'informations que nécessaire, étant donné que la charge utile est généralement déterminée par les développeurs et que les utilisateurs finaux du point de terminaison n'ont souvent pas la possibilité de limiter l'étendue des données renvoyées. 

Par exemple, la commande List Files du connecteur Workiva utilise le point de terminaison Retrieve a List of Files de l'API Workiva Wdata pour renvoyer une liste de tous les fichiers associés à une table Wdata.  La réponse JSON pour ce point d'accès contient les informations suivantes :

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

La commande Array to CSV nous permet de sélectionner uniquement les champs que nous pouvons extraire de la réponse JSON.  Par exemple, nous pouvons choisir de sélectionner les champs id, name, et status en les spécifiant dans la section Columns input de la commande.  La commande extrait chaque ID, nom et état de fichier de la réponse JSON et crée une ligne pour chaque fichier dans la réponse JSON.  

En reprenant l'exemple de la liste des fichiers ci-dessus, un cas d'utilisation courant au sein de la plateforme Workiva est la nécessité de mettre à jour les données (fichier) d'une table Wdata.  Pour importer un ensemble de données mis à jour (fichier), l'ensemble de données existant doit être supprimé du tableau, car Wdata n'autorise pas l'utilisation de plusieurs fichiers portant le même nom.  Pour supprimer un fichier existant, il faut récupérer l'identifiant et le statut du fichier existant (en phase ou importé). 

Une approche pour récupérer ces informations consiste à convertir la charge utile JSON de List Files en un format tabulaire à l'aide de la commande Array to CSV.  Ensuite, vous utiliserez la commande Tabular Transformation Smart Filter Rows pour isoler la ligne individuelle contenant les informations sur le fichier.  Vous pouvez ensuite utiliser la commande Tabular Transformation Extract Value pour extraire l'ID et l'état du fichier.  Pour les besoins de cet article, nous l'appellerons l'approche patrimoniale.   

Utilisation des filtres

L'entrée Filter permet de filtrer une réponse JSON non seulement en termes de champs (colonnes) à sélectionner, mais aussi en termes d'éléments (lignes) à extraire de la charge utile JSON.  Il s'agit d'un mécanisme puissant permettant de sélectionner les données spécifiques nécessaires, ce qui améliore l'efficacité du processus d'intégration.  Le filtre permet d'utiliser un ou plusieurs éléments dans la charge utile JSON pour limiter le nombre d'éléments (lignes) récupérés. 

Un critère de filtrage comporte trois éléments : le chemin de l'élément, la valeur de comparaison et un opérateur.  Les critères doivent aboutir à une valeur vraie ou fausse.  Lorsque les critères de filtrage renvoient une valeur vraie, l'enregistrement est extrait de la charge utile JSON conformément à la définition des colonnes de commande et créé en tant que ligne dans la sortie CSV résultante.  Par exemple :

• L'état du fichier est-il égal à "Staged" ?

Dans cet exemple, l'état du fichier est le chemin d'accès à l'élément, égal est l'opérateur et Staged est la valeur de comparaison.  Pour tout enregistrement dans la charge utile JSON où le statut du fichier est "Staged", une ligne est créée dans le CSV contenant les colonnes définies dans la configuration de la commande.  Dans cet exemple, il s'agit de l'ID, du nom et du statut.

Chemin des éléments

Pour spécifier un filtre, le chemin d'accès à l'élément doit être connu.  Par exemple, dans la réponse List Files, le chemin d'accès à l'élément Status est le suivant :

@.status

La valeur associée à l'élément est récupérée lors de l'exécution de la commande.  Dans l'exemple de charge utile ci-dessus, il s'agirait de la valeur IMPORTED pour l'élément status . 

Note : Le chemin d'un élément doit commencer par le symbole at (@).

Valeur de comparaison

La valeur de comparaison est la valeur à laquelle la valeur du chemin de l'élément est comparée.  La valeur de comparaison peut être une valeur statique définie dans la configuration de la commande ou utiliser une variable ou une valeur de sortie déterminée lors de l'exécution.  

Opérateur

L'opérateur détermine le type d'évaluation qui sera effectué pour filtrer les données. 

Note : Un espace est nécessaire entre le chemin de l'élément et l'opérateur ainsi que entre l'opérateur et la valeur de comparaison.

Opérateurs pris en charge

Il est important de prendre en compte le type de valeurs qui existent pour le chemin d'accès à l'élément lors de la spécification de l'opérateur.  Par exemple, l'utilisation de l'opérateur plus grand que (>) pourrait produire une sortie vide lors de l'évaluation d'un élément contenant des valeurs textuelles, car l'évaluation numérique d'une valeur textuelle est illogique.

Syntaxe des filtres et exemples de filtres

Tous les filtres doivent commencer par un point d'interrogation ( ?) et être contenus entre parenthèses.  

Critères uniques

Un critère unique de filtrage utilise la syntaxe suivante :

?(Element_Path Operator Comparison_Value)

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

Ce filtre renvoie tous les enregistrements dont l'élément name est égal à executions_2023-12.csv.

Critères multiples

Un filtre à critères multiples utilise la syntaxe suivante :

?(Element_Path Operator Comparison_Value Logical_Operator Element_Path Operator Comparison_Value)

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

Ce filtre renvoie tous les enregistrements dont le nom est executions_2023-12.csv et dont le statut est IMPORTED.

Exemple de configuration des commandes

Dans cet exemple, l'entrée Filter est configurée pour évaluer l'élément name dans la charge utile JSON.  Le filtre utilise des variables pour l'année et le mois qui, dans cet exemple, sont des valeurs d'entrée au moment de l'exécution.  Cela permet au filtre de tenir compte dynamiquement de l'année et du mois spécifiés lors de l'exécution de la chaîne.  

La valeur des filtres

Les filtres permettent de ne récupérer que les lignes nécessaires dans une réponse JSON.  Cela permet de réduire la taille du fichier de sortie généré par la commande, ce qui peut améliorer les performances de la chaîne. 

En outre, lorsque l'on tente d'isoler une seule ligne d'une réponse JSON, Dynamic Outputs peut être utilisé pour extraire ces valeurs spécifiques de la charge utile filtrée et les rendre disponibles pour une utilisation dans les nœuds suivants de la chaîne. 

Le schéma ci-dessous montre un exemple de définition de sortie dynamique.

La chaîne qui en résulte est plus rationnelle, un seul nœud (Array to CSV) effectuant les opérations de quatre nœuds requises par l'approche traditionnelle.  Cette chaîne rationalisée est également plus efficace puisque moins de commandes sont exécutées et que les sorties qui en résultent sont plus petites.