Understanding Survey123's custom URL Scheme

130757
335
07-29-2016 11:14 PM
IsmaelChivite
Esri Frequent Contributor
57 335 130K

.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]

335 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 III

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.

BFerri
by
New Contributor II

An oldie but a goodie! This just saved me so much time - thanks!

MartinKoli1
New Contributor

Hi there!

I'm struggling in same way as others. I would like to open a Survey123 form for the certain feature (polygon) from WebMap Viewer, Explorer, Collector or Field Maps pop-up. I tried many different ways from various threads, blogs, docs here. I still finish with a good opened form but without wanted record. Please, what am I missing? What's wrong with my expressions.

arcgis-survey123://?portalUrl=https://www.arcgis.com&itemID=68af1826e56148958c416a67357ce9f4&mode=edit&globalId={globalid}

 I checked upper/lower cases, tried to switch upper/lower, tried relative/absolute values for globalids... Please, help me.

Thank You, Martin

MichaelBruening
New Contributor III

@MartinKoli1if you are using an Operations Dashboard with an "Embedded Content" panel, then try this version of the URL within the "URL" parameters. Also make sure you set the "Type = Features", "Content Type = Document", and possibly increase the maximum number of "Features Displayed".

https://survey123.arcgis.com/share/68af1826e56148958c416a67357ce9f4?mode=edit&globalId={GlobalID}&ve...

 

MartinKoli1
New Contributor

Thank You @MichaelBruening , but it doesn't work.

Only web form is loading. And it is still loading and loading... It shows error of "Editing is not possible because the record specified by the globalId parameter cannot be accessed." I'm not sure I think web forms cannot access existing records, Inbox feature is not supported yet.

MichaelBruening
New Contributor III

That's odd as I am using this workflow to edit existing features currently. You may need to check the "Collaborate" settings of the Survey123 form/database to make sure this workflow is allowed. Check to make sure it is shared with a group, that the "submitters" are allowed to at least "Add and Update features", multiple submissions are allowed, and the survey is accepting submissions.

Are you the owner of the Survey123 form?

MartinKoli1
New Contributor

Yes, I am the owner. Form is publicly shared. Multiple submission are allowed and workers can add, edit and delete records. Form is accepting answers. Feature services has same setup, add, update and delete attributes and  geometry. Weird, that does not work? :) 

daveostrander
Occasional Contributor II

Hi @IsmaelChivite,

 

I am having an issue when attribute values contain a single quote, such as a person's last name (e.g., O'Brien, O'Malley, or O'Hara), which is then interpreted as the end of the string, and all remaining values being passed are truncated (BUG-000118152). The lost attributes can result in orphaned records in my case since the Survey123 forms add records to a related table. That table depends on the feature's GlobalID being passed to ensure relationship integrity. I could move the GlobalID to the first position of the URL scheme, but then I wouldn't be able to tell that data was incorrectly passed into the related table. So, the lack of a GlobalID foreign key in the related table allows me to search for and manually correct these issues. The URL scheme I am using looks like this:

 

Collector popup URL scheme link:

arcgis-survey123://?itemID=<SurveyItemID>&field:permitnumber={permitnumber}&field:name={name}&field:address={address}&field:email={email}&field:permitguid={GlobalID}

 

To mitigate the behavior, I have replaced the handwritten link in the popup with an arcade expression that uses URL encoding functions to ensure my URL scheme is formatted correctly. Fortunately, this also appears to have resolved the issue with single quotes in the attribute values. Unfortunately, however, this now introduces a far worse problem. All of my attributes get passed except the GlobalID field needed to cement the relationship. As a result, every record created with Survey123 becomes an orphaned record, obviously not the workaround I had hoped to develop. The Arcade expression I am using looks like this:

 

Arcade expression replacing previous manual URL scheme:

var urlsource = 'arcgis-survey123://?'

var param1 = {

   itemID : '<Survey ItemID>'

};

var param2 = {

   permitnumber : $feature.permitnumber

};

var param3 = {

   name : $feature.name

};

var param4 = {

   address : $feature.address

};

var param5 = {

   email : $feature.email

};

return urlsource + UrlEncode(param1) + '&field:' + UrlEncode(param2)+ '&field:' + UrlEncode(param3)+ '&field:' + UrlEncode(param4)+ '&field:' + UrlEncode(param5)+ '&field:permitguid=' + $feature.GlobalID;

 

Which returns this:

arcgis-survey123://?itemID=<SurveyItemID>&field:permitnumber=21-F006&field:name=Ariel%20and%20Nancy%20Smith&field:address=555%20South%20SomeRoad%20Road%2C%20Dwight&field:email=someonesemail45%40yahoo.com&field:permitguid={B3F2E6C2-4AE0-46DB-8648-E3C563A32ECA}

 

The URL looks good to me, but as mentioned previously, it never dynamically passes the GlobalID. At this point, it appears that Survey123 might not be interpreting arcade expression URLs correctly. In addition, I see odd behavior beyond the GlobalIDs being truncated. For example, the arcade Replace() function works intermittently. Initially, my idea was to replace all single quotes with backquotes dynamically. However, this didn't seem to work when the single quotes existed between lower case letters. 

 

At any rate, do you or does anyone here have a solution to using Arcade to build the URL scheme without dropping the GlobalIDs? I have a support request open on the issue, but I wanted to reach out directly to the GeoNet community to see if there might be a solution to this that I am somehow missing. I am using data stored in SDE, ArcGIS Enterprise 10.8.1, and the latest Surve123 and Collector apps, 3.13.229 and 21.0.4, respectively.

Arnaud_Brival
New Contributor III

Hello @IsmaelChivite , 
I am once again in need of your magic! Thanks in advance for your time. 

I have been using successfully the Urlparameter feature for more than a year now but something broke during last update and I cannot figure out what went wrong. Maybe you can help? 

I use a Url in a note to open QuickCapture from Survey123 and pass on a unique identifier to the QuickCapture project user input as a mean to link the survey record with the features generated in QuickCapture.

When I test it in Survey123 Connect the link works fine and generate a project user input in Quick Capture. 

 

seatracker url problem.png

But...on our mobile devices (IOS or Android) I get the following error message.

243447948_199380905629379_7371515044982310303_n.jpg

The link successfully opens the QuickCapture project .. but the project user input is not populated. any idea why?

 Here are my links below (in Bahasa and in English)

<center><b><a href='arcgis-quickcapture://?itemId=5ade304e80df4f5ba8599f66dfc32474&userInput:Report Key=${Route_ID_Key}'>Start tracking patrol</a></center></b>

<center><b><a href='arcgis-quickcapture://?itemId=5ade304e80df4f5ba8599f66dfc32474&userInput:ReportKey=${Route_ID_Key}'>Mulai Lacak Patroli</a></center></b> 

I tried removing the space in 'Report Key' but nothing changed.

Thank you so much for your help and looking forward to yet another magical answer!
Best,

PamelaLocke1
Occasional Contributor

Hi, 

I am trying to put a link to a survey into a webmap pop up, and prepopulate 1 field in the survey.  I would like survey123 to open in the webform because not all users will have survey123 d/l onto their devices.

  I am doing everything through portal/enterprise, so the web address seems like it should be slightly different than through AGOL.  Everything I have tried so far either gives me the "this survey does not exist or is not accessible" error even though the survey does exist, and I do have permissions to submit (i am the survey owner, but created a group and shared it to the group and still have the same error).   Or once, I go the survey to open, but the fields do not prepopulate. 

The link I have been trying is:  https://survey123.arcgis.com/share/13d94a05786846cd9ee1df5ca4ed7f91?portalUrl=https://services.uml.e...

Any thoughts? 

Thanks!
Pamela 

 

 

PamelaLocke1
Occasional Contributor

Replying to myself:  My survey link works and will open in a web browser

https://survey123.arcgis.com/share/7a45d6747c6c4ee6b795e19d15464f63?portalUrl=https://services.uml.e...

I just cant get the field in the survey to auto-populate with the attribute from the feature service. 

Pamela