This article describes the procedure for setting up a survey to interact with an external panel for its sample. It assumes knowledge of how to define variables in AskiaDesign.

Introduction

When the sample for your web survey is drawn from an external panel, the panel company will normally handle all of the invitations and reminders to your participants. Instead of providing you with a sample list, they will send qualified respondents directly to your survey. The way that you control access to the survey, and interact with your panel provider is through the exchange of links - the URL of your survey and the URL of the panellist's landing page for the panel operator's site.

It is important to be able to use these links and the information they provide in your survey, such as to control routing. Defining these links, capturing the data from them, and routing participants back to the panel provider are all described in this article.

Creating the survey link

There are different ways that external panel providers operate, but in this article we will cover the two most popular ones. In both, each participant will enter the survey using their own individual link, which will identify the participant. Having a unique identifier is important for two reasons: it means that you and the panel operator can identify who has participated, and also you can prevent people from participating more than once. Panel companies wish to know who has participated so that they can reward the participant appropriately for their participation.

The two models are:

• The panel operator generates the links. You provide the panel company with a generic survey start link and the panel provider appends the panel member's unique ID to this link so that you and they can identify who has participated in the survey.
• You generate the links. You create a series of numbers (ideally unique but random numbers) and append this to the survey start link, then send a batch of fully qualified individual links to the panel provider for them to use in their survey invitations.

In both cases, the format of the link is identical - the difference is whether you complete the link yourself, or send it to the panel company without the unique identifier, and with instructions to them on how to complete it: a 'model' survey start link.

Let's now look at how to create a model survey start link.

The model survey start link

http://servername/webprod/cgi-bin/AskiaExt.dll?Action=DoExternalPanel&SurveyName=AskiaSurvey&Broker=panel-reference&
BrokerPanelId=unique-reference

 

The link consists of five elements:

1. The URL of the web server and the Askia web service.

http://servername/webprod/cgi-bin/AskiaExt.dll

The server name will always be the same for your Askia installation. It can be found by interrogating the survey task. To do this, right click on the survey, and copy the survey link. Note that you will only use the first part of the link, up to the “?” character.

2. Action parameter

?Action=DoExternalPanel

The action is always set to “DoExternalPanel” is always used when working with an external panel. Note that the value is case sensitive.

3. Survey name as defined in the CCA

&SurveyName=yoursurvey

4. Broker name

&Broker=_broker_name

The broker name identifies the panel source being used. This allows you to identify which panel provider contributed which participant. You may choose any sequence of letters and/or numbers to identify the panel broker. You may wish to use a standard set of codes across all your surveys for the different panels that you work with.

5. Broker Panel ID

&BrokerPanelId=unique-reference

The unique reference for each participant in the survey.

Complete examples

Example of a survey link sent to a panel operator for them to complete

http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=DoExternalPanel&SurveyName=JM3277100&Broker=BMC&
BrokerPanelId=unique-respondent-reference

The values set for each parameter are as follows:

• alpha.askia.com is the server where the survey resides
• DoExternalPanel is the survey start action
• JM3277100 is the survey name defined in CCA
• BMC identifies the panel provider
• unique-respondent-reference is a placeholder for the panel provider to replace with the respondent ID on each link it generates.

Example of a survey links from a batch of links sent to a panel operator:

http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=DoExternalPanel&SurveyName=JM3277100&Broker=BMC&
BrokerPanelId=10001626
http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=DoExternalPanel&SurveyName=JM3277100&Broker=BMC&
BrokerPanelId=10001634
http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=DoExternalPanel&SurveyName=JM3277100&Broker=BMC&
BrokerPanelId=10001649
http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=DoExternalPanel&SurveyName=JM3277100&Broker=BMC&
BrokerPanelId=10001655
http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=DoExternalPanel&SurveyName=JM3277100&Broker=BMC&
BrokerPanelId=10001660

 

Using a language ID

Setting the language using an external language ID on the link

If your survey is multi-lingual, you can pre-set the language to that spoken by the participant, by adding a code that selects the right language on the survey link. The panel company may ask you to specify a list of codes, or they may notify you which codes they use for each language.
For example, your survey may have these languages, with these codes:

• 11 English
• 13 French
• 16 German
• 18 Italian
• 22 Spanish

In this example, we will create a numeric variable with the name "lang" to receive the code from the link. If the language codes are letters, rather than numbers, define an open text variable instead.
To assign the language codes:

• Start by creating a numeric question with the name "lang" in Design to receive the language code.
• click on the Import button and select Internet parameter and enter the name "lang" for your question.
• Next create a routing with the directive Set language and assign each language code to the relevant language (When creating the routing, the routing's Action will, once selected, automatically list the questionnaire’s available languages).
• Add the the parameter "&lang=nn" to the end of the survey link, where nn is the code for the language.

For example:

http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=DoExternalPanel&SurveyName=JM3277100&Broker=BMC&
BrokerPanelId=10001626&lang=11

http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=DoExternalPanel&SurveyName=JM3277100&Broker=BMC&
BrokerPanelId=10001626&lang=13

The first link would set the language to English (code 11) and the second would set the language to French (code 13).

Once you have defined a survey with a language identifier in this way, the link must always contain a parameter setting the value of the language. If the parameter is missing, or the data are badly formed, the survey will fail to start, and present an error message.

 

Passing other values

The same method used to define the language (described above) can be used to import additional information into the survey that the panel provider might be willing to provide. This can avoid the need to ask these questions again in the survey, because the information is already known.

Start by creating a question in Design. Choose the variable type according to the range of values it will receive from the panel provider. For example, if it is an alphanumeric string such as a name or letter code, define this as open. If it is to be a number, define it as numeric. Values passed in as parameters through the survey link cannot contain spaces, so any text must be restricted to a single word or group of characters.

Next, click on the Import button and select Internet parameter. Enter the external name for your question, which will be used on the link to pass across the value. This does not have to be the same name as the internal name you have chosen for your question, although for simplicity, you may prefer to give it the same name. Since the name will be visible to the participant, you may choose to disguise it with a different name.

Finally, when defining the survey link, add a parameter in this form to the end of the link.

&var=value

Where var is the external name you defined in the Internet parameter field of your question definition and value is the assigned code, number or keyword for that variable, i.e. the contents of the variable.

If you have more than one variable defined in this way, list all the variables and their values in the same way. The order of the names is not important.

&var=value&var2=value2&var3=value3 [... etc] 

 

A worked example
In this example, two parameters are being passed over from the panel. First is the panellist's gender with the code 1 for male and 2 for female. Second, is a three-digit code which identifies the occupation of the head of household.

• Define a variable with the name "Gender" and with the type single.
• Click Import and enter the name into the Internet parameter field. In this case, we will disguise the name by using "gdr" as the external name.
• Repeat the process, defining another variable, this time a numeric variable called "occ".
• Click Import and enter the same name "occ" into the Internet parameter field.
• Instruct the panel provider to append this parameter to the end of the survey link "&gdr=1" for male or "&gdr=2" for female, followed by "&occ=000" where 000 is replaced with the three-digit occupation code.

Note, in this example, the codes for gender were assigned directly to a single variable. Take care when doing this to ensure only values that correspond exactly to the codes allowed for your single variable are received.

Unlike variable names, parameters on links are case sensitive, so it it may be best to keep to lowercase letters.

Once a parameter has been defined as an import field, it becomes a mandatory item in the survey link. If the parameter missing, misspelled or has the wrong type of data associated with it, the user will see an error message saying that the link is badly formed. This will prevent the survey from operating for all participants where a parameter is missing.

An example link (using the same settings as the previous example) with this qualifier would look like this:

http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=DoExternalPanel&SurveyName=JM3277100&Broker=BMC&
BrokerPanelId=10001626&lang=11&gdr=1&occ=201

In this example:

• lang is the language code defined in the previous example (11 for English).
• gdr is assigned the value 1, which sets the associated Askia variable gender with the code for male.
• occ is assigned the value 201, which sets the associated Askia variable occ with the same value.

Capturing the broker name and ID

Askia automatically stores all the values passed on the survey link into its internal database, but to store the values in the survey data, so that you can refer to them within the survey, e.g. to use them as conditions for your routing, you need to define a variable and set the value using the Import process described above for passing data into the survey. This time, however, the Internet parameter name that you enter will be "Broker" if you wish to capture the panel source, and "BrokerPanelId" if you wish to capture the unique participant's ID.

For example, to use the panellist's ID as your internal respondent ID, create a question "respondent_ID", and in Import, set the Internet parameter to say "BrokerPanelId".

 

Creating a test link

Panel companies will normally ask to test any survey to which they will be directing their panellists. You can provide them with a text link, by adding the qualifier to the link. This may appear anywhere in the link, after "?action=". A test link will not save any data, but it will execute all of the logic and display any question on the currently selected logical path exactly as the respondent would see the survey.

&Test=true

There is no need to define a panel broker or broker ID for test links. It is therefore usually better to use the simpler StartSurvey action. Using the same example as before, a test link would look like this:

http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=SurveyStart&SurveyName=JM3277100&Test=true

If the survey uses import variables on the link, then for these will also need to be tested, and the several test links should be provided to test different situations, e.g.

http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=SurveyStart&SurveyName=JM3277100&lang=11&gdr=1&occ=201&Test=true
http://alpha.askia.com/WebProd/cgi-bin/AskiaExt.dll?Action=SurveyStart&SurveyName=JM3277100&lang=11&gdr=2&occ=132&Test=true

Related topics

Links and personalised invitations when working with your own sample (forthcoming).
Possible AskiaExt Links.