Survey start links

This topic describes the available survey start links that you can send to respondents in your survey invitations. By clicking the links, respondents can begin the survey.

There are several types of start link available (follow the links below for details of a specific start link type):

• StartSurvey: starts a survey without resume capability;
• DoPanel: starts a survey with resume capability; invitation mailing is done by CCA;
• DoExternalPanel: starts a survey with resume capability where invitation mailing is done by an external sample provider;
• SyncData (administrators only): synchronises SQL interviews with the interviews on disk.

StartSurvey link type

This type of link always begins the survey without any resume capability. This means that each time the survey start link is clicked by a potential respondent, a brand new interview will be started. This is most useful when inviting unknown respondents. For example, for surveys starting from a pop-up or an advertisement on a website.

New-format StartSurvey links

After replacing the parameters as appropriate, paste the appropriate link into the website or invitation email. If you are using the new format ("pretty") links (note that your server has to be set up to support them):

Servername should be replaced with the URL of the server on which the survey is running (e.g. askia.com).

MySurvey should be replaced with the external name of the survey as defined in WebProd.

In addition, see StartSurvey parameters below, which are optional for new-format links.

Old-format StartSurvey links

If you are using old-format links, use the following format:

StartSurvey Parameters

• SurveyName: The external name of the survey as defined in WebProd (not applicable for "new format" links).
• Test: This is an optional parameter. If it is set to true, the interview will begin in test mode. This means it will progress as normal, but will be deleted on completion or after a timeout of one hour; the completed survey will not be sent to CCA. If the parameter is omitted, test will be assumed to be false, and therefore a normal interview will be conducted. A test link might appear as follows:
  http://servername/webprod/cgi-bin/AskiaExt.dll?Action=StartSurvey&SurveyName=AskiaSurvey&Test=True

Notes

• In an invitation email template, CCA will replace a StartSurvey link with a DoPanel link.
• Instead of copying and pasting the survey link generated by CCA, you can instead use the keyword [ccaStartSurveyLink] in a mail template.

Generated interview file name (if interviews are saved to disk)

Intvw<seed>[.dat]

Example: Intvw123.dat

DoPanel link type

When the invitation mailing is done via CCA, a DoPanel link will automatically be generated and sent to the respondents.This will start a survey with resume capability. To use it, simply paste a StartSurvey link or the [ccaDoPanelLink] keyword into the invitation email.

This link will be automatically updated by the CCA to transform it into a unique DoPanel link for each respondent within the sample list. Each potential respondent will receive a customised link containing encrypted sample list information. For example:

http://servername/webprod/cgi-bin/AskiaExt.dll?Action=DoPanel&Survey=RYLZDLVLLBHLNJBL&PanelId=RYLZDLVLLBHLNJBL@FFFHPMPFHIGPKFBK

New-format DoPanel links

DoPanel links are simply StartSurvey links used in an invitation email. If you are using new format ("pretty") links (note that your server has to be set up to support them), they will appear as follows:

Servername is the URL of the server on which the survey is running (e.g. askia.com).

MySurvey is the external name of the survey as defined in WebProd.

In addition, see DoPanel parameters below, which are optional for new-format links.

Old-format DoPanel links

DoPanel Parameters

• Survey: The Askia-encoded CCA survey ID (not applicable for "new format" links).
• PanelId: The Askia-encoded panel ID. Format: ContactID@ListID. The Contact ID is the AskInterview field in the AskList table. See below for details on how to decrypt this data.
• Test: This is an optional parameter. If it is set to true, the interview will run in test mode. This means that it will progress as normal, but will be deleted on completion or after a timeout of one hour and the completed survey won't be sent to CCA. If the parameter is omitted, test will be assumed to be false, and therefore a normal interview will be conducted.
• FromStart: This is an optional parameter. If this parameter is set to 1, the survey will always start from the beginning, without erasing any previous answers. This is only available on incomplete interviews.

Note

Instead of copying and pasting the survey start link generated by the CCA into your email template, you can also use the keyword [ccaDoPanelLink] in your mail template, inside square brackets.

Generated interview file name (if interviews are saved to disk)

PIntvw-<surveyid>-<panelid>-<listid>[.dat]

Example: PIntvw-11-22-33.dat

DoExternalPanel link type

This will start a survey with resume capability. This should be used when the invitation mailing is done outside of CCA (for example, with a sample provider). The respondent is identified by a unique combination of Broker and BrokerPanelId.

New-format DoExternalPanel links

After replacing the parameters, paste the following link into the website or invitation email:

Servername is the URL of the server on which the survey is running (e.g. askia.com).

MySurvey is the external name of the survey as defined in WebProd.

In addition, see DoExternalPanel parameters below, which are optional for new-format links.

Old-format DoExternalPanel links

After replacing the parameters, paste the following link into the website or invitation email:

DoExternalPanel Parameters

• SurveyName: The external name of the survey, as defined in WebProd (not applicable for "new format" links).
• Broker: Some text to identify the broker (i.e. the sample provider, usually set by the survey institute).
• BrokerPanelId: Some textual identifier (usually set by the sample provider) to uniquely identify a panel member.
• Test: This is an optional parameter. If it is set to true, the interview will run in test mode; it will progress as normal, but will be deleted on completion, or after a timeout of one hour, and the completed survey won't be sent to CCA. If the parameter is omitted, test will be assumed to be false, and therefore a normal interview will be conducted.

Generated interview file name (if interviews are saved to disk)

XIntvw-<surveyid>-<broker>-<brokerpanelid>[.dat]

Example: XIntvw-11-AskiaBroker-BrokerPanelId.dat

SyncData link type (administrators only)

This will synchronise the SQL interviews with the interviews on disk. An ADO connection string must be entered in the options page (but the WebProd option store dat files on SQL does not have to be enabled).

Link format

Parameters

• SurveyName: The external name of the survey as defined in WebProd.
• Direction: The direction in which the synchronisation will be carried out. Possible values are as follows:
  • ToSQL (since 5.3.3.21/5.3.5.2: DiskToSQL)  or 1: From Disc to SQL Server.
  • FromSQL (since 5.3.3.21/5.3.5.2: SQLtoDisk) or 2: From SQL Server to Disc.
• Qex: This is an optional parameter. It determines whether the Qex file stored in the WebProd database (if the WebProd option store qex in database is enabled) should also be synchronised to/from disk. The synchronisation direction is determined by the Direction parameter (see above). Possible values: 0/1/yes/no/true/false. The default value is no.
• From and To: This is an optional parameter. It specifies the start and end dates/times for activity, in the format YYYY-MM-NN HH:mm:ss. For example:
  http://127.0.0.1/Webprod/cgi-bin/askiaext.dll?Action=SyncData&SurveyName=XXX&Direction=FromSQL&From=2013-01-03&To=2013-01-04
• Type: This is an optional parameter. It specifies which interviews should be synchronised. Possible values are as follows:
  • 0: All interviews (this is the default).
  • 1: Only incompletes.
  • 2: Only completes (note that the To Cca flag is ignored).
• Seed: This parameter is optional in versions 5.3.3.21/5.3.5.2 onwards. It indicates the desired seed (&Seed=1234), or the range of desired seeds (&Seed=1234-5678). For example:
  http://127.0.0.1/webprod/cgi-bin/AskiaExt.dll?Action=SyncData&SurveyName=AskiaDemo&Direction=SQLtoDisk&Seed=2802
  http://127.0.0.1/webprod/cgi-bin/AskiaExt.dll?Action=SyncData&SurveyName=AskiaDemo&Direction=SQLtoDisk&Seed=2504-2901
• Broker: This parameter is optional in versions 5.3.3.21/5.3.5.2 onwards. It specifies the interviews from a specific sample provider will be synchronised (e.g. &Broker=toto). For example:
  http://127.0.0.1/webprod/cgi-bin/AskiaExt.dll?Action=SyncData&SurveyName=AskiaDemo&Direction=SQLtoDisk&Broker=TOTO
• ErrorPage: This is an optional parameter. It defines the page that will be redirected to after synchronisation is done (note: the path is relative to /cgi-bin). This is mainly used by WebProd to show pgEditSurvey.asp again after synchronising. If this parameter is missing (or empty), a result page will be shown, displaying the number of synchronised interviews.

Notes

• Test interviews are never synchronised.
• Synchronising is a very resource-intensive operation. When you use this function, it is possible that other requests may see a response delay, or, in extreme cases, a time-out.
• To test the survey without saving the data, you simply need to add the following text (case sensitive) to the end of your survey's links:
  &Test=True

Configuring your server to allow new-format ("pretty") and encrypted links

If you want to use new-format ("pretty") survey start links or encrypted links, you first need to install an embedded ISAPI filter in Internet Information Services on the web server that is hosting the surveys. This filter allows your server to intercept and change URL requests.

To enable new-format and encrypted links on your web server:

1. On your web server, open IIS Manager (please refer to the official Microsoft IIS documentation for assistance).

2. In the tree on the left, open your website's configuration (not the server configuration).

3. Open the ISAPI Filters item (by double-clicking it).
   

4. In the right-hand pane, under actions, click add....

5. In filter name, enter WebProd.

6. In executable, specify the full path to AskiaExt.dll:
   

7. Click OK. The change takes effect immediately; there is no need to restart IIS or the application pool.

Using encrypted links

To prevent users from editing survey start links, you can distribute encrypted links instead of clear text links. These encrypted links are also shorter than the original links because known parts (like Action=StartSurvey) are replaced with placeholders.

For example, this link...

...would be encrypted to something like this:

A DoExternalPanel link (which is normally quite long), will also be quite a bit shorter in its encrypted format. For example:

...would become something like this:

Extra parameters are also possible, but the encrypted link unavoidably gets a bit longer.

This:

Will become something like this:

Which is quite a bit longer than the link above.

Encrypting a URL

To obtain an encrypted URL, you can use AskiaExt as well, using the parameter Action=EncryptLink, and the parameters (the part after the question mark) as the Link parameter.

For example, for this request...

http://askia.com/WebProd/cgi-bin/askiaext.dll?Action=EncryptLink&Link=Action%3DStartSurvey%26SurveyName%3DMySurvey

...you will get a plain text encrypted value back like this:

O1p1PnpkpSI

To use this in a link you have to include the prefix yourself (including a ~ to indicate this is an encrypted link). So in our case we have to start each link with http://askia.com/WebProd/~

Note that you have to URL-encode the link parameter. So instead of using

You have to use

It is also possible to use a ‘pretty’ version of this command which doesn’t require URL encoding:

This will also return the encrypted value.