Master URL Parameters with ArcGIS Mobile Apps Part 2

Get back into using universal app links to mix and match ArcGIS mobile solutions to support your multi-app field GIS workflows. 

More ArcGIS Field Maps, ArcGIS QuickCapture, ArcGIS Survey123 and ArcGIS Dashboards Integrations

Let’s get right back into working with URL links and parameters for workflows with ArcGIS Field apps as demonstrated in my October 14th webinar. Just a reminder you may re-watch the webinar recording, and for more examples of integrations, see the Part 1 blog.

As with the examples in Part 1, I’ve used templates available in ArcGIS Online for my layers, maps, surveys and projects. Just another reminder that syntax counts when using URL links – double-check for spaces and make sure you are using the correct cases for the parameters if your links don’t work at first. In this blog post, I’ll cover:

Using URL links with ArcGIS Survey123 Integrations
URL links to open ArcGIS QuickCapture
Embedding Survey123 into ArcGIS Dashboards

Using URL links with ArcGIS Survey123 Integrations

Survey123 supports form-based data collection on mobile platforms (iOS and Android) as well as Windows, using the Survey123 field app or the web form in a browser. As a result, there are two different sets of links and parameters you may use. Use a URL link to open Survey123 from other ArcGIS apps that support app linking on iOS and Android. Use what is known as the Survey123 URL scheme to open Survey 123 from other ArcGIS apps on Android and Windows, and on iOS for apps with Survey123 approved to allow linking. Survey123 links are the preferred method, but the URL scheme is convenient to create and test your integrations first on Windows before deploying to mobile users. Note the URL structure differs if you are using the link or the scheme and there are also different parameters that work with the survey whether it is opened with the web app or field app.

In the webinar I showed an example going from Field Maps to Survey123. This workflow is useful for when your field crew needs to complete map-based edits for multiple features using Field Maps, but you require a form with more complex XLS form capabilities provided by Survey123. In my demo I used the Survey123 web designer to create a new survey from the template “Favorite Redlands Restaurant Survey”. To structure a URL link to open Survey123 from a web map used in Field Maps, create a custom popup hyperlink. In my demo I used the Survey123 Field App on iOS so my basic URL link structure was:

https://survey123.arcgis.app

To find the item id of your own survey to add to the basic link, browse to your survey folder in your ArcGIS Organization from My Content - the folder will have “survey” in front of its name. In your survey’s folder click on the form item – you’ll obtain the item id from the url from your address browser. The basic link to open my survey in the Survey123 field app is:

https://survey123.arcgis.app//?itemId=24ee292b75424524bae074f6d16b0cba

Find the survey item Id from survey form item details in your ArcGIS Organization content.

Note for Survey123 url links the item Id syntax differs from how it is used in Field Maps. Also, if you wish for your survey to open in a browser using the web form to collect data, you will need to modify the url parameters from this example. A good tip is to go to your Survey123 website and open your survey, and from the Collaborate tab,select Share Survey to open the form in a new tab. From the browser address you obtain the id as well as the link structure to open the web app.

Obtain the url link for opening in your survey in the web form from the Survey123 website Collaborate page.

For my survey, the link to use to open it in the web app is: 

https://survey123.arcgis.com/share/bfa9fc63fdec42dfaf47a2c09f793652

Once you have the link you are ready to create the web map popup, you can configure it using either the classic map viewer or the new map viewer (formerly known as the beta map viewer), which I showed in the webinar demo. Open the Field Maps web map then click on the layer from the layers list on the left panel. You may open the popup editor from the right panel. While my popup contained a number of elements and used Arcade expressions, you’ll at least want to use the Text element to provide the url from your map.

Configure the webmap popup by adding a text element using the new map viewer.

To add a link to the popup, type in the text as you’d like it to appear in the popup, highlight it then click on the link button. Enter the link you constructed for the survey, then click the check box and save your web map to finish.

https://survey123.arcgis.app//?itemId=24ee292b75424524bae074f6d16b0cba

Use the link button in the map viewer popup editor to add the url link to Survey123.

When the web map is opened from the Field Maps mobile app, the user just has to tap on the popup link and the survey will be opened as the currently signed-in user, or if not signed in, Survey123 will prompt them to sign into your ArcGIS Organization.

To further streamline your app integrations, you can pass attributes from the layer in Field Maps to pre-populate survey questions. To can do this using the &field parameter along with the id and field information for the layers you are passing attributes from and to. When using the additional parameters

To obtain the “from” layer attribute, go to the My Content tab in your ArcGIS Organization and find your web map that you are using in Field Maps. Click on the map to open the item details, then from list of Layers click on the layer you wish to pass the attribute from – go to the Data tab and view the Fields. In my webinar I used the Hamilton Restaurant inspections layer where the from field to pass the restaurant name was establishmentname. Next, you need to do the same for the feature layer used to collect data in Survey123. Go to My Content and browse to the folder for your survey. From the folder open the item details for the hosted feature layer and from the Data tab select Fields. For my demo the restaurant name I passed attributes to was restaurant_name.

To construct the Survey123 link to include additional parameters, add &field: and first add the field going to, then using ={} set the from field you are populating from. For my example the url link is:

https://survey123.arcgis.app://?itemID= 24ee292b75424524bae074f6d16b0cba&field: restaurant_name={establishmentname}

During the webinar I had an issue with only part of the text being passed from the field in Field Maps to the survey due to special characters in my restaurant names (apostrophes). The solution to passing all of the text to Survey123 is to modify the url link to be able to pass on the entire string when your fields store special characters. This is documented in the GeoNet forum for Survey123. Note the solution in GeoNet starts from Collector but this also works using the Field Maps url links. You need to build an expression using the Arcade function Replace to replace any special character (my example was an apostrophe) with UTF-8 encoding of the character (in this case is "%27%"). Note if your field contains text strings with more than one apostrophe or other characters, this expression needs to be modified further – the complete character list for UTF-8 encoding can be found online.

First create the Arcade expression for your layer pop up. In the new map viewer from the popup configuration panel on the right side select Manage Expressions. Click on Add Expression and build your expression similar to this one, making sure you save the expression when done.

Create an Arcade expression to find and replace special characters (a single apostrophe) with their UTF-8 encoding.

Once your expression is saved, modify the link in your popup to use the expression instead of the field name, following the example below (find your own expression number from the list of popup expressions).

https://survey123.arcgis.app://?itemId= 24ee292b75424524bae074f6d16b0cba&field:restaurant_name={expression/expr3}

What is great about using a url link is that you can pass multiple attributes from Field Maps to Survey123, streamlining your mobile users’ workflow. There are many more options to explore for integrating Field Maps and Survey123 workflows. The documentation outlines options, as well as this blog post for using the URL scheme or this blog post for using the URL links.

URL links to open ArcGIS QuickCapture

QuickCapture is a big-button data capture app for rapid data collection. Similar to Survey123, QuickCapture supports data collection on mobile platforms (iOS and Android) as well as Windows. You can use a URL link to open QuickCapture from other ArcGIS apps that support app linking on iOS and Android. The QuickCapture URL scheme opens the app from other ArcGIS apps on Android and Windows, and for iOS for apps with QuickCapture approved, it to allow linking. QuickCapture links are the preferred method, but the URL scheme can be used to create and test the link and parameters on Windows before deploying to mobile users. Note the link structure differs if using the link or the scheme and while both methods support the same parameters, there are platform-dependent differences. See the documentation for full details.

To recreate my webinar workflow linking QuickCapture from Field Maps, follow the steps in the Survey123 example above on how to configure a link in the web map popup. I used the Restaurant Occupancy Counter template to create my QuickCapture project. To obtain the id of the project, from your ArcGIS Organization browse to My Content and scroll to your QuickCapture project folder. Click on project item details to get item id from the url in your browser address bar.

Find the QuickCapture project id from the item details in your ArcGIS Organization.

For basic link, use https://quickcapture.arcgis.app/?itemId= for mobile app on iOS & Android or arcgis-quickcapture://?itemId= on Windows. The link I used in the webinar demo was structured as follows:

https://quickcapture.arcgis.app/?itemId=3429f48e6a64490982d800325b4ae150

Just using the basic link with item id opens the QuickCapture project from Field Maps, however you may want to pass parameters from the map layer in Field Maps. As QuickCapture is designed for simplified data capture and largely relies on pre-configuring attributes to button inputs, your option for passing parameters is limited to project user input variables. These allow users to type in attribute values and up to three can be configured per project. In my webinar QuickCapture project, the site_name attribute was a project user input. To add this as a parameter to the url link, find the unique id of the user input variable you wish to populate from the QuickCapture web designer with your project open for configuration. Go to the Additional settings (the three dots on the right side of the menu bar) and select the JSON Editor. From the window that pops up scroll down until you see “fieldInfos”. As I only have one user input for my project the user input is 001.

Find the userInput id for your QuickCapture project from the JSON Editor.

You will need to add these parameters to the end of your link using &userInput:001={ establishmentname}. Also obtain the field name for the layer you wish to pass from in the Field Maps web map – for my example this is the restaurant name field establishmentname.

Set up the parameter using the to-from format, for my example:

https://quickcapture.arcgis.app/?itemId=3429f48e6a64490982d800325b4ae150&userInput:001={establishmentname}

For more details on how to configure your QuickCapture projects to use project user inputs, see the online help.

Embedding Survey123 into ArcGIS Dashboards

Embedding a survey form in ArcGIS Dashboards can be used to support QA/QC and review workflows as it allows users to open a survey directly within a Dashboard for viewing and editing. Dashboards provide a web-based view that can include various elements such as maps, lists and charts to present visual displays about your organization’s data. Including information collected with any of the ArcGIS field apps is an effective way to summarize and present field program results to stakeholders. I showed in my demo how configure an element in your Dashboards to embed a Survey123 web form directly using its URL link to allow users either to view or edit the data right in the Survey123 form.

First, you will need to create your Dashboard, excellent resources are available are in the documentation if you need help. To configure your Dashboard, start from the app launcher in your ArcGIS organization and open your Dashboard in Edit mode. There are different options for elements that can be included in your Dashboard to effectively integrate with Survey123. The example I showed in the webinar, also documented in this tutorial, uses both a map element to display the features collected by the survey, as well as a list element to show individual survey results. Once you have the map and list elements configured, add an embedded content element to contain your Survey123 form. From the configuration options for this element first set your Data options - Type to features and set the target layer to your Survey123 layer. Set the Content type option to Document and for the URL link use the basic Survey123 web form link including your item id. This displays the survey in read-only format. In order to open the survey in edit mode you need to add more parameters to the end of the URL. Add the ?mode=edit&globalId= and click on Fields to select globalid from the list of your survey attributes.

For my webinar example the URL link for editing the survey was set to:

https://survey123.arcgis.com/share/24ee292b75424524bae074f6d16b0cba?mode=edit&globalId={globalid}

Configure the Embedded content element in ArcGIS Dashboards to display and edit within a Survey123 web form using the url links and parameters.

Now that you have embedded the survey form in the Dashboard, if you wish to allow users to select surveys from the map or list elements you will need to link them by using actions. Configuring actions allows elements to work together for a much more interactive and effective Dashboard. In my example the List element was linked to the survey, so Dashboard users may click on a feature in the List and the selected survey will display in the embedded element.

To set the action for the List open the configuration dialog for this element and add select Actions. Set Selection mode to Single and click on Add action. You will need to select the element to link the action – select the Embedded content element, then set the Source field = GlobalID  to the Target Field = GlobalID.

Configure the Action for the Embedded content element to link to the survey to the items in the List element.

If you prefer instead to configure an action for selecting survey features from the map, open the map configuration dialog and select the Layer Actions. Click on Add Action and select the Embedded content element.

Configure Layer actions for the Map element to link to the survey to the items on the map.

There are many more possibilities for using URL links and parameters to integrate your ArcGIS field workflows. I’ve outlined a few here and I hope you’ll explore the documentation further to enjoy creatively mixing and matching with ArcGIS mobile apps to optimize your field operations.

This post was translated to French and can be viewed here.