Accessing survey data points with scripting

Data points are objects that capture the responses to the questions in a survey. Their format varies depending on the question type. The author must explicitly define what data points the script needs access to.

Survey object names

Scripting works by referencing survey objects (or survey questions) by name. Therefore:

  • The survey question names must be unique within the survey. In the case of a name conflict, only the first object is returned.
  • The author must update object references when they change survey question names. If names do not match, the scripting engine will return a 500 response code error pointing out the broken reference.

Question name parameters should be literal static values. Passing in dynamic variables will not work.

When you refer to survey objects, you can use single quotes or double quotes as a matter of preference.

Response Data Points

const q1 = response.getDataPoint('Q1');

In this example, Q1 is the question name.

Data point metadata

You can access the following read-only values for any data point. These values do not change during script execution.

Property Description
dataPoint.lastVisitedAt

The UTC date and time when the question was last viewed. If the question was never viewed, the value is undefined.

This value is updated:
  • When the application renders the survey page containing the question.
  • When question responses are auto-punched.
  • Regardless of whether the question is skipped, hidden, or shown.
dataPoint.startedAt

The UTC date and time when the question was first viewed. If the question was never viewed, the value is undefined.

This value is updated:
  • When the application renders the survey page containing the question.
  • When question responses are auto-punched.
  • Regardless of whether the question is skipped, hidden, or shown.
dataPoint.lastRespondedAt

The UTC date and time when the question last received a response. If the question has never received a response, the value is undefined.

This value is updated when:
  • The respondent navigates to the next survey page. When this happens, lastRespondedAt is updated for all completed questions on the page.
  • Question responses are auto-punched.
  • Question responses are updated by a script.

Validation

Any data point value changed by a script will be validated by modern survey responding. Validation is performed in two stages:

  • Schema validation. This is to make sure the data is in the correct format. If the data point format is incorrect, the entire response will fail with a 400 error (Bad Request).
  • Data validation. This is to make sure the data point value is correct for a specific question (for example, a required number of answers is provided for a Multiple Choice question). If data validation fails, the data point Status in the database will be set to Incomplete and the response will continue.

Modern survey responding performs an additional data points check while navigating to the next page. If it finds any Incomplete data points that are required to have a correct value on the current page, it will prevent navigation to the next page by returning a 500 error. This logic applies to any data point regardless of whether it was set by a script or by UI.