Understanding Survey123's custom URL Scheme

180886
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
joerodmey
MVP Alum

This method will not work in Survey123

As for Collector, have you turned on editing in the feature service?

CHRISJONES10
New Contributor II

In collector using a downloaded map I want to be able identify on a feature and get the attribute window with the link to open survey123.  As far as the feature service that is created from survey123 it is editable.

by Anonymous User
Not applicable

Hey CHRIS JONES, is this existing data or new data that is being collected? If it is existing data, then I would look into this blog - https://community.esri.com/groups/survey123/blog/2017/09/25/working-with-existing-feature-services-i... that helps explains the uses of Collector and Survey123 using the custom URL to pass parameters.

I have been successful in using a Collector based map to open Survey123 forms for existing data sets. I know that there are some users that have been able to accomplish this while collecting new data also.

CHRISJONES10
New Contributor II

The features I'm wanting click on and see the attributes to get link for Survery123 are exist but it not a feature services, its a map layer. I'm able to it in a none download map but when I download the map to the device it seems to lose that function.

JamesTedrick
Esri Esteemed Contributor

Hi Chris,

By a 'map layer', has the data been loaded directly into the map, or was it added as a Feature Layer into your content and then added to the map?  The latter would be the preferred method, and is the one documented in Collector's help pages - see Prepare maps for offline use—Collector for ArcGIS | ArcGIS  

by Anonymous User
Not applicable

"Passing field parameters for questions within a repeat or attachments is not supported at the moment". has this limitation been addressed? I have a need to pass data form a related table in Collector into a survey123

FGArcOnlineForesite_Group
New Contributor II

I have successfully integrated a custom URL scheme to open Survey123 from Collector, but I am noticing that instead of updating the existing asset with data collected in Survey123, that a new point feature is created instead. What is the best way to have the point feature updated with the data collected via Survey123?

Thank you,

JR

ShanaGail1
Occasional Contributor

Hi JR,

I'm in exactly the same boat.  Asked the question about a workaround in this other thread about a week ago, but haven't seen a reply yet.  https://community.esri.com/thread/208613-pass-global-id-from-collector-to-g

Thanks,

Shana

RamiAlyGad
New Contributor II

 Ismael Chivite

Thanks for all of your helpful content. I have used the URL scheme in multiple applications from collector to survey123, but I have a new workflow that is causing me some trouble.

I have a web app that uses the URL scheme in the pop-up to open the Survey123 field app on a Windows Laptop. I can't seem to get the link to prompt Survey123 to open. Do you have any suggestions? The link is below:

arcgis-survey123://?itemID=cdbc37f68e2742b29cdb80470e72496e&field:foreman=Rami%20AlyGad&field:unit=6255&field:workclass_flag=P&field:oh_ug_flag=UG

Should it be different for Windows? I tried cutting it out to the bare minimum without extra parameters, but I that approach has the same result.

Regards,

Rami

RobBlash
Occasional Contributor III

The URL parameters are not different for Windows. I'm able to launch surveys from a web map on Windows 10. I  haven't tried via web app but I don't see why this would make a difference.

Have you tried a different browser? Whenever folks in my org have issues Chrome doesothe trick 9 times out of 10.

joerodmey
MVP Alum

I've tried your link in the stripped down form (arcgis-survey123://?itemID=cdbc37f68e2742b29cdb80470e72496e) on both IE and Firefox and it opens my field app on my Windows machine as expected.

RamiAlyGad
New Contributor II

Rob  and Joe ,

Thanks for your responses. I have tried from Web Map and Web App in both Internet Explorer and Chrome. None of the combinations seem to work. I am facing this issue both on a Dell Windows laptops. 

After getting a hold of the testers' machines, I found that the machines are running on Windows 7. I am guessing that is the issue. I have requested to re-image to Windows 10 and am hopeful that will do the trick.

RobBlash
Occasional Contributor III

How locked down are the machines? Try re-installing Survey123 as an admin,

maybe the uri was not properly registered during install.

joerodmey
MVP Alum

If worst comes to worse, do you have the option to strictly use the web app instead of the field app for your users?

RamiAlyGad
New Contributor II

They are pretty locked down, but luckily I do have an admin account. On the user's machines, it was installed in the default method and location. I also have a Win 7 Dell laptop and tried installing into the Program Files instead of as a User application and saw no difference in result.

RamiAlyGad
New Contributor II

Unfortunately, the Drafts capability of the field app is an essential part of the workflow.

TonyGroeneveld2
New Contributor III

Can I open a survey to display/edit the results of a previously entered survey. For example my survey has a point question in it. Data is entered for a survey. Then in collector the points are displayed on a map the user clicks on a point and from the popup clicks on an url link that opens the specific survey associated with that point.

AurelieShapiro
Occasional Contributor II

In Survey123 you can see sent surveys and drafts and edit those and sync, but not in a map interface.

If you want to do it in map interface load the survey results feature service (editing enabled) into a web map or app you can then edit it – there is an editing template, or just use the web map. Or you can also use Collector to edit on a mobile device..

Nicole_Ueberschär
Esri Regular Contributor

Hi Rami, 

I tried your link in Edge and it works fine to me. Edge was asking me though if I want to switch apps in order to open the Survey123 app. Could it be that a pop-up blocker is blocking to open another application?

When I paste the link to Chrome I am redirected to the google page...

From Firefox I am also prompted to have the survey opened in Survey123. 

InternetExplorer gives me the following warning:

 Survey123 warning IE

RamiAlyGad
New Contributor II

Nicole,

Thank you for taking the time to test. At this point, I am inclined to believe the link doesn't work for me because I don't have any Windows 10 devices to test with. Your test would be in line with that hypothesis, being that you have Edge would mean you are running on Windows 10. My testers had originally told me their devices were Windows 10, but I later found that they are Windows 7. Unfortunately, it will take some time before the machines are re-imaged so that I can run a successful test.

Regards,

Rami

LiamWhite
New Contributor II

I have put together a URL scheme for a Pop-up in Workforce. It loads the survey and populates the first field i request (Trading_Name), but i can't get it to populate any further fields after this point:

arcgis-survey123://?itemID=c6f75a074f9d45fca6c6cf2f06e4247e&field:TradingName={Trading_Name}&field:Risk={Classification}

any suggestions for how get the URL to populate multiple fields in the survey?

Nicole_Ueberschär
Esri Regular Contributor

Hi Liam, 

normally it should work with adding more fields with a & as you did. If it is not populating the data it might be due to a misspelling of the field name or the question name where the answer is populated to. At least that was always my problem...

LiamWhite
New Contributor II

Hi Nicole, thanks for your response.

I have taken the spelling directly from he relevant fields, and have checked that it is accurate. The only other thing that I could possibly think of is that I am using pop-ups from Workforce, which might work differently to other apps?

RobBlash
Occasional Contributor III

That was my thought as well (maybe workforce doesn't support multiple

fields). Try putting that same URL in a web map popup and see what happens.

I know for a fact that multiple fields are supported in web maps via

browser and Collector.

SusanEnyedy_Goldner
Esri Contributor

Hi James, as this is an old post, just wondering if there is any update to being able to use the url scheme to pass a parameter to denote 'load this existing feature for editing'. I got the question if the survey point can be clicked on from the map Collector or Explorer, and opened this way in Survey123 loaded for editing,

Thanks! Sue

JamesTedrick
Esri Esteemed Contributor

Hi Susan,

This feature has not yet been implemented; support for this is planned in the web form (in a limited context) in the next release.

GeeFernando
Occasional Contributor

Would someone be able to elaborate on this solution (the referred content is no longer there)

Currently, I'm trying to implement a custom URL to open Survey123 and bring in some fields (on 10.4.1)

Any help is greatly appreciated.

Thanks,

Gee

DerrickWestoby1
New Contributor III

James and/or Ismael - I have a survey built with the beta version of Survey123 Connect, which contains a geoshape question. The survey is for project managers to define an area that they would like to have imagery acquired for, and I would like to allow them to use existing taxlots/parcels to define this geometry.  I'd like to launch this survey from a web map containing taxlots, but have a couple questions that I was hoping you could answer before I take a crack at it:

1. Can I pre-populate a geoshape question with correct geometry from a feature layer containing area features? (Click the taxlot you'd like mapped, launch survey123 with the taxlot being used in a geoshape question) 

2. Can I launch the survey in a web browser (or Ops Dashboard embedded content) instead of the app?

3. Can I add log-in credentials via the URL? 

Thank you

JamesTedrick
Esri Esteemed Contributor

Hi Derrick,

Geoshape support is in beta currently.  We plan to make the shape calculable, though we may need to investigate the way to get the parameter in the appropriate format to be read by Survey123.  Geoshape support is not yet available for the web form; credentials cannot be passed.

deleted-user-hyxJSx81t8OL
New Contributor

Hi,

I tried this and followed the procedure. However, I am getting projected coordinates(meters) when I use Geometry or Centroid. I figured it was because of the projection of the feature I uploaded so I created a new one, set the projection to WGS84 and uploaded again. But it seems the upload changes the projection to WKID 102100. Has anyone experienced this or can anyone suggest a fix? Thanks.

JamesTedrick
Esri Esteemed Contributor

Hi Johnel,

The Arcade geometry functions produce coordinates in the web map's coordinate system.  Usually this is Web Mercator (3857/102100).  You need to use a basemap in WGS 1984 (4326) - ArcGIS Online has several appropriate basemaps in this coordinate system.

TonyViveiros
New Contributor III

Hello...is passing field parameters from Collector to S123 no longer possible for fields with a relevant expression? This no longer works for me. I also checked previous surveys that worked but now do not (I haven't changed anything). I'm using S123 3.3.64 but also tested with 3.4.96 without any success.

Thanks.

by Anonymous User
Not applicable

Hi Tony,

Yes that is correct, it is no longer possible to send values via custom url to questions that are not relevant when the form loads. We used to store values in fields that were not relevant, which was wrong and considered a bug as when sending the survey those values got stored in feature service. This was fixed in a recent release which means now the question must be relevant on load to store the value.

Phil.

AdamCottrell
Occasional Contributor II

Ismael, James, and/or James,

I'm scratching my head on this one... So I have a web map that is used in Explorer to find location and open Survey 123 with a field populated and center on lat,long.  The field gets populated in the survey but the geopoint/map in the survey does not get centered.  When I look at the point that gets generated in the hosted feature service, it is off the coast of Africa.  When I click on this link in the web map it opens a new browser tab and the Lat,Long look good.  Below is what I have as the hyperlink link and the second  is what it returns in the web browser.

arcgis-survey123://?itemID=MYitemID&field:apn={apn}&center={expression/expr0},{expression/expr1}

arcgis-survey123://?itemID=MYitemID&field:apn=001.0025.0002.11&center=38.35441308400005,-81.64341213599992

Any help would be greatly appreciated!

by Anonymous User
Not applicable

Hey James, if this did go through in the release, could you point me to any doc or geonet posts available on opening or loading an existing feature for editing in Survey123 online?

RobBlash
Occasional Contributor III

I would love to hear if this is available now, particularly in the app. We have a huge survey with 100+ records in the inbox at any given time, each with many attachments. Performance is not great with this setup, so the ability to target  a specific feature to edit (in app) would be huge!

JamesTedrick
Esri Esteemed Contributor
JamesTedrick
Esri Esteemed Contributor

Hi Rob,

This has only been introduced for the web form at this time.  

I would also encourage you to check out the Early Adopter Community in a few weeks - we've begun some research in improving the Inbox performance and would appreciate your feedback.

by Anonymous User
Not applicable

Thank you! This is great!

RobBlash
Occasional Contributor III

Thanks, will do!

SavannahWinstanley1
New Contributor II

Hi, 

I am wondering if this is tested/usable with opening polygon surveys in the web form. I have tried the following URL in the custom pop-up to open a form, and it flashes as if trying to open something but won't actually open. When testing just the base URL call with itemID only it still does not open in the web form as expected. 

 Additionally, I'm not sure this is possible but it would be great if there were a way to populate the polygon geometry based on an existing feature in the survey, but still have it not edit that existing record?

The intended use case for this survey is to record attendee samples in a small gird of open event space and calculate estimated attendance for various events. 

For this to happen the simplest way for our Events Coordinator would be to open a web map with the sampling grids, use the geolocate feature to find her current location and click the sampling grid she is currently in to open a survey to record the attendance in that sample grid, and based on the number of grids for that park, calculate the total estimated attendance. The below URL call outlines the fields needed for this and the feature class the survey is built from is available at https://mywinterhaven.maps.arcgis.com/home/item.html?id=c065e443fce2451982a6e349292064e0 

arcgis-survey123://?itemID=063e7d330ca3448ea235a15206c0d2f9&field:GRID_ID={GRID_ID}&field:Park_Name={Park_Name}&field:GridArea={GridArea}&field:TotalParkArea={TotalParkArea}&field:NumberofGrids={NumberofGrids}

Any help on this would be greatly appreciated!

Savannah

JamesTedrick
Esri Esteemed Contributor

Hi Savannah,

It is possible to populate a polygon using an existing feature; the input would be the vertices separated by a semi-colon (i.e., y1 x1; y2 x2; y3 x3; ...).  I plan to have a more descriptive blog post out soon, but the following Arcade function can generate this:

var geom = Geometry($feature);
var firstpart = geom.rings[0];
var outparts = [];
var counter = 0;
for (var pt in firstpart){
 var ptstr = Concatenate(firstpart[pt].y, " ", firstpart[pt].x);
 outparts[counter]= ptstr;
 counter = counter + 1; 
}

return Concatenate(outparts, ";")
ChelseaRozek
MVP Regular Contributor

Hi Brandon Armstrong‌ and Ismael Chivite, I realize this thread is old, but I'm having the same problem. I can't open arcgis-survey123://?itemID=cdd7a14129ae47c590c579ec5d4a7136 from a custom popup in AGO Map Viewer to open the Windows Survey123 field app. Just opens a blank browser tab. I have both Survey123forArcGIS and Survey123ConnectforArcGIS installed on my Windows 10 PC.

Nor can I open the link from the webmap in Explorer (sideloaded on Windows 10 PC) to open the Windows Survey123 field app. It just says "You'll need a new app to open this arcgis-survey123".  Any ideas? Thanks

DougBrowning
MVP Esteemed Contributor

Did you install the 123 app with admin access?  It will let you install it without it but then it seems that the file associations do not get set.  So you have the app but windows has no idea to use it with that link.

It was our best guess but we never got an admin to do it.  We just stopped using windows tablets.

Hope that helps.

ChelseaRozek
MVP Regular Contributor

Thanks for the suggestion Doug Browning‌. I just tried that (installed the latest Survey123 field app on my Win10 PC with admin user) but unfortunately (even after a restart) it didn't help. 

KinleyWinchester
New Contributor III

Hi James... 

My query corresponds to question #2 above:

2. Can I launch the survey in a web browser (or Ops Dashboard embedded content) instead of the app?

I have a Survey123 URL in a popup with a dashboard.  The link passes values through to the form along with center.  However, &center=36.2804,-86.87633 is being converted to ¢er=36.28041,-86.87633 and the point is placed at the user's location and not at the point that was selected.

If I do the same action from a webmap, it functions properly.  But I would like this done from the dashboard instead.
Any ideas how to stop this from happening?
BrittneyGibbons1
Occasional Contributor

We are also experiencing this issue when opening a Survey123 form from Operations Dashboard. Pretty frustrating when the behavior in the map and the behavior in the Dashboard is different. 

KinleyWinchester
New Contributor III
Apparently there is a bug logged with Esri about this...
Unsure if they think it has been fixed or not.
BillSimper
New Contributor III

It looks like this field value passing via Survey123 URL scheme is broken in recent versions of Survey123 field app. Forms that utilized this feature are failing with version 3.5 and 3.7, but still work using version 3.2 (posted here). Anyone else noticing this? Did something change with URL scheme (or the concat function)?

JamesTedrick
Esri Esteemed Contributor

Hi Bill,

There haven’t been any changes to the URL scheme; it should be working as it did previously. Can you provide an example the issue you are seeing? Is this in the field app or the Survey123 website?