Survey123 Tricks of the Trade: Encode URL parameters in the web app
The Survey123 web app supports a variety of URL parameters that can be used to initialize the contents, look and feel, and behavior of your online surveys. This article describes how you can make the use of URL parameters more secure, by encrypting them.
In the following example, URL parameters are used to prepopulate and hide the submittedBy question:
https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?field:submittedBy=Fernando%20Par...
Since the URL parameters are in clear text, a smart user could look at the web browser's navigation bar, figure out that a question is being hidden, and manipulate the URL parameters to show and change the question.
Here is the same URL, with encrypted parameters:
https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?code=ShFmaWVsZDpzdWJtaXR0ZWRCeXI...
Once the URL parameters are encrypted, only the Survey123 web app can read them, making the content in your URL secure.
Introduction to URL parameter encoding (encryption) in Survey123
URL parameter encoding is a technique that allows you to encrypt the contents of URL parameters. When parameters are encrypted, it is not possible for end users to manipulate existing or add new parameters to the URL. This functionality is only available with Survey123 online forms published with version 3.11 or newer.
Encoding parameters manually (&encodeUrlParams=true)
Let's pretend you want to add a link to your survey in a website. Using URL parameters, you prepopulate a hidden question so you can tell from which source (website, Facebook, etc) the survey was sent. In this case, since you only need to create and encode two links, you can simply use your web browser. Here is how:
- Create your own online survey URL and add parameters to it as usual.
- Add &encodeUrlParams=true at the very end of the URL and reload your page.
- The encoded URL will appear in your web browser's navigation bar.
- Copy the URL and use it somewhere else.
This animation shows the process step by step.
Encoding parameters with the Survey123 REST API
Manually encoding your survey URLs is only practical when you have a handful of URLs to share. If you need to create many Survey123 links, or you need to create them dynamically, the best choice is to use the Survey123 REST API to programmatically encode your URL parameters.
The encodeUrlParams operation on the Survey123 REST API allows you to pass a collection of Survey123 parameters and get back the encoded URL string.
The URL endpoint of this operation is: https://survey123.arcgis.com/api/encodeUrlParams
It expects a POST request including a valid ArcGIS token and the parameters you want to encode. For example:
{
"token": "<TOKEN>",
"params": {
"field:submittedBy": "Fernando Paredes",
"hide": ["field: submittedBy"]
}
"portalUrl": "<Portal URL>", //Optional}
Note that it is not necessary to pass any information about your survey. All you need to pass are the URL parameters that you wish to encode and a token. The portalUrl parameter is only needed if you are working against ArcGIS Enterprise.
The response from the Survey123 REST API will look like the following:
{
"code": "ShBmaWVsZDpjdXNUcmFja05vchRmaWVsZDpjdXNUcmFja05vPTEyMw==",
"success": true
}
The value of the code property represents your URL parameters, encoded.
Encoding parameters in bulk with the Survey123 REST API and Python
Say you wish to send an email to a very large group of people. You want the email to include a personalized Survey123 link, prepopulating a few questions in the survey based on the recipient's information you already have. You need to create a CSV file that you can import into an email marketing tool like MailChimp, Drip or MailerLite, including the email of the recipients and their corresponding Survey123 link. Of course, you want the Survey123 links to have the URL parameters encoded.
You can use the encodeUrlParams operation in the Survey123 REST API from any scripting language able to send a POST request. The example below highlights how links can be created from an ArcGIS Notebook. The code first performs a query on a feature service and generates a unique link for each record in the returned set. The script prints out the email and its corresponding Survey123 link with encoded parameters. Click here to preview the notebook.
As you can see, the code is straight-forward. A single POST request lets you specify the URL parameters you want to encode. The output of the Survey123 REST API can then be added to your Survey123 link.
Encoding parameters with the Survey123 REST API and Microsoft Power Automate
If you want to create a collection of links in bulk from some information you already have, the Python approach described above is a good fit. In other cases, you may need to create links dynamically.
For example, say you publish a survey for people to self-report damage to their property after a natural disaster. You would like respondents to automatically receive an email with a link that would allow them to update their own information. As you already know, using URL parameters it is possible to create a survey link to open a record in edit mode. You can also dynamically create such a link and email it right after a survey is submitted using Microsoft Power Automate and Integromat, but is it possible to also encode the URL parameters? Yes!
Overall, the Microsoft Power Automate flow could look like the following:
Note that the trigger for the flow is the Survey123 connector. Every time a survey is submitted, the flow is executed. The payload of the trigger includes the globalId of the record just created, which is made available in Microsoft Power Automate as dynamic content.
The HTTP module is used to encode the URL parameters.
The HTTP method is set to POST. The URI parameter targets the encodeUrlParams operation in the Survey123 REST API. In the queries group, the token parameter is populated dynamically with the token value provided in the Survey123 webhook payload. The params parameter includes the URL parameters we want encoded. In this case, we pass edit for the mode and the globalId of the feature we want to edit. The globalId is coming as dynamic content from the Survey123 webhook payload as well.
Next the Parse JSON module is used, so that later we can easily extract the encoded values from the output of the Survey123 REST API.
Finally, the Send Email module is used to dynamically create a Survey123 link within the subject of the email. Note that the encoded parameters are dynamically added to the Survey123 link.
Summary
The Survey123 web app supports several URL parameters, allowing you to preload responses to questions, and change the look and feel and behavior of your online surveys. Using the encodeUrlParams operation in the Survey123 REST API, you can encrypt these parameters to avoid manipulation by end users.
You can generate Survey123 links with encrypted parameters manually right from your browser, programmatically through scripting languages like Python, and dynamically through workflow automation in Microsoft Power Automate and Integromat.