Using URLs to populate project user inputs
User Inputs
QuickCapture project users tap big buttons to capture types of features. The location of the feature is taken from the location of the device, and the attribute values are either fixed, or calculated on the fly using device variables. On top of this, buttons can be configured to allow user enter additional values through the use of user inputs.
User inputs allow users to enter (or select) a value that is subsequently written to a specific field of a captured feature, and they come in two types:
- Button user inputs – Where the value is entered after a project button is pressed. For example a user entering a count that gets written to the count field of the captured feature.
- Project user inputs – Where the value is entered before a project buttons is pressed. For example a user could enter their cost centre, which then gets written to the costCent field of any records that are subsequently captured.
Both input types support free text (single or multiline) or choice lists to help streamline entry. They ultimately make your your projects more flexible, and help reduce the number of buttons that you need to inlude. However, there are some key differences that you should be aware of before we continue:
- Project user inputs are set up at the project level. Meaning that they can be assigned to any button (from any layer) in the project - as long as the field being updated is text. Button user inputs on the other hand are linked to the specific layer/button/field they were created from.
- Although project user inputs support choice lists, these lists are created managed at the project level. At the current release (1.10), choice lists can't be created from any coded value domains in the target layer. Conversly, button user inputs do support both coded value and range domains.
- Project user inputs support URL parameters, where button user inputs do not. Due to this last point, the rest of the blog will focus on project user inputs only.
To learn more about creating user inputs, see the following blog: https://community.esri.com/t5/arcgis-quickcapture-blog/understanding-user-inputs-in-arcgis-quickcapt...
Project user input URL paramters
From 1.10 of the mobile application, we included support for up to 3 user inputs (up from a previous of 1). This meant that the user could, for example, enter their cost center, the project number and company) and have these values written to specific fields of each and every feature they subsequently captured. Further more, the workflow could be streamlined (and made more robust) if these inputed values could prepulated.
This is possible with the use of a URL paramter. Essentially you can construct a URL that when launched would do the following:
- Launch the QuickCapture mobile app, or if not yet installed on the device, take the user to the appropriate app store so it can be downloaded
- Download and open a specific project
- Automatically populate the project user input(s) with fixed values
For example, the following URL will download a project and pre-populate the cost center project user input with the value ES001:
arcgis-quickcapture://?itemId=ee28345410cc4647a74ef66f54f237e&userInput:001=ES001If the cost center later changed, then the URL would need to be updated with a new cost center and redistributed. Alternatively, the user could manually update the value in the app.
Understanding the URL Scheme
Next up we’ll break down the URL to help you better understand it. So, here we go........
To launch the QuickCapture mobile app, we use the custom URL for QuickCapture:
arcgis-quickcapture://As long as the app is installed on the device, this link will launch it.
To launch the QuickCapture mobile app, and download/open a specific project, we use this:
arcgis-quickcapture://?itemId=<id>- ? is put in front of any parameters included in the URL.
- itemID is the itemID parameter name
- = is the operator
- <item id> Should be replaced with the item id of the project that you want to download/open. In the example above it was: ee28345410cc4647a74ef66f54f237e
This item id can be easily obtained from the URL of the project when opened in the Quickcapture Web Designer.
To open the project and pre populate one project userInput, we use this:
arcgis-quickcapture://?itemId=<item id>&userInput:<input id>=<value>Lets focus on the the last part of the URL and break it down:
&userInput:<input id>=<value>- & denotes an additional paramter in the URL
- userInput is the userInput parameter name
- : is a seperator between the parameter name and the <input id>
- <input id> is the id of the user input. This is used to map the entered value to the correct user input in the project. These are a string based number, for example 001, 002 or 003.
- = is the operator
- <value> is the value to enter into the project user input
In order to get the <input id>, you need to open the project in the QuickCapture Web Designer and then go into the JSON editor. Then scroll down to the userInput{} array and look for the project userInput you are interested in.
Note that both button and project user inputs are in the same array, so check the mode property is project when copying the id.
Once you understand the URL structure for a single projet user input, it should be simple enough to expand the url to populate all three (if your project supports this many). Take a look at the following example:
arcgis-quickcapture://?itemId=77eb6d7d68c64f928bcd9135b2516e4c&userInput:001=1001&userInput:002=quickcapture@esri.com&userInput:003=RunningThis passes 1001 to project user input 001; quickcapture@esri.com to project user input 002; and Running to project input 003.
Note: Although user input ids may match display order (e.g. 001, 002, 003), this is not guaranteed. Other combinations are possible, e.g: 003, 001, 002.
When constructing these URLS, make sure the values being passed to the project user inputs are valid. For example, if the project user input is a choice list, then make sure you are passing a value that is in the list. Or if the project user input has an input mask applied (restricting the values can be entered), the passed in value needs to comply If this is not the case, the URL will launch the project and open on the project user input page - but no value will be entered. It will then be up to the user to maually enter a valid input.
Finally, a note on URL distribution. You can open the link by pasting it into a web browser, share the link via an email, or even use them to create a QR Code that can be scanned. You can try the latter by scanning the following with your device camera (this will download a test project to try out):
If you want to find out more about the QuickCapture custom URL scheme or the alternative of app links (https://quickcapture.arcgis.app) please see the documentation.