I webhook sono un metodo ampiamente supportato, impiegato per consentire a più applicazioni di interagire tra loro utilizzando richieste HTTP POST per il trasferimento dei callback. Per ulteriori informazioni, consultare la pagina Wikipedia sui webhook. I webhook sono comunemente usati per l'invio di notifiche via email o SMS, la pubblicazione di messaggi sui social media, la compilazione automatica di record su un foglio di calcolo e l'aggiornamento dei database aziendali.
In ArcGIS Survey123, i webhook possono essere impostati e attivato quando una risposta di un rilevamento è inviato. Ad esempio, dopo il corretto invio delle informazioni al Feature Layer, può essere richiamato un webhook che attiva un'altra azione, come inviare un'e-mail di notifica, allegare il contenuto del rilevamento a un foglio di calcolo o inviare un messaggio di avviso.
Il luogo di lavoro potrebbe possedere il proprio fornire di webhook, ma sono disponibili diversi servizi di flussi di lavoro di terza parte, come Microsoft Power Automate, Make (conosciuto precedentemente come Integromat), Zapier e tray.io. Tutti questi possono essere usati per incorporare Survey123 come attivatore per un processo automatico. In particolare, Microsoft Power Automate e Make dispongono di un connettore Survey123 incorporato, che consente di integrare Survey123 nel flusso di lavoro del webhook con la minima difficoltà, e senza necessità di configurare il webhook nel sito web Survey123 o come input a un URL payload.
Attenzione:
Quando si crea o modifica un webhook per un rilevamento, il rilevamento deve essere aggiornato nell'app di campo Survey123 perché le modifiche diventino effettive.
Ci sono numerosi modi in cui è possibile usare Survey123 come attivare nei flussi di lavoro. Le seguenti sezioni mostrano come configurare un webhook per inviare un'e-mail di notifica quando viene inviata una risposta contenente una domanda a cui è stato risposto con un determinato valore.
Alla fine di questo argomento, tutte le proprietà che sono disponibili nel payload dell'evento webhook sono elencate per riferimento.
Impostare un webhook in Make
Make (conosciuto precedentemente come Integromat) è una piattaforma di automazione online. Per cominciare, è possibile registrarsi per ottenere un account gratuito. Make ha modelli da usare come punto di inizio per includere allegati nelle notifiche e-mail, aggiungendo record ai fogli di lavoro e creando elementi di calendario.
- Navigare a https://www.make.com/ ed effettuare l'accesso.
- Nella pagina Scenari, fare click sul pulsante Crea un nuovo scenario.
- Fare clic sull'icona del modulo al centro della schermata. Cercare Survey123 e selezionalo.
- Selezionare il modulo di attivazione Visualizza rilevamento.
Questo modulo è progettato per eseguire lo scenario ogni volta che viene inviata una risposta al rilevamento.
Compare un popup per configurare il modulo Visualizza rilevamento.
Suggerimento:
Il modulo Creare report può essere utilizzato per generare un report per una risposta al rilevamento.
- Fare clic su Aggiungi e indicare un nome per il webhook.
Il nome deve essere univoco nel rilevamento per il quale si sta configurando il webhook.
- Se è la prima volta che si utilizza il modulo Survey123 in Make, configurare una connessione all'organizzazione ArcGIS. Questa operazione deve essere eseguita una sola volta, in quanto Make salva le informazioni per gli usi futuri. In Connessione, fare click su Aggiungi e dare un nome alla connessione ArcGIS.
- Per connettersi ad ArcGIS Online, fare clic su Salva per accedere all'organizzazione ArcGIS.
- Per connettersi a ArcGIS Enterprise, registrare Make con il portale. Per maggiori informazioni, consultare il post del blog Survey123 Tricks of the Trade: Make.
- Selezionare un rilevamento dall'organizzazione ArcGIS per connettersi.
- Valutare le opzioni da includere nel webhook e fare clic su Salva.
È consigliabile lasciare il valore predefinito di Sì per tutte le impostazioni avanzate, in modo da disporre di maggior flessibilità nella personalizzazione del webhook.
- Fare clic su OK.
Il webhook viene creato e il modulo Visualizza rilevamento è configurato.
- Fare clic sul pulsante Aggiungi un altro modulo sul lato destro del modulo Visualizza rilevamento per collegarvi un altro modulo.
- Cercare E-mail e selezionare il modulo E-mail.
- Selezionare l'azione Invia un'e-mail.
- Se è la prima volta che usi questo modulo in Make fare clic su Aggiungi per impostare una connessione al proprio account di posta elettronica. Selezionare un tipo di connessione ed eseguire l'accesso al proprio account.
Questa operazione deve essere eseguita una sola volta, in quanto Make salva la connessione per gli usi futuri.
- Aggiungere un indirizzo e-mail destinatario.
Si tratta dell'indirizzo e-mail a cui le e-mail attivate verranno inviate.
- Fare clic sulla casella di testo dell’oggetto. Scegliere i campi del rilevamento per costruire l'oggetto dell'e-mail utilizzando il riquadro delle impostazioni del modulo che appare.
- Fare clic sulla casella di testo del contenuto. Scegliere i campi del rilevamento per costruire il contenuto dell'e-mail utilizzando il riquadro delle impostazioni del modulo che appare. È possibile formattare il contenuto utilizzando l'HTML.
- Fare clic su OK.
Questo scenario deve inviare l'e-mail quando una domanda riceve una determinata risposta, pertanto si dovrà fornire un filtro.
- Fare clic sull'icona degli strumenti tra i due moduli e seleziona Imposta un filtro.
- Fare clic nella casella di testo Condizione e scegliere il campo del rilevamento da usare come filtro.
- Scegliere un operatore per la condizione. In questo caso, scegliere quello predefinito Uguale a.
- Inserire un valore per la condizione e fare clic su OK.
- Fare clic su Salva per salvare lo scenario.
È possibile fare clic su Esegui una volta per provare il webhook. Dopo aver cliccato Esegui una volta aprire Survey123 e inviare un rilevamento, assicurarsi che le risposte di rilevamento soddisfi le condizioni di filtraggio. Confermare che il destinatario riceva l'e-mail.
- Usa il pulsante a levetta in basso a sinistra della pagina per attivare il tuo scenario. Impostare il programma su Immediatamente per garantire che lo scenario venga eseguito ogni volta che viene presentata una risposta al rilevamento.
Per conoscere altri modi di usare Survey123 come trigger nei propri scenari Make, consultare integrazioni Survey123.
Impostare un webhook in Microsoft Power Automate
Microsoft Power Automate è un servizio di webhook disponibile sulla piattaforma Microsoft Office 365.
Nota:
Le credenziali ArcGIS Online usate per creare flussi in Power Automate vengono disconnesse automaticamente dopo due settimane. Se non è possibile sfogliare i rilevamenti previsti in Power Automate, verificare che la connessione dati di Survey123 sia attiva. Per ulteriori informazioni, vedere l'articolo di blog Quick Tip: Keeping the ArcGIS Connectors for Power Automate Refresh Token Valid.
Per configurare un flusso in Microsoft Power Automate tramite connettori ArcGIS Enterprise o ArcGIS, completare i passaggi seguenti. Se sono stati precedentemente creati flussi con il connettore Survey123, funzioneranno ancora, ma la nuova funzionalità sarà aggiunta solo ai connettori ArcGIS e ArcGIS Enterprise. Per ulteriori informazioni, vedere l'articolo di blog Survey123 triggers and actions in the ArcGIS connectors for Power Automate.
- Aprire Microsoft Power Automate.
- Selezionare Crea dalla pagina affianco al menu.
- Selezionare Flusso cloud automatico dalle opzioni Avvia da vuoto.
Viene visualizzata la casella di dialogo Costruisci un flusso cloud automatico.
- Assegnare un nome al flusso.
Successivamente, si selezionerà un attivatore.
- Digitare ArcGIS nella barra di ricerca, quindi selezionare Quando viene inviata la risposta a un rilevamento.
Attenzione:
Scegliere l'opzione Quando viene inviata la risposta a un rilevamento. in ArcGIS se il flusso richiede l'accesso a un'organizzazione ArcGIS Online. Scegliere l'opzione Quando viene inviata la risposta a un rilevamento in ArcGIS Enterprise se il flusso richiede l'accesso a un'organizzazione ArcGIS Enterprise.
- Fare clic su Crea.
- La prima volta che si usa questo connettore in Microsoft Power Automate, fare clic su Accedi per effettuare l’accesso con le proprie credenziali aziendali di ArcGIS.
Questa operazione deve essere eseguita una sola volta, in quanto Microsoft Power Automate salva le credenziali per usi futuri.
- Selezionare il rilevamento che si desidera utilizzare per il proprio webhook dall'elenco a discesa di rilevamenti.
L’attivatore del webhook è stato impostato. Perché il webhook esegua le azioni con questo attivatore, tuttavia, è necessario eseguire ulteriori azioni.
Il flusso deve inviare un'e-mail quando una domanda riceve una determinata risposta, pertanto si dovrà fornire una condizione.
- Cliccare il pulsante Passaggio seguente e scegliere Condizione nella parte superiore della sezione Azioni.
- Fare clic sulla casella di testo più a sinistra per aprire una finestra di dialogo per selezionare una domanda o una proprietà del rilevamento da usare per qualificare il rilevamento.
- Nella casella di testo centrale, dal menu a discesa, selezionare la condizione è uguale a come attivatore, dal momento che si sta cercando una risposta esatta.
- Nella casella di testo a destra, digitare il valore della risposta per il quale si desidera inviare una notifica.
Questa e-mail deve essere inviata solo se la condizione è soddisfatta.
- Fare clic su Aggiungi un'azione nella casella Se sì.
La casella Se no rimane vuota.
Molti servizi di posta elettronica dispongono di connettori che possono essere utilizzati in questo flusso.
- Selezionare Office 365 Outlook - Invia un'e-mail (V2).
- Effettuare l'accesso al servizio di posta elettronica con le proprie credenziali, se non sono ancora state salvate.
- Riempire i campi A, Soggetto e Corpo dell'e-mail.
La casella di dialogo Contenuto dinamico che appare quando si seleziona una casella di testo consente di inserire contenuto dalla risposta del rilevamento, ove necessario.
- Una volta completata l’e-mail, fare clic su Salva.
Il webhook è completo e attivo per impostazione predefinita. Il webhook si attiverà ogni qualvolta venga inviata una risposta al rilevamento che soddisfa le condizioni.
Suggerimento:
È possibile utilizzare l'azione Crea report per generare un report per una risposta al rilevamento.
Configurare un webhook nel sito web Survey123
Completare le operazioni seguenti per impostare un webhook nel sito web Survey123:
- Nella pagina I miei rilevamenti, selezionare la scheda Impostazioni dal menu in basso a destra del riquadro del rilevamento.
- Selezionare la sezione Webhook dal menu a sinistra.
Questa pagina consente di configurare un webhook e di accedere a tutti quelli configurati. Se non è stato configurato alcun webhook in Survey123, la pagina è vuota.
- Cliccare Aggiungi webhook.
Appare una nuova pagina in cui è possibile impostare il modo in cui il webhook interagirà con il rilevamento.
- Indicare un nome per il proprio webhook, che sarà utilizzato per identificarlo in futuro.
- L'URL payload è dove verranno inviate le informazioni del rilevamento. Deve essere fornito da un servizio di webhook esterno.
Quando crei un webhook utilizzando un servizio come Microsoft Power Automate o Make, l'URL del payload viene compilato automaticamente in questa pagina. Altri servizi come Zapier o FME Server forniscono l'URL del payload da copiare in questa pagina. Altre app potrebbero richiedere la creazione di un servizio dedicato per l'ascolto del webhook.
- Gli eventi dell'attivatore descrivono le azioni specifiche che richiamerà il webhook. Selezionare Nuovo record inviato.
- I dati degli eventi consentono di scegliere quali informazioni del rilevamento saranno incluse nel payload: Informazioni rilevamento, Risposta del server, Record inviato, Informazioni utente e Informazioni portale. Controllare le Informazioni rilevamento e le opzioni Record inviato.
- Il selettore Stato determina se il webhook sarà attivato dopo il salvataggio. Lasciarlo impostato su Attivato (predefinito).
- Fare clic su Salva.
Il webhook è pronto per l'uso e verrà eseguito ogni volta che viene inviata una risposta al rilevamento. Le regole impostate all'interno del provider del webhook garantiscono che l'e-mail sarà inviata solo laddove vengano soddisfatti determinati criteri.
Proprietà del carico utile dell'evento
Un evento webhook invia un payload di proprietà come oggetto JSON. Il contenuto del carico utile sarà diverso in base al sondaggio. La tabella seguente elenca le proprietà comuni contenute nell'oggetto JSON:
| Proprietà | Descrizione |
|---|---|
| eventType | Il tipo di evento. I valori possono essere addData o editData. |
| portalInfo | Informazioni sull'organizzazione ArcGIS in cui è ospitata l'indagine. Contiene le seguenti proprietà:
|
| surveyInfo | Informazioni sull'indagine che ha generato il webhook. Contiene le seguenti proprietà:
|
| userInfo | Informazioni sull'account aziendale ArcGIS per l'utente che ha inviato l'indagine. Contiene le seguenti proprietà:
|
Le seguenti proprietà variano a seconda del sondaggio e del tipo di evento:
| Proprietà | Descrizione |
|---|---|
| applyEdits | Il payload Apply Edits inviato dall'indagine. Se eventType è addData, conterrà adds. Se eventType è editData, conterrà updates. Quando si aggiunge un nuovo record di ripetizione, esso conterrà anche adds. |
| response | La risposta dell'operazione applyEdits. Include gli ID globali per le caratteristiche create dall'operazione e se l'operazione ha avuto successo. |
| feature | Il verbale del sondaggio che è stato presentato. Contiene le seguenti proprietà:
|