[Updated February 28, 2020]
[Updated April 2, 2020]
Many web applications support the notion of URL parameters and Survey123 web forms are no exception. URL parameters allow you to dynamically pass data into your survey. This data can be used to prepopulate questions, hide questions, change the language of a form and many other things with your survey form. In this blog post, I will explore the options available in detail.
Before I start, I want to clarify that in the past we already covered how to use the Custom URL Scheme in the Survey123 field app. The concept of a Custom URL Scheme is similar to URL parameters, but they are two different things: the Custom URL Scheme applies to the Survey123 field app and the URL parameters discussed in this post only apply to web forms. That is, to forms loaded within a web browser, as opposed to loaded into the Survey123 field app in your device.
With that, lets get started:
Lets first get familiar with how surveys get loaded into the Survey123 web app. Take the following URL:
The first part of the URL refers to the Survey123 web app: https://survey123.arcgis.com/share/ We host the Survey123 web app in our ArcGIS Online servers, and it is used to render your surveys as web forms. The second part of the URL is the unique identifier of your survey. In this particular case, it is: 1cb28b212b5542acbbdbaa35feba0765. The complete URL will open the Survey123 web app in your web browser and immediately present the survey 1cb28b212b5542acbbdbaa35feba0765, in this case it is an Oak Tree Health survey.
So far, no URL parameters have been used, but now we are going to add one parameter to automatically populate one of the questions. Try the following:
You will notice that now the Submitted By question is automatically adding the name Fernando Paredes in the survey. Well, that was a URL parameter! Note that immediately after the basic URL of the web form, I added a question mark (?). The question mark indicates that what follows are URL parameters. Next, I added the name of the parameter, which in this case is field:submittedBy and a value for that parameter: Fernando Paredes.
You can add multiple parameters by simply separating them with an ampersand (&). For example:
Next, lets learn about the different URL parameters you can pass to Survey123 web forms.
Some of the URL parameters described here are supported in surveys published with 3.2 or newer versions. If your URL parameters do not seem to take effect, re-publish your survey so it gets upgraded to the latest version, and then try again.
Setting values on questions (field:fieldname)
In the previous section you saw how a URL parameter can set a value to a question in your form, but lets take a closer look at how it works. The syntax is simple:
The name of the parameter is made out of two distinct parts. First, you have the field: suffix and then you have the name of the question where you want to put a value. Figuring out the name of a question can be tricky. The question name should not be confused with the label of the question. The label is what users see in the form. The question name represents the column in your feature layer where the response will be stored.
If you author surveys in Survey123 Connect, I am sure you already know what I am talking about: The question name is represented by the name column in the survey worksheet of your XLSForm. If you design your forms in Survey123 web designer, then finding out the exact name of your questions deserves a more detailed explanation.
After adding a question into your survey in web designer, you need to set its label and other properties, but not the name. The name of your question is automatically assigned by Survey123 web designer. Assigning a valid question name needs to follow very strict rules (the name cannot start with a number, cannot have special characters, or spaces and must be unique within your entire form) and that is why we put that out of your way in designer. This simplifies authoring for beginners, although in cases like this it obscures what is really going on. In any event, you can look at the question names by using the 'Modify Schema' link during the publishing process.
The Modify Schema dialog will let you define the exact names of your questions only when you add your questions to the form for the first time. Once you publish your survey, questions that already exist in your survey will appear as read-only in the Modify Schema dialog. In my case, I really did not want to change anything, I simply wanted to get the names so I could use them with my URL parameters.
Question names are case sensitive. You must pass the exact name. For example, in the oak survey, field:commonName=Oak will work, but field:CommonName=Oak will not work.
Centering geopoint questions (center)
The center parameter lets you set the default location of the geopoint question in your survey. It looks like this:
This parameter accepts a latitude/longitude coordinate pair where the values are separated by a comma. Now. there are a couple of important things to remember when using this parameter:
- This URL parameter only takes effect if the geopoint question is flagged as required, AND
- If authoring from web designer, the option to 'Ask user's location when opening this question' must be disabled'.
If the geopoint question is not required or the user location is used, the values from this URL parameter will be overridden at runtime when the end-user opens the question.
Hiding questions and survey elements (hide)
The hide parameter is handy when you want to control visual aspects of your survey. You can load a survey and hide questions, the navigation bar and more. This parameter takes as an input more or more values, separated by a comma.
|navbar||Hides the navigation bar. That is, the bar at the top of the survey that includes options to login/logout and to change the language. This is particularly useful when you embed your survey within a website. Example.|
|header||Hides the survey header. The header typically includes the title of the survey or alternatively a banner image. This is particularly useful when you embed your survey within a website. Example.|
|description||The description element is optionally included if you author your survey in web designer.|
|footer||Hides the footer element, which includes the Powered by Survey123 link, or an alternative link if you modified it. Also useful when embedding your survey within a website. Example.|
|theme||Use the theme value to disable any custom theme applied to your survey. Example.|
|field:fieldName||This value is used to hide specific questions within your survey. If you want to hide multiple questions, simply add their names separated by a comma. If you want to hide a question within a group, reference it by its full path: field:groupname/questionname. Example hiding the Submitted by and Survey Date questions.|
The hide parameter is very flexible, allowing you to hide multiple elements at once. That is, you can hide the navigation bar, the footer, description and as many questions in the survey as you like. To hide multiple elements, you simply need to keep adding comma separated values to hide the different components. For example:
Another interesting thing you can do is hide a question and at the same time set its default value through a URL parameter. For example, you can hide the Submitted by question in the Oak survey and also set a value for it through your URL parameter.
Adjusting the width of the survey in the screen (width)
The width parameter sets the width, in pixels, of the survey in the screen. For example:
The width parameter is supported on version 3.9 and above.
Edit existing records and opening surveys in view-only mode (mode)
The mode parameter supports two values: edit and view. Combined with the globalid parameter, you can easily open specific records in edit or view modes. For example, here is how you can update an existing record:
There is a lot you can do with this (mode=edit) alone. Go to Survey123 Tricks of the Trade: Editing records in a web form for more details.
Similarly, you can also open a survey in view-only mode.
If you get an error like shown below when using the view mode, you will need to adjust the sharing.
When a survey is shared for viewing, the Survey123 web app uses a special feature layer view built so users cannot edit your data. This feature layer view is created only when you share your survey results for viewing. That is done through the Collaborate tab in the Survey123 website, by selecting the Viewer section and then sharing with the appropriate groups (and clicking save... ).
Redirect the Survey123 web app to your own ArcGIS Enterprise (portal)
While the Survey123 web app is hosted in ArcGIS Online, there is no reason why you can't load surveys from your own ArcGIS Enteprise instance. You do this through the portal URL parameter, which takes as a value the URL of your own ArcGIS Enterprise Web Adaptor. For example:
Set the app that will open your survey (open)
You can use the open URL parameter to determine the app to use with survey. Valid values for this parameter include: web, native and menu.
|web||Opens your survey in the Survey123 web app, as a web form. This is the default. Example.|
|native||Will open your survey in the Survey123 field app. This option will only work if the Survey123 field app is already installed in the device. Example.|
|menu||Will open web page to let the end user decide if the survey should be open in the Survey123 field app or within a web browser. Example.|
Set the language of your survey (lang)
The lang parameter switches the language of your survey dynamically. This parameter only will work if you have included language translations for your survey. For more details on mutiple-language surveys refer to Introducing Multiple Language Surveys
The lang parameter accepts ISO language codes. For example: lang=zh-cn and lang=en.