Webhook

Los webhooks son un método muy compatible utilizado para permitir que varias aplicaciones interactúen entre sí, a través de solicitudes HTTP POST para pasar devoluciones de llamadas entre ellas. Para obtener más información, consulte la página de Wikipedia sobre los webhooks. Entre los usos habituales de webhooks se encuentran: el envío de notificaciones por correo electrónico o SMS, la publicación de mensajes en redes sociales, la escritura automática de registros en una hoja de cálculo y la actualización de bases de datos corporativas.

En ArcGIS Survey123, es posible configurar y activar los webhooks al enviar una respuesta de encuesta. Por ejemplo, tras un envío correcto de la información a la capa de entidades, se podría llamar al webhook y desencadenar otra acción, por ejemplo, el envío de una notificación por correo electrónico, la incorporación de contenido de la encuesta a una hoja de cálculo o el envío de una alerta.

Su lugar de trabajo puede contar con su propio proveedor de webhook, pero también dispone de una variedad de servicios de flujo de trabajo de terceros, tales como Microsoft Power Automate, Make (anteriormente Integromat), Zapier y tray.io. Todos ellos se pueden utilizar para incorporar Survey123 como desencadenador de un proceso automático. En particular, Microsoft Power Automate y Make tienen, cada uno, un conector de Survey123 integrado, lo cual le permite integrar Survey123 en su flujo de trabajo de webhook con el mínimo de dificultad y sin tener que configurar el webhook en el sitio web de Survey123 ni introducir una URL de carga.

Precaución:

Al crear o modificar un webhook para una encuesta, la encuesta se debe actualizar en la aplicación de campo Survey123 para que los cambios surtan efecto.

Existen muchas maneras de utilizar Survey123 como desencadenador de sus flujos de trabajo. En las secciones que aparecen a continuación, se demuestra cómo configurar un webhook para enviar una notificación de correo electrónico cuando se haya enviado una respuesta que contenga una pregunta respondida con un valor determinado.

Al final de este tema, se muestran como referencia todas las propiedades disponibles en la carga de eventos de webhooks.

Configurar un webhook en Make

Make (anteriormente Integromat) es una plataforma de automatización en línea. Regístrese para conseguir una cuenta gratuita y empezar a trabajar. Make tiene plantillas para utilizar como punto de partida para incluir adjuntos en las notificaciones por correo electrónico, agregar registros a hojas de cálculo y crear elementos de calendario.

  1. Vaya a https://www.make.com/ e inicie sesión.
  2. En la página Escenarios, haga clic en el botón Crea un nuevo escenario.
  3. Haga clic en el icono de módulo del centro de la pantalla. Busque Survey123 y selecciónelo.

    Elija un módulo de Survey123.

  4. Elija el módulo desencadenador Ver encuesta.

    Este módulo se ha diseñado para ejecutar el escenario cada vez que se envíe una respuesta a una encuesta.

    Aparece un elemento emergente que le ayuda a configurar el módulo Ver encuesta.

    Sugerencia:

    Puede utilizar el módulo Crear informe para generar un informe para una respuesta de encuesta.

  5. Haga clic en Agregar y proporcione un nombre para su webhook.

    Este nombre debe ser exclusivo de la encuesta para la cual está configurando el webhook.

  6. Si esta es la primera vez que utiliza el módulo Survey123 en Make, establezca una conexión a su organización de ArcGIS. Solo necesita hacerlo una vez, dado que Make guardará su información para uso futuro. En Conexión, haga clic en Agregar y asigne un nombre a la conexión a ArcGIS.
    • Para conectarse a ArcGIS Online, haga clic en Guardar para iniciar sesión en su organización de ArcGIS.
    • Para conectarse a ArcGIS Enterprise, regístrese en Make con su portal. Para obtener más información, consulte la entrada de blog Secretos de Survey123: Make.
  7. Elija la encuesta de su organización de ArcGIS a la que desea conectarse.

    Cree un webhook para su encuesta.

  8. Considere las opciones que desea incluir en su webhook y haga clic en Guardar.

    Se recomienda mantener el valor predeterminado en todos los ajustes avanzados, ya que es lo que le proporciona la mayor flexibilidad a la hora de personalizar el webhook.

  9. Haga clic en Aceptar.

    Se crea el webhook y se configura el módulo Ver encuesta.

  10. Haga clic en el botón Agregar otro módulo en el lateral derecho del módulo Ver encuesta para conectarle otro módulo.

    Agregar otro módulo

  11. Busque Correo electrónico y seleccione el módulo Correo electrónico.
  12. Seleccione la acción Enviar correo electrónico.
  13. Si es la primera vez que utiliza este módulo en Make, haga clic en Agregar para configurar una conexión a su cuenta de correo electrónico. Seleccione un tipo de conexión e inicie sesión en su cuenta.

    Solo necesita hacerlo una vez, dado que Make guardará su conexión para uso futuro.

  14. Agregue una dirección de correo electrónico de destinatario.

    Esta es la dirección de correo electrónico a la que se enviará el correo electrónico generado por el desencadenador.

  15. Haga clic en el cuadro de texto de asunto. Elija campos de su encuesta para construir el asunto de su correo electrónico utilizando el panel de configuración del módulo que aparece.
  16. Haga clic en el cuadro de texto de contenido. Elija campos de su encuesta para construir el contenido de su correo electrónico utilizando el panel de configuración del módulo que aparece. Puede formatear el contenido con HTML.
  17. Haga clic en Aceptar.

    Este escenario necesita enviar el correo electrónico cuando se ha respondido a una pregunta de una forma concreta, de modo que indicará un filtro.

  18. Haga clic en el icono de las herramientas entre los dos módulos y seleccione Definir filtro.

    Agregar un filtro a su escenario

  19. Haga clic en el cuadro de texto Condición y elija el campo de su encuesta que desea usar en el filtro.

    Definir su filtro

  20. Elija el operador para la condición. En este caso, elija el predeterminado, Igual que.
  21. Introduzca un valor para la condición y haga clic en Aceptar.
  22. Haga clic en Guardar para guardar su escenario.

    Opcionalmente, puede hacer clic en Ejecutar una vez para probar su webhook. Después de hacer clic en Ejecutar una vez, abra Survey123 y envíe una encuesta, asegurándose de que la respuesta de la encuesta cumpla la condición de filtro. Confirme que el destinatario recibe el correo electrónico.

  23. Utilice el botón de alternancia activar/desactivar de la parte inferior izquierda de la página para activar su escenario. Cambie la programación a Inmediatamente para asegurarse de que el escenario se ejecute cada vez que se envíe una respuesta a la encuesta.

Para conocer más formas de utilizar Survey123 como desencadenador de escenarios de Make, consulte Integraciones de Survey123.

Configurar un webhook en Microsoft Power Automate

Microsoft Power Automate es un servicio de webhooks ofrecido en la plataforma Microsoft Office 365.

Nota:

En los siguientes pasos se describe cómo configurar un flujo utilizando el conector de Survey123 integrado para encuestas publicadas en ArcGIS Online. Para utilizar Microsoft Power Automate con encuestas publicadas en ArcGIS Enterprise deberá configurar un conector personalizado. Para obtener más información, consulte el artículo de la base de conocimiento Cómo: Crear un conector de ArcGIS Survey123 para Microsoft Power Automate para su uso con ArcGIS Enterprise.

  1. Abra Microsoft Power Automate.
  2. Seleccione Crear en el menú lateral de la página.
  3. Seleccione Flujo de nube automático en las opciones de Empezar desde cero.

    Aparece el cuadro de diálogo Crear un flujo de nube automático.

  4. Dé un nombre al flujo.

    A continuación, seleccionará un desencadenador.

  5. Escriba Survey123 en la barra de búsqueda. Seleccione Cuando se envía la respuesta a una encuesta.

    Conector de Survey123 en Microsoft Power Automate

  6. Haga clic en Crear.
  7. Si esta es la primera vez que utiliza este conector en Microsoft Power Automate, haga clic en Iniciar sesión para iniciar sesión con las credenciales de su organización de ArcGIS.

    Solo necesita hacerlo una vez, dado que Microsoft Power Automate guardará sus credenciales para uso futuro.

  8. Seleccione la encuesta que desee usar para su webhook en la lista desplegable de encuestas.

    Acaba de configurar el desencadenador de su webhook. Sin embargo, para que el webhook realice acciones con este desencadenador, su proceso necesita más pasos.

    Este flujo necesita enviar un correo electrónico cuando se ha respondido a una pregunta de una forma concreta, de modo que indicará una condición.

  9. Haga clic en el botón Nuevo paso y elija Condición en la parte superior de la sección Acciones.

    UI de condición en Microsoft Power Automate

  10. Haga clic en el cuadro de texto que está más a la izquierda para abrir un cuadro de diálogo y elegir una pregunta o propiedad de su encuesta. Elija la pregunta de encuesta que desee utilizar para calificar su encuesta.
  11. El cuadro de texto central es un menú desplegable en el que seleccionar la condición desencadenadora. Como lo que le interesa es una respuesta exacta, elija Es igual que.
  12. En el cuadro de texto que está más a la derecha, escriba el valor de la pregunta para la que desee enviar una notificación.

    Usted desea que este correo electrónico solo se envíe si se cumple la condición.

  13. Haga clic en Agregar una acción en el cuadro Si se cumple. El cuadro Si no se cumple permanece vacío.

    Varios servicios de correo disponen de conectores que se pueden utilizar para este flujo.

  14. Para este ejercicio, elija Office 365 Outlook - Enviar un correo electrónico (V2).
  15. Inicie sesión en el servicio de correo con sus credenciales, si es que aún no están guardadas.
  16. Rellene los campos Para, Asunto y Cuerpo de su correo electrónico.

    El cuadro de diálogo Contenido dinámico que aparece cuando selecciona un cuadro de texto le permite insertar el contenido de la respuesta de encuesta según sus necesidades.

  17. Cuando haya terminado el correo electrónico, haga clic en Guardar.

Su webhook se completa y se activa de forma predeterminada. El webhook ahora se ejecutará cada vez que se envíe una respuesta de encuesta que reúna las condiciones definidas.

Configurar un webhook en el sitio web de Survey123

Siga estos pasos para configurar un webhook en el sitio web de Survey123:

  1. En la página Mis encuestas, seleccione la pestaña Configuración en el menú de la parte inferior derecha del panel de la encuesta.
  2. En el menú de la izquierda, seleccione la sección Webhook.

    Esta página le permite configurar y acceder a todos los webhooks que haya configurado. Si no ha configurado ningún webhook en Survey123, la página estará vacía.

  3. Haga clic en Agregar webhook.

    Aparece una nueva página donde puede configurar cómo interactuará el webhook con su encuesta.

    Página Agregar webhook en el sitio web de Survey123

  4. Proporcione un nombre para su webhook, que se utilizará para identificar su webhook en el futuro.
  5. La URL de carga es el lugar al que se enviará la información de la encuesta. Debe provenir de un servicio de webhooks externo.

    Cuando crea un webhook mediante un servicio como Microsoft Power Automate o Make, la URL de carga se completa automáticamente en esta página. Otros servicios, como Zapier o FME Server, proporcionan la URL de carga para que la copie en esta página. Otras aplicaciones pueden requerir que cree un servicio específico para escuchar el webhook.

  6. Los eventos desencadenadores describen las acciones específicas que llamarán al webhook. Seleccione Nuevo registro enviado.
  7. Los datos del evento le permiten elegir la información de la encuesta que se incluirá en la carga: Información de la encuesta, Respuesta del servidor, Registro enviado, Información del usuario e Información del portal. Active las opciones Información de la encuesta y Registro enviado.
  8. El botón de alternancia Estado determina si el webhook estará activo al guardarlo. Déjelo como Activado (el valor predeterminado).
  9. Haga clic en Guardar.

El webhook está listo para su uso y se ejecutará cada vez que se envíe una respuesta de la encuesta. Las reglas definidas dentro del proveedor de webhooks pueden garantizar el envío de un correo electrónico solamente si se reúnen determinados criterios.

Propiedades de Carga de eventos

Un evento de webhook envía una carga de propiedades como un objeto JSON. El contenido de la carga variará en función de la encuesta. La siguiente tabla enumera las propiedades comunes contenidas en el objeto JSON:

PropiedadDescripción
eventType

El tipo de modelo. Los valores pueden ser addData o editData.

portalInfo

Información sobre la organización de ArcGIS en la que se aloja la encuesta. Contiene las siguientes opciones:

  • url
  • token

surveyInfo

Información sobre la encuesta que generó el webhook. Contiene las siguientes opciones:

  • formItemId
  • formTitle
  • serviceItemId
  • serviceUrl

userInfo

Información sobre la cuenta de organización de ArcGIS para el usuario que ha enviado la encuesta. Contiene las siguientes opciones:

  • username
  • firstName
  • lastName
  • fullName
  • email

Las siguientes propiedades variarán en función de la encuesta y el tipo de evento:

PropiedadDescripción
applyEdits

La carga Aplicar ediciones enviadas por la encuesta.

Si eventType es addData, contendrá adds.

Si eventType es editData, contendrá updates. Al agregar un nuevo registro de repetición, también contendrá adds.

response

La respuesta de la operación applyEdits. Incluye los Id. globales de las entidades creadas por la operación y si la operación se realizó correctamente.

feature

El registro de la encuesta que se envió. Contiene las siguientes opciones:

  • attributes
  • geometry
  • layerInfo
  • result
  • repeats
    Nota:

    Cada objeto dentro del conjunto repeatses un feature que tiene attributes, geometry , layerInfo , result,repeatsattachments

  • attachments
    • id
    • globalId
    • name
    • contentType
    • size
    • keywords
    • url
    • parentObjectId