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.

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. To make access control work, you need to enable tokens, create a list of participants (tokens), and invite participants with their token. The rest of this manual will explain these three 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. More information on how to do this here.

Adding custom token attributes

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.

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.

Final step

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.


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 usefull 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

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 repsonses (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).