Criar uma ação de fluxo de dados para obter a atividade do usuário

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 9 min. de leitura

    • Crie uma ação de fluxo de dados para obter a atividade do usuário de uma aplicação SaaS.

    Antes de Iniciar

    Se você estiver usando um spoke ServiceNow® IntegrationHub existente, descubra se ele tem uma ação de fluxo de dados para obter a atividade do usuário que você pode usar em vez de criar uma.

    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

    Por Que e Quando Desempenhar Esta Tarefa

    Monitore a atividade do usuário para encontrar assinaturas de software que sua empresa está comprando, mas que não estão sendo usadas. Você pode recuperar essas assinaturas não utilizadas para reduzir as despesas de software da sua empresa.

    Antes de criar a ação de fluxo de dados, decida como você deseja definir uma atividade de usuário significativa. A atividade significativa pode ser uma combinação de ações do usuário. Crie uma ação de fluxo de dados separada para cada métrica de atividade do usuário. Por exemplo, a integração do sistema de base Webex Meetings define uma atividade significativa como hospedar uma reunião. Ele usa uma ação de fluxo de dados para obter as datas das reuniões hospedadas mais recentemente para todos os usuários. Se você também quiser que a integração Webex Meetings inclua o login como atividade significativa, crie uma segunda ação de fluxo de dados para obter os horários de login mais recentes de todos os usuários.

    Sua ação de fluxo de dados para obter usuários pode retornar uma métrica de atividade do usuário, como a hora do último login. Nesse caso, você não precisa criar uma ação de fluxo de dados para obter a atividade do usuário ou um subfluxo para obter a atividade do usuário, a menos que queira definir métricas de atividade do usuário adicionais. Certifique-se de que o subfluxo para obter usuários defina esta métrica de atividade do usuário como a última entrada de atividade na ação Assinatura do usuário de upsert.

    Procedimento

    1. Navegar até Todos > Flow Designer > Designer.
    2. Clique em Novo e selecione Fluxo de dados.
    3. No formulário, preencha os campos.
      Tabela 1. Formulário Propriedades da ação
      Campo Valor
      Nome Nome à sua escolha. Por exemplo, Obter atividade do usuário.
      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 de spoke pode ser um spoke IntegrationHub existente ou um novo spoke que você criou.
      Anotação de fluxo Deixe este campo em branco.
      Descrição Descrição de sua escolha.
    4. Clique em Enviar.
    5. Na seção Entradas do Contorno da ação, clique em Criar entrada.
    6. Adicione uma entrada de tempo de retrospectiva.
      Tabela 2. Entradas
      Rótulo Nome Tipo Obrigatório
      Hora de reversão look_back_time Data/Hora Sim
    7. Se a API com a qual você está trabalhando requer autenticação de usuário para solicitações, adicione entradas para autenticação.
      Exemplos de entradas de autenticação de usuário comuns são o ID do usuário do administrador e o nome do site. Consulte a documentação da API escolhida para saber mais sobre os requisitos de autenticação do usuário no seu caso específico. Se a API exigir um token de acesso, uma variável de valor de credencial será criada automaticamente mais tarde. 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.

    8. Clique em Solicitar no Contorno da ação.
    9. No formulário, preencha os campos.
      Tabela 3. 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.
    10. Clique na etapa Configuração de paginação no Contorno da ação.
    11. Defina variáveis de paginação com base nos parâmetros de consulta usados pela API de SaaS.

      Se você estiver usando a paginação baseada em deslocamento, use o modelo de paginação Limitar/deslocar 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.
    12. 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 concluído da etapa de configuração de paginação. Este exemplo é da ação de fluxo de dados Obter usuários usada no subfluxo Webex Baixar assinaturas.

      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, converta o valor em um número inteiro, execute as operações necessárias e converta-o novamente em uma cadeia de caracteres.
    13. Clique na etapa SOAP ou na etapa REST no Contorno da ação, dependendo da opção selecionada para obter os dados.
    14. Se você selecionou SOAP, preencha o formulário conforme mostrado.
      Tabela 4. 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. Ele é definido como o URL de conexão do registro de conexão HTTP(s) vinculado ao alias.
      Detalhes da solicitação
      Criar os Envelopes Manualmente.
      Ações de SOAP Solicitação de API para obter uma lista de atividades significativas do usuário. Por exemplo, a integração do sistema de base Webex Meetings define a atividade significativa do usuário como hospedar uma reunião para que ele use a solicitação LstsummaryMeeting para obter uma lista de todas as reuniões. 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 escrever uma mensagem de solicitação XML. Em geral, o cabeçalho deve ter suas variáveis de entrada para autenticação do 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 atividades significativas do usuário, uma data de início definida como a entrada de tempo de retrospectiva 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 atividade do usuário usada no subfluxo Atualizar atividade do usuário Webex.
    15. Se você selecionou REST, preencha o formulário conforme mostrado.
      Tabela 5. 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. Ele é definido como o 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 OBTER.
      Parâmetros de Consulta Adicione parâmetros para paginação. Defina os valores como as variáveis que você criou na etapa Configuração de paginação.
      Adicione outro parâmetro para a data de início para que a solicitação retorne resultados da data de início até a data atual. Defina o valor como a entrada Tempo de retrospectiva.
      Nota:
      Certifique-se de que a variável de data/hora de entrada de tempo de retrospectiva esteja formatada corretamente para a API com a qual você está trabalhando. Se você precisar reformatar ou converter para outro tipo de dados, como uma cadeia de caracteres, poderá fazer isso na etapa de script de pré-processamento da ação.

      A imagem a seguir mostra um exemplo concluído da etapa REST. Este exemplo é da ação de fluxo de dados Obter log de auditoria usada no subfluxo Atualizar atividade do usuário Jira.

      Etapa REST
    16. Clique em Analisar no Contorno da ação.
    17. No formulário, preencha os campos.
      Tabela 6. Analisando formulário
      Campo Valor
      Como você identificará cada registro Divisor de JSON/XML
      Como você analisará cada item em um objeto Analisador de Script
    18. Clique na etapa Divisor no Contorno da ação.
    19. No formulário, preencha os campos.
      Tabela 7. Formulário de etapa do divisor
      Campo Valor
      Formatos de Origem Selecione XML ou JSON, dependendo do formato retornado pela resposta da API.
      Caminhos do Item Caminho absoluto para um elemento de atividade significativo 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/meeting
      • Exemplo de caminho de item JSON: $.data.meeting
    20. Clique em Saídas no Contorno da ação.
    21. Clique em Criar saída e edite a variável conforme mostrado.
      Tabela 8. Ação de saída
      Rótulo Nome Tipo Obrigatório
      targetObject targetObject Objeto Não
    22. Adicione itens secundários para targetObject para armazenar o e-mail do usuário e a data da atividade significativa.
      Por exemplo, uma resposta XML pode ser semelhante a esta.
      <message>​
  <body>​
    <meeting>
      <meetingID>​12345</meetingID>​
      <startDate>​08/13/2019 20:08:16</startDate>​
      <hostEmail>​email@email.com</hostEmail>​
    </meeting>​
    <meeting>
      ...
    </meeting>
  </body>​
</message>
      Para esta resposta, adicione os itens secundários conforme mostrado.
      Tabela 9. Itens secundários para targetObject
      Rótulo Nome Tipo Obrigatório
      e-mail e-mail Cadeia de caracteres Não
      last_activity last_activity Cadeia de caracteres Não
    23. No Contorno da ação, clique na etapa Analisador de script.
    24. Crie um objeto de saída targetObject para cada elemento de atividade significativo na resposta e mapeie cada data de atividade e e-mail do usuário para os itens secundários targetObject.

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

      Nota:
      Esses exemplos mostram os tipos de elementos que podem estar contidos em uma resposta. Não copie diretamente esses scripts. Use nomes de elemento da documentação da API com a qual você está trabalhando.
      Script de exemplo que analisa uma resposta XML. 
      (function parse(inputs, outputs) {
    var xmlDoc = new XMLDocument(inputs.sourceItem, false);
    outputs.targetObject.email = xmlDoc.getNodeText('/meeting/hostEmail');
    outputs.targetObject.last_activity = xmlDoc.getNodeText('/meeting/startDate');
})(inputs, outputs)
      Script de exemplo que analisa uma resposta JSON. 
      (function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.email = record.hostEmail;
    outputs.targetObject.last_activity = record.startDate;
})(inputs, outputs)
    25. Para testar sua ação de fluxo de dados, clique em Testar.
      1. Exiba os resultados do teste e os logs do sistema para obter detalhes sobre erros.
        Para exibir os logs do sistema, navegue até Logs do sistema > Log do Sistema > Todos.
      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 de API estão estruturadas conforme o esperado.
    26. Depois de verificar se a ação de fluxo de dados está funcionando conforme o esperado, clique em Publicar.