Understanding Survey123's custom URL Scheme

180824
359
07-29-2016 11:14 PM
IsmaelChivite
Esri Notable Contributor
60 359 180K

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

359 Comments
TaraBoswell
New Contributor III

We do have GlobalID, since we did enable offline capabilities, so I can definitely test that out. Wouldn't we run into the same problem though with more than one user working with an offline copy of the editable feature service? Two people out in the field with offline maps are creating features potentially at the same time, and until they sync the data, how would Collector prevent even the GlobalIDs from being replicated? I like the idea of adding the name of the feature layer to survey123 too, thanks!

BrentKinal1
Occasional Contributor III

No need to worry...the chance of a GUID / GlobalID ever being repeated is infinitely small. 

TaraBoswell
New Contributor III

Fantastic! Much appreciate the advice

daveostrander
Occasional Contributor II

Call me anal, but I would love to see a single feature service that has related surveys.

In example, create points via a desktop web mapping application (Web AppBuilder), open Collector and navigate to said points with Navigator, arrive at destination and return to Collector, bring up point attributes and launch a related survey123 form record, fill out the form using drop downs, radials, etc..., attach images, fill out notes/comments sections using a stylus (i.e. Apple Pencil) and then attach as another image, immediately send completed survey form to a recipient as a PDF via email, return to Collector, and launch a second related Survey123 form record (rinsing and repeating as necessary), return to office and view everything from a single feature service on a web map. As a bonus have workforce be treated as related records too! 

Related records to keep everything connected to a single feature service. Voila the perfect set up! 

daveostrander
Occasional Contributor II

Should have kept reading   . So to be clear, setting up primary and foreign keys (i.e. auto populating GlobalIDs) will ensure a relationship between my feature service and related surveys?

ProvinceBrabant_Wallon
New Contributor

Hello James,

I'm also pretty interested into opening an existing feature and edit it in Survey123, from Collector. Do you know if this enhancement you are talking about is presently handled, and maybe corrected in a soon coming update?

Thanks in advance for your answer.

KadinBaird1
New Contributor

Hi Everyone, I am trying to get Survey123 to launch from a custom web app using a URL scheme inside of the feature pop-up. I am doing it this way because I would like have some of the survey populated with data from the feature layer. I can get this to work on my android tablet but not in a browser. I am using the URL: 

arcgis-survey123://?itemID=04b424a4c3d34868b9cefabef71b0735&field:field_0={City}&field:field_1={Address}&field_2={Pole_Number}&field:field_3={Pole_Type}&field:field_4={Head_Type}&field:field_5={Lamp_Type}

 

Any help would be greatly appreciated.

Thanks 

daveostrander
Occasional Contributor II

Hi Kevin, that behavior is expected since your url scheme is calling the mobile application, and not an http:// address.

JamesTedrick
Esri Esteemed Contributor

Hi Kadin,

By 'not in a browser', are you meaning that clicking on the link in a pop-up in your browser fails to open the Survey123 app?  If so, is this the browser on your tablet or another device?

KadinBaird1
New Contributor

Hi James, 

Yes that is what I mean, I have tried the link on my tablet and it opens the Survey123 app just fine, but on my desktop computer the link opens a new tab but that tab contains nothing.

Here is the link to my web app: ArcGIS Web Application, we are trying to get this to work to allow city residents to report issues with their streetlights directly on the web.  

KadinBaird1
New Contributor

I have tried using an http:// address as well but then the survey pulls up without any of the preset values. 

Is there a way to do that they you know of?

IsmaelChivite
Esri Notable Contributor

Hi Kadin Baird‌  I bet that the Survey123 field app is not installed in your Desktop. Download it from Survey123 for ArcGIS | ArcGIS  and try again.  Thanks,   Ismael

KadinBaird1
New Contributor

Hey Ismael, I too thought that was the problem originally, so I previously downloaded the app onto my desktop before commenting here, and it still will not work.

ChristopherRodgers
New Contributor II

I have had success copying values from Collector to Survey123 forms using the custom URL schema, thanks for all your work on this functionality. However, in some situations the passed values show red in the Survey123 form. In the screenshot below you can see a red value result when data is passed from a field type Double (Collector) to a field type Decimal (Survey123). This is an issue because the user now has to manually type in the value in order for the calculations that are dependent on it to fire. I have seen this occur frequently on iOs devices when the value being passed is above 1000. I have not yet seen this be an issue when the value is below 1000. Has anyone else experienced this issue?

GéomatiqueVRN
New Contributor III

Hi,

The feature layer I use in collector has one text filed that contains single quotes and the corresponding field in Survey123 gets truncated.I replaced the single quote by %27 and "%27" but this does not solve the problem.

I work with android platform.

Any help would be appreciated.

Badradine

GéomatiqueVRN
New Contributor III

Hi,

I finally found the solution for the single quote problem. I replaced ' by &#39 in the attribute table and then published the feature service.

Badradine

TonyViveiros1
Occasional Contributor

Not sure about the 1000 value, but I recently encountered a similar issue and traced the source to an incorrect field type definition.  As I recall, the survey field type was incorrectly defined as text in the xlsform but numeric data entry was expected.  After I changed the field type to integer in the xlsform and republished, the red text went away.

Tony 

ChristopherRodgers
New Contributor II

Thanks for your response Tony. I double checked my field types and created a new survey from scratch. I am still experiencing the same issue when passing numeric values from a field type Double in Collector to a field type Decimal in Survey123. Again, this issue presents itself on iOs, both iPhone and iPad mini, but not if I run the survey from Windows. See screenshots below which are all from the same survey being accessed from different devices:

On iPhone or iPad, passing numeric values (length in feet) from Collector to Survey123 works when the value is less than 1000 and the associated calculation (length in miles in this example) fires correctly.

However, on the same iPhone or iPad using the same survey, if the value being passed is greater than 1000 there is an issue. Note how the survey behaves below. The value is in red and the calculation does not fire.

If I run the same survey from the Windows app there does not appear to be any issue with values greater than 1000 and the survey behaves as expected.

Any thoughts would be appreciated!

FlorentBigirimana
New Contributor III

I finally managed to create a field which links the two data sets. I created a field survey_UID which is filled from a plot layer in Collector and pulled in Survey123 using the custom url. My link is : 

"arcgis-survey123://?itemID=1aa3dfbe16794824ae4c728fe2c9374c&field:Survey_UID={Plot_UID}&field:Plot_ID={Plot_ID}&field:area={Shape__Area}"

The only problem here is  the area does come. I was assuming that collector will transfer the content of Shape_Area field to the field "area" in Survey123, but it is not the case. Does anyone have a work around for this ? 

Best

JamesTedrick
Esri Esteemed Contributor

Hi Florent,

One small thing - there should be 1 underscore in {Shape_Area}.  You may also need to check your popup settings to make sure the field is displayed (it's off by default):

JamesTedrick
Esri Esteemed Contributor

Hi Chris,

I'm seeing the behavior you describe on the survey with the numbers being formatted.  This is occurring in Collector and Explorer when the attribute configuration in the popup specifies the display of the thousands seperator.  To fix, uncheck the 'Use Thousands Separator' for the attribute:

MikeOnzay
Occasional Contributor III

I've been using a popup with a custom url scheme for months without any problems. I tried adding a second link from the same popup and it won't pass the value.

I've added a second custom url to a popup window in a web map that launches a different survey. The form launches without any problems. However, the ID value is not being passed to the (new) repair form.

popup with 2 custom urls

<a href="arcgis-survey123://?itemID=bebe6db8717c40ce8f55acff542a5993&amp;field:ID={ID}" target="_blank">Open Inspection Form<br /></a>

<a href="arcgis-survey123://?itemID=fbc9450254104eb4abecb1057d0f5604&amp;field:ID={StructureID}" target="_blank">Open Repair Form<br /></a>

The first form shows this

arcgis-survey123://?itemID=bebe6db8717c40ce8f55acff542a5993&field:ID=RD35155D3

The second link shows

arcgis-survey123://?itemID=fbc9450254104eb4abecb1057d0f5604&fieIds:ID=

Is this possible?

FlorentBigirimana
New Contributor III

Thanks  James,

However my area field is {Shape__Area} with 2 underscore, and I can tick the display but not Edit option.

BrentKinal1
Occasional Contributor III

I've yet to try the option of opening more than one survey from collector however one thing that throws me off from time to time with the URL schema is the field names are case sensitive, make sure "StructureID" isn't "structureID"  in your survey123 form.

MikeOnzay
Occasional Contributor III

I had the ID parameters backwards. Another set of eyes pointed out what should have been obvious to me. It should be like this

<a href="arcgis-survey123://?itemID=fbc9450254104eb4abecb1057d0f5604&amp;field:StructureID={ID}" target="_blank">Open Repair Form<br /></a>

ChristopherRodgers
New Contributor II

That fixed the issue, thank you James!

Marc-AndreBedard
New Contributor II

Any update on this Brittney ? I have the exact problem !!!

Thanks so much !

GéomatiqueVRN
New Contributor III

Hi James

Would you like to give an example of how to do it?

Thanks,

Badradine

JamesTedrick
Esri Esteemed Contributor

Hi Brittney Gibbons‌, Marc

This can be done currently by having a CSV file with the locations accompany the survey; the pulldata function can then lookup the location parts to set the point.

As an example, take a look at https://survey123.arcgis.com/webclient/cf44ffb345964aa88d402bda7084a50c  the lookup occurs via the bike station id field.

BrittneyGibbons1
Occasional Contributor

Hi James,

I have used external CSV files and also X and Y coordinate fields in the GIS. These work well for static features that we know the coordinates of. However, the issue occurs when a new structure is discovered and added in Collector, which then needs to be inspected immediately using Survey123. The new structure will not have a record in the CSV file or the coordinates in the X and Y fields will not be populated. We also sometimes need to update the location of a feature that we are inspecting in the field and in that case, the locations in a CSV file or coordinate fields are no longer correct. Being able to isolate the X and Y coordinates from the Shape field seems like the only way to get a location for a feature that is accurate at all times.

Thank you,

Brittney

BrandonArmstrong
Esri Regular Contributor

Hi Kadin Baird‌, 

Can you navigate to the following location C:\Users\<username>\Applications\ArcGIS and let me know the names of the folders containing 'Survey123'?

SarahButler
New Contributor II

I have a map in ArcGIS Online that our crews will use to look at 'live' fire data in Collector so they can see if their work location for the day is near an active fire or in a red flag warning zone.  I also have a Survey123 form that has been created from that work location feature layer where they will enter data associated with each work location . I would like to configure the popup in the ArcGIS Online map so that when the crew clicks on the popup link they will open the corresponding record for that work location in the Survey123 Inbox where they can edit fields and submit the data.  They will not collect new data, only edit the data in the inbox.

Any ideas of how to make this work?

Sarah

JamesTedrick
Esri Esteemed Contributor

Currently Survey123 doesn't support the workflow as you describe it.  As of yet, we don't have a parameter to denote 'load this existing feature for editing'.  

An alternative would be to have an Inbox-enabled survey with a query designed for new features (like ID IS NULL) and have Collector open Survey123, from there the user could open and refresh the Form's Inbox to begin editing.

Mennoter_Bals
New Contributor III

Hi nhesp_gis, I'm wondering if you managed to make this work. I am facing the same issue and applied the GlobalID method as described here in this thread. However, the GlobalID that is generated for new features in Collector is not the same as the GlobalID that is copied to the survey. For existing features in Collector it works perfect, but just not for new features. Somehow it seems that a different GlobalID is generated in Collector upon submitting my new feature data. Any help is much appreciated. Thanks!

JamesTedrick
Esri Esteemed Contributor

Hi Menno,

How are you loading the new Collector feature into Survey123?  Currently, you would need to:

1) Enter your feature in Collector

2) Switch to Survey123 with a form that has had the Inbox enabled

3) Refresh the Inbox to get the new Collector feature and open the form in editing mode

CarlHolt1
Occasional Contributor III

Do Custom URLs work in Explorer for ArcGIS for bringing fields over to Survey123?

MikeOnzay
Occasional Contributor III

Yes. I'm doing this now with a sign inventory map in Explorer.

http://doc.arcgis.com/en/survey123/browser/create-surveys/integratewithotherapps.htm

CarlHolt1
Occasional Contributor III

The link appears to open my Survey, but bring over any of the fields, see my Custom URL as an example of fields to be populated in the survey with data from the feature service point.

arcgis-survey123://?itemid=102b96d8619f4f58a6a71ec6974a596a&field:GRNWY_NAME={PROPERTY_N}&field:WATERSHED={CREEK_NAME}&field:GW_ID={GREENWAY_I}&field:GRNWY_TYPE={Fee_CE_Acq}&field:NOTES={NOTES}&field:SPEC_COND_1={SPEC_CON1}&field:SPEC_COND_2={SPEC_CON2}&field:SPEC_COND_3={SPEC_CON3}

MikeOnzay
Occasional Contributor III

You could try passing just one field instead of all of them at once as a test. Otherwise, the other suggestion would be to double check your fieldnames on both sides of the equal sign.

by Anonymous User
Not applicable

Carl,

    You just need to update the custom URL schema to the appropriate schema. You forgot the "$" in front of the filed that you want to pass over. See below
arcgis-survey123://?itemid=102b96d8619f4f58a6a71ec6974a596a&field:GRNWY_NAME=${PROPERTY_N}&field:WATERSHED=${CREEK_NAME}&field:GW_ID=${GREENWAY_I}&field:GRNWY_TYPE=${Fee_CE_Acq}&field:NOTES=${NOTES}&field:SPEC_COND_1=${SPEC_CON1}&field:SPEC_COND_2=${SPEC_CON2}&field:SPEC_COND_3=${SPEC_CON3}

CarlHolt1
Occasional Contributor III

It works when using in Collector. Does Explorer have these capabilities?

MatteoDe_Minicis
New Contributor

Hi,

I'm trying to open a survey from another survey passing parameters and it works if I pass a fixed value for each field:

<a href="arcgis-survey123://?itemID=c08081e730be4c3ebf800676f91b366f&field:QCP=prova"> Apri apparato</a>

But I cannot pass a value filled in my form:

<a href="arcgis-survey123://?itemID=c08081e730be4c3ebf800676f91b366f&field:QCP={QCPQ}"> Apri apparato</a>

I don't understand what I doing wrong, I just added {} to identify the field.

Has anyone experienced with this issue ?

Thanks,

Matteo

CarlHolt1
Occasional Contributor III

In Explorer the text is sent with %24 in the beginning. Do you what the issue could be? I am fairly certain it isn't a space as other spaces are not sent like this.

by Anonymous User
Not applicable

Try this one <a href="arcgis-survey123://?itemID=c08081e730be4c3ebf800676f91b366f&field:QCP=${QCPQ}"> Apri apparato</a>

I added a "$" in front of the field that contains the value you are trying to pass.

JamesTedrick
Esri Esteemed Contributor

Hi Mike, in the pop-up definition, no $ are required.  I can confirm that the latest version of Explorer is not passing over attributes- I'll bring this to the attention of the Explorer team.

CarlHolt1
Occasional Contributor III

Thank you

by Anonymous User
Not applicable

James,
You are correct. I misread the thread and thought that they were passing answers from one form into another form. I use a custom concatenate to create the custom URL to pass data from one form into another form; which is where the "$" in front of the field name matters.

Sorry about that.

JamesTedrick
Esri Esteemed Contributor

Hi Carl, mbrueningesi‌,

On the issue with Explorer - this is a limitation with the version of the new ArcGIS Runtime that the new version of Explorer uses.  Collector is unaffected by this problem.

MikeOnzay
Occasional Contributor III

Do you expect this to be fixed quickly?

JamesTedrick
Esri Esteemed Contributor

The Explorer team is hopeful it will be addressed soon.  This affects popups in general, not just the url links.