You are currently viewing the Token Control section of LimeSurvey.

From this point you can view and edit the tokens for your survey.

What are tokens
Display Tokens
Add New Token Entry
Import/Upload CSV File
Email Invitation
Send Reminder
Generate Tokens

The following options are available from the tokens control main menu bar:

| Home Click here to close the token control window and view the standard administration screen for your survey.
| Summary: Click here to view a sumary of entries in your tokens table, and to access some general database administration features, such as:

Set all entries to 'N' invitation sent:
| Deletes all records of invitations sent out. Usually done if something goes wrong with your email of invitations and you want to try it again.
Delete all unique token numbers:
| Delete all generated token numbers
Delete all token entries:
| Clear the tokens table completely
Drop tokens table:
| Remove tokens from your survey. The survey would then be accessible to all.

| Display Tokens: Click here to display all token entries
| Add new token entry: Click here to add a new participant to the tokens table.
| Import Tokens File: Click here to import a CSV file containing names and email addresses. The CSV file must be a standard comma delimited file with no quotations. The first row is interpreted as a header row. Order of data should be: Firstname, Lastname, Email, [token]. The token field is optional.
| Import Users from LDAP: Click here to import a users' names and email addresses from an LDAP directory. This feature has to be enabled by the administrator in config.php to be available. It is also up to the administrator to setup Ldap queries in config-ldap.php.
| Send email invitation: Click here to send email invitations to the participants listed in your tokens table.
| Send email reminder: Click here to send email reminders to the participants listed in your tokens table. Reminders are only sent to participants who have already been sent an invitation.
| Generate Tokens: Click here to generate unique random token numbers for your participants. Although you can manually create token numbers, or import them from a CSV file, it is usually recommended that you use this feature as it ensures that there are no duplicate entries.
| Drop Tokens Table: Click here to drop the tokens table and remove tokens from your survey. The survey would then be accessible to all.

What are "tokens"
Tokens are a system you can use to have a controlled survey. A controlled survey allows you to have a list of 'participants', or people who have been invited to respond to the survey, and then control their access to the survey. Each participant is issued with a unique token number. This token number gives the participant access to the survey.

When tokens are activated for your survey, the only people who can access the public survey are those who have a 'token' that matches an entry in this table. Using the tokens control section of LimeSurvey you can add, remove and modify these token entries.

The LimeSurvey tokens system allows you to track who has access to your survey, send out invitations and reminders to those participants, and see if they have responded. If you make your survey non-anonymous (or tracked) you can also match responses to the token entry.

Display Tokens
When displaying tokens, you can see all your entries (in lots of 50, or as determined by you). The top section of the display is the Data View Control menu bar. This menu bar gives you the following options:

| Show start: Click here to view entries from the beginning of your list.
| Show last: Click here to view the previous lot of entries.
| Show next: Click here to view the next lot of entries.
| Show last: Click here to view the very last entries in your list.

You are also able to set the number of tokens displayed, and the starting point of your records using the "Records Displayed:" and "Starting From:" fields, then clicking on "Show".

Sorting Display
At the top of each column when displaying tokens, is the name of the field and the 'sort' icon (). Clicking on the sort icon will re-order the display of tokens, sorted alphabetically by that column.

Actions
A set of actions can be performed with each individual token entry. These actions are listed below:

| Edit Entry: Click here to edit this entry.
| Delete Entry: Click here to delete this entry.
| Do Survey: Click here to do the survey using this token.
| View Response: Click here to view the response made by this participant (only available where applicable).
| Invite: Click here to send an invitation to this participant only.
| Reminder: Click here to send a reminder invitation to this participant only.

Add new token entry
With this screen you can create a new token entry, adding an extra participant to the list of people who can access the survey. The fields available are:
Firstname: The participants first name
Lastname: The participants last name
Email: The participants email address
Token: The participants unique token. While you can create your own at this point, it is better to use the "Generate tokens" feature later, and leave this blank.
Invite Sent?: If a "Y" is in this field, the participant will not be sent an invitation email when you choose "Invite". If anything else is in here, the invitation email will be sent.
Completed?: If a "Y" is in this field, the participant will not be able to use the token. When a participant completes the survey, this field is changed to "Y".

There are no mandatory fields in the 'add new token' screen. You can include as much or as little information as you want. There is no duplicate entry control either, so it is possible to have the same name over and over again.

Import/Upload CSV File
With this feature you can import a CSV file containing names and email addresses for use in your LimeSurvey survey. The CSV file must be saved as a comma delimited file, without quotation marks and the very first line is always interpreted as a header row, so if your file doesn't have a header row, the first row will be lost! Your file should look something like this:

Firstname, Lastname, Email, Token Jason, Cleeland, jason@cleeland.org, Bob, Jones, bob@cleeland.org,

Note that the final column (token) is optional. You can import your own token numbers - this may be useful if you want to use another methodology for generating tokens. For example, if you are a membership based organisation you could import your members membership number as their token.

Email Invitation
Use this feature to send invitation emails to all participants in your tokens table. Before sending an email, LimeSurvey checks each entry to ensure that the following conditions are met:
a) Email address exists
b) Token has been generated
c) An invitation has not already been sent
d) Participant has not yet completed the survey

Each invitation is personalised, and is merged with information from the tokens table. You are given the option of modifying the subject and text of your email before it is sent out. To use information from the tokens table in the body of your email, use the following 'merge' codes:
{FIRSTNAME}: First name
{LASTNAME}: Last name
{SURVEYNAME}: The name of your survey
{ADMINNAME}: The name of the survey administrator
{ADMINEMAIL}: The email address of the survey administrator

For example, if your message reads "Dear {FIRSTNAME} {LASTNAME} here is a survey called {SURVEYNAME} for you to try. Love {ADMINNAME}" The recipient will receive an email that looks something like this: "Dear Saddam Hussein here is a survey called What I Did On My Holidays for you to try. Love Jason Cleeland".

Send Reminder
Use this feature to send reminder emails to all participants in your tokens table. Before sending an email, LimeSurvey checks to ensure that the following conditions are met:
a) Email address exists
b) Token has been generated
c) An invitation has already been sent out
d) Participant has not yet completed the survey

Generate Tokens
Use this feature to generate unique random token numbers for each entry in the tokens table that does not have a token.