Access Control

Importing tokens from a CSV file

When you use tokens, you often already have a list of names and emailadresses you want to import. LimeSurvey allows you to do this with a CSV file.

What is a CSV file?

CSV stands for Comma Seperated Values. A CSV file is just that, a list of comma seperated values, typically with column headings on the first line.

Create a CSV file for LimeSurvey

LimeSurvey tokens require at least 3 values; first and last name, and an email address. Extra attributes can be added, but you first have to define them in LimeSurvey. More on that here.

Create a list of relevant information (usually first and last name, as well as an email address) , and enter the data for your intended recipients. You can do this any way you like, as long as the end result has one column for first names, one for last names, and one for email addresses. Make sure the first row has the values “firstname”, “lastname” and “email”, corresponding to the right columns, you results should look like the image below.

LimeSurvey uses the first row to apply data to the correct token attributes, so these labels must be typed exactly as they appear above. Save the file as CSV and you should be ready to import.

Importing a CSV file

To import a ready CSV file, log in to LimeSurvey, and select your survey from the dropdown list on the top right, then click the tokens button on the survey menu bar.

If you have not enabled tokens yet, you will get a warning message, corfirm that you want to initialise tokens. You are now in the token control screen, which should look like the image below.

You have a variety of options, the import tokens from a CSV button is encircled in this image. Click it to start importing. You can now select the CSV file, pick a character set (usually not necessary, leave this as-is, unless you encounter problems with special characters), change the separator used (more on this here), as well as filter blank emails and duplicates. Point LimeSurvey to your tokens csv file, click upload, and LimeSurvey should tell you it has successfully uploaded the csv and created token entries. If not, you may want to take a look at the common errors section here.

Adding extra token attributes

If you already have some more information about your participants that you would like to add to the tokens, you can import them with the CSV file too.

Let’s say you wanted to add the company or institution a participant works for, to create a tailored welcome message later. First, you have to create the token attribute in the LimeSurvey token control screen. Make sure you are in the token control screen, then click the button for additional attributes.

On the next screen, first enter the amount of custom attributes you want to add, then click add fields. You can now enter a description for your custom attributes, for example “company”.

Note that the description you give is not the name of the attribute, the name and label for the attribute in the CSV file and the Expression Manager is attribute_1, attribute_2, etc.

Update your CSV file to look like the below image, save it, and import it to LimeSurvey to have your tokens populated with custom attributes.

Common errors

If something happens that LimeSurvey does not expect, or if LimeSurvey fails to read the CSV file, a message like this will pop up. This often points to one or more problems, which are shortly explained below.

Incorrect delimiters

LimeSurvey expects commas as the delimiter of a comma separated file. Microsoft Excel often saves CSV files with a semicolon delimiter. Recent versions of LimeSurvey allow you to select the delimiter used, the default setting is ‘automatic’. When the delimiter is set to automatic, LimeSurvey is usually smart enough to detect this common error and compensate, but it may be better to ‘manually’ change the csv file to use commas. You can do this in many ways, but the easiest two ways are to open and save the file in a program that does use commas correctly (e.g. SPSS), or open the file in a text editor and use the find and replace function to replace all semicolons with commas. If, for some reason, your csv file uses even more exotic delimiters, you can use a text editor to replace them with commas.

Incorrect attribute names

LimeSurvey uses the first line of a CSV file to assign values to the correct token attributes. Mandatory attributes are first name, last name and email, and their names in LimeSurvey are “firstname”, “lastname” and “email”. Make sure your CSV file uses the correct names, without spaces, and case sensitive.