Triggers

The mail trigger is available for all survey types. When a defined event occurs, it will trigger the dispatch of an e-mail whose content was predefined, dynamically generated or entered by the respondent to an address that was either defined in advance or collected during the survey.

Basic Settings

When configuring basic settings for a mail trigger please note the following features:

• Execution position: As the execution position you should choose “After submitting page, after filter”.

• Condition: Definition of an appropriate condition is of special significance for mail triggers. For example, you can ensure that e-mails are only sent when the participant has completely filled a comments field.

Details

In addition the following specific settings must be made for this trigger type:

• Mail template: Optionally, the contents to be dispatched by the trigger can be imported from a mail template and then modified and stored in the trigger editor.

• Mail sender

  • Manually defined mail sender: The e-mail address of the sender must be entered, it cannot be adopted from a mail template. Entering a real name (e.g. John Doe <john.doe@example.com>) is not possible in triggers.

  • Dynamic mail sender: here you can select the variables for single row text fields (141) and “Other” fields (answer option + text). In personalized projects, the additional “u_email” wildcard is available, which is filled with the stored survey participant’s e-mail address.

  • If you use the ACL right “mail_reply“ to hide “Reply-To” and “Return-Path” for a user team (usually for privacy protection), please take care to enter clearlydefined values in the mail template which the team members are supposed to use for the trigger. The default options “Reply-To = From” and “Return-Path = From” cannot be used, because they are filled with the mail sender entered manually by the responsible user.

• Mail recipient:

  • Manually defined recipient: In this field, you can define one or more recipients who do not necessarily have to be included in the EFS Survey system. You may either enter a single e-mail address or several e-mail addresses separated by commas. The e-mail will be sent to all the recipients you have defined.

  • Dynamic mail recipient: You can select the variables for single row text fields (141) and “Other” fields (answer option + text). In personalized projects, the additional u_email wildcard is available, which is filled with the stored survey participant’s e-mail address.

• Mailing date:

  • Immediately upon activation of the trigger. This option is preset as the default.

  • Scheduled

  • Dynamically upon activation of the trigger: This option triggers the dispatch after a period defined by the user, which can range from 30 minutes to 6 months.

Tips for Creating Mail Templates for Mail Triggers

When creating mail templates specially for mail triggers please note the following:

• The “Subject” field should have a meaningful content as otherwise the e-mail may be filtered out as spam under certain circumstances.

• What you enter in the mail form’s ”Content” field is dependent on the purpose of the trigger:

  • If you wish to send predefined mail content then enter the desired content in the form. At this point you can use the wildcards available in the respective project type.

  • If, on the other hand, you wish to send content entered by the participant, enter the variable of the corresponding input field in the questionnaire as a wildcard enclosed by two hash signs (#).

  • If you wish to output the participant’s answers to closed-ended questions you can work with conditional replacement.

Testing Mail Triggers

When testing a mail trigger, please note: u_email or any project variables used are not replaced correctly when testing via the questionnaire preview, as data generated in the preview cannot be allocated to a participant account and dataset. Instead, the e-mails are always sent to that admin area user who has triggered the dispatch. To test the mail trigger properly, create a test participant with an e-mail address to which you have access, and test in productive mode. In this way you can check whether the wildcards used are correctly replaced by the e-mail address and/or questionnaire entries.

Generally, the questionnaire dramaturgy is configured by setting appropriate filters. As an alternative, the page trigger is available in all project types. You can use this trigger to specify any page as the next page to be shown to the respondent, depending on the selected variable characteristic. You can jump to previous and next pages.

The page trigger is available for all project types.

Example: Realizing a questionnaire with a table of contents

Most questionnaires have a sequential structure: The respondents go through the questionnaire from the first page to the last. Filters and hiding conditions are used to skip blocks of pages and questions. As an alternative, a division into chapters with a table of contents is especially suited for very long surveys that do not have to be answered completely. The respondents will select a topic block they wish to edit from the table of contents, jump to that topic block and will be routed back to the table of contents after editing it.

Using page triggers, a non-sequential project can be realized like this:

• For the table of contents, you can, for example, create a question with a single response list (type 111).

• Create a page trigger that will query the variable created in Step 1. This page trigger is used to jump to the start pages of the individual chapters.

• At the end of each chapter, you must create a question of type 911 (user-defined) with a variable. In a hidden form field (input type=hidden), you must set the variable to a value of 1.

• For the final page of the chapter, you must also define a page trigger that will query whether the hidden variable has a value of 1 and then route to the table of contents. This condition will be ensured in any case when sending the final page: The page trigger is activated, and the respondent can make another selection in the table of contents.

The logout trigger can be used in every project type. “Logout” means that the participant will be routed to the system final page, without any specific message. You can use the logout trigger if, for example, you have a complex, nested questionnaire and want to route respondents to the final page in a very straightforward way.

The participant’s interview will be classified as a completed interview (disposition code 31). If the survey contains additional final pages, the panelist will always be sent to the system final page.

The sample trigger allows to invite participants, depending on a condition which you have defined, to a second personalized survey or panel survey. The participants are added dynamically to the participant administration or sample of the follow-up project.

Example

You are surveying customers of an online shop to find out how satisfied they are and when they expect to receive the goods they bought: Depending on the expected date of delivery, the interview participants will receive a mail inviting them to a second survey after a certain delay. The respondents are entered into the sample as active participants.

Features

• The sample trigger can be set up and executed in all quantitative project types (AN, PE, PA, MD, ES, MSF).

• For target project, you can use all project types with participant administration, i.e. personalized projects, employee surveys, multi-source feedbacks, panel surveys and master data surveys.

• You can only invite participants with existing panelist accounts to panel surveys or master data surveys. The e-mail address is used to match participant and panelist account.

Configuring Sample Trigger

The basic settings are the same as for other trigger types. When configuring the details, please mind:

• Select the participant administration or sample of the target project to which the participants are to be added and invited.

• In the “Mail dynamically to” field, select the variable which contains the e-mail address of the participants:

  • This e-mail address will be used not only for delivering the invitations, but to create the participant accounts in the target project, or to insert the panelists into the sample of the target project in panel and master data surveys.

  • In projects with participant administration, this is usually u_email.

  • In anonymous projects, similar to the mail trigger, you can select the variables for single row text fields (141) and “Other” fields (answer option + text). It is recommendable to apply an “e-mail” input format check to the selected variable.

• Just as with the mail trigger, you have to configure the e-mail to be sent. You can define the mail in the trigger editor. Alternatively, you can import the content of a mail template, too.

  • The mail sender must be specified.

  • The mail text must contain an access code or link for the secondary survey. For this purpose, use the wildcard #url#, #code# and #code_complete#: if participant administration or sample of the secondary project are selected, the wildcards will be filled with URL and/or code of the target project.

• Define the dispatch date:

  • Per default, the mails will be dispatched immediately upon activation of the trigger.

  • Optionally, another dispatch date can be defined. Create a user-defined variable (c variable) or project variable of type “text”. This variable should contain the number of days from the execution of the trigger to the dispatch of the mail, for the proper dispatch date EFS will then add another 12 hours to the value of this variable.Select this variable in the reinvitation trigger.

The reinvitation trigger reinvites participants to take part in a survey, depending on a condition which you have defined. The data records of the participants are reset without deletion of data to disposition code 11 or 12, i.e. if the participants restart at a later date, they will be routed to the first page of the survey again.

Example

At the start of a long, complex survey, you want to offer participants the option to interrupt and participate at a later date. On one of the first pages, you ask if the participant does have sufficient time to respond at the moment. If not, you offer to send a reminder mail. If a participant does not have sufficient time and wishes a reminder mail, he’s routed to a final page via a filter. On this final page, the reinvitation trigger is executed. It resets the data record and sends the reminder mail at the desired later date.

Features

• The reinvitation trigger is only available on final pages.

• It can be used in personalized surveys, employee surveys, multi-source feedbacks, panel surveys and master data surveys. In anonymous surveys, this trigger type is not available.

• The participants’ disposition code will be reset to 11 resp. 12.

• The data records are reset without deleting, i.e. already-given answers of the participant are not deleted.

• Participants who respond to the reminder mail will start again on the first page: Due to the reset of the disposition code, the resumption is considered a restart.

Configuring a Re-Invitation trigger

The basic settings are the same as for other trigger types. When setting the special options, please mind:

• Just as with the mail trigger, you have to configure the e-mail to be sent. Usually, the content of a mail template is imported. Alternatively, you can define the mail in the trigger editor, too.

  • The mail sender must be defined beforehand.

  • Depending of the situation, it might make sense to repeat the access code or link in the mail text. For this purpose, use the wildcards #url#, #code# and #code_complete#.

• Define the dispatch date: 

  • Per default, the mails will be dispatched immediately upon activation of the trigger.

  • Optionally, another dispatch date can be defined. Create a user-defined variable (c variable) or project variable of type “text”. This variable should contain the number of days from the execution of the trigger to the dispatch of the mail, for the proper dispatch date EFS will then add another 12 hours to the value of this variable.Select this variable in the reinvitation trigger.

You can use variable split triggers to

• save transferred parameters in user-defined variables. (This does not refer to URL parameters: You can save any parameters transferred via GET in user-defined variables.)

• read cookies from the respondent and save them in user-defined variables

• break down the variables into their individual components before saving the parameters or cookies, if necessary.

The user-defined variables will be included in any export, but you can also use them for screening within the survey, output them in the questionnaire, etc. The variable split trigger is available for all survey types.

Application Example

You are planning an advertising effectiveness study intended to test a new form of advertising. Your co-operation partner sets a cookie with every website visitor who has seen the new form of advertising. Now, you want to find out whether there are connections between answer patterns in your study and the form of advertising (e.g. “Do people who have seen the form of advertising remember its contents?”).

At the beginning of the survey, all cookies will automatically be read and saved, collectively, in a system variable. The variable split trigger will pinpoint one cookie value, read it from the collection and save it in a user-defined variable.

To read the respondents’ cookies and save a cookie value in a user-defined variable, please proceed as follows:

• Create a new variable in the Project properties menu on the User-defined variables tab. As you want to save the cookie name, choose the “Text” type. Assign a meaningful label. You can output the variable’s content via #Label# or #c_000n#, where n is the number of the user-defined variable.

• Then, switch to the page of the survey on which you wish to create the trigger.

• Click on the Trigger tab and create a trigger of the “Variable split trigger” type.

• First, specify the condition for which the trigger is to be activated. You will normally want to execute the trigger on the first page of your survey. If this page does not contain a variable, create a dummy variable with question type 911.

• In the trigger editor, various source variables are visible:

• A cookie, when it is set, has a name and a value, e.g. opst_demopanel_108 and “7a8cc5c05df7820217d9bf3f6c5b0781”. The “Array field” allows you to define which of the collected cookies is to be written into the user-defined variable.

• The cookie’s value can be structured to contain various values, separated by a separator such as | or ;. For example, the cookie value could encrypt the date, the browser version and the site by which the cookie was set. If your cookie has such a structure, you can save the individual values separately using different destination variables. To do so, you must save the settings, create a new destination variable and enter the separator character (e.g. a comma).

• The value of the cookie named in the “Array field” will now be stored in the userdefined variable.

Reading Get Variables

Analogously, you can read Get variables attached to the survey URL. To do so, use the Get variables at the beginning of the survey as the source variable, enter the name of the Get variable in Array field and choose the user-defined variable you want to write the value to as the destination variable.

The recoding trigger is used to recode variables during a survey. The value(s) for one or more variables can be set either conditionally (i.e. depending on survey results) or unconditionally (i.e. always). For example, the new trigger allows you to

• transfer values from one variable to another

• prefill text fields

• perform calculations and output results on the basis of the entries

• recode multiple variables at the same time

• access and change participant and panelist data

All recodings made as the result of actual participation will be logged (see the section “Viewing the recodings performed”).

Please note:

• The recoding trigger is available for all survey types.

• You can recode project variables (with the exception of variables located within a loop branch), user-defined variables and URL parameters, participant data and panelist data (with the exception of u_account, u_ppasswd, u_passwd, u_email, u_initial_passwd) and master data.

• System variables cannot be recoded.

• If the value to be set is a text, put it between quotation marks.

• Both recodings and trigger actions require a lot of server resources, i.e. the usage of recoding triggers affects the performance of the questionnaire. Therefore, it is recommended to use not more than 100 recodings per trigger and per page.

Recoding syntax

When defining recoding conditions, the following rules apply:

• The operators + - / * and ( and ) can be used.

• Wildcards (#v_xxx#) can be used to insert project variables. Please mind:

  • Special project variables, as e.g. loop variables, cannot be used in the condition.

  • For project variables relating to an open text field, #v_000n# outputs the content. Make sure to enclose the wildcard by quotation marks in this case, e.g. '#v_1#'

  • For closed-ended questions the wildcard #v_000n# in the trigger outputs the code.

• Texts (strings) must be enclosed by quotation marks (e. g. 'foo').

• It is not permitted to use the special characters ? and $ in the recoding condition. They are reserved for internal usage in database queries.

• You can use the MySQL functions NOW() and IF() on all EFS installations.

  • NOW() returns the current date and time. Example: NOW() -> 2011-02-11 12:08:29

  • IF(expr1,result1,result2) is processed as follows: If expr1 is TRUE, IF() returns result1, otherwise it returns result2. Example: IF(#v_1#<2,'Yes','No') →  If #v_1# < 2, IF() returns “Yes”, otherwise it returns “No”.

• On installations with deactivated High-Security Mode, other, non-security-relevant SQL functions can be used. Access to other databases, users, or files is not possible. Unfortunately, our support will not be able to assist you with these advanced functions.

Example: Preallocation using participant data

In an employee survey, the question relating to pertinent departments is to be preallocated according to the information available in participant administration.

• Create the question where the pertinent department is to be entered.

• Switch to the page view and open the Trigger menu.

• Choose the recoding trigger, and confirm by clicking on Submit.

• The trigger will be created.

• Enter “Trigger name” and “Trigger description”.

• Choose the execution position “Directly”.

• Decide whether the “Also execute trigger in preview mode” function should be enabled. In this example, it is advisable to enable this function because it allows you to perform tests directly in the preview.

• Decide whether the trigger can be executed repeatedly in one survey session. In this example, it is not necessary.

• Lastly the settings under “Detail configuration” have to be made, i.e. the recodings need to be defined.

• Select the variable to be recoded, and enter the value for which the recoding condition applies. In the example, “v_1“ is the variable where the answer to the question relating to pertinent departments and characteristic “1” is saved.

• Confirm by clicking on Save.

• Click on the Filter icon, which will now appear, in order to define the condition.

• Choose the variable whose content is to be loaded as well as the condition and the code. In this example, variable v_1 is to be prefilled with code 1 if the participant variable labeled “u_department” equals 1.

• Click on Save.

• Repeat this operation for all characteristics of the variable v_1, which are to be preallocated.

Viewing the recodings performed

Navigate to the Projects → {Selected project} → Documentation → Recoding log menu to view all recodings that have been performed.

• After six months, the log data will be deleted.

For scientific projects in particular, it is often necessary to form participant groups to which different questionnaire versions are presented at random. The random trigger allows you to make random assignments: All you have to do is enter a range for the random number, e.g. “1-5“ (depending on the number of different questionnaires). At the beginning of the survey, “dice” are used to generate a number, which is then written into a user-defined variable (“c” variable). These variables can subsequently be used to create the corresponding filters for the various questionnaire versions.

The additional feature “Approximate uniform distribution within given range” has also been incorporated, in order to achieve a good uniform distribution of the randomly generated numbers and, consequently, of the selected respondent groups, (see last section).

The random trigger is available for all survey types.

Configuring the Random Trigger

• Switch to the page view and open the Trigger menu.

• Choose random trigger, and confirm by clicking on Submit. The trigger will be created.

• On the Detail Configuration, select the the user defined variable already created, into which the random number will be subsequently written.

• Set the user-defined variable: You are free to choose the label, however the variable type should be “Integer or floating point numbers”.

• Make the usual settings: “Trigger name”, “Trigger description”, “Execution position” and “Condition”.

• Decide whether the “Also execute trigger in preview mode” function should be enabled. When testing, it may in certain circumstances be helpful to have conditions that remain constant.

• Decide whether the trigger can be executed repeatedly in one survey session.

• Lastly the settings under “Detail configuration” have to be made: Only user-defined variables can be used to save the random number.

• The minimum and maximum values of the random number are required.

• You have the option of specifying that a uniform distribution should be approximated.

• Finally, click on Save.

Uniform Distribution

The distribution of the randomly generated values will only approximate a uniform distribution only if the number of cases is sufficiently large. The special feature labeled “Approximate uniform distribution within given range” is used in order to allow you to simulate a uniform distribution even with small and medium numbers of participants. If this function is enabled, the numbers generated will no longer be actual random numbers, rather the numbers will be generated in such a way that, even for a small number of cases, their distribution will tend strongly toward a uniform distribution.

The list trigger allows you to transfer the contents of a list into user-defined variables. The contents of the user-defined variables can in turn be displayed in the questionnaire via wildcards. The main purpose of this new function consists in presenting - in certain work situations - an alternative to the use of loops, which are considerably more complex to evaluate. For example, at the beginning of a survey, respondents are often presented with a range of brands and products and asked to select the ones they know. The questions in the subsequent survey will only involve those brands and products marked as “known”. In the past, this kind of questionnaire was realized with the help of loops. Alternatively, the list trigger now allows you to encode the “known” brands or products in user-defined variables and to import these during the subsequent survey via wildcards. Thus, the export data record remains reasonably sized.

The functional scope at a glance:

• The list elements remaining after processing the list inclusion conditions, list options, and sort order, can be written in user-defined variables.

• You can choose whether to record the element number or the element label. Please note that in multilingual projects, labels can only be recorded and displayed in the default language.

• The various list processing options can be separately configured for the trigger. The list trigger is independent of the settings that are made when using the list on the pages of the questionnaire.

The list trigger is available for all survey types.

Configuring the List Trigger

• First, create the list.

• Next, you have to create the required variables in the Project properties menu on the User-defined variables tab.

• In order to create the list trigger, open the Trigger menu on the appropriate page, select the type “List trigger” and confirm by clicking on Submit.

• Make the usual basic trigger settings (name, execution position, etc.).

• Select the desired list and click on Save.

• Further setting options will now be displayed in the lower part of the dialog.

• In the “Settings” section, successively specify for each remaining list element (i. e. for each list element that remains after processing all inclusion conditions etc.) which list property is to be transferred into which destination variable. The available list properties are element number and element label.

• After clicking on Save, the settings will be adopted and the line “New” for selecting the next list element will be displayed again.

• In the lower sections, you can set list options and sort order of the list elements.

• Then, confirm by clicking on Save.

List Trigger data in the Export

In the example shown above, three elements are selected at random from the list elements which the respondents selected in the questionnaire. The list trigger writes these, or rather their labels, in three user-defined variables.

In panel and master data surveys, you can award bonus points for reaching a particular page of the questionnaire, for giving a correct answer or for other events.

Features

EFS offers a lot freedom when allocating bonus points:

• A panelist may receive more allocations in one survey.

• A potential allocation on the final page of the survey does not affect any bonus point allocations via a bonus trigger. In particular, you may use triggers and final page to allocate different amounts of points.

• You may use multiple bonus triggers within one survey.

• You can use the bonus trigger only for allocating points. The subtraction of points makes no sense within the context of a survey and is therefore not possible.

Configuring Bonus Triggers

The basic settings are the same as for other trigger types. Additionally, the following settings specific to this type of trigger have to be performed:

• Bonus points to be allocated: In this field, you define how many points the trigger is supposed to allocate to the panelists.

• Trigger behavior: If the respective panelist has already been allocated points by another bonus trigger, it is up to you to decide whether the current trigger shall be executed.

Configuring bonus trigger entry in the bonus points history

Every allocation of bonus points is logged in the respective panelist’s bonus points history. At the time it is not possible to define a different text for every bonus trigger and every final page. Instead, the message “Entry into panelist’s bonus points history” defined in the Project properties→ Survey messages menu is used for all allocations within the project. Therefore, make sure to enter a meaningful general text.

After they have taken part in a survey, it may often be convenient to collect the panelists in a specific panel group, e.g. to facilitate incentivation or other follow-up processes. The panel group trigger allows you to do this without much effort. It is also possible to remove panelists from a group.

Configuring the Panel Group Trigger

The panel group trigger is available in panel surveys and in master data surveys. The basic settings are the same as for other trigger types. Additionally, the following settings specific to this type of trigger have to be performed:

• Group category

• Target group.

• Trigger mode: You can choose whether the respective panelist is to be added to or removed from the group.

The Pre-Qualification trigger can be used to import participants as panelists. They have to take part in an Anonymous survey (AN), a Personalized survey (PE), Employee survey (ES). The panelists will be created by the means of survey variables. The e-mail address is mandatory. To configure the trigger two tabs are avaiblabe. You will use the Settings and the Detail configuration tabs.

On the Settings tab, a name and a short trigger description can be added. Then you have to set up the conditions and check whether the trigger should also be executed in the questionnaire preview and whether it should be executed multiple times in one survey session.