Introduction

• Import a list of names and email addresses for participants from a  CSV  file or a  LDAP query ;
  
• Generate a unique token code for each participant (invitation code);
  
• Send an email invitation to each person on your list (by group or individually);
  
• Send a reminder email to each person on your list who has not yet responded (by group or individually);
  
• Track who has responded from your survey participants list;
  
• Restrict access for people who have not received a token, and those with a token who have already responded;
  
• Edit/change any details in your list;
  
• Create email templates for invitations & reminders.
  

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

Please refer to the Create Participants Table article for in depth instructions on how to create and manage survey participants.

Create participants table

How to create a survey participants table

The following message will be displayed:

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

Once initialized, a window will be displayed confirming the creation of the survey participants table.

Reactivate a survey participants table

When you delete a survey participants table, a backup is created. It can later be reactivated if you wish to use that specific survey participants table in another survey.

The survey participants table management tools

A survey participant summary will be displayed if the survey participants table was previously created. This is the default screen:

1. Total records: The number of survey participants from the survey participants table;
2. Total with no unique token: Displays the number of users without an assigned token code;
3. Total invitations sent: Shows the number of invitations that have been sent to your survey participants from the Survey participants table by using the Invitations option from the Invitations & reminders menu;
4. Total opted out: Displays the total number of survey participants that have decided to opt out from the survey;
5. Total screened out: Used to screen and exclude potential participants who do not match certain criteria.
6. Total surveys completed: Shows the number of the surveys that have been completed by those users who have been allocated a token code.
   

Above the Survey participant summary table, you will find the survey participants table management tools:

1. Display participants: Displays a survey participants table with all the current participants. From the browse screen you can edit or delete individual entries from the table as well as perform a number of other useful functions (see the  Display participants wiki section below for more details);
2. Create...: Allows the survey administrator to add respondents into the survey participants table either via the Add participan t option or via the Import participants function;
3. Manage attributes: Allows the survey administrator to add additional fields to the survey participants table to store custom participant data;
4. Export: To export the token tables and use them in other surveys, use this function. The file will be saved in the .CSV format;
5. Survey participants: Allows you to invite or remind your participants from the survey participants table to fill out your online survey;
6. Generate tokens: Allows the survey administrator to quickly allocate a random unique token code to each user from the survey participants table that does not have one;
7. View in CPDB: Provides quick access to your LimeSurvey installation central participant database
   (CPDB). From there you can allocate CPDB users as survey participants to any survey.
   

Display participants

Shows the entries list from the survey participants table and allows the user to:

1. sort the survey participants;
2. filter the survey participants;
3. perform certain actions to an individual entry;
4. perform certain actions to more than one entry.
   

Sort survey participants

The second row of the table includes various criteria that can help the survey administrator sort the entries. If you click on any of the columns/criteria from the table, the screen will be refreshed, showing the survey participants ordered in accordance to the criterion you just clicked on. Click twice on it to get the results displayed in a descending order.

Filter survey participants

To filter survey participants, choose the column that you want to filter. Then type in the values/strings that you want to filter on in the empty box below the desired column.

Perform a specific action to an individual entry

The Action column is where you can find all the actions that are available for each individual entry from the survey participants table. The possible actions that can be performed are:

1. View response details : If the survey is a "tracked" (i.e., not anonymous) survey, another button will appear, allowing you to view the response from this individual entry;
   
2. Launch the survey with this token : Used to execute a survey by using the generated token code;
   
3. Send email invitation : Use this option to send an email invitation to the respective participant to complete the survey;
   
4. Edit the survey participant : Click to change survey participant data;
   
5. Delete survey participant : Click to delete that particular entry;
   
6. View this person in the central participant database : An icon will be displayed if the respective entry can also be found in the central participant database.
   

Perform a specific action to more than one entry

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

1. Send email invitations : Send email invitations to the selected survey participants;
2. Send email reminder : Send email reminders to the selected survey participants;
3. Add participants to central database : To use some of the token entries in another survey, add the selected participants to the central participant 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 page .
   

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 survey participants table, you can add new ones or import them from a CSV file or LDAP query.

Add participant

A typical token entry contains the following fields:

1. ID : An integer that is automatically assigned to each survey participant;
2. Completed? : Disabled by default. If enabled, it would contain the date when the survey was completed. No invitations or reminders are sent to the respective users if this is enabled. It is automatically enabled if the respective survey participant completed the survey using his or her assigned token code;
3. First name: The first name of the survey participant;
4. Last name : The last name of the survey participant;
5. Token : This is the invitation code. It can be manually or automatically generated (via the Generate tokens button);
6. Language : Here you can select the default language of the survey for the respective participant;
7. Email : The email address of the participant;
8. Email status : This field helps you track invalid email addresses. For instance, if the survey administrator received email error notifications from this email, then they 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 updates this field automatically;
9. Invitation sent? : If enabled, contains the date when the invitation email was sent;
10. Reminder sent? : If enabled, contains the date when the reminder email was sent;
11. Uses left : Counts the 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 also have to switch the Completed field from "Yes" to "No";
12. Valid from : & Until : You can set a date/time range for when this token can be used. You can leave these empty if you don't want to limit the participation time frame for certain users. 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.
    

Note that the Add survey participan t panel has 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 tokens by email to survey participants, but give them token codes by other means. For example, students doing class evaluations could be given a paper with an invitation code to be entered at the beginning of the online survey. This way, the likelihood of receiving more responses and feedback increases.

Click Create dummy participants and the following page will be displayed:

The Number of participants field allows you to enter the number of dummy participants you want to add to your survey participants table. The explanation of the other fields can be found in the  Add participant  wiki subsection.

After completing the fields, click  Save located in the upper-right part of the screen.

To check whether they were added or not, check the Survey participants table:

Import participants from a CSV file

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

1. Choose the CSV file to upload: Pick the CSV file you wish to import. To eliminate any possible errors, we recommend that you 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, ... .

Hint : To obtain a full list of token field names, export an existing survey participants table..

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

1. Character set of the file : Select the option that fits the characters used in the CSV file;
2. Separator used : You can let LimeSurvey automatically discover the used separator in your CSV or select either the comma separator or the semicolon one;
3. Filter blank email addresses: If enabled, the survey participants without an email address will not be imported into your survey participants table;
4. 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 (e.g.: a@a.net);
5. Display attribute warnings : If enabled, after the importing process warnings will be displayed in case there is something 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 incorrectly introduced in the CSV file.
6. 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.
7. Duplicates are determined by: Select the fields that you want to filter on for duplicates.
   

You can also import customized attributes when importing a CSV file. You will 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  Upload .

Troubleshooting the import of survey participants

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 email addresses saved as an XLS document. A file can be saved as CSV in Excel. However, depending on the locale of the OS, Microsoft Excel may use semi-colons (;) as comma separator, while a standard CSV file uses commas (,) as separators. If you do not know which one you use, open the file with a standard text editor and verify which separator was used.

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

LimeSurvey should also detect semicolons as separators. However, in case the import process is not properly working, replace the semicolons with commas. Double quotes should also be added around values.

Import participants from a LDAP query

Attention : This option is recommended only to those users with advanced knowledge in LDAP queries.

This import function allows you to import information from a LDAP query (tested on openLdap, but should work in any LDAP compliant directory including ActiveDirectory). The following options are available on the Import survey participants from LDAP page:

1. Queries are manually defined by the system administrator in the config-ldap.php file.
2. 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).
   

Manage attributes

1. Attribute field : The value typed here can be used when you want to perform different operations with the respective custom attribute field such as applying conditions  based on attribute fields or when exporting results for non-anonymous surveys.
2. Field description : Used to replace the attribute field name. By giving a custom name to each attribute field , they will look nicer in the administration panel, when you browse tokens, when creating conditions based on attribute fields or when you export results for non-anonymous surveys.
3. Mandatory? : If enabled, the respective attribute field must be filled in by the survey administrator. Otherwise, the respondent cannot be registered into the survey participants table.
4. Show during registration? : If the survey participants have to register before completing a survey, certain details will be requested from them. If disabled, the respective attribute field won't appear on the survey registration page.
5. Field caption : Use this fields to add more details about the role/usage of the respective attribute field.
6. CPDB mappin g: Maps the attribute in order to connect it to its corresponding attribute from the central participant database.
7. Example data : Contains string examples from different fields. For example, if you want to ask for the gender of the survey participant, then you will see in the Example data field examples such as male, female, no answer etc.
   

Once you have finished filling in the boxes, do not forget to click Save located in the bottom-left part of the screen.

Note : Detailed instructions on how to add additional attribute fields and use conditions based on these values can be found on 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 Add fields .  If you want 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 field the attribute you want to delete. Once selected, click Delete attribute and confirm the deletion.

Export

To export a survey participants table, click Export located on the token management tools toolbar. Before exporting the survey participants list, select the desired export options.

1. Survey status:
   
1. All tokens: Exports all survey participants from the survey participants table;
2. Completed : Exports only those survey participants that have completed the survey;
3. Not completed : Exports survey participants that have not yet completed the survey;
4. Not started : Exports the survey participants that have not yet started the survey;
5. Started but not yet completed : Exports survey participants that have already started the survey, but have not completed it.
   
2. Invitation status : Exports participants according to the invitation status: all , invited , and not invited ;
3. Reminder status : Exports participants according to the reminder status: all, Reminder(s) sent, No reminder(s) sent;
4. Filter by language : When you create a survey, you can add additional languages besides the base language. Those additional languages can be used to export survey participants according to the language they are assigned to;
5. Filter by email address : Exports entries which contain the string in the respective email address. For example, you can use it if some of your survey participants use the work email addresses from "Company A". Type @companya.com and export only the users that have received a work email address from the respective company;
6. Delete exported participants : If enabled, the exported users will be deleted from your survey participants table.
   

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

When you export your survey participants, the fields are exported in the following order: