Configuring a Dataform Survey Email Template

This topic provides ClientSpace System Administrators with step-by-step instructions for designing a Customer Satisfaction survey and configuring a survey email template that you can trigger from a dataform such as a Client Service Case.

The pre-configured, default survey is a single question "How Did We Do?" 1 to 10 stars rating survey with an "Additional Comments" section for respondents to optionally add comments. See an example of the default survey layout:

If you do not want to use the pre-configured option, with minimal effort, you can easily create one or more custom survey designs. See an example of a custom survey design:

Create a custom survey design if you want to:

Use a custom survey question instead of the default "How did we do?" survey question.
Enter custom text above the comments section to guide respondent feedback.
Use a different rating scale than the default rating scale.
Customize the rating scale's appearance. For instance, instead of the default stars rating, show the selections in a drop-down selector or as buttons with text.
Use a different color scheme than the default survey color scheme.
Add a logo.
Create multiple (unlimited) survey designs to choose from for specific purposes when configuring your email templates.

Once a survey design is created, you can attach it to your survey email template configuration (as detailed in the Configuring a Dataform Survey Email Template section of this topic.) If you choose not to specify the survey design, ClientSpace will use the default survey.

Note: Any surveys created prior to the availability of the Survey Design feature will continue to use the default survey until you edit the associated survey email template and attach a survey design form.

The use case demonstrated in this topic triggers a survey when a Client Service Case is resolved. You can adjust the configuration as needed for your own use case(s).

Completed survey results are stored in the Survey Results dataform table (gen_csSurveyResults). Use the dataform table to create your own Business Intelligence reports showing survey statistics. Or, for an "on-the-fly" analysis of a specific survey to determine why an exceptionally high or low rating was given, you can click Open Related Form on the Survey Results form to quickly access the related case and review case notes.

Note: Contact Professional Services if you require additional assistance configuring or using this feature.

Optional Prerequisite Configuration

Rating Scale Customization Overview

The following survey rating scale lookups have been set up for you:

1 - 10	This is the default 10-point rating scale used for the default survey layout. However, this rating scale can be selected for custom designs as well. Validate default options range from Excellent to Very Poor.
Frequency	5-point rating scale. Valid default options are Always, Often, Usually, Sometimes and Never.
Agree	5-point rating scale. Valid default options are Highly Agree, Agree, Neutral, Disagree, and Highly Disagree.
YesNo	Valid default options are Yes or No.

You have three options for determining the rating scale used in your design:

Select one of the pre-configured options above.
Edit one of the pre-configured options above.
Create your own rating scale.

Customization of a rating scale is only needed if:

You intend to create a custom survey design and you do not want to use one of the survey rating scale lookups we created.
You are using the default survey or creating a custom survey design and one of the pre-configured rating scales needs some adjustments to work for your design. Example: You want to use the 1-10 point star rating scale but you want change the lookup Decode values so that when users hover their mouse pointer over a star rating, they'll see meaningful hover text instead of numbers 1 through 10. This is illustrated below:

Review the steps below to edit decode values for an existing rating scale or create a new rating scale.

Edit Decode Values

To edit Decode values:

Open the Lookups dashboard (System Admin > Lookups) and search for Survey Rating.
Display the Filter column.

Note:
- All survey ratings are in the Survey Rating lookup group. Filter is used to group survey ratings and establish filtered subsets to use on surveys. The filter determines which items in the Survey Rating lookup group belong together in the same rating scale.
- A lookup item can belong to more than one filter. Multiple filters are entered in a comma-separated list in the Filter field of the Lookup Detail record:
- To display the Filter column, click the vertical three dot menu (i.e., Kebab menu) on any column header, select Columns and then select Filter.
Note the Filter value to make sure you are editing a rating in the correct rating scale and click (Open) next to a Survey Rating record.
To change a decode value, enter a new value to display to survey respondents in the Decode field. Example: On the 1-10 point rating scale using Survey Rating records, replace the "10" in the Decode field with "Excellent".
Click Save.
Repeat steps 2 through 5 on each Survey Rating record until all Decode field values are changed to the desired value.

Create a New Survey Rating Scale

To create a new survey rating scale:

The steps to create the new rating scale involve adding new values to the existing Survey Rating lookup group. This is the same process used to create any lookup values in our system. For detailed steps, please refer to the Add Values to the Lookup Group section of the Configuring lookups topic.

However, in addition to following the general steps to add values to the Survey Rating lookup group, there are a couple of things related to survey rating scale creation that you should note:

The Filter value must match if the ratings belong in the same scale! Ensuring that the Filter field has the same value for all items belonging to the same rating scale is imperative.

Even the slightest misspelling, extra space or stray punctuation mark on one of your rating scale entries will cause that item to not be grouped with the rest of the rating scale items.

Tip: If you want to use a longer Filter value as we've done in the example below, to ensure no mistyping, copy it to a blank Word document and paste it each time you add a new Lookup Detail record/rating scale item.
A lookup value can be used in more than one filter! This allows you to create unlimited subsets. In the example below, we have created filters named 1-10, 1-5, and 1-7. We want the lookup value "1" to be included as a rating value in the 1-10, 1-5 and 1-7 filter groups so we add them all to the Filter field separated by commas):

Note: You can view all of the rating scales a lookup value belongs to when you display the Filters column on the Lookups dashboard (System Admin > Lookups):

Mind the Display Order! The order in which the rating scale displays to users is dependent on the Display Order. Lower numbers display first. Higher numbers display last. Our example above shows the first rating in a 5-point scale. As we would like the most positive rating to display first, we have assigned a Display Order of 1. Following this logic, you can define Display Order as follows:

Rating	Display Order
Very Likely	1
Likely	2
Neutral	3
Unlikely	4
Very Unlikely	5

Note: You do not have to use consecutive numbers from 1 to 5 as we did in the example. The numbers just need to reflect a progression from lowest to highest (or highest to lowest, depending on the order in which you want the items to display.) For example, you could have used 10, 20, 30, 40, and 50 instead of 1 through 5.

Create a Survey Design

In this optional step, you establish the "look and feel" of your survey. If you skip this part of the configuration, the system uses a default survey design that appears as follows. Note the absence of a page header and logo in the upper left corner:

Now, compare the default survey design above to an example of a customized version. Note the addition of a page header and logo along with the customizations of the color scheme, survey question and comment section description. This survey also uses a custom rating scale displayed in a text button style.

To create a custom survey design:

Open the Survey Design form (System Admin > Email Templates> Survey Design).

The Survey Design dashboard displays.
Click Add.

The New Survey Design form displays.

Complete the fields in the Survey Design section as applicable:

Survey Name	Required field. Enter a name for your design. This is the name the survey is listed by on the Survey Design dashboard. The name must be unique and is validated against other survey names to ensure uniqueness. Example: Customer Recommendation Tip:When you open an existing survey and it is added as a Work Center item, it displays as {Survey Name} Survey Design. Therefore, if you include the word "Survey" in the name, the Work Center link includes the word survey twice. Example: Customer Recommendation Survey Survey Design. If the repetition bothers you, avoid using the word "Survey" in the Survey Name.
Page Header	Enter a page header. It displays in the upper left corner of the survey form. If empty, no value is displayed. Example: Helping Hands PEO Customer Recommendation Survey
Survey Question	Enter a survey question. If empty, the default question is displayed. Example: Based on your most recent experience, how likely are you to recommend us to another organization?
Description	Enter some leading text to display above the Comments text box. This guides the respondent to provide the feedback you seek. If empty, the default description is displayed. Examples: In a few sentences, tell us why you would or would not recommend us. Do you have other ideas for future “Lunch and Learn” sessions. If so, enter them here.
Button Style	Required field. This determines the display of the rating scale. Valid options include: Radio Buttons, Text Buttons, Stars, and Dropdown.
Response Option	Required field. Select the rating scale you want to use for your survey. Select a pre-configured option, a filtered rating scale, or a custom rating scale that you created from the drop down list. Note: Survey ratings are created using the Survey Rating lookup group. A filter can further refine the Survey Rating lookups and allow you to use the lookup group more flexibly. You can use the same lookup group to create subsets of the orginal rating scale and use the filtered subsets on various surveys. See Configuring lookups for more information.

Complete the fields in the Survey Theme section as applicable:

Logo File	Select your logo file. Note: You must resize your logo file to the proper display size before uploading the file. Click (Upload File). The Upload File dialog box opens. Click Choose File. Locate the file on your computer and click Open. The file name displays. Optional: For Description, type a description of the uploaded file. Optional: For Category, select an entry from the list. Click Save.
Page Background Color	This color displays as the background of the entire survey page (i.e, the area behind the survey box.) Click the down arrow to select a color and then click Update to apply the selection. Note: For all fields with a color selection option, you can: Create a custom color: In Gradient View drag the selector along the vertical color bar and then drag the selector in the color gradient box to create a custom color. Use your branding colors: In Gradient View, type a hex color code representing a branding color in the HEX field. Select from a defined palette: In Palette View select a color from the limited palette of colors shown.
Survey Background	This color displays as the background of the survey box. Click the down arrow to select a color and then click Update to apply the selection.
Accent Color	This color is used as the background color of the survey question and the Submit button. Click the down arrow to select a color and then click Update to apply the selection.
Text Color	This color is used as the text color for all parts of the survey form except the Page Header which uses the ClientSpace default of white text on a black background.

Click Apply and then click Preview Survey Design.

A mockup of your design displays on a separate tab of your browser.
Make any changes as necessary to your design and then click Save to save any changes to the survey design.

Configuring a Dataform Survey Email Template

The following procedure guides you through the steps to configure an email template that triggers when a case is resolved. Other use cases may be applicable.

To configure a case survey email template in ClientSpace:

Go to System Admin

> Email Templates.

The Email Templates dashboard opens.

Click Add.

The Email Template wizard opens at Step 1 Initial.

Complete Step 1 Initial.

Type	Select Survey.
Triggering Form	Select Client Service Case.
Template Code	Add a short descriptive code to identify this template, such as CaseSurvey.
Template Name	Add a descriptive name (this is displayed in the application list), such as Customer Satisfaction Case Survey.
Description	Include a brief description, such as Customer Satisfaction Case Survey - Triggers after case resolution.
Execute On	Select Insert or Update.
Merge Procedure	Leave blank.
Execution Pipeline	Leave set to Default.
Workspace Templates	Select the Workspace Templates that will receive this email. Default is All Templates.

Click Next and complete Step 2 Content.

Subject

The subject line of the email that is generated. The email recipients see this subject.

Body

The body of the email that is generated. This field supports rich text, so the email may be branded and include links. This is seen by the email recipients. You can use replacement fields to customize the message. To use replacement fields, click See Replace Fields. For details about replacement fields, see Replacement Fields.

Important: The {SurveyURL} Replace Field located in the Survey section of the Replace Fields window is required. Use it to insert the survey link into the body of the email.

To configure the link without showing the actual URL in the email:

Select the text that you want to convert to a hyperlink, such as "here".

Click Insert hyperlink on the Body formatting toolbar as shown below:
Copy or type {SurveyURL} into the Web Address field.
Verify that the text you want to convert to a hyperlink is displayed in the Text field.
Optionally, enter a tooltip that displays when the user hovers their mouse pointer over the link.
Leave Open link in a new window unchecked as the survey is already designed to open the survey in a separate browser tab.
Click Insert.

Survey Design

If you want to use a survey design instead of the default survey, select it from the Survey Design drop down list. (Leave this field blank to use the default survey design.)

Note the presence of the Open button next to your selection.

Click the button to open your survey design, review the design or make and save desired changes. When you are finished making changes, use the work item link on the left pane to return to the Email Template.

Click Next and complete Step 3 Addresses.

Address Stored Procedure

Optionally, select an Address Source Procedure if you want to send the survey to a list of recipients other than the recipients on the triggering form.

From Address

This field defaults to Admin Email Address (the application administrator's email address). This is the default admin email set in System Admin > Advanced > App Settings.

To change this setting:

Click the link (Admin Email Address).
The From Address Options dialog box opens.
Select one of the following options:

Admin Email: Uses the default admin email set in App Settings. For assistance with App Settings, please log a case in the Extranet.
AdHoc: Allows you to manually add to the From list by simply typing it in. This should be an active mailbox address so the respondent can reply directly to the email if they need to contact you. Additionally, you can specify a friendly name in the From Friendly Name field to display to the recipient. For example, you might want to display Company XYZ Support instead of support@companyxyz.com. For more details about using AdHoc with a friendly name, see Specifying a friendly name as From Address.
User: Select a specific user of the system.
Procedure: Select an address stored procedure and pick the From address.
Field on a Form: Select a dataform from a list of forms in the system that have relevant email fields. You can set user fields to values that exist on dataforms across a tabbed set. If the selected user fields are empty, the default value is the system admin. For more details, see From a Field on a Form.

When done, click Ok.

To add recipients, click Add.

A row opens. This is where you specify an email source.

Source

Select the Email Address Source. The drop down list contains multiple valid options for Source such as Current User and other dataforms.

In the example, we are selecting Client Service Case so that we can pick an email address field on the case record to use in the Address field. We are also selecting Adhoc Email Address which allows us to manually type a specific address in the Address field.

Type

Type must be To for surveys.

Note: CC is not an available option as each recipient receives their own unique email and survey. The {SurveyURL} replace field is unique per recipient.

Address

Depending on your Source selection, you can:

Select an email address field from a dataform specified in the Source field.
Enter a specific email address if you selected Adhoc Email Address as Source.
Leave the field blank (if you selected Current User as Source and allow the system to use the email address associated with the current user's System Admin > Users > User Details record.

In our example, we are specifying the Email Address field from the Client Service Case and we have also entered an Adhoc Email Address to receive the survey when the email template triggers.

Click Next and complete Step 4 Conditions.

No Primary Trigger	Enable this option. (Select the option.)
Primary Trigger Field	Not used.
Only Trigger Once	By default, an email template triggers each time any condition specified in the Condition Expression field is met. If you want the email template to only be triggered the first time the Condition Expression requirements are met, select this option.
Condition Expression	Allows for AND, OR, and NOT conditions using the display conditions (Label) from the Add section. Using the Label field that corresponds to the entries in the Add section, you can combine the conditions into more complex expressions. The Condition Expression field could state, for example (C1 AND C2) OR (C3 AND C4) OR C5. This level of complexity was not required for our example. For a detailed explanation about conditions, see Condition expressions.

To configure conditions, click Add.

A row opens for adding conditions to include Source, Field, Operator, Value, and Label. You can add multiple conditions.

Source	Indicates the dataform or stored procedure that provides the triggering condition. Select Client Service Case.
Field	This is the field that is evaluated for the conditions. Select Resolution.
Operator	The type of comparison between Field and Value. Select Equals.
Value	The criteria against which Field is compared. Enter Complete.
Label	The label to be used when constructing Condition Expressions for triggering. Labels are used in the Condition Expression field. Accept the default of C1.

Click Next.

10.

Skip Step 5 Attachments.

11.

Click Finish to save your work.

After you click Finish, a "Would you like to publish?" confirmation message displays. This email template does not work just yet because it is unpublished (inactive). You must publish the new email template to make it active.

If you are ready to publish immediately:

Click Yes on the confirmation message.
The email template is now published.

If you would like to publish later:

Navigate to the Email Template dashboard.
Locate your survey and click the Published checkbox.
The email template is now unpublished.

Working With Survey Results

There are two ways to work with survey results:

Use the Survey Results dataform table (gen_csSurveyResults) as source data to create Business Intelligence reports based on survey results.
If a Global Admin has created a link to the Survey Results dataform from your workspaces, you can click Survey Results in the Action Center under Links to view a list of all Survey Results dataforms for the workspace.

A Survey Results dataform is generated for each survey that is sent as soon as the email template is triggered. Therefore, viewing the Survey Results list includes survey results in Sent and Completed status and you can open individual responses by clicking (Open) next to a survey result in the grid. Opening a Survey Results dataform in Completed status displays any Comments the respondent may have added:

Click Open Related Form to quickly access the related dataform to review any contributory data relating to an exceptionally high or low score without needing to generate a report.

You can use the work item links on the left pane that ClientSpace created for the related dataform and the survey results to toggle back and forth between the two forms.