Custom Variables

Please note we have a new version of our custom variables and this guide is in the process of being replaced.

Often, you will know certain information about a respondent before they respond to your survey, simply based on the place where they saw the survey link.

Custom variables allow you to pass information via the survey web link, which can then displayed within the survey, as well as on any reports generated from the survey.

Because they are transmitted via the URL, Custom variables can only be used by manually editing the values for those variables in the default live survey link e.g. before it is sent out in a letter or email. The link cannot be configured within the SmartSurvey system when creating the survey.

An example web link with the custom variables in blue is:

https://www.smartsurvey.co.uk/s/Surveyname/?Firstname=Bob&Location=Birmingham

Customised links can then be sent manually to respondents. Many organisations use Custom variables by having a CRM system or their website merge these values into the URL when the link is generated for that respondent.

Creating a Custom Variable

To create a variable:

1. Go to My Surveys and select Build in the survey box for the survey you wish to edit. Alternatively you can click on the Survey Title itself
2. In the white navigation bar on the left of the page, click on Custom Variables
3. Click the blue Add Variable button
4. Type a Variable Name in the box. This is the text you want to appear in your survey link, naming the variable
5. Type a Label. This is how the variable name will appear in your results
6. If you want your variable to be required, check the Is Required box. You can find out more about this functionality by hovering over the "?" icon next to Is Requred and it is covered in more detail later on in the guide
7. If you want your variable to be unique, check the Is Unique box. You can find out more about this functionality by hovering over the "?" icon next to Is Unique and it is covered in more detail later on in the guide
8. Click the green Save Changes button
9. If you want to add more custom variables, repeat this process

Certain names for variables are reserved and cannot be used as custom variable names. For security reasons, we would prefer not to publish these. If you choose one when creating a custom variable, you will see an error message prompting you to choose a different name.

Using a Custom Variable

To make a custom variable live, you have to edit the survey link, including the Variable Name (see above) and a value for the variable:

1. From the Home page, click on My Surveys in the blue navigation bar on the left of the page
2. Click the Custom variables in the white navigation bar to the left of the page
3. Click on the Generate Link button to the bottom right of your custom variable list
   
4. Select your desired Tracking Link from the Select a tracking link drop-down box
   
5. Enter the Value you wish to assign to your custom variable
   
6. You should now see your completed link waiting for you in the Copy your link field, you can either copy the link using the blue button to paste elsewhere, or open the link immediately in your browser

Unique and Mandatory Variables

Below the Variable Name and Label text boxes are two tickboxes. These allow you to configure the Survey to require that a variable be present, and / or that the value of the variable is unique for every completed response.

Making a Custom Variable Required

To make it so your survey will only load if a value is present for a particular custom variable, edit the variable as described above, then click the tickbox under Is Required. with this box ticked, the survey will not load unless a value is provided for this variable. If no value is provided, the respondent is shown the same "Survey Link Invalid" message that is shown for any incorrect survey link.

Making a Custom Variable Only Accept Unique Values

To make it so your survey will only load if a provided value is unique, edit the variable as described above, then click the tickbox under Is Unique. With this box ticked, the survey will only load if the value provided for this variable is unique - meaning that it has not been used to complete this survey before. If a respondent accesses the survey using a previously-used value, the "You have already completed this survey" message will be displayed, and the survey is not loaded.

If no value is provided for the variable, then this does not block further responses from being provided with no value. The lack of a value is not in itself considered a value.

Making a Custom Variable Require Unique Values Only

The fact that the lack of a value is not considered as a value means that, for nearly all applications where you'll want to require unique values for a variable, you will also want to make the variable required.

Requiring Unique Combinations of Values

The Is Required and Unique Value functions only work on single variables and cannot check for combinations. If you need to check for unique combinations, then you will need to concatenate (join together) your varables in whatever system is generating the links and then use as single variable in SmartSurvey to receive them.