Help Center

  1. home
  2. Help
  3. Logic
  4. CSL – Survey Variables

CSL – Survey Variables

CheckMarket offers a powerful scripting language to enhance your surveys and reports called the CheckMarket Scripting Language or CSL for short.

At its most basic level, it is easy to use. You can use it to place variables in your surveys and reports by selecting them from a drop-down.

This article lists the variables available in the Survey Interface (SI). Which includes the following places:

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

Basic concepts

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. Here 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 meta data for the current respondent filling in the survey
  • Contact: meta data for the contact filling in the survey. Not all respondents are also contacts

List of survey interface variables

VariableDescription
{{survey.id}}
ID of the survey
{{survey.title}}
survey title in the current language
{{survey.clientRef}}
get the reference to the survey
{{survey.maxScore}}
get the highest score possible for the survey
{{survey.dateCreated}}
show the creation date of the survey
{{survey.startDate}}
show the start date of the survey
{{survey.endDate}}
show the end date of the survey
{{survey.status}}
     {{survey.status.id}}
get 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 the CheckMarket tool
{{survey.notifications.editUrl}}
URL of the manage notifications page in the CheckMarket tool
{{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 CheckMarket user that owns this survey.

Note that ‘Questions’ is plural. This means that it is a collection of the questions in the survey. But how do you find the question you are looking for? Well there are three ways:

  • Number: use the question number (not recommended)
    easy to use, but it is 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 (recommended)
    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, it 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 some number
VariableDescription
{{survey.questions}}
a collection of all the questions in the survey – used mostly in ‘each‘ loops
{{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 ‘myDataLabel‘ (recommended method)
{{survey.questions.myDataLabel.id}}
ID of the question with data label ‘myDataLabel’.
{{survey.questions.myDataLabel.text}}
the 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}}
returns true if the answer choice is hidden

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

We highly recommend using 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 clearer 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.

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: Web, Email, Kiosk, SMS, etc. – 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 that respondents that screen out will show as 100%.
{{respondent.browser}}
the browser the respondent used to take the survey: Google Chrome, Mozilla Firefox, etc.
{{respondent.os}}
the operating system the respondent used to take the survey: Windows, Android, etc.
{{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. Read more.
{{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

Get the responses of the current respondent.

We highly recommend using 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 clearer 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 a ‘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 – if 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 check-boxes 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 ‘myDataLabel’ (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 themselves.
  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. 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 formating will come through.
{{respondent.questions.myDataLabel.openAnswer}}
the open text that the respondent entered themselves 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 check boxes 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 check boxes 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. More info about date objects can be found in the Date Operators section in this article.
{{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}}
To get the open ended response to the ‘other, please specify’ option in a matrix question. Replace the X by 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 either 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
VariableDescription
{{contact.id}}
the contact ID of current contact
{{contact.firstName}}
the first name of the contact
{{contact.lastName}}
the last name of the contact
{{contact.fullName}}
the first and last name of the contact
{{contact.status}}
     {{contact.status.id}}
the 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}}
the street address of the contact
{{contact.houseNumber}}
the house number of the contact
{{contact.apartmentOrSuite}}
the apartment number or suite number of the contact
{{contact.postalCode}}
the postal code of the contact
{{contact.city}}
the city of the contact
{{contact.province}}
the province of the contact
{{contact.state}}
     {{contact.state.code}}
the state or state abbreviation of the contact
{{contact.country}}
     {{contact.country.code}}
the name of the country or country code of the contact
{{contact.email}}
the email address of the contact
{{contact.phone}}
the telephone number of the contact
{{contact.gender}}
     {{contact.gender.code}}
     {{contact.gender.isMale}}
     {{contact.gender.isFemale}}
the gender of the contact or some tests that return either true or false
{{contact.dateOfBirth}}
the 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}}
the date the contact was added to the survey
{{contact.dateInvited}}
the date the contact was invited to the survey
{{contact.dateSawEmail}}
the date the contact saw the email invitation or reminder to the survey
{{contact.dateClickedThrough}}
the date the contact clicked through to the survey
{{contact.dateReminded}}
the date the contact was sent a reminder to the survey
{{contact.dateRemindedPartial}}
the date the contact was sent a partial response reminder to the survey
{{contact.dateSecondReminder}}
the date the contact was sent a second reminder to the survey
{{contact.dateToExpire}}
the date the contact’s invitation to the survey expires
{{contact.dateResponded}}
the date the contact answered the survey
{{contact.dateSentThankYouEmail}}
the date the contact was sent a thank-you email
{{contact.dateToBeInvited}}
the date and time that the contact was to be invited
{{contact.dateLastModified}}
the last date and time that the contact was edited
{{contact.customFields}}
collection of all custom fields. Useful for each loops
{{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}}
the ‘live‘ survey URL for this contact
{{contact.reportUrl}}
     {{contact.reportUrl.en}}
     {{contact.reportUrl.internal}}
the 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}}
the URL of the opt-out page for this contact
{{contact.showEmailInBrowserUrl}}
     {{contact.showEmailInBrowserUrl.en}}
the URL to show the email invitation in the browser
VariableDescription
{{querystring.parameterName}}
     {{querystring.q1}}
     ...
the value of a parameter in the querystring of the survey URL
{{currentDate}}
     {{currentDate.date}}
     {{currentDate.time}}
     {{currentDate.utc}}
     {{currentDate.iso}}
the 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}}
the time difference between the survey owner’s local timezone and UTC (Coordinated Universal Time). This is based on the setting in the user profile of the survey owner.
{{account.company}}
the company name of your CheckMarket account.

 

Related articles

September, 2020 Alexander Dobronte

Leave a Reply

Your email address will not be published.