How-to: External Survey Start

Owned by Dennis Mergemann (Unlicensed)
Last updated: Sept 24, 2021
12 min read

The “external survey start” of EFS allows to send survey participants from one project to a second project and to redirect them upon completion. This can be necessary in the following situations, for example:

  • You want your panelists to take part in a project that was created by somebody else on another EFSinstallation or using external software. However, for the incentive management in your panel you would like to record which panelists have completed the survey.

  • You want to conduct a conjoint survey using external survey software, the frame survey is to be created with EFS, though.

Technical Background

The external survey start is based on the use of GET parameters. GET parameters are variable values that are transferred to a page via the URL. This is a well-established standard web technology. It has already been used in EFS for a long time, e.g. for the transfer of external data to a survey via URL parameters.

Constructing URLs with GET Parameters

When adding GET parameters to a URL the following rules apply:

  • The GET parameter(s) must be separated from the actual URL by a question mark (?). This way the server can distinguish the actual URL from the GET parameter(s).

  • 􏰀If more than one GET parameter is added, then they must be separated from each other by &.

  • 􏰀For every GET parameter the URL lists first the variable name, followed by an equation symbol (=) and ultimately the variable value to be transferred. In the example below, a and b are variable names, 1 and seminar are the variable values. Different types of data are possible: In the example, variable a with the value 1 is of the “integer” type, variable b with the value “seminar” is of the “text” type.

External Survey Start in Practice

The external survey start in EFS makes use of GET parameters to send survey participants from one project to a second project, to authenticate and subsequently redirect them. In this chapter you will configure an external survey start yourself, linking two EFS projects within the same installation.

Creating the Questionnaires and Configuring Forward and Return Jumps

  • Create the primary and secondary projects. The primary project can be of the “anonymous” or the “personalized” type, for the sake of simplicity the secondary project should be “anonymous”.

  • Create the first part of the primary questionnaire.

  • Next up is the page that redirects the participants to the secondary survey.

    • Click on + Dynamics and select External Survey Start to create the External Survey Start page.

  • The new page is displayed in the questionnaire view. Click on the link.

  • You are automatically taken to the Page properties tab.

  • In the “Destination URL of external survey” field, enter the URL of the secondary project. You will find this in the field labeled “URL” in the project information of the secondary project.

  • The other options are configured appropriately for this example by default: “Add ticket” is activated, “Use long clear-text tickets” is deactivated.

  • Confirm by clicking on Save.

  • Create the questionnaire for the secondary project.

  • The final page of the secondary project serves as the jump page to return to the primary survey. This means that instead of filling this page with contents as usual, you click again on the page link to open the Properties (left hand side).

  • Enter the URL of the primary project as the destination URL. This you will find in the project information of the primary project, as explained above.

  • The other options are configured appropriately by default: the checkboxes “Automatically add ospe.php3” and “Add return ticket” are ticked.

  • Confirm by clicking on Save.

  • Create the second part of the primary project that the participants will complete after the return.

  • The configuration of the questionnaires is now complete.

It is, in principle, not possible that the primary project times out while the participants complete the secondary project.

Testing

When testing, some aspects require special consideration:

  • The external survey start cannot be tested in the preview but only in productive mode.

  • In order to be able to repeatedly test an anonymous survey, you either delete the cookies from the browser after every test run or disable the use of cookies for both projects in the Project properties menu.

  • After testing, both projects have to be compiled in order to delete the data of the testers entirely.

The browser address bar will tell you whether the jump occurs in the desired place. The figure below shows the URL of a questionnaire page in the primary project right before the jump to the secondary project. There you will notice the folder “3a6f” of the sample project.

After the jump, the folder “38d1” of the secondary project will appear in the same place.

After the return jump the participant is taken back to the primary project with the folder “3a6f”. In the URL you will also recognize the automatically or manually inserted attachment ospe.php3 and the GET parameter return_tic which is used to identify the participant and to direct him to the correct page.

Checking the statistics and the export data record

The statistics and the export data record of both primary and secondary project should be showing you the values from your test run. The consecutive number of the respondents (“lfdn”) is automatically transferred to the secondary project via “tic”. You should be able to locate the “lfdn” of a data record in the primary project in the column labeled “external_lfdn” of the secondary project’s matching data record.

Data Transfer in Detail

During the external survey start information on the participants is transferred from one survey to the other by adding it to the URL as a GET parameter. Basically, this is done in one of the following ways:

  • Identifying participants

  • Authenticating participants in secondary projects with limited participant pool

  • Transferring any data via GET parameters (via URL parameters when jumping forward, via user-defined variables when jumping back)

Identifying Participants and Matching Data Records

If you select the default settings (option “Add ticket” activated, option “Add ticket for target EFS project < 5.2” deactivated), the external survey start will be executed automatically based on pre-configured tickets.

  • Parameter “tic” is transferred at the jump from the primary to the secondary survey, “return_tic” is transferred at the return jump to the primary project.

  • The parameters ensure that the participants can be identified at the return jump and that they resume the primary project at the correct location.

  • It the jump connects two EFS projects, the tickets ensure that you can match the data records. For this purpose, the consecutive number of the respondents in the primary project is transferred automatically into the variable “external_lfdn” of the secondary project.

  • If you are using external software and wish to match the data records later, Instead, you have to transfer “tic”, “lfdn” or another value that might serve to identify the participants via GET parameter.

EFS allows to customize the external survey start according to special requirements:

  • Both of the “tic” parameters can be renamed. This can be necessary when you are using external software that requires parameters with different names.

  • You can decide for yourself whether you want to use “tic” and “return_tic” at all. If no ticket is added, only the URL (optionally with attached parameters) will be transferred when jumping to the secondary survey. This has the following consequences:

    • It will no longer be possible to jump back to the primary survey.

    • It will no longer be possible without further effort to merge the data from the primary and secondary surveys and match the records of individual participants from both surveys. If you wish to match the data from the primary and secondary surveys without using the tickets, a suitable parameter must be transferred instead of the tickets. For example, you can attach the consecutive number by adding the string ?a=#lfdn# to the destination URL.

    • If you do not want to use the tickets, untick the “Add ticket” checkbox on the Page properties tab. By default, this checkbox is ticked.

In addition to the default tickets described above, older tickets, the so-called “plain text tickets”, are still kept alive until EFS 8.1. They should be used if the secondary project is located on an EFS installation < 5.2.

  • To use these tickets, please activate the option “Add ticket for target EFS project < 5.2”.

  • As with the default tickets, the consecutive number of respondents (“lfdn”) in the primary project is stored automatically in the variable “external_lfdn” of the secondary project to allow matching of data records.

  • Please bear in mind that during the transfer of the “lfdn” via GET parameter it is possible for unauthorized users to extract the “lfdn”.

  • The strings of the plain text tickets are very long. Some web servers may have difficulties processing these strings.

  • Please note that the plain text tickets will be dropped in the next release.

Authenticating Participants in Secondary Projects with Limited Participant Pool

The various EFS products support different project types: anonymous and personalized survey, panel survey, master data survey and employee survey. All of these types can be used both as primary surveys and as secondary surveys. If projects with a clearly-defined participant pool serve as destinations of a jump, an authentication is necessary at the start of the secondary project.

  • When jumping from one personalized project to another, this is realized by using the same code from the secondary project in the primary project, too.

  • When jumping from a panel survey into a personalized project, personalized links are constructed for all participants, containing the codes of the secondary project.

  •  If external survey start is used to connect two panel projects, project ID, sample ID and data for authentication must be transferred.

Authentication When Jumping From One Personalized Project to Another

If both primary and secondary project are personalized, then the secondary project requires an authentication. For this, the participants’ authentication codes are used twice: The codes are generated in the secondary project and subsequently imported into a specially created participant variable of the primary project. When jumping from the primary to the secondary project, the codes are transferred as GET parameters to the variable “code”, the authentication is performed automatically. Please proceed as follows:

  • Import the participants into the secondary project or create the accounts manually. The participants’ codes are usually generated by the system. (Alternatively, the codes can also be generated in Excel and imported along with the participants.)

  • Next, the codes of the secondary project have to be extracted and imported into the primary project. Click on the Excel export or CSV export button to export the list of participants including the codes. The list of participants can be used as it is as an import file for the primary project.

  • Proceed to import the participant data and codes into the primary project. From EFS 6.0, the codes can be imported directly: they are stored in the “code” database field.

  • Assign the “code” column to the appropriate database field when importing into the primary project.

  • The desired participant data including access code are now available in the primary project as well. Next, the jump page has to be configured so as to allow for the automatic authentication by transfer of the code. Switch to the questionnaire of the primary project. Locate the jump page and, select the Edit page properties icon.

  • Extend the URL so that the value of the variable #code# of the primary project is transferred to the “code” field of the secondary survey: http://www.efs-survey.de/xyz/?code=#code#

  • Confirm by clicking on Save.

  • The return page in the secondary project is configured as usual.

You can only import links for panelists who have not started the survey yet, i.e. disposition code is < 20.

Authentication When Jumping From a Panel Survey to a Personalized Project

Since EFS 6.0, panel surveys can be used as target projects. I.e., you can route partici- pants from one panel survey to another, as long as both surveys are placed on the same installation. This option is used quite frequently, in particular in situations when the content of a survey has to be spread over several projects.

There are two possible settings:

  • Only selected panelists can participate

  • All panelists can participate

Only selected panelists can participate

If you want only selected panelists to participate in the two connected projects, please proceed as follows:

  • 􏰀  Make sure the participating panelists are members of the samples of both projects.

  • 􏰀  The link for the jump from primary to secondary project should look as follows: http://www.your-domain.com/xyz/ ?syid=573&sid=574&pcode=#panelist_code#&pses=#panel_ses#

This contains:

  • syid: Project ID

  • sid: Sample ID of the appropriate sample in the secondary project. You can find this ID by scrolling over the title in the overview of samples with the mouse pointer while observing the link in the status bar of your browser. It looks like this:

    http://www.your-domain.com/ front.php?module=panel_sampling&act=view_sample&pid=610&sid=611

  • pcode: Panelist code.

  • pses: Session ID of the panelists. If you can trust that the panelists have cookies activated, you can drop the session ID. But if you want to allow the jump with cookies switched off, the session ID must be transferred.

All panelists can participate

If you want all panelists to participate in both projects or at least in the secondary project, please proceed as follows:

  • Activate the option “All panelists can participate in the survey (independent from being in a sample for the survey)” in the Project properties menu of both projects resp. only in the secondary project.

  • The link for the jump from primary to secondary project should look as follows: http://www.your-domain.com/xyz/

    ?syid=573&sid=574&pcode=#panelist_code#&pses=#panel_ses#

This contains:

  • syid: Project ID

  • 􏰀sid: Sample ID of the “internal” sample of the secondary project.

  • pcode: Panelist code.

  • pses: Session ID of the panelists. If you can trust that the panelists have cookies activated, you can drop the session ID. But if you want to allow the jump with cookies switched off, the session ID must be transferred.

Transferring Data from the Primary to the secondary Project and storing these Data in URL Parameter

The return jump from the secondary to the primary project is a very different situation than the forward jump: The participant is not taken to the start page of a new project but resumes an already started project. Therefore, unlike in the case of the forward jump, the data transfer cannot be done using URL parameters: These can only be processed on the first page of a project. Instead, the data are transferred to user-defined variables (c variables).

The following steps are required:

  • In the Project properties menu of the primary project you create the required user- defined variables. When doing so make sure that the file type matches the values to be transferred.

  • After that, you enter the destination URL for the return jump in the secondary project. It looks as follows: http://www.efs-survey.de/xyz/ospe.php3

  • To this URL you have to add

    • the appropriate user-defined variable of the primary project. In our example, this is “c_0001".

    • the value of the variable. This can be a constant value or also a participant- specific value dynamically inserted via wildcard. In our example, this is the participant variable “u_group”.

  • The destination URL would then be, for example: http://www.efs-survey.de/xyz/ospe.php3?c_0001=#u_group#

Besides project folder and “return_tic”, the example URL contains a GET parameter “c_0001” with the value “11”.

Linking More Than Two Projects

It is possible to link more than two projects via external survey start. The following combinations are possible, for example:

  • 1. project → 2. project → 3. project → 2. project → 1. project

  • 1. project → 2. project → 1. project → 3. project → 1. project.

Please note that the participants always have to be redirected back along the same path they came. This is necessary as the “tic” parameters can only be used to transfer those data regarding session, jump page etc. of the previous project that are available in the current project.

  • The path 1. project->2. project->3. project->2. project->1. project is possible.

  • The path 1. project->2. project->3. project->1. project->2. project is not possible.

When redirecting from the second to a third project the options “Add return ticket” and “Add ospe.php3” have to be disabled. They are used for returning primary-project relevant information back to the primary project. They cannot be used to relay secondary-project relevant information to another project.

When analysing the data, please mind that the variable “external_lfdn” contains the “lfdn” of the primary project in all following projects.

Special Considerations when using External Software

You can rename the GET parameters “tic” and “return_tic” if this is required for redirecting to a survey that was created using external software.

External Software requires

The relevant function can be found both in the Edit page properties dialog (Figure 3.7) and in the Projects → {Selected project} → Project properties menu, “General options” section, in the following fields:

  • Name of ticket variable (external start of survey)

  • Name of ticket variable (when returning from an external survey)

The following names cannot be used, because they are reserved for other purposes: sid, pid, syid, oid.

External Software

It may happen sometimes that you wish to transfer a number of values while the external software is able to evaluate only one GET parameter. In such situations, please check whether there is another option for transferring the desired values.

Sawtooth, for example, can accept only one parameter, however, this may contain several values that are separated by comma. In this case it is possible to transfer both the “tic” parameter and other values as a comma-separated string.

Suppose you want to transfer the following values:

1, x, #tic

In the EFS primary survey you combine those in a value of the variable “a” as follows:

a=1,x,#tic#

Via the wildcard, “tic” is inserted at a precisely defined position in the URL: Sawtooth is now able to accept the resulting string and break it down by means of an analysis algorithm. This way, the value for “tic” can be extracted, stored, and subsequently transferred back.

© 2024 Tivian XI GmbH