Skip navigation
All Places > Survey123 for ArcGIS > Blog > 2016 > July
2016

The purpose of a URL scheme is to provide a well-known protocol for apps to communicate with each other. Through a custom URL scheme you can remotely launch apps and invoke actions in them.  Specifically, the URL scheme in Survey123 allows you to:

 

  • Launch the Survey123 app
  • Open a survey
  • Prepopulate answers in the survey

 

A common practical scenario for using the Survey123 custom URL scheme is integrating Survey123 with other ArcGIS apps like Explorer, Collector for ArcGIS or even your own web mapping apps. Take for example a case where you want field users to use a map to identify a particular asset, and then use a smart form in Survey123 to capture information about that particular asset. Explorer, Collector or a plain Web Map can serve the first purpose.


In this post I will first describe the syntax of the Survey123 custom URL scheme, then how to execute a call with it and later how to integrate URL scheme calls into feature popups in ArcGIS Web Maps, so other ArcGIS Apps can leverage it.

 

About the Survey123 Custom URL Scheme syntax

 

A call to Survey123 through its URL Scheme looks something like this:

 

arcgis-survey123://?itemID=89bc8c7844e548e09baa3aad4695e78b&field:AssetID=FF34001&field:Status=Good&center=43.567,-117.380

 


Let’s break it down:


The first bit is pretty obvious: arcgis-survey123:// invokes the Survey123 mobile app. For this to work, the Survey123 app must be installed in the device in which the call is being made.


Everything after arcgis-survey123:// are optional parameters that you can pass if you want the app to do additional things. The list of parameters starts with a question mark (?).


Parameters are separated from each other through ampersands (&). Each parameter is actually made of two parts: the parameter name and the parameter value, which are separated by the equal (=) sign.  The rules for how to properly pass parameters are common to how you build query strings for the web.


The itemID parameter (itemID=89bc8c7844e548e09baa3aad4695e78b) refers to the survey you want to open. If the survey is not already in the device, the app will attempt to download it automatically. 

 

To obtain the proper itemID for a survey follow these instructions:

 

1.    In a web browser, login into survey123.arcgis.com
2.    Click on the survey for which you want the itemID
3.    Now get the ID of your Form from the location bar of your browser.

 

For example, if the URL of your survey looks like this:

  http://survey123.arcgis.com/surveys/3d02eec41a224902ab4c44e6d39319c8  , the itemID will be: 3d02eec41a224902ab4c44e6d39319c8

 

The app will automatically attempt to download the survey as specified in the itemID parameter.  If the survey is shared publicly, it must be stored in ArcGIS Online. Public surveys are not supported in Portal for ArcGIS.  If the survey is private, the survey will be downloaded using the currently logged-in user. If no user is logged-in, a dialog will prompt the user for credentials.


In the example above we use the field:AssetID and field:Status parameters to prepopulate questions in the survey.  If you want a survey to open and have some or all questions already answered, you will add as many field parameters as needed. Field parameters always are prefixed with the word field:  After that, you enter the name of the actual question for which you want to set the answer, then you add an equal sign and the answer. For example:

 

  • field:AssetID=FF34001 will populate the AssetID question in your survey with the value FF34001.

 

Here are some tips when passing field  parameters:

 

  • The value to insert immediately after field: is the value of the corresponding NAME question in your XLSForm. Do  not pass the Label!
  • The value to insert after the equal (=) sign is the actual value that will be stored in the feature service. If you are working with select_one type of  questions this is very relevant, since the value you must pass is that of the XLSForm Name of the choice, rather than its Label.
  • Passing field parameters for questions within a repeat or attachments is not supported at the moment.
  • If you would like to prepopulate a question, but do not want to user to change its value, flag the question in the XLSForm as read-only.


The last parameter we pass in the example above is center=43.567,-117.380.  This will set the location of geopoint questions in your survey at the provided coordinate pair. You must pass a latitude-longitude pair in decimal degrees separated by a comma as no other coordinate systems or formats are supported.

 


Invoking a Custom URL Scheme call: The Basics


If you would like to give this a quick try, I recommend that you use a web browser to experiment. Start by downloading the Survey123 app into your desktop. You can download it for Windows or for your Mac. Once you have the app, manually launch it and login to download a couple of surveys. Then get the itemID of one of them to start and use it to adjust the itemID parameter:  arcgis-survey123://?itemID=insert your own Form item ID here Then paste it into your web browser to launch Survey123 and open one of the surveys you downloaded. Continue experimenting by pre-populating survey questions.


Once you feel comfortable with the syntax of your URL scheme links, try in your own device. Start by e-mailing the URL Scheme invocation to yourself, and using it from your device's web browser. You can also use Survey123 URL scheme strings to configure hyperlinks in an email, or include them as part of a web page.

 


Invoking a Custom URL Scheme call from a Web Map


Things get pretty interesting when Survey123 URL scheme links are used within an ArcGIS Web Map. This allows you to integrate Survey123 into other ArcGIS apps, by allowing users to launch Survey123 from the popup of a Web Map in Collector for ArcGIS, Explorer for ArcGIS or even a web application. This gets interesting for a couple of reasons:

 

  • First, you can use a map centric app to help the user find a particular asset or location, then easily launch Survey123 from that app to capture data using a smart form.
  • Second, you can use the existing attributes of a feature in the map and pass them into the form to prepopulate answers. This is extremely useful to ensure, for example, that the unique ID of an asset as identified in your map, is passed into Survey123.

 

To embed custom URL scheme calls within a Web Map, you will want to edit the popup of an existing layer. Choose the Configure Pop-up option in the layer’s menu.

 

Next, select the Custom Attribute display as shown in the next screenshot.
 


In a Custom Attribute display you can now embed your Custom URL scheme call as a hyperlink. You can ignore the warning indicating that the value is not valid.  If you prefer, you can also work directly using the source HTML view of the popup.
 


As shown below, you can reference attributes from the underlying feature in your Survey123 custom URL scheme by enclosing the name of the feature attribute within curly brackets.


 arcgis-survey123://?itemID=89bc8c7844e548e09baa3aad4695e78b&field:AssetID={assetid}


With this technique, you will be populating the AssetID survey question with whatever value is present in the assetid attribute of the feature’s popup. This will ensure that captured data in Survey123 can always be associated back into the feature selected in the map.

 

Field names are case sensitive in iOS. Ensure  you reference your feature service fields with the exact capitalization used in the feature service.

 

If you want to pass lat/lon values from attributes in your feature, be aware that the default formatting rules for the double data type cut-off decimal values to two. You will want to adjust the formatting rule to pass all decimal values to Survey123.

   1) Open the 'Configure pop-up dialog of your feature layer's and then select 'Configure Attributes' .
   2) Now select the attributes with your latitude and longitude values and pick the number of decimals you want to include in the Format drop-down option in the right side of the dialog.


If you want to pass lat/lon values from the geometry in a feature, you can add an Attribute Expression to your popup do dynamically get the lat/lon values from the geometry of your feature.

   1)
Open the 'Configure pop-up dialog of your feature layer's and then select 'Configure Attributes'.
   2) Add a new Attribute Expression.
   3) Look for Geometry under the Globals tab and fetch Geometry($feature).x
   4) Use the Edit link at the top to give your expression a friendly name
   5) Repeat steps 2 through 4 to create a second expression for the y coordinate.


Once your Web Map is ready, you can next use it within multiple applications such as Explorer* for ArcGIS, Collector for ArcGIS as well as your own web mapping apps.

 

Tip: Check Announcing a handy tool to generate Survey123 URLs if you would like to automate the generation of Survey123 Custom URLs for us in popups.

 

 

Invoking a Custom URL Scheme programmatically


In a web app or website, simply create an HTML link:

<a href='arcgis-survey123://?itemID=89bc8c7844e548e09baa3aad4695e78b'>Launch Survey123</a>

In QML AppStudio for ArcGIS:

Qt.openUrlExternally('arcgis-survey123://?itemID=89bc8c7844e548e09baa3aad4695e78b')

In Java, using Android's Intent:

PackageManager manager = mContext.getPackageManager();

Intent i = manager.getLaunchIntentForPackage(
"com.esri.survey123");
i.setData(Uri.parse("arcgis-survey123://?itemID=89bc8c7844e548e09baa3aad4695e78b"));
startActivity(i);

 

 

 

[This post was updated on October 30, 2018]

The earliest known official or large-scale celebration of Pi Day was organized by Larry Shaw in 1988 at the San Francisco Exploratorium. Pi Day has been observed in many ways, including eating pies, throwing pies and, we have been told, cutting the 1.6 build of Survey123 for ArcGIS which you can today enjoy.

 

First things first: You can now update your Survey123 mobile app. Updates are available from the iTunes and Google Play app stores If you would like to refresh Survey123 Connect, go to the Download page.  Both Connect and the mobile app are now at version 1.6.x.

 

Here is a summary of the work that went into the 1.6 release:

 

Integration with Workforce for ArcGIS: You can now configure your Workforce for ArcGIS projects to launch the survey of your choice right from the Workforce mobile application. This makes data capture with Survey123 much more  convenient: field users keep track of their to-do lists in Workforce, and with a single tap Survey123 will pop with the exact survey needed to get the job done. The Integration with Workforce for ArcGIS help topic describes step by step how to make this happen.

 

Note: The Workforce for ArcGIS mobile application is currently available on iOS only. Android and Windows versions are coming soon.

 

Localization: While the Survey123 web site and help are in English only, both Survey123 Connect and the Survey123 mobile app are localized into the following languages: Arabic, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hebrew, Italian, Japanese, Korean, Latvian, Lithuanian, Norwegian, Polish, Portuguese (Brazil), Portuguese (Portugal), Romanian, Russian, Serbian, Simplified Chinese, Spanish, Swedish, Thai, Traditional Chinese (Taiwan), Traditional Chinese (Hong Kong), Turkish, and Vietnamese.  This update includes numerous localization enhancements.

 

Better offline map support: The 1.6 release includes several key fixes and better documentation for configuring your survey with ArcGIS tile  packages. In short, you can author your offline basemaps in ArcGIS for Desktop (ArcMap or ArcGIS Pro) as tile packages, upload them into your Portal for ArcGIS or ArcGIS Online, and then associate them with  your survey. The Prepare basemaps for offline use help topic describes the process in detail.

 

Documentation: The documentation now gives help for both the desktop and browser workflows for creating and using surveys. At the top of each topic there is a switch for viewing a Desktop or Browser version of the topic. Some topics might be only available for Browser or Desktop. That means the functionality is only available in that environment.
If you have some links saved to your favorite doc pages that no longer work, you might need to update them. To enable the switching we had to add a new level to the topic names.

 

Focused fixes: We had a handful of issues addressed.

  • In Survey123  Connect for example, some of you reported crashes when attempting  to publish surveys including geopoint questions within a repeat. This was a Windows specific issue, which has been addressed.
  • Some of you reported that the date set on newly captured photos was  one month off... and you were right! Fixed too.
  • Regular expressions can now include single backslashes. This one may sound like a minor one, but was  preventing some folks from using email regex in constraints as described in our Formulas help  topic.
  • Devices running Google's  Android N Preview are now supported.
  • External selects now support labels using UNICODE strings
  • Image questions can now be displayed in Operations Dashboard for ArcGIS as part of popups.

 

We continue paying close attention to your feedback in GeoNet and use it to prioritize our work. We are now looking into our next update, which will probably need to wait until September. Keep your questions coming!