Survey participants

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:

• Import a list of names and email addresses for participants (from a CSV file or an LDAP query)
• 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
• Create email templates for invitations & reminders

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 responses?

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:

1. After survey activation you will be asked if you want to activate tokens:
2. 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.
• Server type: Three options: 1) Off, 2) IMAP or 3) POP
• Server name & port:  Host name and port number.   Port number isn't typically needed unless the email host uses a non-standard port. Example:  mail.example.net:25 or imap.gmail.com:995
• User name:  User Name or User ID of the email account
• Password:  password of the email account
• Encryption type:  Three options:  1) None (default), 2) SSL, or 3) TLS

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.

Detailed instructions on how to add additional attribute fields and use conditions based on these values can be found at this blog post: "Conditions based on token attributes"

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.
• Clear tokens: Clears all tokens. Similarly shouldn't normally be used.
• Drop tokens: Allows you to remove the tokens feature from your script. Deletes the entire table and all records, and allows the survey to be accessed by anybody who knows the URL.

Importing/exporting tokens

CSV import

When you click the icon to import tokens you will be presented with the following screen:

File:Uploadtoken.jpg

Your CSV file must be a standard CSV (Comma Separated Value) file. The first line of text is always the header information and will be used to identify the field data. Possible data fields are:

   firstname,lastname,email,emailstatus,token,language code,tid,attribute_1,attribute_2, attribute_...

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,email
   John,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-01 00: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.

Recommended free raw text editors are: PSPad, NotePad2 or Notepad++ for Windows, and TextWrangler for Macintosh.

You can use LibreOffice Calc to export import your xls file and export your csv file.

Add additional attributes at import It is also possible to add new custom attributes when import a CSV file. It is still needed to define what attributes will be added. The way to do this is:

   firstname,lastname,email
   attribute_1 <Casenr>; token; attribute_2 <Title>; attribute_3 <destination>; lastname; firstname; attribute_4 <Sender>;

Creating CSV file with Excel on the Mac

When you create a CSV file with Excel 2011 on the MAC and use the standard "save as" option, you loose special characters such as ü, ë, é etc. when importing into LimeSurvey Token Table.

To make this work properly choose to save the file as a Windows text CSV file (tested on the Dutch version of Excel, saved as "Door lijstscheidingstekens gescheiden Windows tekst (.CSV)").

Then when importing the file in the LimeSurvey token table, under "character set of file" choose "Mac West European". The special characters will be imported correctly.

Tested on LimeSurvey 2.0 only.

CSV export

When you export your tokens the following fieldorder is exported:

   tid,firstname,lastname,email,emailstatus,token,language code,attribute_1,attribute_2,...

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

A tip for generating a large number of individual links which include the token already

The structure of the survey link is the following:

http://url-to-your-limesurvey-installation/index.php?sid=XXXX⟨=en&token;={TOKEN}

So you proceed similar to the example above for generating email adresses.

• First column: http://url-to-your-limesurvey-installation/index.php?sid=XXXX⟨=en&token;= (the same for all, as long as the language is the same!)
• Second column: {TOKEN} (put your tokens here, of course they must be individual)
• Third column: use the CONCATENATE funtion to joint the first column with the second column.

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:

{TOKEN:EMAIL}	Email of the recipient
{TOKEN:FIRSTNAME}	First Name
{TOKEN:LASTNAME}	Last Name
{TOKEN}	Token to access the survey
{TOKEN:ATTRIBUTE_1}	Attribute 1
{TOKEN:ATTRIBUTE_2}	Attribute 2 (and so on for more attribute fields)

See examples on using information from tokens table.

Starting in Version 1.92, you can use Expression Manager to use expressions for tailoring an email. Please have a look at the Expression Manager HowTos for an example.

Emails settings

1. Invitation Email Subject: The subject line for the invitation email that gets sent out when tokens are used with your survey.
2. 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:

• • {FIRSTNAME} - gets replaced with the token table's "firstname" value
  • {LASTNAME} - gets replaced with the token table's "lastname" value
  • {SURVEYNAME} - gets replaced with your surveys name
  • {SURVEYDESCRIPTION} - gets replaced with your surveys description
  • {ATTRIBUTE_1} - gets replaced with the token table's "attribute_1" value
  • {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.

1. Email Reminder Subject: The subject line for the reminder email that gets sent out from the tokens tool
2. 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.
3. 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
4. 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.
5. Public Registration Email Subject: This is the subject line for the invitation email sent to members of the public who register for a survey.
6. 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.

Spam problems

Often users complain not having received an invitation/reminder email because the user’s spam filter treated the email as spam.

If an email is treated as spam mostly depends on the spam filter being used and its settings. A spam filter usually checks the sender address and the email subject and content, so there are ways and means to influence how they treat your LimeSurvey invitation and reminder emails.

At this blog post on limesurvey-consulting.com a lot of possible issues and solutions are listed.

Wrong domain in invitation/reminder email link

LimeSurvey automatically tries to determine the URL for the invitation link by looking at the URL by which you logged in to the LimeSurvey administration. However with some server (mis-)configurations this might not work properly and you will have to set this manually.

You can edit /path/to/application/config/config.php to change the default base URL value. Add hostInfo property like this to the existing 'components' array.

    'components' => array(
       ...
       'request' => array(
           'hostInfo' => 'http://www.example.com',
       ),
   )

Regarding the source of the problem: LimeSurvey tried to determine the domain from the server PHP variable $_SERVER['HTTP_HOST']] or $_SERVER['SERVER_NAME']].

Some web server software do not properly seem to provide this information or are mis-configured.

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)