Webhooks são métodos extensamente suportados utilizados para permitir a múltiplos aplicativos interagir uns com os outros, utilizando pedidos de HTTP POST para passar retornos de chamadas entre eles. Para mais informações, consulte a Página da Wikipedia sobre webhooks. Os usos comuns para webhooks incluem enviar notificações via e-mail ou SMS, postando mensagens em rede social, gravando registros automaticamente em uma planilha e atualizando bancos de dados enterprise.
No ArcGIS Survey123, os webhooks podem ser instalados e ativados quando uma resposta de pesquisa for enviada. Por exemplo, após um envio bem sucedido de informações para a camada de feição, o webhook pode ser solicitado e ativar outra ação, como enviar um e-mail de notificação, anexar o conteúdo de pesquisa a uma planilha e enviar um alerta.
Seu local de trabalho pode ter seu próprio provedor de webhook, mas vários serviços de fluxo de trabalho de terceiros estão disponíveis, como Microsoft Power Automate, Make (anteriormente Integromat), Zapier e tray.io. Todos estes podem ser utilizados para incorporar Survey123 como um gatilho para um processo automatizado. Em particular, Microsoft Power Automate e Make tem um conector do Survey123 embutido, permitindo a você integrar Survey123 no fluxo de trabalho do webhook com o mínimo de dificuldade e sem a necessidade de configurar o webhook no site Survey123 ou inserir uma URL de carga útil.
Aviso:
Quando você cria ou modifica um webhook para uma pesquisa, a pesquisa deve ser atualizada no aplicativo de campo Survey123 para que as alterações tenham efeito.
Há várias maneiras de usar o Survey123 como um gatilho em seus fluxos de trabalho. As três seções a seguir demonstram como configurar um webhook para enviar um e-mail de notificação quando uma resposta for enviada contendo uma pergunta respondida com um determinado valor.
No final deste tópico, todas as propriedades disponíveis na carga útil do evento do webhook são listadas para referência.
Configurar um webhook no Make
Make (anteriormente Integromat) é uma plataforma de automação online. Registre-se para uma conta gratuita para começar. O Make tem modelos para usar como ponto de partida para incluir anexos em suas notificações de e-mail, adicionar registros a planilhas e criar itens de calendário.
- Vá para https://www.make.com/ e registre-se.
- Na página Cenários, clique no botão Criar um novo cenário.
- Clique no ícone do módulo no meio da tela. Procure por Survey123 e selecione-o.
- Escolha o módulo de ativação Assistir à pesquisa .
Este módulo foi projetado para executar o cenário toda vez que uma resposta de pesquisa é enviada.
Um pop-up aparece para ajudá-lo a configurar o módulo Assistir à pesquisa.
Dica:
O módulo Criar relatório pode ser utilizado para gerar um relatório para uma resposta da pesquisa.
- Clique em Adicionar e insira um nome para o seu webhook.
Este nome deve ser único para a pesquisa na qual você está configurando o webhook.
- Se esta é a primeira vez que usa o módulo Survey123 no Make, configure uma conexão para sua organização do ArcGIS. Você precisa fazer isto somente uma vez, já que o Make salvará suas informações para uso futuro. Em Conexão, clique em Adicionar e nomeie a conexão para o ArcGIS.
- Para conectar ao ArcGIS Online, clique em Salvar para entrar na sua organização do ArcGIS.
- Para conectar ao ArcGIS Enterprise, registre o Make com seu portal. Para mais informações, consulte a postagem do blog Tricks of the Trade do Survey123: Make.
- Escolha uma pesquisa da sua organização do ArcGIS para se conectar.
- Considere as opções para incluir no seu webhook e clique em Salvar.
Manter o valor padrão de Sim é recomendado para todas as configurações avançadas, oferecendo mais flexibilidade ao personalizar seu webhook.
- Clique em OK.
Seu webhook é criado e o módulo Assistir à pesquisa é configurado.
- Clique no botão Adicionar outro módulo no lado direito do módulo Assistir à pesquisa para conectar outro módulo a ele.
- Procure por E-mail e selecionar o módulo E-mail.
- Selecione a ação Enviar um e-mail.
- Se esta for sua primeira vez utilizando este módulo no Make, clique em Adicionar para instalar uma conexão para sua conta de e-mail. Selecione um tipo de conexão e entre em sua conta.
Você precisa fazer isto somente uma vez, já que o Make salvará sua conexão para uso futuro.
- Adicione um endereço de e-mail do destinatário.
Este é o endereço de e-mail para o qual o e-mail ativado será enviado.
- Clique na caixa de texto do assunto. Escolha os campos da sua pesquisa para construir o assunto do seu e-mail usando o painel de configurações do módulo que aparece.
- Clique na caixa de texto do conteúdo. Escolha os campos da sua pesquisa para construir o conteúdo do seu e-mail usando o painel de configurações do módulo que aparece. Você pode formatar o conteúdo usando HTML.
- Clique em OK.
Este cenário precisa enviar o e-mail quando uma pergunta for respondida de uma determinada maneira, então você fornecerá um filtro.
- Clique no botão de ferramentas entre os dois módulos e selecione Configurar um filtro.
- Clique na caixa de texto Condição e escolha o campo da sua pesquisa que você deseja utilizar no filtro.
- Escolha o operador para a condição. Neste caso, escolha o padrão Igual a.
- Insira um valor para a condição e clique em OK.
- Clique em Salvar para salvar seu cenário.
Opcionalmente, você pode clicar em Executar uma vez para testar seu webhook. Depois de clicar em Executar uma vez, abra Survey123 e envie uma pesquisa, garantindo que a resposta da pesquisa satisfaça a condição do filtro. Confirme se o destinatário recebe o e-mail.
- Use o botão de alternar na parte inferior esquerda da página para ativar seu cenário. Defina a programação como Imediatamente para garantir que o cenário seja executado sempre que uma resposta da pesquisa for enviada
Para saber mais maneiras de utilizar o Survey123 como um ativador em seus cenários Make, consulte as integrações do Survey123 .
Configurar um webhook no Microsoft Power Automate
Microsoft Power Automate é um serviço de webhook fornecido na plataforma Microsoft Office 365.
Anotação:
As credenciais do ArcGIS Online usadas para criar fluxos do Power Automate serão desconectadas automaticamente após duas semanas. Se você não conseguir navegar pelas pesquisas esperadas no Power Automate, verifique se sua conexão de dados do Survey123 está ativa. Para mais informações, consulte o artigo da base de conhecimento, A lista suspensa não exibe pesquisas.
As etapas a seguir descrevem como configurar um fluxo usando o conector do Survey123 embutido para pesquisas publicadas no ArcGIS Online. Para utilizar o Power Automate com pesquisas publicadas no ArcGIS Enterprise, você precisará configurar um conector personalizado. Para obter mais informações, consulte o artigo de base de conhecimento Instrução: Criar um conector ArcGIS Survey123 para Microsoft Power Automate para uso com ArcGIS Enterprise.
- Abra o Microsoft Power Automate.
- Selecione Criar a partir do menu lateral da página.
- Selecione Fluxo de nuvem automatizado a partir das opções Iniciar em branco.
A caixa de diálogo Construir um fluxo de nuvem automatizado é exibida.
- Nomeie seu fluxo.
Em seguida, você selecionará um gatilho.
- Digite Survey123 na barra de pesquisa. Selecione Quando uma resposta de pesquisa é enviada.
- Clique em Criar.
- Se esta for sua primeira vez utilizando este conector no Microsoft Power Automate, clique em Entrar para entrar com suas credenciais de organização do ArcGIS.
Você só precisa fazer isso uma vez, pois Microsoft Power Automate salva suas credenciais para uso futuro.
- Selecione a pesquisa que deseja usar para o seu webhook na lista suspensa de pesquisas.
Você agora configurou o ativador para seu webhook. Porém, para que o webhook execute ações com esse gatilho, seu processo precisa de mais etapas.
Esse fluxo precisa enviar um e-mail quando uma pergunta for respondida de uma determinada maneira, para que você forneça uma condição.
- Clique no botão Nova Etapa e escolha Condição no topo da seção Ações.
- Clique na caixa de texto mais à esquerda para abrir uma caixa de diálogo para selecionar uma pergunta ou propriedade de sua pesquisa. Selecione a pergunta de pesquisa que deseja utilizar para qualificar sua pesquisa.
- A caixa de texto do meio é um menu suspenso onde você seleciona a condição a ser acionada. Já que você está procurando uma resposta exata, selecione é igual a.
- Na caixa de texto mais à direita, digite o valor da pergunta para a qual deseja enviar uma notificação.
Você deseja que este e-mail seja enviado apenas se a condição for atendida.
- Clique em Adicionar uma ação na caixa Se sim. A caixa Se não permanece em branco.
Muitos serviços de e-mail têm conectores que podem ser usados neste fluxo.
- Para este exercício, selecione Office 365 Outlook - Enviar um e-mail (V2).
- Entre no serviço de e-mail com suas credenciais, se as suas credenciais ainda não estiverem salvas.
- Preencha os campos Para, Assunto, e Corpo de seu e-mail.
A caixa de diálogo Conteúdo dinâmico que aparece quando você seleciona uma caixa de texto permite inserir o conteúdo da resposta da pesquisa conforme necessário.
- Quando seu e-mail estiver completo, clique em Salvar.
Seu webhook está completo e está ativo por padrão. O webhook agora executará toda vez que uma resposta de pesquisa for enviada com as condições fornecidas.
Dica:
Você pode usar a ação Criar relatório para gerar um relatório para uma resposta de pesquisa.
Configure um webhook no site da web Survey123
Conclua as etapas a seguir para configurar um webhook no site Survey123:
- Em sua página Minhas Pesquisas, selecione a guia Configurações no menu na parte inferior direita do painel da pesquisa.
- Selecione a seção Webhooks a partir do menu à esquerda.
Esta página permite a você configurar e acessar todos os webhooks que você configurou. Se você não configurou nenhum webhook no Survey123, a página estará vazia.
- Clique em Adicionar webhook.
Uma nova página aparece, onde você pode configurar como o webhook irá interagir com sua pesquisa.
- Forneça um nome para seu webhook, que será usado para identificá-lo no futuro.
- A URL de carga útil é onde as informações da pesquisa serão enviadas. Isto precisa ser fornecido por um serviço de webhook externo.
Quando você cria um webhook usando um serviço comoMicrosoft Power Automate ou Make, a URL de carga útil é preenchida automaticamente nesta página. Outros serviços, como Zapier ou FME Server, fornecem a URL de carga útil para você copiar para esta página. Outros aplicativos podem exigir que você crie um serviço dedicado para ouvir o webhook.
- Os eventos de gatilho descrevem as ações específicas que chamarão o webhook. Selecione Novo registro enviado.
- Os dados de evento permitem que você escolha as informações de sua pesquisa que serão incluídas na carga útil: Info da Pesquisa, Resposta do servidor, Registro enviado, Info do usuário e Info do portal. Marque as opções Info de pesquisa e Registro enviado.
- O botão de alternar Status determina se o webhook estará ativo quando salvo. Deixe-o definido como Ativado (o padrão).
- Clique em Salvar.
O webhook está pronto para ser utilizado e executará toda vez que uma resposta de pesquisa for enviada. As regras configuradas no provedor de webhook podem garantir que um e-mail seja enviado somente se determinados critérios forem atendidos.
Propriedades de carga útil do evento
Um evento do webhook envia uma carga útil de propriedades como um objeto JSON. O conteúdo da carga útil será diferente com base na pesquisa. A tabela a seguir lista as propriedades comuns contidas no objeto JSON:
| Propriedade | Descrição |
|---|---|
| eventType | O tipo de evento. Os valores podem ser addData ou editData. |
| portalInfo | Informações sobre a organização do ArcGIS onde a pesquisa está hospedada. Contém as seguintes propriedades:
|
| surveyInfo | Informações sobre a pesquisa que gerou o webhook. Contém as seguintes propriedades:
|
| userInfo | Informações sobre a conta organizacional do ArcGIS para o usuário que enviou a pesquisa. Contém as seguintes propriedades:
|
As seguintes propriedades variam de acordo com a pesquisa e o tipo de evento:
| Propriedade | Descrição |
|---|---|
| applyEdits | A carga útil de Aplicar Edições enviada pela pesquisa. Se eventType for addData, conterá adds. Se eventType for editData, conterá updates. Ao adicionar um novo registro de repetição, ele também conteráadds. |
| response | A resposta daoperação applyEdits. Inclui os global IDs para feições criadas pela operação e se a operação foi bem-sucedida. |
| feature | O registro da pesquisa que foi enviado. Contém as seguintes propriedades:
|