Survey participants

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 need to enable tokens for the respective survey), only the people with a valid token code (not already used) can access the survey.

If you enable the Allow public registration option from the Participant tokens panel, the survey participants will be able to register for your survey by receiving an automatically generated token code.

Some tokens-related settings are stored in the Participant tokens panel.

How to activate a tokens table?

To activate the tokens functionality of LimeSurvey, access the survey and click on the Survey Participants button located in the Settings menu. You will be prompted by the following message:

If you initialize participant table, the survey will be accessible only to those users that provide in the survey registration process a token (either manually or by URL). In this way, the survey will be switched to the closed-access mode.

Once initialized, a window will load up with the confirmation of the participant/token table creation.

Reactivate a token table

Sometimes you may want to change a set of questions from the survey after you have already activated your survey. Deactivate your survey, make the changes. When reactivating it and reusing the tokens table, you have the possibility to restore the previously closed one:

The token management tools

A survey participant summary will load up if the token/participant table was previously created. The following options are displayed:

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). This is the default screen.

[[File:]]

• Total records: The number of survey participants from the tokens table;
• Total with no unique token: It displays the number of users without an assigned token id;
• Total invitations sent: It shows the number of invitations that have been sent to your survey participants from the tokens table by using the Invitations option from the Invitations & reminders menu;
• Total opted out:
• Total screened out:
• Total surveys completed: It shows the number of the surveys that have been completed by those users who have been allocated a token id.

Above the Survey participant summary table, you may find the token management tools:

• Display participants: If clicked, a tokens table with all the current participants will load up. 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)
• Create...: This options allows the survey administrator to add participants into the tokens table either via the Add participant option or via the Import participants function;
• Manage attributes: It allows the survey administrator to add additional fields to the tokens table to store custom participant data;
• Export: If you wish to export the token tables and used them in other surveys, use this function. The file will be saved in the .CSV format;
• Invitations & reminders: Use this option in order to quickly invite or remind your participants from the tokens table to fill in your online survey;
• Generate tokens: It is a LimeSurvey functionality that allows the survey adminstrator to quickly allocate a random unique token id to each user from the tokens table;
• View in CPDB: It's a button that offers quick access to your LimeSurvey installation central participant database (CPDB).

Display participants

It lists 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)

The browse screen will show you the entries list from the tokens table. It allows the user to:

• sorth the survey participants;
• filter the survey participants;
• perform certain actions for an individual entry;
• perform certain actions for more than one entry.

Sort the survey participants

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

Filter the survey participants

If you wish to filter the survey participants, chose the column according to which you want to filter the participant and type in the string according to which the filtering should be done:

For example, type in the email status "OK" in order to let LimeSurvey return only those users that use a good email address.

Perform a specific action to an individual entry

The second column is the Action column where you can find all the actions that are available for the individual entries:

• View response details: If the survey is a 'tracked' (ie: not anonymous) survey, another button will appear, allowing you to view the response from this individual entry;
• Launch the survey with this token: It is used if you wish to execute a survey by using the generated token;
• Send email invitation: Use this email to send an email invitation to complete the survey to the respective user;
• Edit the survey participant: Click on this button if you would like to change some survey participant data;
• Delete survey participant: Click on this button if you want to delete that particular entry.

Perform a specific actions for more than one entry

On the bottom-left part of the table, you may find the Selected participant(s)... button that allows you to perform certain actions at a macro level:

• Send email invitations: Send email invitations to the selected survey participants;
• Send email reminder: Send email reminders to the selected survey participants;
• Add participants to central database: In the case in which you would like to use the survey participants table in another survey, add the selected participants to the central participants database. From there, you have the option to add the participants to any survey you wish. For more details, continue reading the Share this participant wiki section.

Before executing any of the functions mentioned above, do not forget to select the survey participants upon which the action will be performed.

Create...

To have more participants listed in the tokens table, you can either add new ones or import them from a .csv file or LDAP query.

Add participant

A typical token entry contains the following fields:

• ID: It represents a number that is automatically assigned to each survey participant;
• Completed?: It is disabled by default. If enabled, it would contain the date when the reminder email was sent;
• First name: The first name of the survey participant;
• Last name: The last name of the survey participant;
• Token: This is the invitation code. It can be manually or automatically generated via the Generate tokens button;
• Language: You can select here the default language of the survey for the respective participant;
• Email: the email address of the participant;
• Email status: This field helps you track the bad email addresses. For instance, if the survey administrator received email error notifications from this email, then he can set this field to anything other than "OK" (for instance "user unknown" or "mailbox quota exceeded"). Marking this field 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;
• Invitation sent?: If enabled, it would contain the date when the invitation email was sent;
• Reminder sent?: If enabled. it would contain the date when the reminder email was sent;
• 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: & 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.

Please that the Add survey participant panel is made of two tabs: the General tab and the Additional attributes tab. The additional attributes tab offers you access to your custom attributes - read the following wiki section for more details.

Create dummy participants

A dummy participant can be used when you do not want to send emails with the token code to each participant, but to give him or her the token code by other means. For example, during class evaluations, students receive a paper with a unique token to be introduced at the beginning of a survey. The survey is completed in the class, making sure that the survey response rate is high.

Once clicked, the following page will load up:

The Number of participants field allows you to introduce the number of dummy variables you wish to be introduced in your tokens table. The explanation of the other fields can be found in the Add participant wiki.

After completing the fields, press the Save button located in the upper-right part of the screen to save the dummy variables.

To check whether they were added or not, visit again the Survey participants list:

Import participants from a CSV file

The import function permits you to import information from a CSV file or LDAP query.

• Choose the CSV file to upload: Pick the CSV file you wish to import. To eliminate any possible errors, it is recommended to import a standard CSV (comma delimited) file with optional double quotes around values (default for OpenOffice and Excel).

The first line must contain the field names. It must also contain the following fields: firstname, lastname, email. They have to contain at least one character. Simply adding double quotes and no characters between them will not work!

The other fields are optional: emailstatus, token, language, validfrom, validuntil, attribute_1, attribute_2, attribute_3, usesleft, ... .

{{Note|To obtain a full list of token field names, you can [[export an existing token table.}}

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

• Character set of the file: Select the option that fits the characters used in the CSV file;
• Separator used: You can let LimeSurvey automatically discover the used separator in your CSV or select either the comma separator or the semicolon one;
• Filter blank email addresses: If enabled, the survey participants without an email addresses will not be imported into your tokens table;
• Allow invalid email addresses: If disabled, this function will look into the email addresses fields and check whether the addresses have the structure of an email or not (eg a@a.net);
• Display attribute warnings: If enabled, after the importing process warnings will be displayed in the case in which something is wrong with the fields. For example. you might get an attribute warning if nothing is provided in any of the mandatory fields or if an email is wrongly introduced in the CSV file.

• Filter duplicate records: If enabled, you can set which fields are used to identify duplicates. By default First name, Last name & Email-address are preselected. If a duplicate is found while importing, the related line is omitted.

• Duplicates are determined by: Select the fields according to which you would like to see the filtering process happening.

You can also import customized attributes when importing a CSV file. You will just have to define what attributes will be added. You can do it like this:

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

Once you are done choosing the desired importing settings, do not forget to click on the Upload button.

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, depending on the locale of the OS Microsoft may use semi-colon (;) as the comma separator, while a standard CSV file uses comma (,) as the separator. If you do not know, open the file with a standard text editor and check what separator was used.

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

Import participants from a LDAP query

  Use this option only if you have advanced knowledge of LimeSurvey.

This import function allows you to import information from an LDAP query (tested on openLdap but should work in any LDAP compliant directory including ActiveDirectory). Once accessed, the following options are available:

• 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.

For more details about the LDAP settings in LimeSurvey, read the following wiki page.

Manage attributes

This option allows you to add/edit the additional fields that were added to the tokens table to store custom survey participant data:

Type in the number of new attribute fields you wish to add to your survey participants table. Click on the Add fields button. The following page will load up:

The attribute fields table contain the following list:

• Attribute field: It is used when you wish to do different operations with the respective custom attribute field such as: applying conditions based on attribute fields or when exporting results for non-anonymous surveys;
• Field description: Used in to replace the attribute field name. By giving a custom name, they will look nicer in the administration panel, when you browse tokens, when creating conditions based on attribute fields or even when you export results for non-anonymous surveys;
• Mandatory?: If enabled, the respective field data has to be filled in. Otherwise, the survey participant cannot be registered into the tokens table;
• Show during registration?: If the survey participants have to register before completing a survey, certain details will be required from them. If disabled, the respective attribute field won't appear in the survey registration page;
• Field caption: Use this fields to add further explanations about the role/usage of the respective attribute field.
• CPDB mapping:;
• Example data: It contains data examples from different fields. For example, if you wish to ask for the gender of the survey participant, then you will observe in the Example data field examples such as male, female, no answer etc.

Once you finish filling in the boxes, do not forget to click on the Save button, located in the bottom-left part of the attributes table

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".

To add more fields, go to the bottom of the page, and type in the Number of attribute fields to add box the desired number and click on the Add fields button.

If you wish to delete a custom attribute, go to the bottom of the page and select from the drop-down list situated under the Delete this attribute row the attribute you wish to delete. Once selected, click on Delete attribute and confirm the deletion.

Export

• Survey status:
  • All tokens: It exports all the survey participants from the tokens table;
  • Completed: It exports only those survey participants that completed the survey;
  • Not completed: It exports the survey participants that have not yet completed the survey;
  • Not started: It exports the survey participants that have not started yet the survey;
  • Started but not yet completed: It exports the survey participants that have already started the survey, but did not complete it.
• Invitation status: Export the users according to the invitation status;
• Reminder status: Export the users according to the reminder status;
• Filter by language: When you create a survey, you can add additional languages beside the base language. Those additional languages can be used to;
• Filter by email address: It exports entries which contain the set of characters in the respective email address. For example, you can use it if your survey participants use the work email addresses from "Company A". Type @companya.com and export only the users that have a work email address at that company;
• Delete exported participants: If enabled, the exported users will be deleted from your survey participants table.

One you have selected the exporting options, click on the Download CSV file button located in the upper right part of the screen.

When you export your tokens the following field order is exported: tid,firstname,lastname,email,emailstatus,token,language code,attribute_1,attribute_2,...

Invitations & Reminders

Send email invitation

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

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

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.

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 application/config/config.php to change the default base URL value. Add hostInfo property like this to the existing 'components' array.

    'components' => array(
       ...
       'config' => array(
           .......
           'publicurl' => '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.

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.

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 sent to participants where the "completed" field is "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, just deactivate this in the General survey settings.

Edit email templates

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.

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.

Bounce settings

Please also check out the Email bounce tracking system page for more information how to correctly configure this feature.

• 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

Generate tokens

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

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. You can use these fields in confirmation and notification email template too.

{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)

Additional hints

• If your survey is using anonymized responses then token-related placeholders will not work in notification email templates.
• You can use Expression Manager to use expressions for tailoring an email ^{(New in 1.92 )}. Please have a look at the Expression Manager HowTos for an example.

Also have a look at the examples on using information from tokens table.

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)

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.

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:

Limesurvey 2.x: http://url-to-your-limesurvey-installation/index.php/survey/index/sid/xxxx/newtest/Y/lang/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&lang=en&token= (for version 1.x) OR http://url-to-your-limesurvey-installation/index.php/survey/index/sid/xxxx/newtest/Y/lang/EN/token/ (for version 2.x) (same URL 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 function to join the first column with the second column.