From LimeSurvey Manual

*'''Reminder sent''': defaults to 'N', otherwise would contain the date when the reminder email was sent

*'''Reminder sent''': defaults to 'N', otherwise would contain the date when the reminder email was sent

*'''Completed''': defaults to 'N', otherwise would contain the date when the survey was submitted for not anonymous survey, or 'Y' for anonymous survey

*'''Completed''': defaults to 'N', otherwise would contain the date when the survey was submitted for not anonymous survey, or 'Y' for anonymous survey

−

*'''Uses left''': A counter of number of times the token can be used.

+

*'''Uses left''': A counter of number of times the token can be used. ''Note:'' When increasing this value (default = 1) for a user who has already filled out the survey (which sets uses left to 0), you have to add "N" at the "completed" field.

*'''Valid from''' & '''Valid until''' : You can set a date/time range where this token would be allowed to use. You can leave these empty if you don't want to limit participation time frame for certain users. Note: If the user is answering the survey and the participation time ends then the user is locked out immediately and won't be able to finish the survey.

*'''Valid from''' & '''Valid until''' : You can set a date/time range where this token would be allowed to use. You can leave these empty if you don't want to limit participation time frame for certain users. Note: If the user is answering the survey and the participation time ends then the user is locked out immediately and won't be able to finish the survey.

*'''Attribute1 to Attribute x''': These are user-definable attribute fields - see the next paragraph.

*'''Attribute1 to Attribute x''': These are user-definable attribute fields - see the next paragraph.

Note: Tokens have changed alot in Version 1.85 and later. So if you are using an earlier version there will be differences between your version and the documentation. We recommend to upgrade as soon as possible.

Introduction

On many occasions you will want to invite a group of people to participate in your survey, keep track of who has completed the survey, and ensure that each person can only participate once. The tokens feature allows you to do the following:

Manually create invitations (name, email address, ...)

Import a list of names and email addresses for participants (from a CSV file or an LDAP query)

Add/Remove invitations

Generate a unique token number for each participant (invitation code)

Send an email invitation to each person in your list, by group or individually

Send a reminder email to each person in your list who has not yet responded, by group or individually

Track who from your list has responded

Restrict access against people who have not got a token, and those with a token who have already responded

Edit/change any details in your list

Once the survey is switched to Closed-access mode (you have enabled tokens for this survey), then only the people with a valid token code (not already used) can access the survey.

If you enable Auto-registration in the survey properties, participants will be able to register for your survey to have their personal token code automatically generated.

Can a survey using tokens ensure anonymous answers?

The answer to this question is Yes. Tokens can be used both for anonymous and non-anonymous surveys. This is determined when creating a survey. If a survey is not anonymous (or 'tracked') then the token list can be used to find the responses that an individual has made to the survey. If the survey is anonymous, then no link (technically: foreign key relationship) is available between the tokens table and the responses.

How to activate tokens?

There are two ways to activate tokens:

After survey activation you will be asked if you want to activate tokens:

OR you can click on the tokens symbol - even before the survey is activated.

The token management tools

After creating the tokens table you can click on the tokens icon to get to the token administration. The following is a brief rundown of the menu options in the tokens screen:

Admin: Returns to the main survey admin screen

Summary: Displays just the brief summary of tokens in the table (number of tokens, how many have been sent an invitation, and how many have responded). Also provides access to the Database Admin functions (see below). This is the default screen.

Browse: Displays the complete list of participants in the tokens table. From the browse screen you can edit or delete individual entries in the token table as well as perform a number of other useful functions (see browse section below)

Add new token entry: Allows you to add an entry to the tokens table

Add dummy token: Allows you to add 1 or more tokens to the token table

Manage additional field attributes: Allows you to add additional fields to the tokens table to store custom participant data

Import from CSV: Allows you to import information from a csv file

Import from LDAP: Allows you to import information from an LDAP query (tested on openLdap but should work in any LDAP compliant directory including ActiveDirectory)

Export tokens to CSV file: creates a standard CSV (comma delimited) file with a complete list of participants of your current tokens table

Edit email templates: Used to customize the templates used for the invitations, reminders, confirmations, and registration emails

Send email invitation: Sends bulk email invitations to all participants in the tokens table who have not already been sent an invitation.

Send email reminder: Sends bulk email reminders to all participants in the tokens table who have not yet responded, but have been sent their first invitation.

Generate tokens: Creates unique tokens for all individual entries in the tokens table that do not yet have one

Drop token table: delete the token table and set the survey to Open-access mode.

Bounce settings: Email bounce back settings. Bounce back settings can be set at the survey level or at the system level. This feature was added in version 1.91

Editing/adding a token

A typical token entry contains the following fields:

First and last name: .. of the participant (can be used in the emails & survey)

Email: the participant's email address

Email status: a field to keep track of bad emails. For instance, if the survey administrator received email error notifications from this email, the he can set this field to anything other than 'OK' (for instance 'user unknown', or 'mailbox quota exceeded'). Marking this token with an email status other than 'OK', will help skip this entry when sending invitation or reminder emails. Note that this is completely manual, unless you decide to implement a script which does update this field automatically.

Token: this is the invitation code. It is usually automatically generated by the 'Generate tokens' button

Language: if you want to set the default language for this participant

Invite sent: defaults to 'N', otherwise would contain the date when the invitation email was sent

Reminder sent: defaults to 'N', otherwise would contain the date when the reminder email was sent

Completed: defaults to 'N', otherwise would contain the date when the survey was submitted for not anonymous survey, or 'Y' for anonymous survey

Uses left: A counter of number of times the token can be used. Note: When increasing this value (default = 1) for a user who has already filled out the survey (which sets uses left to 0), you have to add "N" at the "completed" field.

Valid from & Valid until : You can set a date/time range where this token would be allowed to use. You can leave these empty if you don't want to limit participation time frame for certain users. Note: If the user is answering the survey and the participation time ends then the user is locked out immediately and won't be able to finish the survey.

Attribute1 to Attribute x: These are user-definable attribute fields - see the next paragraph.

Dummy Tokens

Dummy Tokens were added in 1.91. Here is a typical screen:

Number of tokens: Number of tokens to be added. Default is 100.

Token length: Number of characters or length of token. Default 15

First and last name: .. of the participant.

Email: the participant's email address

Language: If you want to set the default language for this participant

Uses left: A counter of number of times the token can be used.

Valid from & Valid until : You can set a date/time range where this token would be allowed to use. You can leave these empty if you don't want to limit participation time frame for certain users. Note: If the user is answering the survey and the participation time ends then the user is locked out immediately and won't be able to finish the survey.

Attribute1 to Attribute x: These are user-definable attribute fields - see the next paragraph.

Note that Name, email, language will be set to the same value for all dummy Tokens

Bounce Settings

Email bounce back processing was added in 1.91.

Survey bounce email: A valid email address for return mail. For faster bounce back processing, this email box should be limited to bounce back only.

Bounce settings to be used: There are three options: 1) None (default) - no bounce back processing, 2) Use settings below - Will set bounce back processing at the survey level, or 3) Use global settings -- Settings based on the system level.

User-defined attribute fields

It is possible to add a number of additional fields to the tokens table to save additional data for a participant. By clicking on the icon you can manage these fields. You can add more attribute fields (by default they have a a length of 255 chars) and also set descriptions for each field - so they look nicer in the administration, when you browse tokens, when creating conditions based on attribute fields or even when you export results for non-anonymous surveys.

Using the browse screen and editing tokens

The browse screen will show you a list of all entries in the tokens table, as well as giving you some 'action' buttons that can perform specific tasks for that individual entry.

The top row of the table has three columns: The dialogue on the right gives options for displaying a number of records, and a starting point. In the middle is a search bar and the symbols on the left let you move backwards or forwards through your list.

The second row of the table (see image below) includes various criteria to sort the entries and for each a green arrow that - if clicked - will refresh the screen showing the tokens ordered by that criterion.

The "Actions" column gives a list of specific tasks that can be performed on that individual entry:

Do the survey using the unique token of this entry

Edit this entry

Delete this entry

Send a invitation/reminder to this individual entry

If the survey is a 'tracked' (ie: not anonymous) survey, another button will appear, allowing you to view the response from this individual entry.

Database Admin

While the summary screen shows a brief summary of tokens in the table, it also provides access to the "Database Admin" features which include:

Clear invites: Sets all records that an invitation has been sent out to 'N'. Obviously shouldn't normally be used.

To obtain a full list of token field names, export an existing token table.

The fields can be in any order but firstname, lastname and email are mandatory, and they must contain at least one character. Empty data (such as "") is not sufficient. If you would like to import data for attribute fields, you must add the desired attribute fields to the token table prior to importing token data.

A bare minimum CSV file could look like this:

firstname,lastname,emailJohn,Doe,john@doe.net

Date format for token import

The date format for the "validfrom" and "validuntil" fields in the CSV token inport file is "YYYY-MM-DD HH:MM", e.g.:

2012-01-0100:00

--would correspond to 1st January, 2012, at 12:00 AM.

Filtering duplicates

If you activate the option to filter for duplicates you can set which fields are used to identify duplicates. By default First name, Last name & Email-address are pre-selected. If a duplicate is found while importing the related line is omitted.

Troubleshooting the token import

A common error when users try to import tokens is an invalid CSV file. This is often caused by Microsoft Excel. Many users have a list of e-mail addresses saved as an XLS document. A file can be saved as CSV in Excel, however, Microsoft uses semi-colon (;) as the comma separator, while a standard CSV file uses comma (,) as the separator. If you try to import an Excel saved CSV file you will get an error message. A simple solution is to save your XLS document as a CSV file in Excel and then open the file in a raw text editor and replace all semi-colon characters with commas.

CSV export

LDAP import

Queries are manually defined by the system administrator in the config-ldap.php file

Duplicates are identified by First Name, Last Name & Email-Address. If a duplicate is found while importing the related line is omitted, unless you have unchecked the Filter Duplicates checkbox.

A tip for generating a large number of fake e-mail addresses

Sometimes you may need a large number of fake e-mail addresses and tokens. You can use functions in a spreadsheet (e.g. OpenOffice Calc) to generate them. Let's assume you want thousands addresses in a form: 1@test.com, 2@test.com, 3@test.com... Put consecutive numbers in column A: 1 in the A1, then insert function =A1+1 in A2, then copy A2 down as many times as you need. In B1 use concatenation function to join A1 and "@test.com", which is =CONCATENATE(A1;"@test.com"). Then copy B1 down for each copied A. You may generate fake names in a similar way. Finally, save the file as CSV for import in LS.

With the 1.91, you can use "Generate dummy token" functionnality

Emailing

Email placeholders

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)

If your survey is NOT anonymous, the following field names are available to insert token data in survey text and javascript:

Emails settings

Invitation Email Subject: The subject line for the invitation email that gets sent out when tokens are used with your survey.

Invitation Email: This is the text for the invitation email that gets sent out when tokens are used with your survey. This is initially filled by the default invitation message (from the language files) but you can modify it to suit yourself. If you are using English as your base language, the default invitation and reminder text can be found in the limesurvey/tokens.php file. Of course if you don't plan to use tokens on your survey, whatever is in this field is irrelevant. You can use the following "form" fields to insert individualized information in each email:

{ATTRIBUTE_2} - gets replaced with the token table's "attribute_2" value and so on

{SURVEYURL} - gets replaced with the fully qualified URL to this particular survey - in HTML emails this is a fully linked HTML link

@@SURVEYURL@@ - Gets replaced with the survey barebone link. Use this if you want to integrate the link in your custom email HTML (available in v1.90 and later)

{OPTOUTURL} - gets replaced with the URL for a respondent to opt-out of this particular survey

Note that these "form fields" apply to the following email fields.

Email Reminder Subject: The subject line for the reminder email that gets sent out from the tokens tool

Email Reminder: This is the text for the reminder email that gets sent out when tokens are used with your survey. See "invitation email" for specific details on how this field is used.

Confirmation Email Subject: When tokens are used, this is the subject line of the email that gets automatically sent to participants after completion of the survey

Confirmation Email: This is the text of the email that gets sent to users after completion of the survey. Delete/blank this text remove the confirmation email sending.

Public Registration Email Subject: This is the subject line for the invitation email sent to members of the public who register for a survey.

Public Registration Email: This is the text for the invitation email sent to members of the public who register for a survey. The same "form fields" apply in this email as in the earlier ones.

Sending emails

Send invitations

You can skip tokens for which the email status field is different from 'OK', by choosing the 'Bypass token with failing email addresses' option.

Resending invitations

Sometimes you might want to send invitations again to certain token entries / persons. When you use the send invitations-function only e-mail addresses that has not previously received an invitation will get one. This means that if you add new addresses to the token list after the first time you sent invitations, only these new addresses will receive an invitation the second time you send invitations.

This means that you can also edit/change an e-mail in a particular token entry that you got a bounce from and then send to only this edited address. Just substitute the date Invite sent? for a capital N (no) and click send invitations again.

Participant opt-out

When you use the {OPTOUTURL} tag in your invitation/reminder email, your participants have the possibility to opt out of this particular survey by just clicking on the related URL in the email - so you don't harrass them with reminder emails. A participant that opted out of your survey will have the email status 'OptOut' set in the token.

Send reminders

When sending reminders you can:

bypass tokens with failing email addresses

skip tokens for which an email has been 'recently' sent

skip tokens for which a given number of emails have already been sent

Note: A reminder will only be send to tokens where the "completed" field is not "N" (this means the respondent has either not taken or has not completed the survey).

Sending emails by batch

When you have to send a lot of emails at the same time, LimeSurvey will only send a first batch of N emails (this threshold is set by the administrator in the Global Settings).

You'll then need to click "Next" to send the next batch, and so on untill all emails have been sent.

Confirmation email

If you are using tokens and a participant fills out the survey, a confirmation email is sent to his/her email address.

If you don't want this message to be sent, remove all content from the "Confirmation email subject" and "Confirmation email" fields - see these instructions.

Public registration

Allowing public registration

You may want to open your survey to the public, but utilize the sort of respondent control available when using tokens. This is possible: If you initialize your tokens table, and have chosen to Allow Public Registration in the main survey setup, people who visit your survey's URL without a token, will be given the opportunity to register. If they provide an email address that is not already in the current survey's tokens table, an entry in the tokens table will be created, and they will be emailed an invitation containing their unique Token. All tokens provided to "registering" visitors will begin with the letter "R".

Captchas in public registration

To protect your survey from robot registration there is a captcha feature on all Registration, Save and Load forms. (starting from version 1.48) This feature is only available if you have GD-support activated in your PHP configuration. (see Installation Requirements)