Callback URLs! How do I get this thing to actually work?
The Premise
Here's the hypothetical scenario:
- You've got an asset feature layer with a related table in your ArcGIS web portal of choice (ArcGIS Online or ArcGIS Enterprise portal) and you've added it to a web map for intended use in ArcGIS Field Maps mobile.
- You've published a Survey123 survey from the feature layer's related table for completing repeat inspections of those assets.
- You want mobile workers to query the asset feature, launch a particular survey in Survey123, and automatically return them to the ArcGIS Field Maps mobile app after submission...
But after searching through documentation and community posts, configuring the syntax for this URL seems clear as mud...
So how do we piece together our URL and configure it?
The Workflow
First of all, we need to write the first part of our URL that will call the alternative app; in this case Survey123. There are two options you can use:
- arcgis-survey123://?portalUrl=https://www.arcgis.com&
- https://survey123.arcgis.app?
In option 1, you can specify the portal URL that you want Survey123 to authenticate through, whether that be ArcGIS Online or ArcGIS Enterprise. In option 2, we are simply calling the Survey123 app with either the default, or the most recent active web portal that was logged into on that mobile device. Users may be prompted to log in, if they have not done so already.
Note: '?' indicates we're going to add a query. '&' indicates we're going to add parameters.
Next, we need to specify our survey's itemID. This is an alphanumeric string that identifies the specific Survey123 form item that we want to access. It can be found by logging into the Survey123 web designer accessing your survey and copying the string from the browser URL. Alternatively, we can log into our web portal > navigate to 'Content' > the survey's folder > access the 'Item Details' page for the 'Form' item > copy the Item ID from the browser URL.
It should look something like this:
- itemID=5550529ee2314fe5b721904854b49456
Next, we might add field matching parameters if we wish to pass an attribute from the feature we're querying to the Survey123 form. We use the syntax, field:<destinationFieldName>={<originFieldName>}.
As an example, I might wish to pass the GlobalID value from my feature layer to the GUID field in my Survey123 form (related table). So I would add the following to my URL:
- &field:GUID={GlobalID}
You can pass multiple attribute values at once using the syntax above and separating each with an '&' symbol. The field names MUST match those within your respective attribute tables.
Lastly, we want to add the callback and accompanying parameters. This can often be the trickiest part to get working successfully.
The following will call the ArcGIS Field Maps mobile app to re-launch:
- &callback=https://fieldmaps.arcgis.app/
Now... Let's add it all together:
BUT WAIT!!!
You need to encode the callback section of your URL in order for it to actually work... We can use websites like https://www.urlencoder.org/ in order to do this. But essentially, we need to encode everything after the 'callback=' part of our URL, so that it looks a little something like this instead:
- https://survey123.arcgis.app?itemID=5550529ee2314fe5b721904854b49456&field:GUID={GlobalID}&callback=https%3A%2F%2Ffieldmaps.arcgis.app
Now you can open Map Viewer, add your configured callback URL to your feature layer's pop-up and enable your mobile workers to smoothly switch between their Map-Centric workflows in ArcGIS Field Maps and the advanced Form-Centric capabilities of Survey123.
Furthermore, if we want to pass an action to the ArcGIS Field Maps mobile app, we can use the 'referenceContext' parameter, added to our callback. The following is simply telling ArcGIS Field Maps which web map to open according to the web map's Item ID:
- ?referenceContext=open&itemID=b7a7a2af1bbc457eaefe5018ef912egd
- Encoded: %2F%3FreferenceContext%3Dopen%26itemID%3Db7a7a2af1bbc457eaefe5018ef912egd
Note: Other examples of 'referenceContext' actions can be found here - https://doc.arcgis.com/en/field-maps/android/help/deploy-your-map.htm