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:
|
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:
|
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:
|
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.