Os webhooks permitem que vários aplicativos interajam entre si, usando solicitações HTTP POST para transmitir retornos de chamada 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 Survey123, os webhooks podem ser configurados e ativados quando um registro é criado ou excluído de uma camada de feição ou quando uma resposta de pesquisa é 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.
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.
Seu local de trabalho pode ter seu próprio provedor de webhook, mas uma variedade de serviços de fluxo de trabalho de terceiros estão disponíveis, como Microsoft Power Automate, Make, Zapier, e tray.io. Todos estes podem ser utilizados para incorporar Survey123 como um gatilho para um processo automatizado.
Microsoft Power Automate e Make também incluem componentes de fluxo de trabalho para auxiliar na criação de webhooks para uso com o Survey123.
Tipos de webhooks suportados pelo Survey123
O Survey123 suporta dois tipos de webhooks:
- Webhooks da camada de feição — estes são armazenados e acionados pela camada de feição ou pela visualização da camada de feição da pesquisa.
- Webhooks Survey123—esses dados são armazenados no formulário da pesquisa e são acionados pelo aplicativo de campo ou pelo aplicativo da web.
O Microsoft Power Automate inclui um conector ArcGIS que ajuda a configurar webhooks de camadas de feição ou webhooks Survey123. Para saber mais, consulte Conectores do ArcGIS. Os seguintes componentes de fluxo de trabalho que ajudam a configurar um webhook Survey123 continuarão disponíveis, mas não serão mais atualizados:
- Microsoft Power Automate—conector Survey123
- Make—módulo Survey123
Exemplos de como configurar um webhook
Há várias maneiras de usar o Survey123 como um gatilho em seus fluxos de trabalho. Os três primeiros exemplos desta seção usam o mesmo cenário — enviar um e-mail de notificação quando uma resposta contendo uma pergunta respondida com um determinado valor for enviada — mas cada um com um componente de fluxo de trabalho de terceiros ou tipo de webhook diferente. O último exemplo pressupõe que você tenha criado um webhook personalizado (sem usar um conector Microsoft Power Automate ou módulo Make) e descreve como adicionar o webhook ao Survey123.
Veja os seguintes exemplos:
- Configure um webhook de camada de feição no Microsoft Power Automate
- Configurar um webhook Survey123 no Microsoft Power Automate
- Configurar um webhook Survey123 no Make
- Adicione um webhook ao site do Survey123
Configure um webhook de camada de feição no Microsoft Power Automate
Complete as seguintes etapas para configurar um webhook da camada de feição no Microsoft Power Automate:
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, confirme se sua conexão de dados do Survey123 está ativa. Para obter mais informações, consulte o artigo do blog Dica Rápida: Mantendo o token de atualização do ArcGIS Connectors for Power Automate Válido.
Para configurar um fluxo no Microsoft Power Automate usando o ArcGIS ou conectores do ArcGIS Enterprise, complete as etapas abaixo. Se você criou fluxos anteriormente com o conector do Survey123, eles ainda funcionarão, mas novas funcionalidades serão adicionadas apenas ao ArcGIS e aos conectores do ArcGIS Enterprise. Para obter mais informações, consulte o artigo do blog Ativadores e ações do Survey123 em conectores do ArcGIS for Power Automate.
- 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 o fluxo.
Em seguida, você selecionará um gatilho.
- Digite ArcGIS na barra de pesquisa e selecione Quando um registro é criado em uma camada de feição como gatilho neste fluxo de trabalho.
- Clique em Criar.
- Inicie a sessão com as credenciais da sua organização do ArcGIS e escolha a camada de feição que deseja monitorar.
Você deve selecionar a camada de feição ou a visualização da camada de feição para a qual os envios serão feitos.
- Adicione a ação Buscar atualizações, alterações ou exclusões da camada de feição a este fluxo de trabalho.
- Defina Alterar URL como entrada de Obter alterações de.
- Defina layerId como a entrada do ID da camada de feição.
- 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.
O webhook está completo e fica ativo por padrão. O webhook agora será executado a cada 30 segundos.
Configurar um webhook Survey123 no Microsoft Power Automate
Conclua as etapas a seguir para configurar um webhook Survey123 no Microsoft Power Automate:
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, confirme se sua conexão de dados do Survey123 está ativa. Para obter mais informações, consulte o artigo do blog Dica Rápida: Mantendo o token de atualização do ArcGIS Connectors for Power Automate Válido.
Para configurar um fluxo no Microsoft Power Automate usando o ArcGIS ou conectores do ArcGIS Enterprise, complete as etapas abaixo. Se você criou fluxos anteriormente com o conector do Survey123, eles ainda funcionarão, mas novas funcionalidades serão adicionadas apenas ao ArcGIS e aos conectores do ArcGIS Enterprise. Para obter mais informações, consulte o artigo do blog Ativadores e ações do Survey123 em conectores do ArcGIS for Power Automate.
- 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 o fluxo.
Em seguida, você selecionará um gatilho.
- Digite ArcGIS na barra de pesquisa e selecione Quando uma resposta da pesquisa for enviada.
- Clique em Criar.
- Efetue o login com as credenciais da sua organização do ArcGIS.
- Selecione a pesquisa que deseja usar para o webhook na lista suspensa de pesquisas.
Agora você configurou o ativador para o webhook; no entanto, para que o webhook execute ações com esse ativador, há etapas adicionais.
O fluxo deve enviar um e-mail quando uma pergunta for respondida de uma determinada maneira, então você deverá fornecer 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 da pesquisa e selecione a pergunta da pesquisa que deseja usar para qualificar a pesquisa.
- Na caixa de texto do meio, no menu suspenso, selecione a condição é igual a como ativador, já que você está procurando uma resposta exata.
- 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.
- 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.
O webhook está completo e fica 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.
Configurar um webhook Survey123 no Make
Conclua as etapas a seguir para configurar um webhook Survey123 no Make:
- 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. Em Conexão, clique em Adicionar e nomeie a conexão para o ArcGIS.
Você precisa fazer isto somente uma vez, já que o Make salvará suas informações para uso futuro.
- 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 o artigo de blog Survey123 Tricks of the Trade: 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 deve enviar um e-mail quando uma pergunta for respondida de uma determinada maneira, portanto, você deverá 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 .
Adicione um webhook ao site do Survey123
É possível adicionar um webhook Survey123 ou um webhook da camada de feição ao site. As etapas a seguir mostram como configurar um webhook de camada de feição. Um webhook Survey123 é semelhante, mas com opções adicionais de Dados de evento que são listadas nas Propriedades da carga útil do evento.
- 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 e selecione Adicionar webhook à camada de feição.
Uma novo painel 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.
- Selecione Novo registro enviado.
- Deixe-o definido como Ativado (o padrão).
- Clique em Salvar.
A URL de carga útil é onde as informações da pesquisa serão enviadas. Isso deve ser fornecido por um serviço 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.
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 varia de acordo com o tipo de webhook utilizado e a pesquisa.
Os webhooks da camada de feição contêm apenas addData ou eventos editData. Para obter mais informações, consulte Cargas úteis do webhook da camada de feição.
Os webhooks Survey123 contêm o tipo de evento e propriedades adicionais. A tabela a seguir lista as propriedades comuns contidas no objeto JSON de um webhook Survey123:
| 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 dos webhooks Survey123 variam dependendo do tipo de pesquisa e 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:
|