LimeSurvey Manuals

Access Control

By default, LimeSurvey allows anyone who can find the survey to participate. Usually, this means that respondents will have been sent a link to an active survey. For many reasons, you may wish to limit access to a pre-selected group of respondents. LimeSurvey handles this by using personalized tokens. If you choose to enable it, LimeSurvey can also allow for public registrations. This means that anyone with the link can register for a token. This ensures that respondents provide a valid e-mail address, and the use of tokens allows participants to save and continue a survey later, which might be a good idea for very long surveys.

What is a token?

A token is a personal, unique identifier given to each participant in a Survey. LimeSurvey can generate random tokens when you set up participants, or you can set them manually. A token is associated with one specific person, and more personal data (first name, last name, email, and any other data you choose to specify) is linked with each token.

It is important to note that the term ‘token’ can mean two things; in LimeSurvey, a token is a code that uniquely identifies a respondent, and nothing more. By default this is a random string of 15 characters and numbers, but you can specify the exact tokens to be used, or the length of randomly generated tokens. This code can be used to link additional (prior) information to a specific response and/or respondent, but in itself it is meaningless.

The term token as it is often used in this manual and in other sources means the code, and all the information associated with it. In essence then, the token is the respondent, or at least the prior information we have about the respondent.

How do tokens work?

Enabling tokens on a survey will block access from anyone who does not have a token. LimeSurvey makes it easy to send participants a personalized e-mail inviting them to participate, including a link to the survey with the token.

Using tokens

To make access control work, you need to enable tokens, create a list of participants (tokens), generate the actual token strings, and invite participants with their token. The rest of this manual will explain these steps.

Enabling tokens

You can enable tokens at any time, you do not have to have finalized or activated the survey first. To enable tokens, click the ‘token management’ button from the survey menu bar. Token management button

LimeSurvey will warn you that enabling tokens will limit access, press the initialise tokens button when you are sure.

Token management screen, add tokens button

You are now in the token control screen. The top of the screen shows the token menu bar, replacing the default menu(s). To go back to the survey menu bars, press the home button in the top left. From left to right, the buttons are; home, token summary (the current screen), view tokens, add tokens, add dummy tokens, manage additional attributes, import tokens from CSV, import tokens from LDAP, export tokens to CSV, edit e-mail templates, send invitations, send reminders, generate tokens, drop token table and bounce settings. The final button takes you to the LimeSurvey manual site.

Create a list of participants (tokens)

For now, click the add tokens button. You can now create a token for each participant. By default, the token has three attributes with information on the participant, containing first name, last name and email address. The other fields are used within the system to keep track of email address validity, invitation and reminder emails, validity periods, etc. You do not have to enter anything other then the names and email address, although you might want to define a period of validity.

Importing a large amount of tokens

In theory, you can use this form to create a token for each participant, but with large surveys it is often faster to import tokens from a CSV file to automatically create a large amount of tokens. See the ‘Importing tokens from a CSV file’ section below.

Using more prior information

If you already have some more information about your participants that you would like to add to the tokens, you can do this with custom attributes. See the ‘custom attributes’ section below.

Generating token strings

Once your token table is ready, you need to generate the actual tokens, if you have not set them manually. Click the generate tokens button (the sprocket icon) to have LimeSurvey generate a random 15 character token for each participant. This is the ‘access code’ respondents have to enter to fill out a survey. If you send invitations through LimeSurvey it is automatically added and respondents should never have to fill it out themselves. However, you could also create them yourselves. One example where this might be useful is if respondents can also fill out a paper survey, and the LimeSurvey token needs to match the survey code of the paper version.

Sending invitations

Rather then manually sending each participant an invitation to the survey with their personal token, LimeSurvey allows you to send a batch of automatically generated invitation emails, as well as reminders.

Editing e-mail templates

To get started, you may want to review the default e-mail template. Click the ‘edit email templates’ button (the open enveloppe icon). The screen now shows the template for the invitation e-mail, the tabs at the top allow you to edit the templates for the other e-mails LimeSurvey can send autmatically.

When editing the templates, the following field names are allowed in invitation/reminder email templates and must be entered in the survey properties. When sending out the emails these field names will be already replaced in the preview of your invitation/reminder email.

{ADMINEMAIL}

Email of the Survey admin

{ADMINNAME}

Name of Survey Admin

{SURVEYNAME}

Title of your survey

{SURVEYDESCRIPTION}

Description of your survey


The following field names are allowed in invitation/reminder emails (subject and/or body) and will be replaced while sending out the mails:

{EMAIL}

Email of the recipient

{FIRSTNAME}

First Name

{LASTNAME}

Last Name

{SURVEYURL}

The URL pointing to the survey start - if you are sending HTML emails this will be a fully linked HTML version

@@SURVEYURL@@

The URL pointing to the survey start - this is the barebone link. Use this if you want to integrate the link in your custom HTML elements somewhere (available in v1.90 and later)

{OPTOUTURL}

The URL to deactivate sending of mail for this survey - this will be a fully linked HTML version

{TOKEN}

Token to access the survey

{ATTRIBUTE_1}

Attribute 1

{ATTRIBUTE_2}

Attribute 2 (...and so on for more attribute fields)


Sending emails

To send invitation or reminders, click the corresponding button in the token control menu bar. LimeSurvey will only send each participant an invitation once, even if you send multiple mass invitations. This means that if you add a token after having sent (a first round of) invitations, sending invitations again will only send an invitation to the new token(s). To resend an invitation to a participant (e.g. if the first invitation bounced), edit the participants email in the edit tokens screen, and set the ‘invitation sent’ field to ‘N’, a capital n, for no.

When you send reminders, there are a number of options to limit ‘spam’ from sending multiple reminders. You can set the minimum amount of days between reminders, and the maximum amount of reminders that will be sent in total to any given participant. This is especially useful if you did not invite all participants at the same time, for example allowing you to send reminders to participants who were added later without spamming other participants.


Additional token options

Tokens are not limited to just name and e-mail addresses, you could add a range of prior information about your respondents, to be used in the survey. Additionally, you can change a number of additional access control related options in the general settings of the survey. Anonymize responses, allow respondents to edit their responses, set up token based persistence (saves progress on the server so a participant will automatically be taken to back to where he was, for example after a browser crash) and allow public token registration.

Adding custom token attributes

Let’s say you wanted to add the company or institution a participant works for, to create a tailored welcome message later. First, you have to create the token attribute in the LimeSurvey token control screen. Make sure you are in the token control screen, then click the button for additional attributes.

Token management screen, custom token attributes button

On the next screen, first enter the amount of custom attributes you want to add, then click add fields. You can now enter a description for your custom attributes, for example “company”.

Custom token attributes screen

Note that the description you give is not the name of the attribute, the name and label for the attribute in the CSV file and the Expression Manager is attribute_1, attribute_2, etc.

The custom attribute is now created and can be filled in for new tokens or existing tokens by using the add or edit token pages.

General settings

You can set some additional survey options related to the use of tokens in the General settings page of the survey menu. If you are in the token control, click the home button to go back to the main meny, open your survey, then hover over the survey properties button and click the general settings link.

Survey menu, general settings button

Open the tokens tab to change some token options. You can anonymize responses, separating tokens from the participants’ responses (more information on anonymity here), allow editing after completion, set up token based persistence (saves progress on the server so a participant will automatically be taken to back to where he was, for example after a browser crash), allow public registration (which will allow anyone who knows the address of the survey to create a token and participate, one per email address) and the use of HTML in emails (if you don’t know what this means, then leave it on yes. If you do change it, make sure your emails still display as expected) and an option to change the length of the token (for increased security you could use longer tokens, but the default of 15 is usually fine. Only accepts values higher than 5).

Importing tokens from a CSV file

When you use tokens, you often already have a list of names and email addresses you want to import. LimeSurvey allows you to import a large number of tokens quickly by importing from CSV files.

What is a CSV file?

CSV stands for Comma Separated Values. A CSV file is just that, a list of comma separated values, typically with column headings on the first line.

Create a CSV file for LimeSurvey

LimeSurvey tokens require at least 3 values; first and last name, and an email address. Extra attributes can be added, but you first have to define them in LimeSurvey. More on that here.

Create a list of relevant information (usually first and last name, as well as an email address) , and enter the data for your intended recipients. You can do this any way you like, as long as the end result has one column for first names, one for last names, and one for email addresses. Make sure the first row has the values “firstname”, “lastname” and “email”, corresponding to the right columns, you results should look like the image below.

LimeSurvey uses the first row to apply data to the correct token attributes, so these labels must be typed exactly as they appear above. Save the file as CSV and you should be ready to import.

Importing a CSV file

To import a ready CSV file, log in to LimeSurvey, and select your survey from the dropdown list on the top right, then click the tokens button on the survey menu bar.

If you have not enabled tokens yet, you will get a warning message, confirm that you want to initialise tokens. You are now in the token control screen, which should look like the image below.

You have a variety of options, the import tokens from a CSV button is encircled in this image. Click it to start importing. You can now select the CSV file, pick a character set (usually not necessary, leave this as-is, unless you encounter problems with special characters), change the separator used (more on this here), as well as filter blank emails and duplicates. Point LimeSurvey to your tokens csv file, click upload, and LimeSurvey should tell you it has successfully uploaded the csv and created token entries. If not, you may want to take a look at the common errors section here.

Common errors

If something happens that LimeSurvey does not expect, or if LimeSurvey fails to read the CSV file, a message like this will pop up. This often points to one or more problems, which are shortly explained below.

Incorrect delimiters

LimeSurvey expects commas as the delimiter of a comma separated file. Microsoft Excel often saves CSV files with a semicolon delimiter. Recent versions of LimeSurvey allow you to select the delimiter used, the default setting is ‘automatic’. When the delimiter is set to automatic, LimeSurvey is usually smart enough to detect this common error and compensate, but it may be better to ‘manually’ change the csv file to use commas. You can do this in many ways, but the easiest two ways are to open and save the file in a program that does use commas correctly (e.g. SPSS), or open the file in a text editor and use the find and replace function to replace all semicolons with commas. If, for some reason, your csv file uses even more exotic delimiters, you can use a text editor to replace them with commas.

Incorrect attribute names

LimeSurvey uses the first line of a CSV file to assign values to the correct token attributes. Mandatory attributes are first name, last name and email, and their names in LimeSurvey are “firstname”, “lastname” and “email”. Make sure your CSV file uses the correct names, without spaces, and case sensitive.

Incorrect encoding

By default, LimeSurvey expects UTF-8 encoding. Different spreadsheet programs may use different encoding sets. For example, Microsoft Excel uses Windows-1252 on computers with a US English operating system installed. This is not a problem for most characters, but accented characters such as é, õ, ç and ä may be stored differently depending on the character set. When LimeSurvey comes upon such a character it does not recognize, it will throw an error and stop importing.

To fix this, you have two options. Either delete the offending characters, or force the file to be saved using the correct encoding. Replacing accented characters with their ‘regular’, unaccented counterparts is an easy fix in some cases, but may not be desirable.

The alternative is to force encoding. This option is absent in Microsoft Excel, but luckily most other software does offer this option. Google Docs (or Google Drive), OpenOffice and LibreOffice all have spreadsheet software that either saves in UTF-8 by default, or allows you to specify the encoding used when saving the file (you may have to use ‘save as’). Simply open the file or copy/paste the contents into one of the above spreadsheet programs, and save it as a new file. LimeSurvey should now correctly recognize all characters.