Centro de suporte da Workiva

Histórico

As cadeias interagem com uma variedade de sistemas de terceiros, bem como com a plataforma Workiva, aproveitando a API REST do sistema com o qual está se integrando.Muitas respostas da API REST estão no formato JSON, incluindo as várias APIs da Workiva .Embora uma resposta JSON possa ser bem documentada e estruturada de forma consistente, é difícil trabalhar com dados nesse formato.O comando Array para CSV no conector JSON é uma maneira útil de converter uma carga útil JSON em um formato tabular (linhas & colunas) para uso na plataforma Workiva. 

Neste artigo, exploraremos como usar os recursos de filtragem desse Command para retornar apenas os resultados necessários da carga útil JSON.Isso pode ser necessário porque uma resposta da API REST geralmente contém mais informações do que o necessário, pois a carga útil é geralmente determinada pelos desenvolvedores e os usuários finais do endpoint geralmente não têm a capacidade de limitar o escopo dos dados retornados. 

Por exemplo, o comando Listar arquivos do Workiva Connector usa o endpoint Recuperar uma lista de arquivos da API Workiva Wdata para retornar uma lista de todos os arquivos associados a uma tabela Wdata.A resposta JSON para esse endpoint contém as seguintes informações:

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

O comando Array para CSV nos permite selecionar apenas os campos que podemos recuperar da resposta JSON.Por exemplo, podemos optar por selecionar os campos id, name e status especificando-os na seção de entrada Colunas do Comando.O comando extrairá cada ID, nome e status de arquivo da resposta JSON e criará uma linha para cada arquivo na resposta JSON.  

Continuando com o exemplo da lista de arquivos acima, um caso de uso comum na plataforma Workiva é a necessidade de atualizar os dados (arquivo) em uma tabela Wdata.Para importar um conjunto de dados (arquivo) atualizado, o conjunto de dados existente precisa ser removido da tabela porque o Wdata não permite vários arquivos com o mesmo nome.Para excluir o arquivo existente, é necessário recuperar o ID e o status (Escondido provisoriamente ou Importado) do arquivo existente. 

Uma abordagem para recuperar essas informações é converter a carga útil JSON dos arquivos de lista em um formato tabular usando o comando Array para CSV.Em seguida, você usaria o comando Transformação tabular Linhas de filtro inteligente para isolar a linha individual com as informações do arquivo.Em seguida, você usaria o comando Transformação tabular Extrair valor para recuperar o ID e o Status do arquivo.Para fins deste artigo, chamaremos isso de abordagem legada.   

Uso de filtros

A entrada Filtrar permite que uma resposta JSON seja filtrada não apenas em termos dos campos (colunas) a serem selecionados, mas também de quais itens (linhas) serão recuperados da carga útil JSON.Esse é um mecanismo poderoso para selecionar os dados específicos necessários, o que melhora a eficiência do processo de integração.O filtro permite que um ou mais elementos em da carga útil JSON sejam usados para limitar o número de itens (linhas) recuperados. 

Um critério de filtro tem três componentes: caminho do elemento, valor de comparação e um operador.Os critérios devem resultar em um valor verdadeiro ou falso.Quando os critérios de filtro retornam um valor verdadeiro, o registro é extraído da carga útil JSON de acordo com a definição Colunas de Comando e criado como uma linha na saída CSV resultante.Por exemplo:

• O status do arquivo é igual a Escondido provisoriamente?

Neste exemplo, o status do arquivo é o caminho do elemento, igual é o operador e Escondido provisoriamente é o valor de comparação.Qualquer registro na carga útil JSON em que o status do arquivo seja Escondido provisoriamente, uma linha é criada no CSV contendo a definição de colunas na configuração Comando.Para este exemplo, eles são ID, nome e status.

Caminho do elemento

Para especificar um filtro, o caminho para o elemento deve ser conhecido.Por exemplo, na resposta Listar arquivos, o caminho para o elemento Status é:

@.status

O valor associado ao elemento é recuperado durante a execução do comando.No exemplo de carga útil acima, esse seria o valor IMPORTED para o elemento de status . 

Observação: Um caminho de elemento deve começar com o símbolo de arroba (@).

Valor de comparação

O valor de comparação é o valor com o qual o valor do caminho do elemento é comparado.O valor de comparação pode ser um valor estático definido na configuração do comando ou pode utilizar um valor de variável ou de saída determinado na execução.  

Operador

O operador determina o tipo de avaliação que será realizada para filtrar os dados. 

Observação: É necessário um espaço entre o caminho do elemento e o operador , bem como entre o operador e o valor de comparação.

Operadores suportados

É importante considerar o tipo de valores que existem para o caminho do elemento ao especificar o operador.Por exemplo, o uso do operador maior que (>) produziria potencialmente uma saída em branco ao avaliar um elemento que contém valores de texto, pois uma avaliação numérica de um valor de texto é ilógica.  

Sintaxe de filtro & Exemplo de filtros

Todos os filtros devem começar com um ponto de interrogação (?) e estar contidos entre parênteses.  

Critérios únicos

Um critério de filtro de critério único utiliza a seguinte sintaxe:

?(Element_Path Operator Comparison_Value)

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

Esse filtro retorna todos os registros em que o elemento name é igual a executions_2023-12.csv.

Critérios múltiplos

Um filtro de vários critérios utiliza a seguinte sintaxe:

?(Element_Path Operator Comparison_Value Logical_Operator Element_Path Operator Comparison_Value)

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

Esse filtro retorna todos os registros em que o elemento name é igual a executions_2023-12.csv e o elemento status é igual a IMPORTED.

Exemplo de configuração de comando

Neste exemplo, a entrada Filtrar está configurada para avaliar o elemento name no payload JSON.O filtro está usando variáveis para o ano e o mês que, neste exemplo, são valores de entrada de tempo de execução.Isso permite que o filtro contabilize dinamicamente o ano e o mês especificados quando a cadeia é executada.  

O valor dos filtros

Os filtros permitem que apenas as linhas necessárias sejam recuperadas de uma resposta JSON.Isso pode reduzir o tamanho do arquivo de saída gerado pelo comando, o que pode melhorar o desempenho da cadeia. 

Além disso, ao tentar isolar uma única linha de uma resposta JSON, o site Saídas dinâmicas pode ser usado para extrair esses valores específicos da carga filtrada e disponibilizá-los para uso nos nós subsequentes da cadeia. 

A figura abaixo mostra um exemplo de definições de Dynamic Saída.

A cadeia resultante é mais simplificada, com um único nó (matriz para CSV) executando as operações de quatro nós necessárias com uma abordagem herdada.Essa cadeia simplificada também tem um desempenho mais eficiente, pois menos comandos são executados e as saídas resultantes são menores.