Criar uma ação de fluxo de dados para obter usuários

  • Versão de lançamento: Yokohama
  • Atualizado 30 de jan. de 2025
  • 7 min. de leitura

    • Crie uma ação de fluxo de dados para obter uma lista de assinaturas de usuário da aplicação SaaS.

    Antes de Iniciar

    Se você estiver usando um spoke ServiceNow® Integration Hub existente, descubra se ele tem uma ação de fluxo de dados para obter uma lista de usuários que você pode usar em vez de criar um. Para obter mais informações sobre ações de fluxo de dados, consulte Ações de fluxo de dados.

    Função necessária: flow_designer ou administrador

    Procedimento

    1. Navegar até Tudo > Flow Designer > Designer.
    2. Selecione Novo.
    3. Selecione Fluxo de dados.
    4. No formulário, preencha os campos.
      Tabela 1. Formulário Propriedades da ação
      Campo Valor
      Nome Nome de sua escolha.

      Por exemplo, Obter usuários.
      Acessível de Todos os escopos da aplicação.
      Categoria Deixe este campo em branco.
      Proteção Nenhum.
      Aplicação App Spoke para integração com a aplicação SaaS.

      Este app spoke pode ser um spoke Integration Hub existente ou um novo spoke que você criou.
      Anotação em fluxo Deixe este campo em branco.
      Descrição Descrição de sua escolha.
    5. Selecione Enviar.
    6. Se a API com a qual você está trabalhando exigir autenticação de usuário para solicitações, selecione Entradas em Descrição da ação e adicione entradas para autenticação.
      Exemplos de entradas comuns de autenticação de usuário são ID de usuário administrador e nome do site. Consulte a documentação da API escolhida para saber mais sobre os requisitos de autenticação de usuário em seu caso específico. Se a API exigir um token de acesso, uma variável Valor de credencial será criada automaticamente posteriormente. Você não precisa adicionar um token de acesso como entrada.

      Ao usar a ação de fluxo de dados concluída em um subfluxo, você define quais valores serão passados como essas entradas.

    7. Selecione Solicitar em Descrição da ação.
    8. No formulário, preencha os campos.
      Tabela 2. Formulário de solicitação
      Campo Valor
      Como você obterá dados Escolha a Etapa REST ou a Etapa SOAP.

      Sua escolha depende da API da aplicação SaaS com a qual você está integrando.
      Habilitar paginação Selecionado.
      Execute um script antes de cada solicitação Não selecionado.
    9. Selecione a etapa Configuração de paginação em Descrição da ação.
    10. Defina variáveis de paginação com base nos parâmetros de consulta usados pela API SaaS.

      Se você estiver usando a paginação baseada em deslocamento, use o modelo de paginação Limitar/Deslocamento para pré-carregar a configuração de paginação.

      Nota:
      O valor da variável getNextPage reservada determina se outra página de resultados deve ser solicitada. Contanto que a variável getNextPage seja verdadeira, a ação continuará a enviar solicitações para a próxima página.
    11. Grave um script de Variáveis de paginação para atualizar as variáveis de paginação.

      O script é executado em cada solicitação. Se você estiver usando um modelo de paginação, ajuste o script pré-carregado conforme necessário.

      A imagem a seguir mostra um exemplo da conclusão da etapa de configuração de paginação. Este exemplo é da ação de fluxo de dados Obter usuários usada no subfluxo Webex de assinaturas de download.

      Etapa de configuração de paginação
      Nota:
      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.
    12. Selecione a etapa SOAP ou a etapa REST em Descrição da ação para receber dados.
      • Se você selecionou a etapa SOAP, preencha os detalhes.
        Tabela 3. Formulário de etapa SOAP
        Campo Valor
        Detalhes da Conexão
        Conexão Usar alias de conexão.
        Alias de conexão Alias de conexão que você criou ao criar o perfil de integração. Se você ainda não criou um perfil de integração, siga as etapas para criar um perfil de integração personalizado com um alias de conexão.
        Endpoint Este valor é preenchido automaticamente quando você seleciona o alias de conexão.

        Este valor é definido como a URL de conexão do registro de conexão HTTPs vinculado ao alias.
        Detalhes da solicitação
        Criar os Envelopes Manualmente.
        Ações de SOAP Solicitação de API para obter uma lista de todos os usuários. Consulte a documentação da API escolhida para selecionar a solicitação apropriada.
        Envelopes de SOAP Mensagem de solicitação XML para obter uma lista de todos os usuários. Consulte a documentação da API escolhida para saber como gravar uma mensagem de solicitação XML. Em geral, o cabeçalho deve ter suas variáveis de entrada para autenticação de usuário, bem como a variável Valor de credencial como o token de acesso. O corpo deve incluir a solicitação para obter uma lista de todos os usuários e suas variáveis da etapa de configuração de paginação.
        Nota:
        Para obter um exemplo de um envelope SOAP, consulte a ação de fluxo de dados Obter usuários usada no subfluxo Webex Assinaturas de download.
      • Se você selecionou etapa REST, preencha os detalhes.
        Tabela 4. Formulário de etapa REST
        Campo Valor
        Detalhes da Conexão
        Conexão Usar alias de conexão.
        Alias de conexão Alias de conexão que você criou ao criar o perfil de integração. Se você ainda não criou um perfil de integração, siga as etapas para criar um perfil de integração personalizado com um alias de conexão.
        URL base Este valor é preenchido automaticamente quando você seleciona o alias de conexão. É definido como a URL de conexão do registro de conexão HTTP(s) vinculado ao alias.
        Detalhes da solicitação
        Criar solicitação Manualmente.
        Caminho do recurso Caminho para o recurso. Este valor é anexado ao URL base. Consulte a documentação da API com a qual você está trabalhando para saber como construir o caminho do recurso.
        Método HTTP GET.
        Parâmetros de Consulta Adicione parâmetros para paginação. Defina os valores como as variáveis que você criou na etapa de configuração de paginação.

        A imagem a seguir mostra um exemplo concluído da etapa REST. Este exemplo é da ação de fluxo de dados Obter Jira Usuários usada no subfluxo Jira Assinaturas de download.

        Etapa REST
    13. Selecione Análise em Descrição da ação.
    14. No formulário, preencha os campos.
      Tabela 5. Formulário de análise
      Campo Valor
      Como você identificará cada registro Divisor de JSON/XML
      Como você analisará cada item em um objeto Analisador de Script
    15. Selecione a etapa Divisor em Descrição da ação.
    16. No formulário, preencha os campos.
      Tabela 6. Etapa do divisor
      Campo Valor
      Formato de Origem Selecione XML ou JSON, dependendo do formato retornado pela resposta da API.
      Caminhos do Item Caminho absoluto para um elemento de usuário na mensagem de resposta. Consulte a documentação da API com a qual você está trabalhando para obter informações sobre o formato da mensagem de resposta.
      • Exemplo de caminho de item XML: /message/body/user
      • Exemplo de caminho de item JSON: $.data.user
    17. Selecione Saídas em Descrição da ação.
    18. Selecione Criar saída e edite a variável conforme mostrado.
      Tabela 7. Ação de saída
      Rótulo Nome Tipo Necessário
      targetObject targetObject Objeto Não
    19. Adicione itens secundários para targetObject com base nos elementos secundários de usuário retornados na mensagem de resposta.
      Por exemplo, uma resposta XML pode ser semelhante a esta.
      <message>​
  <body>​
    <user>
      <userID>​12345</userID>​
      ​<email>​email@email.com</email>​
      <firstName>​Jane</firstName>​
      <lastName>​Doe</lastName>​
      <lastLoginTime>​08/13/2019 20:08:16</lastLoginTime>​
      <active>​TRUE</active>​
    </user>​
    <user>
      ...
    </user>
  </body>​
</message>
      Para esta resposta, adicione os itens secundários conforme mostrado.
      Tabela 8. Itens secundários para targetObject
      Rótulo Nome Tipo Necessário
      userID userID Cadeia de caracteres Não
      e-mail e-mail Cadeia de caracteres Não
      nome nome Cadeia de caracteres Não
      sobrenome sobrenome Cadeia de caracteres Não
      lastLoginTime lastLoginTime Cadeia de caracteres Não
      ativo ativo Verdadeiro/falso Não
    20. Selecione a etapa Analisador de script em Descrição da ação.
    21. Crie um objeto de saída targetObject para cada elemento de usuário na resposta e mapeie cada elemento secundário de usuário para um item secundário de targetObject.

      O script do analisador é executado para cada elemento de usuário.

      Nota:
      Esses exemplos mostram os tipos de elementos que geralmente estão contidos em uma resposta a uma solicitação de obtenção de usuários. Não copie diretamente esses scripts. Use nomes de elemento da documentação da API com a qual você está trabalhando.
      Exemplo de script que analisa uma resposta XML. 
      (function parse(inputs, outputs) {
    var xmlDoc = new XMLDocument(inputs.sourceItem, false);
    outputs.targetObject.userID = xmlDoc.getNodeText('/user/userID');
    outputs.targetObject.email = xmlDoc.getNodeText('/user/email');
    outputs.targetObject.firstName = xmlDoc.getNodeText('/user/firstName');
    outputs.targetObject.lastName = xmlDoc.getNodeText('/user/lastName');
    outputs.targetObject.lastLoginTime = xmlDoc.getNodeText('/user/lastLoginTime');
    outputs.targetObject.active = xmlDoc.getNodeText('/user/active');
})(inputs, outputs)
      Exemplo de script que analisa uma resposta JSON. 
      (function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.userID = record.userID;
    outputs.targetObject.email = record.email;
    outputs.targetObject.firstName = record.firstName;
    outputs.targetObject.lastName = record.lastName;
    outputs.targetObject.lastLoginTime = record.lastLoginTime;
    outputs.targetObject.active = record.active;
})(inputs, outputs)
    22. Para testar sua ação de fluxo de dados, selecione Testar.
      1. Veja os resultados de testes e os logs do sistema para obter detalhes sobre erros.
        Para exibir logs do sistema, navegue até Logs do sistema > Log do Sistema > Tudo.
      2. Se a ação de fluxo de dados tiver erros, verifique se você está usando os endpoints corretos e se as solicitações e respostas da API estão estruturadas conforme o esperado.
    23. Depois de verificar se a ação de fluxo de dados está funcionando conforme o esperado, selecione Publicar.

    O que Fazer Depois

    Criar um subfluxo para obter usuários.