Fondo
Cadenas interactúa con diversos sistemas de terceros, así como con la plataforma Workiva, aprovechando la API REST del sistema con el que se está integrando. Muchas respuestas de las API REST están en formato JSON, incluidas las distintas API Workiva. Aunque una respuesta JSON puede estar bien documentada y estructurada de forma coherente, es difícil trabajar con datos en este formato. El comando Matriz a CSV del conector JSON es una forma útil de convertir una carga útil JSON en un formato tabular (filas y columnas) para utilizarlo dentro de la plataforma Workiva.
En este artículo exploramos cómo utilizar las capacidades de filtrado de este comando para devolver solo los resultados de la Carga útil JSON que se necesitan. Esto puede ser necesario porque la respuesta de una API REST suele contener más información de la necesaria, ya que la carga útil suele estar determinada por los desarrolladores y los usuarios finales del punto final no suelen tener la capacidad de limitar el alcance de los datos devueltos.
Como ejemplo, el comando List Files del Conector Workiva utiliza el punto final Retrieve a List of Files de la API Workiva Wdata para devolver una lista de todos los archivos asociados a una tabla Wdata. La respuesta JSON para este punto de conexión contiene la siguiente información:
[
{
"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
}
]
El comando Matriz a CSV nos permite seleccionar solo los campos que podemos recuperar de la respuesta JSON. Por ejemplo, podemos elegir seleccionar los campos id, nombre, y estado especificándolos en la sección Introducir columnas del Comando. El comando extraerá cada ID del archivo, Nombre y Estado de la respuesta JSON y creará una fila para cada archivo en la respuesta JSON.
Siguiendo con el ejemplo de los Archivos de Listas anterior, un caso de uso común dentro de la plataforma Workiva es la necesidad de actualizar los datos (archivo) de una tabla de Wdata. Para importar un conjunto de datos actualizado (archivo), es necesario eliminar el conjunto de datos existente de la tabla, ya que Wdata no permite varios archivos con el mismo nombre. Para llevar a cabo una eliminación del archivo existente, es necesario recuperar el ID y el estado (Preparado o Importado) del archivo existente.
Un enfoque para recuperar esta información es convertir la carga útil JSON de los archivos de listas a un formato tabular utilizando el comando Matriz a CSV. A continuación, utilizarías el comando de transformación tabular Filtrado inteligente de filas para aislar la fila individual con la información del archivo. A continuación, utilizarías el comando de transformación tabular Extraer valor para recuperar el ID del archivo y el Estado. A efectos de este artículo, lo llamaremos el enfoque heredado.
Utilizar filtros
La Entrada Filtrar permite filtrar una respuesta JSON no sólo en función de los campos (columnas) que se seleccionen, sino también de los elementos (filas) que se recuperarán de la carga útil JSON. Se trata de un potente mecanismo para seleccionar los datos específicos necesarios, lo que mejora la eficacia del proceso de integración. El Filtrar permite utilizar uno o varios elementos en la carga útil JSON para limitar el número de elementos (filas) recuperados.
Un criterio de filtrado tiene 3 componentes: la ruta del elemento, el valor de comparación y un operador. Los criterios deben resolverse con un valor verdadero o falso. Cuando los criterios de filtrado devuelven un valor verdadero, el registro se extrae de la carga útil JSON de acuerdo con la definición de Columnas de comandos y se crea como una fila en la salida CSV resultante. Por ejemplo:
- ¿El archivo está en el estado de oculto provisionalmente?
En este ejemplo, el Estado del archivo es la ruta del elemento, Igual es el operador y Oculto es el Valor de comparación. En cualquier registro de la carga útil JSON en el que el estado del archivo sea Tramitado, se crea una fila en el CSV que contiene la definición de las columnas en la configuración de Comandos. En este ejemplo son ID, nombre y estado.
Ruta del elemento
Para especificar un filtro, debe conocerse la ruta de acceso al elemento. Por ejemplo, en la respuesta Archivos de lista, la ruta al elemento Estado es:
@.status
El valor asociado al elemento se recupera durante la ejecución del comando. En el ejemplo de carga útil anterior, éste sería el valor IMPORTADO para el elemento estado .
Nota: La ruta de un elemento debe comenzar el en (@) símbolo.
Valor de comparación
El Valor de comparación es el valor con el que se compara el valor de la Ruta del elemento. El Valor de Comparación puede ser un valor estático definido en la configuración del comando o puede utilizar un valor de Variable o de Salida que se determina en la ejecución.
Operador
El operador determina el tipo de evaluación que se realizará para filtrar los datos.
Nota: Se necesita un espacio entre la ruta del elemento y el operador , así como entre el operador y el valor de comparación.
Operadores soportados
| Tipo de operador | Operador | Utiliza |
| Numérico | < | Evalúa si el valor del elemento es menor que el valor de comparación |
| Numérico | <= | Evalúa si el valor del elemento es menor o igual que el valor de comparación |
| Numérico | > | Evalúa si el valor del elemento es mayor que el valor de comparación |
| Numérico | >= | Evalúa si el valor del elemento es mayor o igual que el valor de comparación |
| Lógico / Texto | == |
Evalúa si el valor del elemento es igual (idéntico) al valor de comparación. El valor de evaluación debe ir entre comillas dobles ("") y DISTINGUE ENTRE MAYÚSCULAS Y MINÚSCULAS. Los comodines NO son compatibles. |
| Lógico / Texto | != |
Evalúa si el valor del elemento es no es igual a al valor de comparación. El valor de evaluación debe ir entre comillas dobles ("") y DISTINGUE ENTRE MAYÚSCULAS Y MINÚSCULAS. Los comodines NO son compatibles. |
| Lógico / Texto | && | El operador AND que permite evaluar múltiples rutas de filtrado y/o criterios. El uso de este operador solo devuelve los Registros en los que todas las condiciones se evalúan como verdaderas. |
| Lógico / Texto | || | El operador OR que permite evaluar múltiples rutas de filtrado y/o criterios. El uso de este operador devuelve cualquiera de los Registros en los que una o más de las condiciones se evalúan como verdaderas. |
Es importante tener en cuenta el tipo de valores que existen para la ruta del elemento al especificar el operador. Por ejemplo, el uso del operador mayor que (>) produciría potencialmente un resultado en blanco al evaluar un elemento que contiene valores de texto, ya que una evaluación numérica de un valor de texto es ilógica.
Filtrar sintaxis y filtros de ejemplo
Todos los filtros deben comenzar con un signo de interrogación (?) y estar contenidos entre paréntesis.
Criterio único
Un único criterio de filtrado utiliza la siguiente sintaxis:
?(Ruta_del_elemento Operador Valor_de_comparación)
?(@.name == "executions_2023-12.csv")
Este filtro devuelve todos los registros en los que el elemento de nombre es igual a executions_2023-12.csv.
Criterios múltiples
Un filtro de criterios múltiples utiliza la siguiente sintaxis:
?(Ruta_de_elemento Operador Valor_de_comparación Operador_lógico Ruta_de_elemento Operador Valor_de_comparación)
?(@.name == "executions_2023-12.csv" && @.status == "IMPORTADO")
Este filtro devuelve todos los registros en los que el elemento de nombre es igual a executions_2023-12.csv y el elemento de estado es igual a IMPORTADO.
Ejemplo de configuración de comandos
En este ejemplo, la entrada Filtrar está configurada para evaluar el elemento name de la Carga útil JSON. El Filtrar está utilizando Variables para el Año y el Mes, que en este ejemplo son valores de Entrada en tiempo de ejecución. Esto permite que el filtro contabilice dinámicamente el año y el mes especificados cuando se ejecuta la Cadena.
El valor de los filtros
Los filtros solo permiten recuperar las filas necesarias desde una respuesta JSON. Esto puede reducir el tamaño del archivo de Salida generado por el Comando, lo que puede mejorar el rendimiento de la Cadena.
Además, cuando se intenta aislar una sola fila de una respuesta JSON, se puede utilizar Dynamic Outputs para extraer esos valores específicos de la carga útil filtrada y ponerlos a disposición para su uso en los nodos posteriores de la Cadena.
A continuación se muestra un ejemplo de definiciones de Resultado dinámico.
La Cadena resultante es más ágil, con un único nodo (Matriz a CSV) que realiza las operaciones de cuatro nodos necesarias con un enfoque heredado. Esta Cadena simplificada también funciona de forma más eficiente, ya que se ejecutan menos Comandos y los Resultados resultantes son más pequeños.