Understanding Survey123's custom URL Scheme

116312
325
07-29-2016 11:14 PM
IsmaelChivite
Esri Frequent Contributor
55 325 116K

.Updated August 10, 2020 (Added reference to Arcade UrlEncode operation)

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, QuickCapture, Collector 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 will open right away.  If the survey is private, it 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, Explorer 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.

A few quick tips when creating popups:

  • When passing text attributes with spaces, you will want to use the urlencode ArcGIS Arcade function. Otherwise, your links may get cut off at the first space encountered.
  • 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 ArcGIS Explorer, Collector 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]

325 Comments
BillSimper
New Contributor III

Hi James,

Yes, specifically I've been using the calculation parameter of XLSFORM to assemble the URL and create the link as a text question type to dynamically pass field values (text and numeric data types) as above. Here's a typical example using the concat function:

 

concat('<a href="arcgis-survey123://?itemID=XXXXXXXXXXXXXXXXXXXXXXXXX&field:parent_uuid=',${survey_uuid}, '&field:individual_id=', ${individual_id}, '&field:alive_dead=', ${alive_dead}, '&field:sex=',${sex}, '">Click here to open a CHILD form.</a>')

The correct form is opening up when the link is clicked, but no data being passed in. This is on forms where this was working previously, so had been tested and was working-- and continues to work when run using version 3.2.

JamesTedrick
Esri Esteemed Contributor

Hi Bill, 

Would you be able to share the form?  A couple of things that may help debug:

- Can you create a test form that exposes the url outside of the <a> tag so that you can see it get created?

- Do any of the questions you are using in the URL have relevant statements?

JamieLambert
Occasional Contributor III

Hi Chelsea,

Hope this helps - Is the Windows version of the Survey123 field app installed in the default file location? Or did you install it somewhere else or rename folders?

My understanding is that when you launch Survey123 from a URL it is looking for the application in a specific folder in a specific location. If the location/folders don't match, it wont work.

Jamie.

AdamBakiera
Occasional Contributor

"Passing field parameters for questions within a repeat or attachments is not supported at the moment."

Does anyone know if this is supported now?

IsmaelChivite
Esri Frequent Contributor

Still not supported. Sorry.

mariaibal
New Contributor III

Good afternoon, I have tried to follow the tutorial step by step, however it has not worked as it should. I say this because when using the created url that redirects to the survey of "Survey123" it does not take into account the position of the selected point, but rather it takes into account the position of the device on which the survey was opened. This is the URL I made to try without getting a successful result. If I open the URL on a computer, the location does not take it into account, but on a cell phone or tablet it does.I Attached screenshots to show the problem.

Thanks and have a great day

arcgis-survey123://?itemID=d491d0be8e0d45e889e5c1143837ba5a&center={latitud},{longitud}&field:Codigo_otea={Id}

RobBlash
Regular Contributor

Try creating an arcade expression to combine the lat long, then reference

that expression instead of the separate lat and long fields

mariaibal
New Contributor III

 I do it as an arcade expression, but only works with computer navigator (Mozzila firefox, Microfost edge, Etc.) And I need works with the android Survey123 Application too...

// Converts Longitude from metres to decimal degrees
var originShift = 2.0 * PI * 6378137.0 / 2.0;
var lon = (Geometry($feature).x / originShift) * 180.0;

// Converts Latitude from metres to decimal degrees
var originShift = 2.0 * PI * 6378137.0 / 2.0;
var lat = (Geometry($feature).y / originShift) * 180.0;
lat = 180.0 / PI * (2.0 * Atan( Exp( lat * PI / 180.0)) - PI / 2.0);

// Combines the features coordinates to the Google Street View URL
var url = Concatenate("https://survey123.arcgis.com/share/d491d0be8e0d45e889e5c1143837ba5a?center=" , lat, ",", lon);
return url;

This is the expression I used, what can i change to opens from Arcgis collector to Survey123 (Both Android Applications)

Nicole_Ueberschär
Esri Regular Contributor

I'm afraid this is a bug that somehow changes the center into ¢ character when opened in Collector (if I recall correctly, this was reported for happening when opening the survey from a dashboard but I could reproduce it also from collector). Can't find the correct bug right now...

mariaibal
New Contributor III

And that bug have a temporary solution?

RobBlash
Regular Contributor

You can do this with an Arcade script

RobertTaylor5
New Contributor II

All works exactly as described when working w/ iOS (in this case Collector 20.2.1, Build 2844; Survey123 version 3.9.149 ) but problems arise when using the app on Android devices (Collector 20.2.0, Build 2952, Survey123 version 3.9.149).  Specifically, the hyperlink does not function as a hyperlink (typically shown in blue font) but is displayed simply as text (gray font).   

DustinBaumbach1
Occasional Contributor

Hi Ismael Chivite and James Tedrick‌,

Thanks so much for posting this helpful guide to survey123 custom URLs. I noticed at the bottom you have placed a snippet of java code for android development. Does this code work for embedding your Suvey123 form in a native android application written in Java? or is there a separate code structure for that? If so, is there some example you can direct me to?

Thank you,

Dustin Baumbach

Loma Linda University

DustyJordan
New Contributor II

At the time of writing this article, passing data from Collector to a repeat within Survey123 was not supported. Does anyone know if this functionality has since been added/developed in the Collector-Survey123 workflow? 

JFBuzzetti1
New Contributor

I've followed this step by step and even though I'm able to launch Survey123 from Collector, it does not edit the existing feature; it just adds a new point at that location. Anyone know what I might be doing wrong?

Nicole_Ueberschär
Esri Regular Contributor

Hey Juan Buzzetti‌, 

the edit mode is currently not supported with using the URL scheme for Survey123 from Collector. It is only working with the Webform at the moment.

RenéGonzalez
New Contributor II

Does the pre-populate function work with the web form version of Survey123? I'm trying to pre-populate a field within the web form version of Survey123 and not through the actual Survey123 app. We have a lot of users and have our users submit their surveys through the web form since they can access it anymore. 

Any help is greatly appreciated! 

yaserkhouja
New Contributor II

Can I use the custom URL to update an existing record? or create a new related survey record (relational table)?

JoseGarcinuno
New Contributor

Is there a way to open through this workflow the inbox , right now at least for me, when I follow this workflow I am able to just add new records into my survey123, but if I want to edit existing record through the feature_Service option and then INBOX, I can not follow this workflow. Let me know if I am missing something. Best regards.

I just read that this is not supported yet. 

MichaelBruening
New Contributor III

Jose,

I would take a look at this help page to get a better feel for how you can use a custom URL to open a Survey123 form within the Inbox. I am unsure if you want to use a Survey123 form, a webpage url, or a webmap pop-up, or something else to open the Inbox.

https://doc.arcgis.com/en/survey123/reference/integratewithotherapps.htm

I am using the following "calculation" for a "note" question within one Survey123 form to open a different Survey123 form into the "Inbox" for the user to "manually" refresh and use previously submitted forms.

concat('<a href="arcgis-survey123://?itemID=def0d5e7ddb94e1fb45############&folder=inbox','">','Click here to open a Mileage/Fuel Data Entry Form','</a>')

You could give this a try, but you will have to replace the "bold" text with the ArcGIS Online ID of the Survey123 form. You can find this by going to the Survey123 form details page and once there you want a portion of the URL there "item.html?id=". You will copy the text behind this and insert it into the one above for the bolded text. Then you can change the "Click here to open a Mileage/Fuel Data Entry Form" to something that is more fitting for your survey.

I know this works within the most current BETA application that is available through the ESRI Early Adopter community. We are currently testing the release candidates...

Cheers!

Mike

JoseGarcinuno
New Contributor
Hello Mike, thank you very much for your post. I was able to open my survey123 form from the hyperlink, now I am trying to figure it out how to pass an UniqueID value to the inbox folder and open that record instead to see the all list.
The workflow would be.
Using an offline map then click in a feature this trigger the popup click on the link and from here open the inbox and edit the record.

AliciaRitzenthaler
New Contributor III

I am trying to open and edit already submitted surveys in an operations dashboard. Any suggestions on how to resolve the following error would be greatly appreciated. 

"Editing is not possible because the globalId parameter was not provided"

My survey is published in version 3.10.239. The URL I'm using is:
https://survey123.arcgis.com/share/df751061341341a687df7f394e365f02?mode=edit&globalId={globalId}

In my dashboard I have a map layer action filtering my related table (where my survey responses are saved) when I select a feature.

@IsmaelChivite? Others?

 

JamieLambert
Occasional Contributor III

@AliciaRitzenthaler likely in your case you need mode=edit&globalId={globalid}

{globalid} or {globalId} is used depending on how the data was created (for example, ArcGIS Online vs Pro).

I find the best thing to do is use the Fields:{} dropdown to insert the globalid into the URL. This way you are pulling it from the data directly and it will match exactly.

globalid or globalId.png

 Hope this helps.

Jamie.

 

EmilySpeck
New Contributor II

I will have my field workers use a Survey123 map. I have a feature layer on arcgis online that has existing sites they need to go to. How do I prepopulate some questions in the survey using the existing sites in arcgis online? I want to repeat that the new survey has not been used yet. 

Philip-Wilson
Esri Frequent Contributor

Hi @EmilySpeck,

If you want to prepopulate a survey with values from a existing feature layer in the web map, you can use the custom URL scheme to launch Survey123 and pass in the values into those questions. This is done by creating a URL in the pop-up in the web map in AGO. The survey then needs to be configured and have the corresponding questions to pass the vlaues into. Please refer to blog post above which details how to do this. 

Is this the workflow you are after? 

Regards,

Phil.