[Updated February 29, 2020]
IMPORTANT: Check the Upcoming changes to Survey123 web form's query parameters blog post for upcoming changes affecting content described in this article.
Today we will explore how you can edit existing records using the Survey123 web app, also known as a web form. The idea is quite simple, we will populate the contents of a Survey123 web form using an existing record from a feature layer and let users update (edit) that information. When working this way, the submit button in the survey will update an existing record, as opposed to creating a new record for a new survey response.
This technique for editing data in a web form be quite handy. You can use it for example to let people review and modify existing submitted data, or to simply let them finish an uncompleted form. You can also incorporate web forms into QA/QC and data validation workflows.
Before we start, be aware of the following:
- The editing of records in web forms is only available in the Survey123 web app after May 23, 2019 (version 3.4 and newer). I will describe later in this blog how you can make your surveys run in this latest version, even if you published it in the past in an earlier version.
- Starting with version 3.9, we will introduce important changes to the syntax used to edit features in a web form. Refer to the Upcoming changes to Survey123 web form's query parameters for details.
Editing of existing data in a web form is possible through the use of web form URL parameters. If you are not familiar with web form URL parameters in general, I strongly suggest you read the Survey123 Tricks of the Trade: Web form URL parameters first.
Here is an example:
Note the two URL parameters:
- objectId=9, this parameter loads the record in your feature layer with objectId 9 into your form. Of course, you can replace 9 with the specific objectId of the feature you want to load.
- mode=edit, puts the web form in edit mode. This essentially ensures that when the user hits the submit button, the current record is updated. If the mode is not set to edit, the form will create a new record when submitted, even if the form was initialized with data from a particular record.
URL parameters are case sensitive. For example: objectId is not the same as ObjectID or objectID. If you see that your form is not loading the record you want, double check the spelling of the parameter, and also ensure the objectId you are trying to load exists.
As described above, the editing mode in web forms was incorporated in version 3.4. If you want to edit records using a survey that was published in the past, you can bring things up to speed in two different ways:
- Upgrade your survey by simply re-publishing it. If you originally published your survey using Survey123 Web Designer, then use Designer to publish it again. You do not need to make any changes other than simply clicking the Publish button. The same goes with Survey123 Connect for ArcGIS: If you originally published your survey with Connect, go back to Connect and hit publish.
- Upgrade your survey at run-time: You can alternatively add the version=latest URL parameter to force the survey to be loaded using the latest available Survey123 web app. Something like this:
My recommendation is that whenever possible you upgrade your surveys by re-publishing them. It will improve the initial loading time of the survey in the web browser, and it will guarantee that the behavior of your web form remains unchanged even if the Survey123 release changes.
From a practical perspective, the technique described above is useless unless you somehow present a ready-to-use link (URL) to the end user; A link that already includes the appropriate objectId to edit. Do not expect end users to modify that objectId manually in the web browser URL address! I will next describe three scenarios to illustrate how you could apply this technique.
Launching an edit web form from a feature popup
Our first scenario allows users to navigate a map, and launch an edit web form from the popup of an existing record. The key is to customize the feature layer popup so it dynamically generates the correct URL to launch the survey. Once the popup is configured, you can use the web map within the ArcGIS Map Viewer, custom Web AppBuilder apps, Explorer for ArcGIS and any app that supports web maps.
Here is a brief step by step guide to configure your popups:
- Using the ArcGIS map viewer, add your survey feature layer (or hosted feature layer view) into a web map.
- Open the configure popup dialog for your survey feature layer.
- In the popup contents section, select a custom attribute display.
- Add the URL of your web form into the attribute display. Then add the mode and objectId parameters.
- Dynamically populate the objectId parameter using the OBJECTID field from your feature layer.
- Use the full web form URL with its parameters to create a link.
- Save the popup and test it out.
And here are the same steps in a short animation.
Embedding an edit web form within Operations Dashboard for ArcGIS
The idea with this one is to add an embedded content element within the dashboard, and configure it to display your web form. The URL of the web form will include the mode parameter set to edit and the objectId will be dynamically populated. Using a filter action triggered by other element within the dashboard, such as a list, the embedded content element will refresh your web form with the relevant record to be edited.
At a high level, the steps are as follows:
- Set a refresh rate on a web map displaying your survey feature layer.
- Add your web map to a new dashboard and configure a list element to display survey records.
- Add an embedded content element. In the Data options, set the Type to Features and add the URL of your web form with the mode=edit and objectId parameters. Make sure the objectId parameter is set to pull a value from the ObjectID column in the fields collection.
- Next configure a filter action on the list element and target your embedded content element.
- Click on a record in the list, and your web form in the embedded content element will display your record in edit mode.
The animation will guide you through the whole process. Click on the animation to make it larger.
Including an edit web form link in an e-mail.
In this scenario, we will use a web hook to automatically send an e-mail to the user submitting the survey. This email will contain a link for the user to complete or make modifications at any time. To do this you must be familiar with web hooks in general or with either Microsoft Flow or Integromat. Like in the examples above, the trick is to be able to dynamically populate the objectId of the record you want to edit. Luckily enough, the payload of a Survey123 web hook includes information about the user submitting the data (if logged-in) as well as responses to questions in the survey. So as long as the user is logged-in or a specific question in the survey captures the contact e-mail, you can make this work.
Here are the high level steps:
- Create a new survey. If you plan to share your survey publicly, include an e-mail question and make it required. If you plan to keep your survey secured, you will be able to get the e-mail from the logged in user's profile.
- Use Microsoft Flow or Integromat to automate e-mail notifications when your survey is submitted. The objectId of the record submitted is included in the payload of the web hook. Simply add the objectId to the URL of your edit web form when you add the link in the body of your e-mail.
Here is some visual aid in case you are using Integromat.
If you are using Integromat or Zapier, the pattern is pretty much the same: use the webhook payload to retrieve the objectId of the submitted record and use if for your edit web form url.