CSL survey variables

Custom Scripting Language (CSL) is a powerful scripting language that can enhance your surveys and reports. You can use it to place variables in your surveys and reports by selecting them from a dropdown.

This article lists the variables available in the Survey Interface (SI), which are as follows:

  • Survey — The survey itself when the respondent is filling it in.
  • Emails — The invitation, reminder, and thank-you email.
  • Notifications — All the different types of notifications.

The default context is always the current survey, current respondent, current contact, and current language.

Syntax

Variables in the scripting language are wrapped with double curly brackets, like this: {{someVariable}}. They are case-insensitive, so {{SomeVariable}} is the same as {{someVariable}}.

Hierarchy

The variables are hierarchical, so you can navigate through them by using dot notation from top-level objects working your way down. The following are the top-level objects in the Survey Interface:

  • Survey — Details of the survey and collection of all questions in the survey.
  • Respondent — Responses and other metadata for the current respondent filling out the survey.
  • Contact — Metadata for the contact filling out the survey. Not all respondents are also contacts.

See the following sections for a list of survey interface variables.

Survey

VariableDescription
{{survey.id}}
ID of the survey.
{{survey.title}}
Survey title in the current language.
{{survey.clientRef}}
Gets the reference to the survey. 
{{survey.maxScore}}
Gets the highest score possible for the survey.
{{survey.dateCreated}}
Shows the creation date of the survey.
{{survey.startDate}}
Shows the start date of the survey.
{{survey.endDate}}
Shows the end date of the survey.
{{survey.status}}
     {{survey.status.id}}
Gets the text label of the status of the survey in the current language – add 'id' to get the id of the status.
{{survey.defaultLanguage}}
     {{survey.defaultLanguage.code}}
returns the name default language in the current language – you can add 'code' to get the language code
{{survey.url}}
     {{survey.url.en}}
     {{survey.url.languageSelection}}
     {{survey.url.otherLanguages}}
Live URL of of the survey in the current language. You can also add a specific language code to the URL for that language.
{{survey.signInUrl}}
     {{survey.signInUrl.en}}
URL of the sign-in page for the survey in the current language. You can also add a specific language code to the URL for that language.
{{survey.privacyNoticeUrl}}
     {{survey.privacyNoticeUrl.en}}
URL of the privacy notice of the survey in the current language. You can also add a specific language code to the URL for that language.
{{survey.printingUrl}}
     {{survey.printingUrl.en}}
URL of the printable version of the survey in the current language. You can also add a specific language code to the URL for that language.
{{survey.editUrl}}
URL of the edit questions page in Agile Research.
{{survey.notifications.editUrl}}
 URL of the manage notifications page in Agile Research.
{{notification}}
     {{notification.id}}
     {{notification.name}}
Only works in a notification.
{{survey.owner}}
     {{survey.owner.company}}
     {{survey.owner.firstName}}
     {{survey.owner.lastName}}
     {{survey.owner.fullName}}
     {{survey.owner.email}}
     {{survey.owner.phone}}
     {{survey.owner.language.code}}
 Information about the Agile Research user that owns this survey.

Questions

Questions refers to a collection of the questions in the survey. Use the following to locate the question for which you are searching:

  • Number — Use the question number. This is not recommended as it is the least safe and most likely to change. If a question is added or removed above the question you need, its number will change
  • ID — Use the unique ID of the question. This is recommended as it never changes even if questions are added or removed. It also does not change if the question is moved.
  • Data label — Use the data label. Like the ID, t does not change if the question is moved or if other questions are added or removed. Its main advantage is that the data label can convey meaning, so 'questions.nps' is easier to read than a number.
VariableDescription
{{survey.questions}}
A collection of all the questions in the survey. Used mostly in each loop.
{{survey.questions.1}}
 Reference to the question in the survey with question number 1.
{{survey.questions.id-1}}
Reference to the question in the survey with ID 1. 
{{survey.questions.myDataLabel}}
Reference to the question in the survey with the data label (recommended method)
{{survey.questions.myDataLabel.id}}
ID of the question with data label 'myDataLabel'.
{{survey.questions.myDataLabel.text}}
Text of the question in the current language. Use the .unformatted suffix to remove all formatting.
{{survey.questions.myDataLabel.questionNumber}}
The question number of the question.
{{survey.questions.id-1.dataLabel}}
The data label of the question with ID 1.
{{survey.questions.myDataLabel.pageNumber}}
The page number of the question.
{{survey.questions.myDataLabel.questionTypeId}}
The type of question; possible values can be found here.
{{survey.questions.myDataLabel.maxScore}}
The maximum score possible for the question.
{{survey.questions.myDataLabel.isHidden}}
 Returns true if the question is hidden else it returns false; often used in 'if' statements.
{{survey.questions.myDataLabel.subQuestions}}
     {{survey.questions.myDataLabel.subQuestions.1}}
     {{survey.questions.myDataLabel.subQuestions.id-123}}
Collection of the sub-questions of a matrix question. To get to specific sub-question, you can either use the order number or the sub-question's ID. If you know the data label for the sub-question, you can use that directly like a normal question. Once you get to the sub-question, you can use all the other properties of a question as listed here such as '.answerChoices'.
{{survey.questions.myDataLabel.answerChoices}}
Collection of the answer choices. You can reference specific answer choices, based either on their order number or ID.
{{survey.questions.myDataLabel.answerChoices.1.id}}
ID of the first answer choice.
{{survey.questions.myDataLabel.answerChoices.id-1.orderNumber}}
 The order number of the answer choice with ID 1.
{{survey.questions.myDataLabel.answerChoices.1.text}}
     {{survey.questions.id-1.answerChoices.1.text.unformatted}}
The text of the first answer choice. Use the .unformatted suffix to strip all formatting.
{{survey.questions.myDataLabel.answerChoices.1.scaleValue}}
 Returns the scale value of the answer choice. In a rating scale or matrix question, the scale of question may start at '0 (zero)' or it may go from -3 to +3. The scale value will return that value. For instance, in an NPS question, the first answer choice has a order number of '1' but a scale value of '0 (zero)' since an NPS question scale goes from 0-10.
{{survey.questions.myDataLabel.answerChoices.1.score}}
     {{survey.questions.myDataLabel.answerChoices.1.score.percentage}}
Returns the score of the first answer choice.
{{survey.questions.myDataLabel.answerChoices.1.isNotApplicable}}
Returns true if the answer choice is a 'Not Applicable' option.
{{survey.questions.myDataLabel.answerChoices.1.isOther}}
Returns true if the answer choice is a 'other ' option.
{{survey.questions.myDataLabel.answerChoices.1.isHidden}}
r
Returns true if the answer choice is hidden.

Results

Get the results of all respondents for the entire survey, a question, a sub-question, or an answer choice.

It is recommended that you use the data label of a question to reference a question as the data label does not change as a survey is edited and makes it clear what the variable holds.

VariableDescription
{{survey.results.respondentCount}}
     {{survey.results.respondentCount.completed}}

{{survey.questions.myDataLabel.results.respondentCount}}
     {{survey.questions.myDataLabel.results.respondentCount.completed}}

{{survey.questions.myDataLabel.answerChoices.1.results.respondentCount}}
     {{survey.questions.myDataLabel.answerChoices.1.results.respondentCount.completed}}
The total number of people that filled in the survey, question, or answer choice. Add '.completed' to only count respondents that reached the end.
{{survey.questions.myDataLabel.results.average}}
     {{survey.questions.myDataLabel.results.average.completed}}
The average scale value to a question across all respondents. Add '.completed' to only count respondents that reached the end.
{{survey.results.averageScore}}
     {{survey.results.averageScore.completed}}

{{survey.questions.myDataLabel.results.averageScore}}
     {{survey.questions.myDataLabel.results.averageScore.completed}}
The average score for a specific question or the entire survey. Add '.completed' to only count respondents that reached the end.
{{survey.questions.myDataLabel.results.sum}}
     {{survey.questions.myDataLabel.results.sum.completed}}

{{survey.questions.myDataLabel.answerChoices.1.results.sum}}
     {{survey.questions.myDataLabel.answerChoices.1.results.sum.completed}}
The sum of all values for a question or answer choice across all respondents. This works for sliders, textboxes with numeric validation, and questions with scale values. Add '.completed' to only count respondents that reached the end.
{{survey.results.scoreSum}}
     {{survey.results.scoreSum.completed}}

{{survey.questions.myDataLabel.results.scoreSum}}
     {{survey.questions.myDataLabel.results.scoreSum.completed}}

{{survey.questions.myDataLabel.answerChoices.1.results.scoreSum}}
     {{survey.questions.myDataLabel.answerChoices.1.results.scoreSum.completed}}
The sum of all scores for a survey, question, or answer choice across all respondents. Add '.completed' to only count respondents that reached the end.
{{survey.questions.myDataLabel.results.nps}}
     {{survey.questions.myDataLabel.results.nps.completed}}
The overall NPS for a question. Add '.completed' to only count respondents that reached the end.
{{survey.results.contactCount}}
     {{survey.results.contactCount.noResponseYet}}
     {{survey.results.contactCount.reachedEnd}}
     {{survey.results.contactCount.completed}}
     {{survey.results.contactCount.screenedOut}}

{{survey.questions.myDataLabel.results.contactCount}}
     {{survey.questions.myDataLabel.results.contactCount.noResponseYet}}
     {{survey.questions.myDataLabel.results.contactCount.reachedEnd}}
     {{survey.questions.myDataLabel.results.contactCount.completed}}
     {{survey.questions.myDataLabel.results.contactCount.screenedOut}}

{{survey.questions.myDataLabel.myDataLabel.answerChoices.1.results.contactCount}}
     {{survey.questions.myDataLabel.myDataLabel.answerChoices.1.results.contactCount.noResponseYet}}
     {{survey.questions.myDataLabel.myDataLabel.answerChoices.1.results.contactCount.reachedEnd}}
     {{survey.questions.myDataLabel.myDataLabel.answerChoices.1.results.contactCount.completed}}
     {{survey.questions.myDataLabel.myDataLabel.answerChoices.1.results.contactCount.screenedOut}}
The number of contacts for a survey, question, or answer choice.
{{survey.results.startPageViews}}
     {{survey.results.startPageViews.contacts}}
     {{survey.results.startPageViews.nonContacts}}
The number of start page views of the survey. This is the number of times the first page of the survey has been requested. You can also get this value for just contacts or non-contacts.

Respondent

These variables refer to the current respondent.

VariableDescription
{{respondent.id}}
ID of current respondent.
{{respondent.hash}}
Unique hash of the respondent.
{{respondent.score}}
Total score of the respondent.
{{respondent.score.percentage}}
The percentage of the respondent's score to the maximum possible score of the survey.
{{respondent.dateResponded}}
The date the respondent answered the survey.
{{respondent.language}}
     {{respondent.language.code}}
The name of language of the respondent in the current language. You can add '.code' to get the language code instead of the name.
{{respondent.status}}
     {{respondent.status.id}}
The status of the respondent: partial, complete, screened out. You can add '.id' to get the number ID of the status instead.
  • 0 — partial complete
  • 1 — complete
  • 2 — screened out
  • 3 — quotafull
{{respondent.channel}}
     {{respondent.channel.id}}
The channel the respondent used to take the survey. Examples include Web, Email, Kiosk, and SMS. You can add '.id' to get the number ID of the channel instead.
{{respondent.completionPercentage}}
The percentage of the survey that has been completed by the respondent.
Note: Respondents that screen out will be shown as 100%. 
{respondent.browser}}
The browser the respondent used to take the survey. Examples include Google Chrome, and Mozilla Firefox.
{{respondent.os}}
The operating system the respondent used to take the survey. Examples include Windows and Android.
{{respondent.thankYouPageUrl}}
    {{respondent.thankYouPageUrl.short}}
URL of the respondent's thank-you page. If the respondent was screened out, this leads to the alternative thank-you page.
{{respondent.reportUrl}}
     {{respondent.reportUrl.en}}
     {{respondent.reportUrl.internal}}
     {{respondent.reportUrl.internal.share}}
The URL of the respondent report for the current respondent. You can specify the language or add '.internal' so that only tool users with access to the survey can see the report, which is often used in notifications. Use '.internal.share' to include all metadata without requiring people to log in.
{{respondent.resumeUrl}}
URL a respondent can use to continue their survey where they left off.
{{respondent.editResponsesUrl}}
URL to edit a respondent's responses. See editing survey responses for additional information.
{{respondent.ipLocation}}
     {{respondent.ipLocation.city}}
     {{respondent.ipLocation.country}}
          {{respondent.ipLocation.country.code}}
     {{respondent.ipLocation.latitude}}
     {{respondent.ipLocation.longitude}}
Location of the respondent based on their IP address. You can add 'city' or 'country' to give just a part of the location.
{{respondent.timing.totalDuration}}
Total time (in seconds) the respondent spent inside the survey.

Respondent answers

Use to get the responses of the current respondent.

It is recommended that you use the data label of a question to reference a question as the data label does not change as a survey is edited and makes it clear what the variable holds.

VariableDescription
{{respondent.questions}}
Collection of the questions that the respondent answered. You can refer to a specific question by using the question's number, ID, or data label. You can also loop through them using an "each" loop.
{{respondent.questions.1}}
Response of the respondent to question number 1. If it is an open question, then it will return the open answer the respondent entered If not an open answer, it will return the text of the answer choice. If that is blank, it will return the scale value. iI there is no scale value, it will return the order number of the answer choice. If the respondent gave more than one answer, as in a checkboxes question, then a comma-delimited list is returned. If the respondent did not answer this question, then it will return nothing and the variable will be replace with a zero-length string.
{{respondent.questions.id-1}}
Response of the respondent to question with ID 1.
{{respondent.questions.myDataLabel}}
Response of the respondent to question with the data label (recommended method). This will return the answer given by the respondent to this question. There is a fallback order in what is returned:

  1. The open answer the respondent entered.

  2. The caption of the answer choice.

  3. The scale value of the answer choice.

  4. The order number of the answer choice.

{{respondent.questions.myDataLabel.styled}}
 A styled representation of the respondent's answer. This is ideal to use inside a notification or report. Don't use this for prefilling or display logic. For instance, if your answer choices have color, that formatting will come through.
{{respondent.questions.myDataLabel.openAnswer}}
The open text that the respondent entered as an answer.
{{respondent.questions.myDataLabel.caption}}
The text of the answer choice itself, NOT the open answer the respondent enters. If more than one answer could be given as in a checkboxes question, then a comma-delimited list is returned.
{{respondent.questions.myDataLabel.scaleValue}}
The scale value of the answer choice the respondent selected. For instance, some questions have a scale from 0-10 or from -3 to +3.
{{respondent.questions.myDataLabel.orderNumber}}
The order number of the answer choice. If more than one answer could be given as in a checkboxes question, then a comma-delimited list of the order numbers is returned.
{{respondent.questions.myDataLabel.score}} {{respondent.questions.myDataLabel.score.percentage}}
The score the respondent got on the question.
{{respondent.questions.myDataLabel.npsType}} {{respondent.questions.myDataLabel.npsType.styled}}
The NPS type: detractor (0-6), passive (7-8), or promoter (9-10) of the respondent based on their response to the question. Add .styled to color this based on the NPS type.
{{respondent.questions.myDataLabel.date}} {{respondent.questions.myDataLabel.date.iso}}
Date representation of the respondent's answer. See Custom Scripting Language (CSL) for additional information about date objects. 
{{respondent.questions.myDataLabel.isNotApplicable}}
Returns true if the answer choice is a 'Not Applicable' option.
{{respondent.questions.myDataLabel.isOther}}
Returns true if the answer choice is a 'other' option.
{{respondent.questions.myDataLabel.subQuestions}}
Collection of the answers from the current respondent to the sub-questions of the matrix question.
{{respondent.questions.myLabel.subQuestions.X.answerChoices.nth-1}}
Use this to get the open-ended response to the 'other, please specify' option in a matrix question. Replace the X with the actual subquestion number.
{{respondent.questions.myDataLabel.subQuestions.1}} {{respondent.questions.myDataLabel.subQuestions.id-123}} {{respondent.questions.myDataLabel.subQuestions.myDataLabel2}}
To get a specific sub-question, you can use the the sub-question's data label, order number, or ID. Once you get to the sub-question you can use all the other properties of a question as listed here, such as '.answerChoices'.
{{respondent.questions.myDataLabel.answerChoices}} {{respondent.questions.myDataLabel.subQuestions.1.answerChoices}}
Collection of the answers to the answer choices from a question. This is used when you want all the answers the respondent gave to a question or sub-question.
{{respondent.questions.myDataLabel.answerChoices.1}}
Returns the answer to the first answer choice. If the respondent did not select this answer choice, then it will return nothing.
{{respondent.questions.myDataLabel.answerChoices.id-123}}
Returns the answer to the answer choice with ID 123
{{respondent.questions.myDataLabel.answerChoices.nth-1}}
Returns the answer to the nth answer choice that the respondent selected. For instance, in a checkbox question and the respondent selects the 2nd and 5th answer choices, then 'nth-1' would be answer choice number 2 and 'nth-2' would be answer choice 5

Contact

VariableDescription
{{contact.id}}
Contact ID of current contact.
{{contact.firstName}}
 First name of the contact.
{{contact.lastName}}
Last name of the contact.
{{contact.fullName}}
First and last name of the contact.
{{contact.status}}
     {{contact.status.id}}
Contact status of the contact.
{{contact.language}}
     {{contact.language.code}}
The name of language of the contact. Add 'code' to get the language code instead.
{{contact.street}}
Street address of the contact.
{{contact.houseNumber}}
House number of the contact.
{{contact.apartmentOrSuite}}
Apartment number or suite number of the contact.
{{contact.postalCode}}
Postal code of the contact.
{{contact.city}}
City of the contact.
{{contact.province}}
Province of the contact.
{{contact.state}}
     {{contact.state.code}}
State or state abbreviation of the contact.
{{contact.country}}
     {{contact.country.code}}
Name of the country or country code of the contact.
{{contact.email}}
Email address of the contact.
{{contact.phone}}
 Telephone number of the contact.
{{contact.gender}}
     {{contact.gender.code}}
     {{contact.gender.isMale}}
     {{contact.gender.isFemale}}
Gender of the contact or some tests that return either true or false.
{{contact.dateOfBirth}}
Date of birth of the contact.
{{contact.isOptedOut}}
Returns true if the contact opted out.
{{contact.isBounced}}
Returns true if the contact's email address bounced.
{{contact.dateAdded}}
Date the contact was added to the survey.
{{contact.dateInvited}}
Date the contact was invited to the survey.
{{contact.dateSawEmail}}
Date the contact saw the email invitation or reminder to take the survey.
{{contact.dateClickedThrough}}
Date the contact clicked through to the survey.
{{contact.dateReminded}}
Date the contact was sent a reminder to the survey.
{{contact.dateRemindedPartial}}
Date the contact was sent a partial response reminder to the survey.
{{contact.dateSecondReminder}}
Date the contact was sent a second reminder to the survey.
{{contact.dateToExpire}}
Date the contact's invitation to the survey expires.
{{contact.dateResponded}}
Date the contact answered the survey.
{{contact.dateSentThankYouEmail}}
Date the contact was sent a thank-you email.
{{contact.dateToBeInvited}}
Date and time that the contact was to be invited.
{{contact.dateLastModified}}
Last date and time that the contact was edited.
{{contact.customFields}}
Collection of all custom fields. Useful for each loop.
{{contact.customFields.1}}
     {{contact.customFields.2}}
     {{contact.customFields.3}}
     ...
Returns the contents of a custom field. Change the '1' at the end to return the other custom fields.
{{contact.customFields.custom_field_name}}
     {{contact.customFields.custom_field_name_2}}
Use the name of the custom field instead of the number. This makes the variable more legible and understandable. Spaces in the custom field name are replaced with underscores (recommended method).
{{contact.surveyUrl}}
     {{contact.surveyUrl.en}}
     {{contact.surveyUrl.languageSelection}}
     {{contact.surveyUrl.otherLanguages}}
Rhe 'live' survey URL for this contact.
{{contact.reportUrl}}
     {{contact.reportUrl.en}}
     {{contact.reportUrl.internal}}
URL of the respondent report for this contact. You can specify the language or add '.internal' so that only tool users with access to the survey can see the report, which is often used in notifications.
{{contact.optOutUrl}}
     {{contact.optOutUrl.en}}
URL of the opt-out page for this contact.
{{contact.showEmailInBrowserUrl}}
     {{contact.showEmailInBrowserUrl.en}}
URL to show the email invitation in the browser.

Miscellaneous

VariableDescription
{{querystring.parameterName}}
     {{querystring.q1}}
     ...
Value of a parameter in the querystring of the survey URL.
{{currentDate}}
     {{currentDate.date}}
     {{currentDate.time}}
     {{currentDate.utc}}
     {{currentDate.iso}}
Current date, including the time. You can optionally select just the date or the time

also available: the date in UTC (Coordinated Universal Time) and the date in an ISO 8601-compliant format.

Note: All these date properties are also available for any other date (e.g., respondent.dateResponded). 
{{regionalSettings.timezoneOffsetHours}}
     {{regionalSettings.timezoneOffsetMinutes}}
Time difference between the survey owner's local timezone and Coordinated Universal Time (UTC). This is based on the setting in the user profile of the survey owner.
{{account.company}}
Company name of your Agile Research account.