Hunter Ray, GISP, Technical Services Manager
Creating Survey123 forms in Survey123 Connect provides access to many options for supercharged forms that streamline the user experience and minimize data entry errors. Calculations for questions using the pulldata() function and its various functionalities allow for pre-population of answers, incorporation of advanced logic, external data lookup and other techniques that are not available with standard XLSforms.
The pulldata() Function
The pulldata() function can be used in the calculation and constraint columns of the XLSForm to pre-populate answers and compare answers to external sources. Advanced uses of the pulldata() function include querying ArcGIS Services and other 3rd-party APIs as an option for pre-population of questions and/or constraints on questions. When using the pulldata function to query external 3rd-party API data, there are typically two pulldata functions needed. The first would be the pulldata(“@javascript”) function to initially retrieve the data, and then the second would be the pulldata(“@json”) function to parse/extract, individual properties of the JSON object can be used to pre-populate answers.
JavaScript Functions
Within Survey123 Connect, creators have the ability to create and invoke custom JavaScript functions within survey calculations to expand and enhance the basic XLSForms functionality. JavaScript functions can be used for both simple and complex functions. One of the simplest example uses of a JavaScript function in a Survey123 form could be converting input text to uppercase, something easily done in Excel spreadsheets, but not inherently capable in XLSForms. Another simple function that requires JavaScript is the ability to split a text entry using a character such as a comma or hash. As mentioned above, a more advanced use of a JavaScript function in a form would be to query a 3rd-party API using an HTTP request to get a JSON object response, and then use a secondary pullday(“@json”) calculation to parse the response and extract JSON object values.
Querying ArcGIS Layers
One of the newest functionalities of the pulldata() function is the ability to query ArcGIS Services using the pulldata(“@layer”) function. Before October 2022, this type of query was only possible using a custom JavaScript function. With the enhanced functionality specifically for use with ArcGIS Services, the request is much easier to construct and manage and can be executed in a single-line calculation expression in the XLSForm. There are a few different ways to construct the pulldata expression to further refine the type of query (spatial or non-spatial) and whether or not the entire JSON object is needed or a single attribute within the JSON object. To see the syntax of the calculation with a few clicks, create a new survey using the sample “Query a Feature Layer” in Survey123 Connect.
Survey123 Connect allows creators an array of options to create powerful and user-friendly Survey123 forms. Specifically, incorporating the various functionalities of the pulldata() function as a calculation or constraint can take your forms to the next level and save time for both GIS administrators and field users.