Libraries

The survey library allows access to readymade sample questionnaires. A set of ready-made English surveys is available from the library. The sample surveys are listed in the menu Libraries → Survey library.

Open

Media library

Each project has its own media library, located in the Questionnaire editor under the Media library menu. It enables you to upload multimedia files such as images, sounds or movies from your local hard disk or from your network into the project directory on the EFS server and to insert them into the questionnaire.

Open

The library, the project-specific library (Current project) and the optional installation-wide library  are arranged on successive tabs. The library provides ready-made visuals, made available for free. The frequently-requested option to download only selected files instead of the
whole library has been realized.

Managing Multimedia Files

To upload a file, click the Upload file button. Then proceed as follows:

• Locate the file on your hard disk using the Browse function.

• If you are uploading a zip file, you can have the system unpack it and automatically create subdirectories in one operation. To do so, tick the “Unpack ZIP file” checkbox.

• You have the option of defining a wildcard. You can use the characters a-z, A-Z and 0-9. The wildcards must be enclosed in two hash signs (#).

• If you want to overwrite files in your own media library with an updated version, simply activate the new “Overwrite file(s)” checkbox during upload.

• Confirm by clicking on Upload

Editing individual files

If you scroll over a row or activate a checkbox, the following action icons are displayed:

• Info: In a pop-up window, you can find the img tag that can be used to incorporate a file into the questionnaire, with both absolute and relative path. Furthermore. The absolute path is displayed separately for copy&paste.

• Edit file: Opens an entry form in which you can change the file name and description.

• Move file: Opens a drop-down list from which you can choose a different category for the file.

• Delete

Editing several files at the same time

Using the icons above the file list, you can download, move or delete several or all files. Just activate the desired files and click on the appropriate icon.

Using Categories to Organize Files

You can create categories in the media library, i.e. in the project-related directory / images, which help to improve the overview.

Creating new categories

• Click on the category below which you wish to create the new category.

• Click on the Create category icon.

• Enter the name.

• Confirm by clicking on OK.

Renaming categories

• Click on the category you wish to rename.

• Click on the Rename category icon.

• Enter the new name.

• Confirm by clicking on OK.

Deleting categories

• Click on the category you wish to delete.

• Click on the Delete category icon.

• Affirm the confirmation window.

Downloading Files from Media library

Individual or several files can be downloaded. For this purpose, a Download icon is available on every level of the category structure on the Current project and Common library tabs. If you select the desired files and click this icon, a zip file will be generated that contains the content of the current folder including its subfolders. You can save this file locally to a PC, open it and then view or edit the images.

• When working in the installation-wide media library, in particular, take care to select only reasonable amounts of data for download, i.e. less than 10 MB and not more than 30 files. Otherwise, the download process can affect the performance of the EFS installation.

Protecting images

Customers running product or cover tests frequently ask for a better protection against illegal copying and screenshotting of their content. A dedicated image protection feature makes storing or screenshotting of images considerably more difficult.

• In the questionnaire, participants will see only the silhouette and outline of the protected image, plus an instruction for display.

• If the participants press the key combination specified in the instruction, the image will be displayed. (They have to keep the blank key pressed and click on the image with the left key of the mouse pointer.)

Survey library

The survey library allows access to readymade sample questionnaires. A set of ready-made English surveys is available from the library. The sample surveys are listed in the menu Libraries → Survey library. Its interface design is analog to the media library. Inside the library, the sample questionnaires are read-only.

• To use a survey from the library as base for an own project, click on the + New project split button above the project list and select “Survey library”. In the project template field, select the desired library survey via the Magnifying glass icon. Fill all other fields as usual. Once the survey has been created, you can modify the questionnaire as you like.

Mail templates

Usually, e-mails are written on the basis of existing mail templates, which are centrally created, edited and managed in the Libraries → Mail templates menu. In the mail form’s “Mail template” drop-down list, you can select one of these templates and upload it by clicking on Apply mail template.

To create a new template, click on the Manage mail templates link. The Libraries → Mail templates menu, which allows you to create the desired new template, will be opened in a pop-up window.

Creating new mail template

To create a new template, click on the button + New draft and select the desired option. You have different template types for the Panel website, survey project and portals. Depending on whether you want to create a template for the Panel website, a survey project or portals, the available template types also change.

In addition to selecting an e-mail template type, you also specify a language version, enter a short description in the free text field, and choose a delivery method. The following types are available:

• E-Mail

• SMS

• E-Mail und SMS

Configuring advanced mail settings

The “Advanced mail settings” area, which provides various special functions, is usually hidden. You can easily show or hide this dialog as required.

Character set

The character set for e-mails is set separately and can depending on your requirements vary from the settings for the character set for the overall project. This can be sensible, if:

• in a project carried out using UTF-8, you are not sure whether the mail program of the majority of respondents is compatible with this character set. Most modern mail programs can display UTF-8 correctly, in particular with internet-based mail programs complications can arise.

• you will be carrying out a project, that will use a character set other than UTF-8 or diverse character sets, where you would like to use UTF-8 or another divergent character set for the display of special characters in e-mails.

For the mail form, the character set ISO-8859-1 is preset by default.

Conversion problems with Windows-specific characters

When you copy and paste from a Microsoft program, such as MS Word or Excel to a e-mail form, that is coded in a character set other than UTF-8, the conversion problems may occur: If the text contains Windows-specific characters that are not in the character set of the mail form, then these must be converted.

EFS Survey is able to convert many Windows-specific characters correctly, however the conversion will still require checking. Characters, for which there is no match, will be deleted completely from the mailtext, because they could not be sensibly converted (for example Chinese characters could not be displayed in a ISO-8859-1 coded questionnaire). Therefore a warning message will be displayed in the mail preview, that ask you to make a check, as soon as you open an e-mail with characters that have been converted or cannot be displayed.

Reply-To: = From

The “Reply-To” information in an e-mail indicates where the recipient is to send any replies. Making different entries may be advisable, for example, in surveys you conduct for a third party. Under “Sender”, you can then enter your customer’s address: This will be displayed for the recipient and may increase their willingness to respond. However, the “Reply-To” address makes sure that the reply mail will be sent to you as the supervisor of the survey. Furthermore, server messages indicating that an e-mail could not be delivered will also be sent to the “Reply-To” address. You can set the “Reply-To” address using the drop-down list contained in the row of the same name.

• Read rights for “mail_reply” are required for accessing and using this field, plus the “Return-Path” and “Read confirmation” options explained in the following sections.

• The default setting is “Reply-To = From”, i.e. the sender’s address will be used.

• If you complete a mail form without read rights for “mail_reply”, i.e. without seeing the “Reply-To” and “Return-Path” options, the default setting “Reply-To = From” will be used. “Read confirmation” will be deactivated as per default. If you do not have read rights and use a mail template in which “Reply-To”, “Return-Path” or “Read confirmation” have been defined, the values from the mail template will be used.

• Additionally, the same addresses as in the “Sender” field are available for selection. If you wish to change the sender addresses, you can do so in the Mail templates → Mail senders menu.

Return-Path

Error messages and other transfer errors (e.g. “bounce messages”) will be sent to the address configured in the field “Return-Path”. These messages will be forwarded to the mail sender, if no address has been configured. Access to the “Return-Path” option is controlled by the “mail_reply” right described above. The default setting is “Reply-To = From”, i.e. the sender’s address will be used. Assuming that you have the required read rights, the addresses in the drop-down list are the same as those found in the drop-down list in the field “Mail sender”.

X-Priority (importance)

This information allows you to assign the e-mail a status. Commonly used mail clients can use this information to highlight or arrange your e-mail according to the recipient’s settings. Five statuses are available, “1” being used for the lowest significance and “5” for highest priority.

Sensitivity

For recipients using Outlook, you can set the message’s sensitivity.

Read confirmation

Commonly used mail clients support sending automatic read confirmations. Once the recipient opens the e-mail, a message is automatically sent to the recipient you selected (sender or Reply-To). Since this happens automatically, such a read confirmation of course does not mean that the recipient has actually read or even understood your e-mail. It merely indicates that the message has been displayed in the recipient’s mail program. Also, it is not mandatory for a mail client to send a read confirmation. The recipient may also have deactivated this option or deliberately decided not to send a read confirmation for this particular mail. They may nevertheless have read the mail. Also, in particular in the case of recipients in larger companies, the header line may have been removed by a mail filter.

Access to the “Read confirmation” option is controlled by the mail_reply right described above in the “Reply-To” section.

Send mail copy to sender (without substitutions)

If this checkbox is ticked, a copy of the e-mail will be sent to the sender. This copy will be sent as the first e-mail of the operation. Any existing wildcards will not be substituted because the sender (administrator) is usually not a survey participant.

Forwarding copies of all mails to additional mail recipients

You can, for example, within the context of a test forward copies of all mails, which are to be sent out in a dispatch process, to an additional mail recipient. In this process the wildcards will be replaced and the additional mail recipient will see the mails in exactly the same way as the real recipients.

To do this enter the e-mail address of the additional recipient in the field “Additional mail recipient (CC)” or, if the address should not be visible to other recipients, in the field “Additional hidden mail recipient (BCC)”.

• Read rights for mail_cc are required for accessing and using the CC and BCC options.

• Per default, both fields are empty.

• If you complete a mail form without read rights for “mail_cc”, i.e. without seeing the CC and BCC options, the fields will be empty i.e. the mails will not be forwarded to additional recipientsd. If you do not have read rights and use a mail template in which CC or BCC have been defined, the values from the mail template will be used.

Base URL

The feature “Base URL” allows to define how wildcards with URL elements (e.g. #url#, #code_complete#) will be filled.

• You can explicitly define the protocol (http, https) and the domain which is to be used in the e-mail.

• The option “Use protocol / domain from current URL” allows to make the wildcards dependent on the protocol and domain with which the user who triggers the mail action is logged into the admin area.

• Wildcards which enforce a specific protocol, as e.g. #code_complete_http#, are not affected by these settings.

Predefined mail sender

The drop-down list in the “Mail sender” row allows you to select the sender address. The default setting is the e-mail address of the user logged in. Additionally, addresses which were created in the Mail templates → Mail senders menu and for which you have access rights will be available for selection. The e-mail address you select is also valid as return and bounce address if the following definitions are true:

• Reply-To: Reply-To = From

• Return-Path: Return Path = From

Dynamic mail sender

E-mail address and name of the mail sender can now be defined dynamically by filling the fields „Dynamic mail sender“ and „Name of the sender“ as well as selecting a predefined mail sender from the drop-down list „Mail sender“ as fallback. When filling the fields, you can use wildcards and if-conditions like in mail-text.

Dynamic mail senders always overwrite predefined mail senders from the drop-down list. Should the Reply-To or the Return Path address be equivalent to the address of the predefined mail sender, the dynamic mail sender will be entered in these fields also.

• This function can be used in mail templates as well. However, it is not available in mail triggers, since they already contain a similar function for setting a dynamic mail sender that can be defined from survey responses.

Sending TO

Only for EFS People installations: The People → Contacts → Send e-mail menu contains a mail sending function that allows you to contact individual recipients in a targeted manner. Whereas in all other action areas the group of recipients is determined in advance (e.g. a group of participants identified through the disposition code or the sample drawn from a panel), the mail sending function in this menu allows you to contact individual recipients whose data are not even present in the EFS Panel system. Enter the address in the “To” field.

Mail format

You can send either text or real HTML mails from EFS Survey. To do so, you must specify the format before writing the mail. The following options are available:

• Text only (default)

• HTML only

• Text and HTML

After you have confirmed the selection by clicking on Apply mail format, the appropriate input field(s) will be shown.

HTML format

By default, EFS sends e-mails in plain text format. Alternatively you can also send HTML mails. The line breaks are not automatically inserted with the “HTML format” checkbox ticked. EFS generates the HTML mails as content type “multipart/alternative”. This means: The actual text is contained in the e-mail in duplicate. This allows mail clients that cannot display HTML to display the alternate text. Web mail services, in particular, often warn users against displaying e-mails in HTML format and suggest displaying the alternate text (if available).

• Old e-mail clients as e.g. Outlook 2003 cannot process the content type “multipart/alternative” properly. E.g. if a recipient has restricted Outlook 2003 to “Text only”, the client will not output the alternative text, but the HTML part converted into text.

Disadvantages of e-mails in HTML format

In particular, the doubled amount of data in HTML mails is considered unnecessary by some Internet users and, because of the longer loading time, often also as impolite. Since both scripts and so-called web bugs may be hidden in HTML code, some mail systems classify these messages as potentially dangerous. Insofar, it cannot be ruled out that the post master of a recipient system may remove the HTML code or tag it with a security alert. If you still want to send HTML mails and can easily narrow the group of the recipients of your mailing (e.g. in the case of employee surveys), you should contact the recipients’ post master in advance to find out how they deal with these mails.

Subject

In the “Subject” field you enter the title of your e-mail. Wildcards can be used.

• You should avoid special characters, such as the German umlauts, in this field. The line is part of the so-called mail headers. Encoding special characters, as in the email’s content, is not possible here.

• Please note that mail subjects should in general not be longer then 60 characters. Many servers make a cut after 248 characters for security reasons.

Masking special characters in the subject

If you still need special characters, you will have to mask them appropriately. For example, “Ä” (A umlaut) will then become “=?ISO-8859-1?Q?=C4?=”. However, please note that theses maskings are not supported by all mail clients and that some mail gateways or virus scanners shorten very long subject lines. In extreme cases, a virus scanner may even mistake very long subjects for an attack on the mail client and immediately delete the entire mail. EFS therefore limits the permissible number of characters to 254, which is within the commonly used limits.

• The best way to create a subject with masked special characters is to use your mail program and send yourself an e-mail with the subject. Then, copy the masked string from the source text of your mail into the entry form’s subject row.

Mail text

In the “Mail text” field, you can enter the actual content of the mail or edit the content of the chosen template. Depending on the format you select in the “Mail format” field, you will be provided with either an input field for a text mail, a form for an HTML mail or two fields:

• Mail text in normal text format: You merely have to enter the text. You have no option to design the text, e.g. by formatting characters. Wildcards and conditional replacement can be used.

• Mail text in HTML:

  • The modern WYSIWYG editor TinyMCE can be used when creating HTML mails or HTML mail templates (WYSIWYG = what you see is what you get).

  • Wildcards and conditional replacement can be used as usual.

  • Both attached images and external images can be inserted (see below for instructions).

  • If necessary, you may access and edit the source code through the Source code editor. The information on which editor has been used will be saved for all users within the template. This enables the creation of complex templates which would not be possible using only the WYSIWYG editor.

  • If you do not want to use the WYSIWYG editor, go to the menu Options → Personal preferences and on the tab General settings, select the option “Deactivate WYSIWYG editor for mail forms”

Automatic line breaks

In text mails, a line break is automatically generated after 72 characters. In HTML mails, you must insert the line breaks yourself. The length of 72 characters is a quasi standard which is generally recognized for electronic messages. The origins of this are in the so-called text mode of earlier PC systems which is used, to this day, with a line length of 80 characters for 25 lines. Therefore, some mail clients generally insert a line break after 80 characters. To make it easier for an e-mail’s recipients to use quotations in their replies, this limit has become established as a rule of courtesy when working with electronic messages (news messages, mailbox messages and e-mails).

If you insert a line break yourself, e.g. to mark the end of a paragraph, this will be respected and kept. Also, words will not be hyphenated. If the width limit of 72 characters is exceeded with the last word in a line, the whole word will be moved to the next line.

Uninterrupted character strings, such as very long web addresses (URLs), are not subject to automatic line breaks.

Incorporating images in HTML mails

You can insert both attached images and external images into the text of a HTML mail.

• To insert attached images, open the Insert image dialog of the WYSIWYG editor and select the desired images from the “Image list”.

• When editing the source code, you can integrate the attached images using a wildcard #file name#. Example: The name of the appended image is image.jpg, the wildcard is therefore #image.jpg#. You can insert the image with <img src=#image.jpg#>.

• If you want to use external images, enter the URL in the Insert image dialog. When editing source code, enter the URL into the src tag.

Adding attachments

It is possible to send e-mails with attachments.

• The maximum size for the attachments is 1 MB.

• You can use all the file types which are permitted for the media library.

• The XML based formats of Microsoft Office 2007 / 2010 (docx, pptx, xlsx etc.) can be uploaded into the media library and used as mail attachments.

• If you intend to attach not only “normal” attachments (e.g. pdf files), but one or several of the incorporated images described above, to an e-mail, take care to upload the “normal” attachments first. Otherwise, mail recipients using Outlook won’t be able to open the attachments.

• The attachments can be saved as an attribute to mail templates.

In order to add an attachment to an e-mail or mail template, select the desired file in the “Add an attachment” field. Once confirmed with the Attach file button, the attachment will be uploaded and attached to the e-mail. You can remove an unwanted attachment by clicking on the respective Delete icon.

• The functionality is protected by the “mail_attachments” right, with read rights required to use it.

Additional functions for personalizing e-mail texts

You can use wildcards in your e-mail to personalize the text. The following wildcards are used only when sending mails. They can be used, for example, to insert system data, to send access codes and to output various panel data.

Limits

The permissible number of wildcards is not directly limited. However, there is a limit with regard to the overall length of the text. It must not exceed 20 MB (excluding wildcards). That said, many Internet users regard mails of this size as impolite because the can quickly exceed the storage capacity allotted by their e-mail provider. Also, some mail servers are set up to simply delete messages of more than 1 MB, assuming an attack on the mail system (mail bombs).

EFS is capable of generating hundreds of personalized e-mails within a few seconds. The procedure used for this purpose is also subject to an installation-related limit. You can approximate the number of permissible wildcards as follows:

2 * text length in byte ^ number of wildcards < 20 MB

One text character equals one byte. Please note that the text of mails in HTML format is about 2.2 times larger than the actual text. The amount may even grow sixfold if you use Unicode characters. 

The so-called “Dr. Grauert letter” (ISO 10561), which is commonly used in printer tests, contains about 1500 characters.

20000000 bytes / 1500 bytes = 13334

For a plain text mail, this equals about 213. This means that you could use a total of 13 wildcards. Most mails, of course, are much shorter and also contain fewer wildcards. However, the installation’s limit can also be changed by system administration if required.

Additionally the total number of if-conditions available for mail templates is limited to 400 for all if-, else- and /if-conditions in one mail template.

Conditional replacement of e-mail text

The EFS e-mail functions allow you to use conditional replacement. This means that, in the future, it will be possible to output various mail contents depending on data from participant administration or on other pre-set conditions. The syntax for conditional replacement, in a generalized form, is as follows:

In this, the following variables must be adjusted to specific projects:

• operand1 and operand2: Wildcards or fixed values.

• operator: One of the comparative operators (“=”, “!=”, “<” or “>”).

xample

An invitation mail to the respondents in a personalized project is to contain German text if the participant lives in Germany. Participants from other countries are to receive an English text. The information on which country the participant lives in is stored in the corresponding column of participant administration and accessible via the #country# e-mail wildcard. Code: 1 = Germany, 2 = other countries. In this case, the condition definition used to address the participant is as follows:

• {if #country# = "1"}Sehr geehrter Teilnehmer,{else}Dear participant,{/if}

German participants will now be addressed in German, while participants from other countries will be addressed in English.

Example: Gender-specific salutation

You want to address participants depending on their gender with „Der Mrs. x“ or „Dear Mr. x“. The gender of participants is stored in the variable „u_gender“ in participant administration. Encoding: 1 = male, 2 = female. It can be inserted using the e-mail wildcard #u_gender#. Use the following syntax to insert the proper saluation in the email:

• {if #u_gender# = "2"}Dear Mrs.{else}Dear Mr.{/if} #u_name#

Example: Language-specific text

In a bilingual survey, you want to address participants in German if this is their native language, otherwise in English. Participants’ language is stored in the variable „u_language“. Encoding: 1 = German, 2 = English. The wildcard #u_language# allows to access the language information. The following syntax ensures that participants receive the e-mail in the proper language:

• {if #u_language# = "1"}Sehr geehrter Teilnehmer...{else}Dear participant, ...{/if}

Setting the dispatch date, dispatch period and status of e-mails

Located below the actual mail form, the “Delivery options” section allows you to set the dispatch date and the dispatch period or to set the status of the mails to “Hold”.

Validate disposition codes before dispatch

Check option in order to avoid multiple invitations or reminders to the same participant. The respective mail will now only be sent to participants who are active, and either have not been invited yet, have suspended their survey or where mail delivery has failed previously.

Set mail status to “Hold”

If, before sending the e-mails, you want to check their number and content in the mail report, you can tick this checkbox. The mails will then be kept in the queue. Using this option is advisable if, for reasons relating to the organization of work, you have a staff member create the e-mails, but they are not to be sent until released by the project manager.

When to send: .. : (Time at server = ...)

Instead of sending the prepared e-mails immediately, you also have the option of choosing a later date. The mails will then be kept in the queue until the sending date. This is advisable, for example, if the invitation to a survey is not to be sent until a certain event has occurred or outside of your office hours. For example, you can prepare the invitation mails for a survey which is scheduled to start on a weekend, but have the mails sent automatically only when the pre-set time is reached. This way, you can prevent participants from trying to access the survey before the start of the project.

A group of drop-down lists in the “When to send” field is available for setting the date and time.

• You can use a calendar, which is opened by clicking on the Calendar icon, to set the date.

• The exact time of sending must be specified manually. The current time is displayed on the left below the menu. If you have taken advantage of the possibility to set your local time, this time will be displayed below, in the “Local date” field, to facilitate the conversion.

• Queued e-mails which have the same dispatch time will be sent in the order in which they were created. Any mails which have been set eight hours ahead due to a previous failed attempt but have an earlier or the same dispatch date will therefore be sent with priority.

„When to send“ uses recipient‘s time zone

Check option in order to conform the time of mail dispatch to the recipient‘s individual time zone. A recipient‘s individual time zone is saved within the u_timezone variable. Please note that participants may live in time zones ahead of your own, therefore it may be required to plan in advance.

Setting a dispatch period for dynamic dispatch

In large surveys, mail dispatch is often organized in waves in order to avoid server overload. The organization of participants in waves is frequently performed manually: In the participant administration, participants are assigned to the respective waves with specific variables or characteristics. In order to invite a wave, the project manager then looks for the participants with the appropriate value and manually completes the entire mail dispatching process. With EFS, this is not necessary: Instead of manually organizing the participants in different waves to be processed in daily intervals, you simply specify a time frame within which the mails of your mailing action are to be sent. The system will then divide the total amount of mail into portions to be sent out in even distribution across the specified interval.

You will find the corresponding function in the “Dispatch period for dynamic dispatch” field. Enter the interval in minutes. By default, the field is blank and no distribution is performed.

Checking finished e-mails and saving them as templates

The mail preview allows you to check your message to the respondent before finally sending it.

• Separate previews are output for text and HTML mails.

• Both wildcards and line breaks are taken into consideration.

• You can scroll through the e-mails to the various recipients and check them successively.

Special features of HTML mails in the preview

E-mails for which the HTML format has been chosen and used according to the instructions in the preceding chapter can only be displayed correctly in the preview if the HTML code used is also XML-compliant. They will, however, be sent in the correct format.

Any HTML code characters you have entered will be displayed in a masked form. This means that the characters will also be displayed as HTML code. Therefore, they cannot have any impact on, for example, formatting. Before sending, they will be converted to the original tags you entered. Please note that HTML formats in plain text mails cannot be interpreted. Therefore, you must have specified the HTML format for the mail.

Passwords in the preview

The participants’ passwords are not always displayed in the mail preview as clear text, but will be either masked using “*” characters or displayed, depending on the project type and the team the user viewing the data belongs to:

• Personalized surveys (PE): If you have read rights for “mail_passwords”, passwords will be displayed in the mail preview. If you do not have read rights, the passwords will be masked using “*”.

• Employee surveys (ES): The passwords should never be visible in the mail preview.

Saving the e-mail as a mail template

If you wish to re-use the e-mail at a later stage, simply tick the “Save as mail template (including wildcards)” checkbox below the preview and enter a title for the new template before you confirm by clicking Send.

Managing mail templates

In the Libraries → Mail templates menu, you will find an overview of all the mail templates for which you hold access rights along with their most important properties. You have the following editing options:

• Create template button: The dialog for creating a new template will be opened. The other form fields for mail settings and mail text are familiar from the e-mail dispatch.

• Clickable links in the table and the familiar icons in the “Actions” column allow you to edit individual mail templates:

  • Description link: The dialog for editing an existing template will be opened.

  • Status link: The entries Active and Inactive in the “Status” column are also clickable links. You can change the status with a click on the respective link: An inactive mail template will no longer be offered in the mail forms.

  • Preview: The template will be opened in the preview. As the project context is missing in the Mail templatemenu, wildcards will not be replaced in the preview.

  • Edit mail template: The dialog for editing an existing template will be opened.

  • Copy mail template: The template is copied. You can open the copy directly by clicking the link in the green confirmation message.

  • Edit rights: The dialog for assigning object rights for the template will be opened.

  • Delete mail template: The template will be deleted following a confirmation prompt.

Properties of mail templates in detail

Mail templates are characterized by the following properties, which are partly defined by the user and partly set automatically by the system.

Mail template types

When selecting mail templates via the EFS mail forms, only those templates will be available that are appropriate to your current operation. For example, if you are inviting participants, only templates for invitation mails will be offered for selection. This is controlled by assigning the templates to certain mail template types. The following table provides an overview of the various types and their respective applications.

Defining senders’ addresses for mail dispatch

Not only the mail contents but also the senders’ addresses are usually predefined in EFS. This is of particular importance if you want to use addresses other than your own, e.g. a common mailbox that may be accessed by other staff, as well: In order for you to be able to select these addresses in the EFS mail form, they must be registered in the system. This function in brief:

• The senders’ addresses are managed in the Libraries → Mail templates → Mail senders menu.

• Optionally, it is possible to enter a real name to be inserted next to the actual email address in the mail subject header. Usually, this is the name of the project owner. Please note that it is not possible to use names in double-byte languages (e.g. Chinese).

• Which user teams may use or configure a particular sender’s address, is controlled via a specific object right.

• Which user teams may access the Mail senders menu, is controlled via read right for “options”.

Managing sender addresses

In the Mail senders menu, you will find an overview of all those senders’ addresses for which you hold access rights.

Edit options

Click on the Add e-mail address button to open the dialog for creating a new sender. All you have to enter is the e-mail address, the corresponding real name, if desired, and the teams that are granted full access. Clickable links and icons allow you to edit existing mail templates:

• Rights: Opens the dialog where you can assign read or write rights for the sender’s address to user teams.

• Delete: E-mail addresses can be deleted by ticking the checkbox in the “Delete” column and then clicking on the Delete button

The mail dispatch process in EFS

If you trigger the dispatch process, EFS forwards your mails to a dedicated mail server which is responsible for organizing the actual dispatch. The available dispatch volumes are split up as follows:

• At the start of each dispatch interval (i.e. every ten minutes), all mail dispatch orders in the queue will be registered along with their size (i.e. the number of mails).

• It will be checked whether the sum total of the mails to be sent is greater than the maximum mail volume allowed per dispatch interval. The maximum mail volume can be configured.

• If the sum total is smaller than the maximum mail volume, all mails will be sent.

• If the sum total is greater than the maximum mail volume, the dispatch orders are sorted by ascending size. Then, the dispatch resources are distributed equally among the dispatch orders. I.e. one by one, each order is assigned one mail, until the limit is reached. This way, smaller orders are completed quickly. The remaining mails would be processed according to the same principle in the subsequent dispatch intervals.

• If the mail server does not accept a mail at all, the system will try to dispatch it again eight hours later. After four failed dispatch attempts, the mail will be deleted and the recipient will be assigned disposition code 14. The number of repeats can be configured.

Syntax check for e-mail addresses during dispatch

Generally, EFS performs a syntax check on every mail address. This happens once when entering mail addresses and also, to be on the safe side, a second time when generating and sending mails. If EFS detects a mail address which does not comply with the RFC, this address will automatically be excluded from mail sending, and a corresponding message will be output on the screen. EFS Survey only allows addresses with the following format:

• local_part@domain

• Please not that “domain” must be an Internet domain with a valid syntax.

If, despite all this, an invalid mail address has found its way into the database, e.g. through subsequent corrections, the mail will be checked again when it is actually sent. The sender will then be notified that the e-mail’s address is incorrect and, therefore, the e-mail cannot be delivered.

Standard mail headers

As EFS performs mailings in the form of bulk dispatch, a corresponding header line (“Precedence: bulk”) is added to each e-mail, which enables automatic recognition as a bulk mailing. So-called auto responders should detect this. Unfortunately, not every mail system is properly configured. Therefore, it may still occur that you receive automatically generated notifications of absence as replies.

• If necessary, installation-specific mail headers can be used.

Limiting the Mail Volume per Mail Interval

The mails in the queue are processed in packages: per default, up to 300mails will be processed in 10 minute intervals. You can change the value of 300 mails. To do so, open the Options->System settings menu and enter the new maximum value in the “Job size for mail sending” field. Up to 2,000 mails can be sent per package.

Defining the number of repeats for dispatch problems

If the mail server does not accept a mail or if it is not possible to connect to the mail server at all, the sytem will try to dispatch it again eight hours later. After four unsuccessfull attempts, the mail will be deleted and the recipient will be assigned disposition code 14. You can change the maximum number of dispatch attempts. To do so, open the Options → System settings menu and enter the new maximum value in the “Maximum number of attempts to dispatch the mail” field.

Delay between delivery attempts

You may define the amount of time (in minutes) to pass between delivery attempts. Find the respective option in the Options menu → System Settings.

Using installation-specific mail headers

Installation-specific mail headers can be attached to the mails sent from an EFS installation. This is particularly useful for external bounce systems, for example. To do so, our support has to activate this function and define the desired mail header values. In the mail form, you will then find a field “Value for wildcard #extra_values# in additional mail headers”. There you can specify the values that were predefined by the support.

Controlling dispatch processes and intervening in processes

The Mail report is designed to assist you in properly managing the large numbers of e-mails needed in bigger projects. You will find the mail report.

• for project-specific mails: in the Survey menu of all project types.

• on EFS People installations: for mails sent from the People → Groups menu: in the Groups menu.

• on EFS People installations: for mails sent from the People → Contacts → Send e-mail menu: in the Contacts menu.

The mail report displays all mails in the outgoing queue, sorted by sending operations. You have the following editing options:

• View: Allows you to display a mail that has been selected from the respective dispatch process at random with the wildcards replaced.

• Release: Allows you to release and execute a dispatch process with “Hold” status.

• Hold: The mail dispatch is interrupted, e.g. if a questionnaire requires re-editing.

• Delete: Mails are removed from the queue. In EFS Panel installations, this work process includes the option of saving the recipients of the deleted e-mails in a separate group.

Viewing archived mails

Most of the mails sent from EFS are archived and can be viewed for a period of six months:

• Personalized surveys, employee surveys, multi-source feedbacks, panel surveys and master data surveys feature an overview of all sent mails.

• In personalized surveys, employee surveys and multi-source feedbacks, the mails are listed in the detail view of the respective participant.

• In panel and master data surveys, the mails are listed on the Contacts by system mail tab in the detail view of the respective panelist.

• With the appropriate rights you can view all project-specific mail processes of the installation in a centralized manner.

Viewing project-specific dispatch processes

Project-specific dispatch processes are archived. You can view the data here:

• personalized projects and employee surveys: Survey menu → Mail report menu.

• panel and master data surveys: Sample → Mail archive menu.

Mail report

The Mail report, which is located in the survey menu, gives an overview of all e-mails that were sent during the course of the survey. Every time you send one or more e-mails from participant administration, an entry is
made in the report. This enables you to subsequently check whether, for example, a certain group or individual has already received an e-mail. You may view the complete mail (with placeholders) by clicking on Mail.

In the overview list, the following information is displayed for the different sending processes within the respective project:

• Mailing: internal mailing-ID. The link displayed will provide you with detailed information to the specific process.

• Subject: e-mail subject. The link displayed will provide you with detailed information to the specific process.

• User: user who performed the dispatch.

• Date: time and date of dispatch.

• Total: total of all e-mails.

• Queued: total of all e-mails generated for immediate or future dispatch. Queued emails may be held, resumed or cancelled.

• Sending: total of all e-mails delivered to the dispatching mailing server yet to be delivered to the respective recipient(s). Please note this process might take up to
  several days.

• Sent: The number of e-mails that were successfully delivered to the receiving mailing server.

• Rejected: total of all e-mails rejected and classified as spam-mail.

• Delivery failed: total of e-mails which could not be delivered due to trouble on part of the recipient address.

• Not reachable: total of all e-mails which could not be delivered because the recipient‘s address or the domain do not exist.

• Canceled: The number of e-mails canceled.

If you click on the ID of a dispatch process in the “Mailing” column, you will see detailed information on all individual processes.

Viewing project-specific dispatch processes installation-wide

The Project mail overview tab in the Options → Platform cockpit menu gives a central overview of all mail processes that can be initiated from the current installation.

• You can display mail activity from any desired period in time.

• Listed for each mail activity are the name of the project, precise dispatch date, project type, field time, e-mail subject and number of mails submitted.

• Excluded from the count are mail submission processes from deleted projects.

• Mail activities are arranged by project.

• Access to this tab is only possible for users with root or admin rights. These users may see mail activities for those projects for which their team holds read rights.

Categories

Under the menu item Categories you can create both Default group and Rater group catgories. Under Default groupyou create global categories which you use to create thematic links between the projects. Rater group categories belong in the context of the Me Guide scenario.

Default group

We have a new Categories area available within our Libraries. Libraries are accessible from the main top-right System menu. Categories allow you to create themes within your surveys/projects and can also be assigned to tickets within our Action Board portals module. Once in the Categories area you can add a category using + Category. The configuration area opens, where you assign an individual meta name, select a color and deliver a translation that is optional. The meta name is mandatory and limited to 3 to 30 characters. Umlauts cannot be used. If you want to delete a category, you must make sure that all connections have been disconnected. By clicking on the edit icon, you can find out which connections are available for a category. Questions can be assigned to a category in the questionnaire editor and action tickets in the detail view. Before you can delete a category, however, you must undo each individual connection for which the trashcan icon is available in the library area.

You create default groups in each of the languages available in the drop-down list. You select a language by ISO code after clicking + Category, enter the title in the desired language and click Add.

Path:

• Libraries → Categories → Default group (Tab)

Rater group categories

You create the new Rater-Groups  category used in the Me Guide scenario under Libraries. You will find there the cagtegories: Self-Assessment, Manager, Peers and Team. These cannot be configured either. However, you can create new ones by clicking on + category and assigning a unique meta name in the first step. Then you use the ISO code to specify the language of the title you want to assign. You save.

Path:

• Libraries → Categories → Rater-Groups categories (Tab)

Scale Library

Matrix scales are frequently used several times: It may be that a specially developed scale is used several times in a survey or that a popular scheme such as, for example, school marks, crops up time and time again. The scale library available across the entire installation saves you the trouble of creating a scale repeatedly: You only need to create a frequently requested scaling scheme once in the scale library. From there you can import it into the matrix questions and then adapt it to the specific situation.

Imagine, for example, that in your survey you have evaluated the skills of ten wellknown football players each in a matrix question. For the purpose of evaluation, you choose the following scale:

• Football wizard – Good technique – Acceptable average – Useless – Don’t know'.

Instead of rebuilding this scheme for each of the ten matrix questions only create the scale once in the scale library and then import it into the corresponding matrix questions.

To access the scale library, go to the Libraries → Scale library menu. Various icons allow to open these scales for viewing or editing as well as to copy or delete them. Read rights for show_scala are necessary for accessing the scale library.

Creating a new scale in the scale library

Please proceed as follows:

• Click on the Create scale button.

• Enter the name plus a short description of the scale to be created, then click on Save.

• As with Paste from Word, enter all desired scale options into the “Scale options” field. Each row in the input field is interpreted as an answer option.

• Usually, the options are automatically numbered and encoded. If you want to specify your codes yourself, enter the desired value before each option, using a semicolon. Then, specify this separator in the “The separator for the code” field.

• Confirm by clicking on Save.

• In the next dialog, you can edit the new options or define graphical form elements.

From now on, you can use this scale when creating matrix questions.

Exporting a scale from a question into the scale library

As an alternative to creating a scale in the scale library, you can also export a scale from a question into the scale library.

• In the question view, open the “Scale options” section.

• Click on the Export scale button.

• A pop-up window will prompt you to enter the title under which the scale is to be stored in the scale library.

• After you have clicked OK to confirm, the scale will be stored. You will receive a message indicating that the operation was successful and can continue your work.

Inserting scales from the scale library into the questionnaire

All matrix questions containing a scale allow you to access the scale library:

• To do so, open the “Scale options” section in the question view.

• Click on the Import scale button.

• A pop-up window will open. In it you can select scales from the scale library using a drop-down list.

• Confirm by clicking on Save.

• The desired scale will be inserted into your matrix question, and you can continue editing the characteristics as desired.

Survey messages

Every EFS installation has a library where survey messages can be stored for use in other projects. It can be found in the Libraries → Survey messages menu.

• This library contains translations of the default messages in 29 languages. If you want to conduct a project in one or more of these languages, simply select and upload the translated default version.

• You can create further sets of messages or save them from a project to the library, as described above.

• Survey messages can be exported and imported into another installation.

• You can compare two selected sets of survey messages.

Overview of the survey messages in an installation

In the Libraries → Survey messages menu, you will find an overview of all the survey messages for which you hold read rights. The following essential processes can be invoked via buttons:

• Create survey messages: After entering a name and a description, a new empty set of messages is created.

• Import survey messages: Allows you to import new survey messages in an Excel file.

• Export all survey messages: Triggers the export of all existing messages.

Furthermore, you can export survey messages selected via the “Actions” checkbox and the drop-down list. You can edit individual sets using the “Actions” icons:

• For default sets only: Preview: Opens the dialog, where you can view the default set. Please note that the default sets cannot be edited. If you want to edit a default set, copy it and subsequently modify the copy.

• For user-defined sets only: Edit: Opens the edit dialog.

• Copy: You can copy a set of survey messages and then modify this copy as required. This is particularly recommended if you want to modify standard messages: the standard texts themselves cannot be edited directly.

• For user-defined sets which were created by copying the standard messages: Recover: Resets the content to its original status, i.e. the texts of the standard message.

• For user-defined sets only: Rights: Opens the dialog where you can assign rights for the messages to the desired teams. The default sets are availabe to all users.

Transferring survey messages to another EFS installation

Survey messages can be exported and imported into another installation. There are two options:

• To export one or several sets of survey messages, tick the checkboxes in the “Actions” column of the Libraries → Survey messages menu, select the action “Export”, and confirm by clicking on Execute. An Excel file containing the selected message sets will be generated.

• If you want to export all existing messages, use the Export all survey messages button.

In the target installation, go to the Libraries → Survey messages menu, and click on the Import survey messages button. Via the import dialog, you can upload an Excel file with the desired messages.

Defining default survey messages for an installation

As an administrator you can determine what default set of messages is to be used across the installation when creating a new project. When administering an installation where English is predominantly used, this allows you to ensure, for example, that an English message set is always imported.

To do so, navigate to the Options → System settings menu. In the “Default survey messages” field you can select one of the available message sets and then save it with Change.

Comparing survey messages

You can compare two sets of survey messages. This may be useful, for example, if there are two sets that are linguistically very similar, such as survey messages in American and British English. Please proceed as follows:

• Open the Comparison of survey messages submenu.

• Specify which sets are to be compared.

• By clicking on Compare, you trigger the check.

• The two sets will be listed in full, highlighting any divergent fields.

Macros

In the Libraries → Macros menu, you can find all macros of the installation which you’re authorized to access. The following editing functions are available:

• Edit: By clicking on this icon, you can switch to the Macro settings tab for the respective macro.

• Edit actions: By clicking on this icon, you can switch to the Actions tab for the respective macro.

• Delete: By clicking on this icon, you can delete the macro.

• Rights: Clicking on this icon opens the dialog for rights administration. Here, you can define, which teams will be allowed to execute the respective macro. Read rights permit execution of a macro, while write rights allow users to edit a macro. Please note that macros can only be executed in projects for which the user has additional write rights.

Macros are created in the Libraries → Macros menu. To create a macro the create_macro write permission is needed. You have to select the actions to executed and you have to configure the actions by setting the appropriate parameters.

Creating a new macro and selecting actions

• Click on the Create macro button. This will open the entry form shown.

• Set the basic properties of the macro:

  • Name

  • Description

  • Suppress output: If the checkbox is ticked and the macro activated, the output of precise information on the process will be suppressed, and only a message indicating success or failure will be output. It is recommended that you activate the message output when first testing a macro, but switch it off after a successful test.

  • Offer for projects of type: You can select the project types for which the macro is to be available.

• The select boxes in the “Actions” area allow you to select preset actions.

• If you wish to select only individual actions, click on these actions in the “Available actions” field, and then click on the simple Arrow icon to move them into the “Selected actions” field.

• If you wish to select all available actions, click on the larger arrow.

• After that, use the up and down arrows below the “Selected actions” select box to sort the actions in the desired order.

• Finally, confirm by clicking on Create.

After creating the macro, you will automatically be taken to the Actions tab, which is now active. It allows you to edit or delete actions.

• Click on the name of an action or on the related Edit icon.

• In the “General” area of the entry form, you can enter a specific title for the action and describe it.

• In the “Parameters” area, the specific parameter for the respective action must be set, in this example, the message set to be chosen.

• After that, the setting must be saved by clicking on Save.

• The action now has a completed configuration and will be marked accordingly in the overview of the actions.

• Make the required settings for all actions accordingly.

Macro Actions in detail

The following actions can be used in macros.

Granting access rights to macros

In order to be able to define macros and to determine who will be allowed to execute them, a user must belong to a team that has write rights for create_macro. You can use the Rights icon in the overview to assign write or read rights for specific macros to individual teams.

Checking the application of macros

The Macro log menu logs all macro executions.

Question types

If you want to create user-defined question types not only temporarily, but add them to the library, you can do this in the menu Libraries → Question types. The new defined question types are available across all projects in the Questionnaire Editor. You can add or import a new question type from another existing EFS installation. Click the New button or the drop-down menu → Import.

• Enter the title of your new question type and select the appropriate category. Assign your newly created question type to one of the following categories of question types : Single response list, Multiple response list, Standard matrix, Text field or 911 special. Also in the Questionnaire Editor you can find the newly created question type in the selected category.

• The newly created question type will be listed in the overview. To edit it, click on its title. This opens an HTML editor that allows you to create the new question type. Here you can customize the template, the stylesheet, the Javascript, the exact settings and resources.

The following actions are available in addition to the further editing of the question types.

An already created question type can be imported as a ZIP file. By doing an export/ import question types are portable across installations.

Library of question types

You may only use Latin characters and numbers for the name. An internal name will be generated from your given name. It has all whitespaces removed, so it can be used as an identifier. The category determines the underlying data structure for the answers as well as the initial files and available configuration options. The Preview button opens a dialog with a live preview of your question type, as it would be rendered in a survey with an unmodified responsive layout. The Save button is disabled by default. As soon as something is edited it will be activated and a modification marker is shown in the navigation to the left. The navigation on the left consists of five items: Template, Style Sheet, JavaScript, Settings and Resources.

• Save any changes, before you navigate through the menu.

Template

It is compiled with the Smarty 2 template engine and makes use of several variables supplied by EFS. The initial template contains basic functionality that enables you to develop your own template.

Every question contains one or more variables (configured in Settings). A variable represents an answer option. In the case of a matrix every dimension is an answer option (or item) and therefore has its own variable.

For every variable there needs to be a list of possible values. These are the scale elements (internally called “r_cat”), which are also configured under Settings.

In the template you have a variable $items, which is an array that contains all answer options of the question. You can iterate over them with a for-each loop or a section. Every item-object has a variable $r_cats, which is an array that contains all scale elements of the question. Again you can iterate over them with a loop.

If you want to see all existing Smarty variables insert {debug} in your template. A button will appear at the top right corner of the question preview, which opens a complete list of variables available at the point the debug-plugin was called.

A simple example how to iterate over items and r_cats:

To submit values to the server the form needs to have a field (depending on the question type e. g. input, checkbox, hidden or select tag) containing the name of the variable matching its name. For example:

This will print a selectbox for each item including any scale options (r_cat).

Style Sheet

In the Style Sheet menu you can edit the question type’s CSS file. Some styles are predefined, but you can remove them to get the default styling of the Responsive Layout and start your styling from there. The question type’s main container gets a CSS class with the following structure:

In our example the class name would read as follows:

You should use this class as a namespace to limit your styles to your question type and prevent interferences with the outer layout or other questiontypes.

Java Script

In the JavaScript menu you define the logic of your question type.

• If you do not need any JavaScript behaviour you can remove the example code and leave the file empty.

At the beginning of the template file there is some code that makes the question type’s settings available in the JavaScript. You can find these settings in the options object of the JavaScript plugin. For example the answer options (items) are stored in an array called items. Likewise the scale options (r_cats) are stored in an array called rcats.

You will also find the question type’s options (defined in the Settings area) inside the this.options object. I.e. if you have an option named “orientation” in the options group optionsGroup1, you can access it like this:

You should start your code inside the plugin’s main function, but you can use the prepareOptions function to parse and cast the given options beforehand or to modify the type if you need to.

Settings

In the Settings menu you define the question type’s options and features. It is separated into five sections. Each section is responsible for a different kind of characteristics.

Question type options

The options you define in the question type options section will show up in the question editor and allow the creator of the survey to configure instances of your question type. All Options belong to an options group, so you have to create an options group by clicking on the “Add options group” button.

Enter a name for the options group by which it can be referenced in the template and JavaScript files. You can also set its label in your current language and in other languages by clicking on the globe icon next to the label field. Click on the Add option button to open a menu with possible option types.

The option has been given the internal name “orientation”, a label and a help text that will be shown in the question editor and a default value of “1”. The default value corresponds to the code of one of the options, defined in the lower area. When you save the changes and create a question of your question type in a survey you will see the options group and the “orientation”-option below the general question configuration. The help text is shown in a tooltip when you hover over the info-icon.

• You can have as many options and options groups as you want. For example you could separate your options into an options group for functional options and one for layout related options.

To access the defined options in the template you can use the question_info variable. You can find your options groups in the question_info.settings.questionTypeOptions object. For the “orientation”-option it looks like this:

Answer options

In the Answer options section you define the initially available answer options for your question type. In matrix type question types every answer option stands for a dimension. In multiple choice question types they represent the checkboxes and in single choice question types you will not have this section at all, as these have exactly one answer option.

Scale elements

In the Scale elements section you set the possible answer values (codes). In matrix type question types every element stands for a column. In single choice question types they represent the radio buttons, whereas in multiple choice question types you don’t have this section, because every checkbox has exactly two scale elements with the values “0” and “1”.

Question editor features

In this section you can enable or disable a variety of features for your question type. Which ones are available depends on the category of your question type. For example, matrix type question types have different features available than single choice question types.

• Please refer to the info-text of each feature to get a description of what the feature does

Configuration

Here you can change the name of the question type.

• This applies only to the displayed name. It does not change the initially created internal name, as you would have to update the template, CSS and JavaScript files to match the updated name.

Ressources

In the Resources area you can manage the files that you need for your question type. These fall into two categories:

• Files that you use as default value for “Resource”-options (image, audio or video files).

• Files that you need to include in your code (i.e. JavaScript libraries).

In any case you first upload your files by clicking on the upload icon next to the “Resources”-entry in the list on the left.

Using a ressource in an option

Now that we have uploaded some files, those can be recycled for use in the Options menu, for options of the type “resource”. We will use the image as the default value for a “Resource”-option.

• Go to the Settings area, expand Question type options and click on “Add option” inside an Options group.

• Select “Resource” from the menu and enter values for the options name, label and help text.

• Select “test.jpg” from the selectbox to assign it as default value.

The respective image will be displayed as default once you are creating a new question of your question type. To access the image in your template you can do (without linebreaks):

You can also enter the following in the JavaScript file:

Using a ressource directly

The second case is using an uploaded file directly. This means including a file that can’t be modified by the user (as opposed to the previous case, where the user could select his own resource as value for an option). In your template you can access the file “test.jpg” like this (without linebreaks):

When loading the file “test.js” in JavaScript enter as follows:

Consent form templates

You do not have to configure the consent form for each project, but create consent forms under Libraries, which you will use when creating an consent form as required. Pre-filled forms depicting the most common use cases can also be found there, so that you have GDPR-compliant consent forms by means of minor but indispensable adjustments to your own project circumstances.