ichivite-esristaff

Survey123 Tricks of the Trade: Web form URL parameters

Blog Post created by ichivite-esristaff Employee on Feb 6, 2019

Many web applications support the notion of URL parameters; 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:

 

The Basics

 

Lets first get familiar with how surveys get loaded into the Survey123 web app. Take the following URL:

 

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765

 

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:

 

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?field:submittedBy=Fernando Paredes

 

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:

 

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?field:submittedBy=Fernando Paredes&field:commonName=Oak

 

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:

 

field:commonName=Oak

 

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. 

 

Modify Schema in Survey123 web designer

 

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:

 

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?center=34.1,-117

 

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:

 

  1. This URL parameter only takes effect if the geopoint question is flagged as required, AND
  2. 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.

 

Parameter ValueDescription
navbarHides 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.
headerHides 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.
descriptionThe description element is optionally included if you author your survey in web designer.
footerHides 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.
themeUse the theme value to disable any custom theme applied to your survey.  Example.
field:fieldNameThis 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. 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:

 

...?hide=field:submittedBy,field:surveyDate,theme,footer

 

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.

 

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:

 

https://survey123.arcgis.com/share/acb28b212b5542acbbdbaa35feba0765?portalUrl=https://acme.com/gis

 

The above URL will load into your web browser the survey with identifier acb28b212b5542acbbdbaa35feba0765 as found in the https://acme.com/gis ArcGIS Enterprise instance.

 

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.

 

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?open=menu

 

Parameter Value Description
webOpens your survey in the Survey123 web app, as a web form. This is the default. Example.
nativeWill 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.
menuWill 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.

Outcomes