Skip navigation
All Places > Survey123 for ArcGIS > Blog > Author: zkovacs

Survey123 for ArcGIS

3 Posts authored by: zkovacs
Check out Part 1 and Part 2 of the series.

In the final part of this series we'll see how to set up an email template for our webhook containing dynamic elements from the survey data and where to access additional webhook settings.

 

The steps below build on the webhook started in Part 1 & 2 but can be applied to any other webhook.

1.  Click on Add an action under 'Convert time zone' of the If yes branch of your condition.No alt text provided for this image
2.   Search for ‘send an email’ and select the action from the result list. No alt text provided for this image
3.   Complete the To and Subject fields (you should be able to search for your O365 contacts). No alt text provided for this image

4.   Compose the message

 

What formats and options do we have to include different content? By default, your message is sent as plain text - no hyperlinks or bold/coloured text, but you can include dynamic content like your converted time and values from your submitted survey data. What if you want more?

 

At the bottom left of the Send an email step, there is an option called Show advanced options. Hidden here you have the availability to switch your email format to HTML (and include HTML formatting tags to change the look of your email), send the email on behalf of someone else, add attachments, set CC and BCC recipients, set the importance of your message and so on.
No alt text provided for this image
That's general formatting out of the way, so we can now focus on including dynamic content in our message template. The following example will add a hyperlink to a web map that will show the location of the reported close call when it's clicked on. We will use a web map application that is shared with the relevant AGOL group(s), thus notified people can see the reported close call in a map.

 

The web map application to use may contain many other layers and we only want to show the one that contains the survey data and want to zoom in onto the close call location. How do we do this? Documentation to the rescue! The online help for Web AppBuilder for ArcGIS has a section about using URL parameters - we just need to have a look at the following sections:
  • Open a saved app
  • Set layer's visibility
  • Query a feature

 

Using the information from the help we can construct the url:

 

https://<your portal url>/apps/webappviewer/index.html?id=<itemId>&showLayers=<layerID>&query=<layerID>,<queryField>,<queryValue>


Where to find the values required?
  • itemId: Open the item's page in AGOL and look at the end of the URL in your web browser or scroll down to URL on the item's page and copy the hash value.

 

No alt text provided for this image

 

  • queryField: this is the field from your layer to use for the query. (We use the OBJECTID in our example.)

 

  • queryValue: value coming from your survey data, so your link is dynamic and will work with any close calls. (For testing purposes you can use a static value.)

 

It is highly recommended to test your URL in a web browser to make sure your web map application loads with the layers you need and shows the queried feature. It would look something like this:

 

https://XXXXXXXX.maps.arcgis.com/apps/webappviewer/index.html?id=a0b000c00d0e0ff0gh000iiij0kkl00f&showLayers=service_00a0b00000c00000d000e0f0g0000h0i_0123&query=service_00a0b00000c00000d000e0f0g0000h0i_0123,OBJECTID,95 

 

Once the URL is tested and you are happy with the results, it can go in to the email message with the rest of the dynamic content (change to 'Yes' under Is HTML first in advanced options). An example can be seen below.

 

No alt text provided for this image

 

The sent email would look like this: 

 

No alt text provided for this image

 

Clicking on the hyperlink opens the web map application, pans to the feature and displays a pop-up:

No alt text provided for this image

 

With using dynamic content in custom functions in the body of your message you can create a template that could be dynamically updated with the correct close call reason for example: No alt text provided for this image

 

Additional webhook settings on the Survey123 website

Most of your webhook settings can be controlled in your Power Automate (aka MS Flow) account, but there are a few settings that can only be accessed on the Survey123 website.

 

1.  Open your web browser and go to https://survey123.arcgis.com

 

2.  Log in and find the survey with the webhook in question

 

3.  Click on the ellipsis (...) button and select Settings

No alt text provided for this image

4.  Click on Webhooks on the left-hand side to see all webhooks for your survey

 

5.  Click on Edit (the pencil icon) under Operations to see more details No alt text provided for this image

6.  On the new page you can make changes to your webhook:

  • Edit its name
  • Change when it should be triggered: new records submitted, existing records edited
  • Event data: information included in the payload. Hover over the grey '?' icon after each item to see the information they include
  • Turn the webhook off or back on

 

No alt text provided for this image

NB: Changing the payload URL can break your webhook, only do it if you are sure you know what you're doing.

 

Summary

In this series of articles you learnt how to

  • Create a new webhook in Power Automate (MS Flow) for a Survey123 survey
  • Add conditions, convert and format the survey time
  • Send a notification email with dynamic content as part of the webhook
  • Find additional settings for your webhook

 

I hope you enjoyed the series! Feel free to share the articles with your network, leave feedback or message. 

You can download the article series in PDF format from here.

Part 1 of this article can be found here.

In Part 2 we'll have a look at how we can add the survey's time to the webhook and how to convert time zones and format the date/time string.

Add survey time to your notification email

Survey123 submits date and time from your survey form in UNIX format. This means that the date & time value will be in milliseconds. By default, you cannot really display this in any usable format unless you convert it first. There are many time converters available on the internet, like this one to do that. However, we don’t need to use these in Flow as we can set up a function for this.The steps below are based on the webhook we created in Part 1 - but can be applied to any existing or new webhook (assuming that your survey has a date/time field in it).

1.   Click on Add an action under the If yes branch of your condition No alt text provided for this image
2.   Search for ‘add to time’ and select the action from the result list.
No alt text provided for this image

3.   To edit the action, click into Base time and switch to the Expression tab in the context dialog:
No alt text provided for this image

4.   Enter the expression* into the function box (fx) and save your webhook:
addseconds('1970-1-1',div(triggerBody()?['feature']?['attributes']?['survey_datetime'],1000))

NB:
This example assumes that the date/time field in your survey is called 'survey_datetime'. If it's different in your survey, you need to modify the expression accordingly.

* I am aware that a similar expression exists in this blog article, but all the date formatting strings I've tried gave me an error in Flow. I believe Flow was updated since that article and no longer accepts the formatting string as part of the expression. When leaving the formatting string out, the expression was accepted and works just fine.

So, what does the above snippet do?

The addseconds() function adds the seconds specified to a base time. The base time for Unix is 1st January 1970, hence the '1970-1-1' part as base. Then in the second parameter we call the dynamic value from the ‘survey_datetime’ field – but as this is in milliseconds, we need to divide this by 1000 as the addseconds() function needs a value in seconds. That’s why we added the div() function, which provides this division for us.

 

You can add a static hour/day/month/etc. value to this calculation specifying the Interval and Time unit in the step. (For example if your device's clock is misconfigured.) We don't need to add anything in our case, so we just set it to '0 Hour'. 
No alt text provided for this image

Convert time zone and format string

As discussed above, your survey's date & time is submitted in UNIX format (also known as UNIX Epoch, UNIX timestamp or POSIX time) which starts at midnight (UTC) on 1st January 1970. If your local time zone is different from UTC, you may want to convert the calculated time into your correct time zone.

The below steps assume you have completed the time calculation step in the previous section.

1.   Click on Add an action under the If yes branch of your condition.
No alt text provided for this image
2.   Search for ‘convert time zone’ and select the action from the result list to add it to your flow. No alt text provided for this image
3.   Click into Base time, then in the Dynamic content tab of the context dialog select Calculated time – this is the function we just created in the top half of this article. No alt text provided for this image
4.   Set up the Source time zone (it must be UTC) and your Destination time zone, then choose a Format string you want to use. 
No alt text provided for this image

 

 

In Part 3 we will discuss how to include the calculated/converted time and other dynamic content in the notification email and where to find additional settings for your webhook.

Update: Microsoft recently renamed Flow to Power Automate - link.

 

Note: Creating webhooks in ArcGIS Enterprise was introduced in v10.7 and the authoring process in that environment is different and will be discussed in a future post.

 

Starting with Survey123 for ArcGIS 3.0, webhooks can be set up and activated when a survey response is submitted. What does this mean? Basically, when a survey is successfully submitted, different workflows can be triggered based on the content of the submission: sending notification emails, adding results to a spreadsheet and so on.

 

There are a wide variety of workflow services available, such as Power Automate (aka MS Flow), Integromat, tray.io, Zapier, IFTTT, n8n.io, CloudHQ and the list goes on. Most (if not all) of them can be used to incorporate Survey123 as a trigger to build your automated process. Out of these, Integromat and Power Automate have a Survey123 connector making it easier to implement your processes. This article guides through an example using Power Automate.

 

What will you need to create Survey123 webhooks?

  • ArcGIS Online (AGOL) Organisational account
  • Your Survey123 form published into AGOL
  • Office 365 account to access Power Automate

 

Below is a workflow for creating a webhook that triggers an alert email if the submitted data meets a condition (for example the weather is Adverse).

 

1.  Open Power Automate (go to your O365 account and search for the app), go to My flows and click on + New > Automated - from blank :

 

2.  Give your webhook a meaningful name, so you know which one to edit/disable later if needed when you have more of them.

 

3.  Search for ‘Survey123’ under Choose your flow’s trigger, select When survey response is submitted and log in to your AGOL account (you only need to log in once, the connection is stored in your Flow profile). No alt text provided for this image

 

4.  Select your survey from the drop-down and click on New StepNo alt text provided for this image

 

5.  Choose an action: for example ConditionNo alt text provided for this image

 

and add your survey field(s) and the value(s) you want the webhook to be triggered for. You can select your survey fields from the Dynamic content part for the condition: No alt text provided for this image

 

Under the If yes branch, add a new step (click on the ‘+’ sign) and search for Send an email (Outlook). Set up the required details and save your flow – use both Save buttons: one at the bottom and one in the top right corner! No alt text provided for this image

 

You should be able to see the webhook triggered on the webhook’s page under RunsNo alt text provided for this image

 

If you click on an item on the list, you can see the details of that run. You can use this to see if a run failed (and why). No alt text provided for this image

 

6.  Download your survey in the Survey123 app and test your trigger. If you downloaded the survey before the trigger was added, delete the survey and re-download it. Otherwise your webhooks won’t work.

 

In Part 2 we will discuss how to add the survey time to your webhook/flow and convert time zones.