JavaScript functions in survey forms

You can use the pulldata() function to invoke JavaScript functions, allowing you to use advanced techniques and logic beyond what is possible through XLSForm alone.

You can manage and edit JavaScript functions on the Scripts tab of Survey123 Connect. On this tab, you can create a JavaScript file, review the code and test the function. This tab is not a complete replacement for an integrated development environment (IDE), which can provide code validation and best practice analysis to help develop JavaScript functions, but is designed to assist with the integration of these functions in Survey123.

Script tools in Survey123 Connect

The following tools are available on the on menu of the Scripts tab of Survey123 Connect:

  • Script files—Show all JavaScript files located in the Scripts folder of your survey. Select a file to view and edit.
  • Open scripts folder—Launch the file browser at the location of the Scripts folder of your survey.
  • New script file—Create a script file in the Scripts folder of your survey. Enter the filename and click Create.
  • Select function—Highlight the first function in the opened file and present the parameters for testing.
  • Save—Save changes to the opened file.
  • Launch external editor—Launch the systems default JavaScript IDE with the opened file.

Click the Select function tool to test the behaviour of the first function in the file by entering values for each parameter and viewing the output. Once you are finished with the function, you can copy the pulldata statement presented here and paste it in the XLSForm. If you are signed in to your organization, right-click any of the parameters and click Paste token, if required.

Note:
Basic syntax errors are shown on the Scripts tab with an error indicator alongside the line number. Execution error handling must be implemented inside the JavaScript function. Console output is displayed on the Scripts tab, so by including console messages in your function, you can see errors, warnings, and information messages displayed along with the output.

Basic syntax

You can invoke custom JavaScript functions to return values. Use the following syntax to invoke custom JavaScript functions with the pulldata() function:

pulldata("@javascript","yourJSFile.js","yourFunction","parameter1","parameter2")

You must store your custom JavaScript files in a folder called scripts in the survey directory. In the example above, the JavaScriptfunction expects two parameters, but you can add any number of function parameters.

The pulldata() function can also extract specific values from a JSON object produced by a JavaScript function. The following example extracts the attributes.ZIP_CODE field from the JavaScript function run in the json_output question:

pulldata("@json",${json_output},"attributes.ZIP_CODE")

Repeats

You can pass all values from across a repeat into your JavaScript functions. The pulldata("@javascript") function supports two styles of implementation for retrieving the values from a repeat. The one to use depends on whether you want your JavaScript function to interact with one field or many fields in a repeat.

If a question from a repeat is passed in as a function parameter, the JavaScript function receives an array of values from the specified question as follows:

pulldata("@javascript", "yourJSFile.js", "yourFunction", ${question1})

If a repeat name is passed in as a function parameter, the JavaScript function receives the parameter as an array of rows of all the values in the repeat as follows:

pulldata("@javascript", "yourJSFile.js", "yourFunction", ${repeat1}, "question1")

Each of these produces a JSON object with individual questions as properties in that object.

Note:

Accessing values in repeats using pulldata("@javascript") is not supported in the Survey123 web app. You can collect values for a single question in a repeat in the web app using join() to convert the list of values into a character-separated string, and then split the values in the JavaScript function.

Other properties

Sometimes, particularly when using JavaScript to access web services and secure ArcGIS services, you may need properties that are not available through standard XLSForm. Survey123 includes the properties listed below that can be extracted using the following structure:

pulldata("@property", 'propertyname')

  • portalurl
  • token
  • online—A Boolean value indicating whether the device has network connectivity.
  • language—The language currently used in the survey.
  • locale—The Locale object used in the current survey. This property is only useful for JavaScriptfunctions.
  • localeinfo—The AppStudio LocaleInfo object used in the current survey containing the language code in various notations. This property is only useful for JavaScript functions.
  • timezone—The time zone code.
  • utcoffset—The offset in hours from universal coordinated time (UTC) for the local time zone.
You can use these properties with the pulldata("@javascript") function. The following example uses the token property to generate a token for a feature service:

pulldata("@javascript","myJSFunctions.js","returnFirstIntersectingFeature","https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_ZIP_Codes_2016/FeatureServer/0",string(${location}),"*",pulldata("@property","token"),true)

Known limitations

The following are known limitations when using JavaScript functions in survey forms:

  • Document Object Model (DOM) is not supported.
  • Frameworks such as JQuery, Ember, and Angular are not supported.
  • You cannot access local files.
  • Asynchronous calls are not supported.
  • JavaScript functions are only supported in forms completed by users in the same organization as the form author.
  • JavaScript functions are not supported for public surveys.
  • A pulldata("@javascript") function cannot be called inside a pulldata("@json") function on the Survey123 web app.