Configuring Participant Authentication

Home / DatStat Illume Product Documentation / Working With Basic Questions / Configuring Participant Authentication

This page describes the concepts of unauthenticated and authenticated surveys, and how to set up each type in the Illume Survey Designer.

What is an Unauthenticated Survey?

An unauthenticated survey is one in which:

  • No credentials are required to take the survey
  • A respondent may take the survey multiple times, as the survey does not “know” who the respondent is, or that the respondent has previously taken the survey.

This type of survey might be a link on a website like Facebook, wherein the respondent simply clicks on the link and is taken immediately to a series of questions

Configuring an Unauthenticated Survey

Every Illume survey contains a Login Collection, which is the one and only collection that cannot be deleted.  It is within this collection that authentication is handled.  The purpose of the login collection is to ask participants for credentials to log in. By nature of being an unauthenticated survey, no credentials are required to log in.  Thus, to configure a survey to be unauthenticated, you simply need to ensure you create no questions in the Login Collection.  Your login collection may contain a text object, such as a welcome page, but should not capture any information.

If you do not want/need your participants to see the login collection page of the survey, you can add a tag to the end of the URL: &LoginID=1.  For example, if your survey URL is:

Then the URL to use when you want to bypass the login collection is:

What is an Authenticated Survey?

An authenticated survey is one in which:

  • Access is controlled and limited to a defined set of participants
  • A passcode or unique combination of passcodes/IDs must be entered to launch the survey
  • The passcode (or unique combination of passcodes) can only be used once – one submission per participant

Configuring an Authenticated Survey

Setting up a survey to be authenticated requires implementation steps in the Survey Designer, as well as steps in the Enterprise Manager.  This page will cover the steps in the Survey Designer.

The first step in configuring an authenticated survey is determining on what participant variable, or combination of variables, do you want to authenticate.  There are two options in this regard:

  1. Use a customer-defined pre-assigned ID schema (Custom ID authentication)
  2. Have Illume generate a unique ID for each participant (System-Generated ID authentication).  This method is typically only used when the survey link is being distributed via an Illume Email Job, wherein Illume automatically generates a unique URL per participant, allowing the participant to click on the link and be taken directly to the first page of the survey without ever seeing the Login page or needing to enter an ID.
Custom ID Authentication

When using this method of authentication, you have pre-defined a single participant variable, or a combination of participant variables, that uniquely identify your respondent.  For example, you may have a file containing the first and last names of all participants, along with their email addresses and employee ID numbers. Let’s assume these fields are named FIRSTNAME, LASTNAME, EMAIL, and EMPID. Let’s also assume you want participants to log in using their email address and employee id number. To do this, you would create two questions in the Login Collection: one name EMAIL that asks for the participant’s email address, and another named EMPID that asks for employee id.  When a participant types in his or her email address and employee id, Illume checks that the following two things are true:

  1. The list of participants associated to the survey contains a participant with  the given email address and employee id.
  2. The participant with the given email address and employee ID has not already taken the survey for the current Time Period (see Academy section on Time Periods)

You may use any field or combination of fields in your participant list to authenticate participants. For each field you want to use:

  1. Add a question to the Login Collection (in the standard way you would create any type of question)
  2. Make sure the question’s data dictionary name matches the desired field name in the participant list.

The recommended data dictionary name to utilize for a single custom authentication variable in the login collection is DATSTAT_ALTPID.  DATSTAT_ALTPID is a built-in participant property on Illume participant lists designed to capture and store the participant’s alternate participant ID.

If utilizing DATSTAT_ALTPID in the login collection, ensure the data type utilized on the Response Options tab is “Text” to match the data type of the participant property.  Utilizing this property instead of building your own custom property for authentication provides advantages in regards to ease in updating participants via flat files.

Manual vs Auto-Authentication

Manual authentication involves sending your participants to the survey URL, and requiring your participants to enter their ID or unique combination of IDs in order to enter the survey.  Auto-Authentication involves having Illume’s Email Job generate a unique survey URL per participant, and having each participant click on that link and be taken immediately to the first question in the survey, bypassing participant visibility of the Login page (see section below on System-Generated ID Authentication)

Regardless of whether you are using manual or auto-authentication, you must build a question or question in the login collection to capture the ID(s).  Therefore your only other design consideration is in regards to what other content you may or may not choose to place in the Login collection.  If your survey uses manual authentication, then the first page your participants will see is whatever is in the login collection.  Given this, you may want to put a welcome page, logo, or or other information in the Login Collection.  If your survey uses auto authentication, then your participants will never see what is in the login collection.  Given this, any welcome pages or other instructional text should not be placed in the Login Collection, but rather should be placed just outside of the login collection.

System-Generated ID Authentication

This method of authentication is to be used when you do not want to create unique ids for all of your participants, but you do want to ensure that only people on your participant list can take your survey (and can take it only once).

When you upload a participant list in the Enterprise Manager of Illume, a unique ID is automatically generated for each participant on the list.  That ID is an alpha-numeric string and it is stored in a field called DATSTAT_PID.  System-Generated ID Authentication takes advantage of this automatically generated identifier by utilizing it for authentication.

The first step is to create a single question in the login collection. The question must have the display type “Text”, and the question’s unique name must be “DATSTAT_PID”. Your participants  will never see this question, as the first thing the participant will see when he/she clicks on the link generated in the Email Job is the first question in the survey.  That being said, you will still need to enter something for the prompt of the DATSTAT_PID question.

In the Enterprise Manager you will upload and associate a participant list to this survey.  It will not need a column for an ID.  The only required column is a column to contain the email addresses of each participant.

When you create an Email Job, Illume will send out email invitations to your survey with the unique ID appended to the URL.  Here is an example URL:

Important Cautions

  1. Do not include duplicate entries in your participant list.For example, if you are requiring participants to provide an email address and employee id to access your survey, do not include in your participant list more than one participant with the same combination of email address and employee id, even if other data for these two participants differs. When a participant logs in, Illume looks for a unique participant in the list who matches the supplied credentials. If Illume cannot find a unique entry matching the credentials, the participant will not be allowed in.
  1. Do not include questions in the Login Collection whose data dictionary names are not column names in the participant list.The example above used EMAIL and EMPID as the unique names of questions in the Login Collection. These matched the EMAIL and EMPID fields in the participant list. If the EMPID question had been named EMPLOYEEID, no participants would be able to log in, because the participant list contains no EMPLOYEEID column.
  1. Do not include survey questions in the Login Collection. The Login Collection is only for authentication. Survey questions should live outside of the login collection.