Criar uma ação de fluxo de dados

Versão de lançamento: Xanadu

Atualizado 1 de ago. de 2024

10 min. de leitura

Crie uma ação reutilizável para processar um fluxo de dados de resposta em um fluxo.

Antes de Iniciar

Configure uma aplicação no Criador de aplicações assistido para armazenar conteúdo Workflow Studio.
Desabilite regras de negócio ou fluxos de trabalho conflitantes antes de criar uma ação.
Função necessária: action_designer ou administrador

Por Que e Quando Desempenhar Esta Tarefa

Criar uma aplicação personalizada para conter seu conteúdo Workflow Studio permite que você o implante usando o repositório de aplicações ou o ServiceNow Store.

Nota:

Limpar uma opção em uma página de configuração remove a etapa do contorno Fluxo de dados e exclui todos os dados associados à etapa.

Procedimento

Navegar até Todos > Flow Designer > Designer.
Clique na guia Ações e selecione Fluxo de dados.

Preencha as Propriedades da ação e clique em Enviar.


Campo	Descrição
Nome da ação	Insira um nome exclusivo para sua ação de fluxo de dados.
Descrição	Descrição da ação de fluxo de dados.
Aplicação	Escopo da aplicação da ação de fluxo de dados.
Domínio	Escopo do domínio da ação de fluxo de dados. Para obter mais informações sobre Domain Separation, consulte Domain separation explained.
Propriedades adicionais
Acessível de	Acessível de todas as aplicações com escopo ou somente dentro do escopo da aplicação especificado.
Categoria	Categoria definida no escopo da aplicação para uma ação. A partir da versão Xanadu, você pode criar uma categoria personalizada para organizar suas ações de fluxo de dados.
Proteção	Selecione se a ação de fluxo de dados é somente leitura. Você só pode selecionar um valor ao criar a ação de fluxo de dados em um escopo da aplicação que possui. O valor padrão é Nenhum.
Anotação de ação	Texto de ajuda que aparece abaixo do título da ação de fluxo de dados em Workflow Studio para ajudar os autores da ação de fluxo de dados a entender o que a ação de fluxo de dados faz quando usada em um fluxo.

Uma ação Fluxo de dados vazia é aberta.

Defina entradas de ação para disponibilizar dados para as etapas de ação.
1. Selecione + Criar entrada e preencha os campos.
  As entradas são representadas como cápsulas de dados no painel direito.
Para obter mais informações sobre entradas de ação, consulte Workflow Studio - Como criar ações personalizadas.
Clique em Pré- processamento de ação no contorno Fluxo de dados e configure as opções desejadas.
1. Selecione Recuperar informações de conexão para adicionar a etapa Obter informações de conexão como a primeira etapa no pré-processamento da ação.
  A etapa Obter informações de conexão permite que você recupere detalhes de conexão e credencial para usar em sua ação. Para obter mais informações, consulte Get Connection Info step.
2. Selecione Habilitar script de pré -processamento para executar um script de pré-processamento antes que a ação envie a solicitação de API inicial. Por exemplo, valide entradas de ação ou defina valores padrão. O pré-processamento é executado uma vez por ação, antes da primeira solicitação de API.
  
  A seleção desta opção adiciona uma etapa de script à ação Fluxo de dados. Para obter mais informações, consulte Script step.
  
  Importante:
  As ações de fluxo de dados exigem uma conexão constante com o fluxo de resposta. Eles não são compatíveis com scripts de pré-processamento que pausam a ação para chamar um MID Server ou pausam a ação para aguardar uma condição ou duração. Um script de pré-processamento que pausa a ação por qualquer motivo retorna uma mensagem de erro.
Clique em Solicitar no contorno Fluxo de dados e configure as opções desejadas.
1. No campo Como você obterá os dados, selecione Etapa REST , EtapaSOAPou Etapa JDBC para adicionar a etapa associada à ação Fluxo de dados.
  Para obter mais informações, consulte Etapa REST, Etapa SOAPe Etapa JDBC .
  
  Esta seção pode ser executada em MID Server ou na instância. O ambiente é determinado pelo campo Usar MID Server no registro de Conexão [sys_connection] associado.
  Nota:
  Se você estiver usando a etapa JDBC, deverá testá-la. Após a execução bem-sucedida, você pode usar o resultado para criar a saída da etapa e a saída da ação de fluxo de dados.
  
  Se você estiver usando a etapa REST ou a etapa SOAP, deverá criar manualmente a saída da ação de fluxo de dados.
2. Selecione Habilitar paginação para solicitar resulta em lotes. Depois que uma página de dados é processada, a ação Fluxo de dados executa a seção de solicitação novamente para retornar o próximo conjunto de resultados.. Esta opção adiciona uma etapa de configuração de paginação ao contorno Fluxo de dados.
  
  Nota:
  Para uma etapa JDBC, a paginação não é aplicável. Cada página pode recuperar até 1 GB de dados e uma solicitação pode recuperar até 8 GB de dados.
3. Selecione Executar um script antes de cada solicitação para executar um script antes de cada solicitação para a próxima página ao chamar uma API paginada.
  Por exemplo, grave um script para transformar tipos de dados variáveis da resposta inicial antes de enviar uma solicitação para a próxima página.
  
  A seleção desta opção adiciona uma etapa de script à ação Fluxo de dados. Para obter mais informações, consulte Script step.
  
  Nota:
  Para uma etapa JDBC, isso não é aplicável.
  
  Esta seção pode ser executada em MID Server ou na instância. O ambiente é determinado pelo campo Tempo de execução necessárioda etapa do script.
  
  Importante:
  Evite mudar várias vezes o ambiente de execução entre a instância e o MID Server. Por exemplo, você pode configurar a etapa Request Script para ser executada em MID Server, mas a etapa REST para ser executada na instância. Nesse caso, o sistema alterna os ambientes entre a instância e MID Server para cada página de dados, o que pode prejudicar o desempenho.
Opcional: Se a paginação estiver habilitada, configure a etapa Configuração de paginação.
Configure a etapa Configuração de paginação manualmente ou selecione um modelo pré-criado para aplicar configurações comuns. Por exemplo, aplique o modelo Limite/Deslocamento para especificar o número de itens que você deseja retornar por página (limite) e o número inicial do primeiro item (deslocamento). Depois de aplicar um modelo, atualize os valores para garantir que a configuração esteja em conformidade com os requisitos da API.
1. Criar variáveis de paginação.
  Por exemplo, se a API de terceiros usar um parâmetro de limite na solicitação, crie a variável de limite e defina o valor inicial para limitar o número de resultados por página. O valor inicial só é usado na primeira solicitação. getNextPage é uma variável reservada somente leitura. Contanto que a variável getNextPage seja verdadeira e a página anterior contenha dados, a ação continuará a enviar solicitações para a próxima página.
2. No campo Próximo valor de, defina como as variáveis de paginação recebem um valor para solicitações subsequentes.
  Escolha entre:
  - Script: grave um script de variáveis de paginação para definir como as variáveis são preenchidas. Variáveis de paginação só são compatíveis com o tipo de dados de cadeia de caracteres. Para executar operações matemáticas, você deve converter o valor em um número inteiro, executar todas as operações necessárias e convertê-lo novamente em uma cadeia de caracteres.
  - Corpo da resposta: use um valor na resposta da solicitação anterior para preencher a variável. Se a resposta for no formato JSON, defina Extrair valor usando como Expressão JSONPath e forneça o caminho para o valor no campo Expressão. Se a resposta estiver no formato XML, defina Extrair valor usando como Expressão XPath e forneça o caminho para o valor.
Neste exemplo, a variável getNextPage é verdadeira até que a variável nextOffset atinja o valor de contagem total retornado no cabeçalho de resposta da API. Contanto que a variável getNextPage seja verdadeira e a página anterior contenha dados, a ação continuará a enviar solicitações para a próxima página. Este exemplo inclui uma configuração de paginação de limite/compensação comum. As APIs de terceiros com as quais sua ação Fluxo de dados interage podem usar um token de página ou outro método.

Importante:
Evite loops infinitos em solicitações de paginação, criando uma condição que defina a variável getNextPage como falsa. Cancele todos os fluxos de longa execução. Sempre teste as ações Fluxo de dados antes de usá-las na produção.
Clique em Análise no contorno Fluxo de dados e configure as opções desejadas.

Nota:
Para uma etapa JDBC, isso não é aplicável.
1. No campo Como você identificará cada registro, selecione Divisor JSON/XML para adicionar uma etapa de Divisor ao contorno Fluxo de dados.
2. No campo Como você analisará cada item em um objeto, selecione Analisador de script para adicionar uma etapa de Analisador de script ao contorno de Fluxo de dados.
Configure a etapa Divisor.

Esta etapa identifica o nó primário no fluxo de resposta para mapear para um objeto complexo. Por exemplo, identifique um elemento de usuário em uma carga XML para criar um objeto complexo para cada usuário no fluxo de resposta.

Nota:
Para uma etapa JDBC, isso não é aplicável.
1. No campo Formato de origem, selecione o formato retornado pela seção Solicitação.
  - JSON: identifica objetos de um fluxo de dados JSON. Use uma expressão JSONPath para identificar uma matriz JSON que contém dados repetidos.
  - XML: identifica objetos de um fluxo de dados XML. Use uma expressão XPath para identificar um elemento XML que contém dados repetidos.
2. No campo Caminho do item, defina o caminho absoluto para o item no fluxo de dados que você deseja mapear para um objeto.
  
  JSON
  
  Identifique o caminho absoluto para uma matriz de objetos como uma expressão JSONPath. Por exemplo, use $.result para separar cada item em uma matriz de resultado JSON em um objeto de resultado.
  Nota:
  Se você selecionar uma matriz no nó raiz de um fluxo de dados JSON, o sistema exibirá o caminho absoluto como $.* em detalhes de execução e mensagens de erro.
  
  XML
  
  Identifique o caminho absoluto para um objeto de dados repetido como uma expressão XPath. Por exemplo, use /result para separar cada instância de um elemento XML de resultado em um objeto de resultado.
  Nota:
  A etapa Divisor ignora namespaces XML.
  Por exemplo, suponha que a etapa REST retorne um fluxo de dados JSON. O caminho do item $.response.result.companies retorna cada item na matriz de empresas.
```
{
  "response": {
    "result": {
      "companies": [
        {
          "name": "company1"
        },
        {
          "name": "company2"
        },
        {
          "name": "company3"
        }
      ],
      "metadata": {
        "token": 1558666526
      }
    }
  }
} 
```
  Por exemplo, suponha que a Etapa REST retorne um fluxo de dados XML. O caminho do item /response/result/companies/company retorna cada elemento da empresa dos dados XML.
```
<response>
  <result>
    <companies>
      <company>
        
      </company>
      <company>
        
      </company>
      <company>
        
      </company>
      <company>
        
      </company>
      <batch>10645C53D4BED73YQ</batch> 
    </companies>
    <metadata>
      <timestamp>1558666526</timestamp>
    </metadata>
  </result>
</response>
```
Na etapa Analisador de script, use as APIs JavaScript e ServiceNow para mapear itens no fluxo de resposta para uma saída de objeto complexo representada pelo objeto global targetObject.
Por exemplo, mapeie os elementos de registro de incidente identificados na etapa do divisor para um objeto complexo que contém campos de incidente. Se o fluxo de dados incluir irmãos do item identificado na etapa do divisor que você não deseja mapear para um objeto complexo, inclua condições para excluir esses itens.

Nota:
Para uma etapa JDBC, isso não é aplicável.
Você pode acessar as saídas das etapas anteriores na ação de fluxo de dados usando o objeto fd_data, excluindo:
- Saídas de corpo de resposta, fluxo ou mensagem de erro da etapa REST ou SOAP.
- Saídas da etapa do divisor.
Um script de exemplo que analisa uma resposta JSON.
```
(function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.id=record.number;
    outputs.targetObject.name=record.short_description;
})(inputs, outputs)
```
Um script de exemplo que analisa uma resposta XML.
```
(function parse(inputs, outputs) {
    var xmlDoc = new XMLDocument(inputs.sourceItem, false);
    outputs.targetObject.id = xmlDoc.getNodeText("/result/number");
    outputs.targetObject.name = xmlDoc.getNodeText("/result/short_description");
})(inputs, outputs)
```
Opcional: Se você selecionou a etapa JDBC, clique em Transformar.
Depois de testar com sucesso a etapa JDBC, clique em Usar resultado para criar a saída da etapa e a saída da ação de fluxo de dados. Você pode usar este resultado ou personalizá-lo usando o script de transformação.
1. Marque a caixa de seleção Habilitar script de transformação para transformar e personalizar a saída do fluxo de dados padrão.
Crie uma saída de objeto complexo.

Nota:
Para uma etapa JDBC, isso não é aplicável.
1. Selecione Saídas em Descrição da ação e clique em + para criar uma saída.
2. Atualize o campo Rótulo para representar o objeto.
  Por exemplo, se a ação analisar um fluxo de registros da empresa, adicione o rótulo Empresa.
3. Atualize o campo Tipo para Objeto.
  Esta é a saída de objeto complexo representada pelo objeto global targetObject na etapa Analisador de script.
4. Adicione campos secundários ao objeto complexo usando o ícone +.
5. Torne o nome de cada campo secundário mais amigável para que você possa se referir a ele de forma significativa no script.
  
  O valor no campo Nome é o nome interno usado na etapa Analisador de script. Por exemplo, para se referir à saída Cidade na etapa Analisador de script, você usaria outputs.targetObject.city.
  
  Aviso:
  Depois de salvar a ação Fluxo de dados, você não pode alterar os valores no campo Nome.
Clique em Salvar.
Workflow Studio salva um rascunho da ação.

O que Fazer Depois

Testar uma ação Fluxo de dados.