The pulldata("@layer") function was introduced with Survey123 version 3.16 (October 2022). It allows you to query an ArcGIS layer and retrieve data from it. In this blog, I will explore common scenarios for this function and describe design best practices and limitations.
Querying ArcGIS layers using XLSForm expressions is not a new concept. Back in the day, I described how to do it using custom JavaScript functions. Using custom JS functions gives you great flexibility, but you need to know how to write JavaScript, and most importantly, you can't execute a custom JS function if you share a survey publicly.
The new pulldata("@layer") function simplifies the syntax for querying ArcGIS layers, and it can be used in public surveys too!
The animation below shows a typical scenario for pulldata("@layer"). A calculation takes the location set in the map, and triggers a point-in-polygon query to retrieve a value from the intersecting polygon; a parcel's APN (Assessor Parcel Number) in this case.
I can think of a gazillion cases where point-in-polygon queries will be handy... just think of the polygon layers you may have: parcels, soils, fire perimeters, sales territories, evacuation zones, city boundaries...
Point-in-polygon queries do not strictly require a map in your form: They require a location and a polygon layer. In the example below, the respondent enters an address, and a point-in-polygon query is triggered to automatically calculate the City Code that applies to that location. In this case, the location for your point-in-polygon query does not come from a map, but an address. The City Code comes from the feature layer targeted in your point-in-polygon query.
Point-in-polygon calculations will help you make your forms geographically smarter. You can choose to display the geo-calculated values in the form, or keep them hidden.
You can use the output of pulldata("@layer") to calculate a value, like in the examples above, or to feed a data validation rule. In the next animation, a point-in-polygon query checks if a reported incident falls within a City of Redlands public park. If it does, the report is accepted. If it does not, the user will not be able to submit the form.
Again, we are essentially doing a point-in-polygon query using pulldata("@layer"). In this case, the output of the query is used to check the integrity of the data.
In the example below the respondent enters a customer number and the form automatically populates contact information about that customer. That is all done through pulldata("@layer"): The customer number is used to find a record in the customer layer. If found, the name and email attributes are populated.
Customers, assets, buildings, parts... You can query any ArcGIS layer or table as long as, of course, the user completing the form has access to the layer or table.
Another common use case is that in which you want a survey to stop accepting responses once a certain number of records are submitted. This is also something pulldata("@layer") can do for you. Check out the next screenshot: Through a query to the signup table, we can tell how many people already signed up. A constraint in the form uses this value to allow (or not allow) another person to submit the survey.
Now that we have reviewed some common scenarios, we are going to get hands on...
If you have read this far, you will be eager to start. The pulldata("@layer") syntax is described in this help topic. Have a good read of this topic as it describes the basics very well.
This three-minute video shows, step-by-step, how to construct a simple point-in-polygon query using the World Administrative Divisions layer from ArcGIS Online. If you want to follow along, make sure you have Survey123 Connect version 3.16 or newer.
For your reference, you will find the getValueAt.xlsx file attached at the bottom of this post.
The getValueAt_Constraint.xlsx file shows how you can use the calculated value from the point-in-polygon query to ensure the location chosen by the user falls within a polygon.
Another three-minute step-by-step video building on the previous one. In this case, the getRecordAt operation is used to do a point-in-polygon query and get an entire record. Using the pulldata("@json") function, the record is parsed locally to get multiple attributes efficiently.
Find the getRecordAt.xlsx file in the attachments section below for reference.
On top of the well defined parameters you can pass to the getRecord and getRecordAt operations, you can also pass extra parameters to the feature layer url to perform some more advanced queries. For example:
pulldata("@layer", "getRecordAt", "https://services.arcgis.com/QVENGdaPbd4LUkLV/ArcGIS/rest/services/USFWS_Critical_Habitat/FeatureServ...?distance=1600&units=esriSRUnit_Foot", ${location})
I highlighted in blue the key part where the distance and units are specified. These extra parameters are added to the URL. You need to add a question mark (?) to start adding extra parameters and then separate them with an ampersand symbol (&).
Check the Query (Feature layer) help topic to learn more about all the extra parameters you can use. The Request Parameters section in this help topic describes the parameters that you cannot use.
Survey123 Connect includes a sample called Query a Feature Layer. Have a look at it, as it illustrates some advanced techniques you can leverage to gather statistics and construct dynamic queries.
A one hour session covering pulldata("@layer") was recorded some time ago. More info here.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.