Rich text templates

Rich text templates facilitate the work of the Web Client users by providing them with drafts for emails and comments. In addition, the text of automatic emails or automatically added comments can be stored in text templates. Templates help to keep emails consistent regarding wording and layout, and increase the productivity of the users who do not have to type as much text.

Rich text templates can include variables which are filled with data from the case where the template is used. Variables can retrieve case data, data of the case’s contact or assignee, and data of the current user.

When using a rich text template, the template content is inserted into the comment or email editor. The user can edit it as desired to create the final comment or email. It is possible to use several templates for a comment or email.

Rich text templates are saved on the Rich text templates page. Templates which are only used in the workflow and should not be available for selection in the Web Client, can also be saved on the Technical templates page.

Settings for rich text templates

Rich text templates have the following general settings. They can be edited in the Settings tab.

• Internal name: Mandatory. The name of the template. It must be unique within the language. In the table, templates which have attachments are indicated by a small paperclip icon next to the template name.
• Localized name: Optional. The localized name of the template which is shown in the template selector in the Web Client.
• Language: Mandatory. The language of the template. This is useful if you communicate in several languages, so that you need to have the same template in each language. You can then use the language setting to retrieve the correct template in scripts.
• Type: Mandatory. There are four types of templates:
  • Template: The template which can be used for comments or emails.
  • Include: Includes can be used within other templates. They allow reusing text for several templates. A common use case for includes is the email signature, which is required for all email templates.
  • Text block: Text blocks can be used within other templates. They are useful for manual emails and comments because the user can choose which text blocks to include in the final comment or email. See Using rich text templates.
  • Script: Scripts can be used within templates, includes or text blocks. They are written in Freemarker and allow adding logic to templates. See Using scripts in rich text templates.
• Group: Mandatory. The group which the template belongs to. This setting is useful to organize your templates and locate them more easily, both in the template administration and in the email or comment editor.
• Subgroup: Optional. The subgroup which the template belongs to. This setting is useful if your groups contain many templates.
• Usage: Indicates how many times the template was used, i.e. selected by a user in the template selector of a case, on the current ConSol CM system. Only shown on the overview table.

There are three places where rich text templates can be used. You can select one or several of the places in the Availability tab:

• Email: The template can be used for manual emails sent using the email editor in the Web Client.
• Case creation: The template can be used for comments written in the comment editor of the Web Client when creating a new case.
• Case editing: The template can be used for comments added or edited in the comment editor of the Web Client in an existing case.

Usages of rich text templates

In the Usages tab, you can see how the template is related to other entities in the system:

• Incoming references: Usage in queues, scripts and other templates
• Outgoing references: Data fields and other templates used in the template

If you have general administrator permissions, you can click the chip icons to navigate to the referenced entities.

Basic tasks

Finding a rich text template

The rich text templates are displayed directly after accessing the Rich text templates page. You can filter the table to locate a template more easily:

• Text search: Enter a text in the Search field and select In name to search in the templates' name or In content to perform a free text search in the content of the templates.
• Template type: Select the type in the All types selector to display only templates of a certain type.
• Template availability: Select the availability in the All availabilities selector to display only templates which are shown in a certain context.
• Template group: Select the template group or subgroup in the All groups selector to display only templates which belong to a certain group.
• Queue: Select the queue in the All queues selector to display only templates which are available in a certain queue.

Managing rich text templates

You need to have the Manage templates permission or administrator permissions to manage templates, see Global permissions.

Best practice

Set up a specific role for the users in charge of the text and document templates. Create a role with the permission Manage templates only and assign it to the users who create or edit templates.

The following actions are available for rich text templates:

• Create a new template: Click the Create rich text template button above the list of templates. Fill out the basic template data (see Settings for rich text templates) and write the template content (see Writing rich text templates) You can define the template's availability, see Defining the availability of rich text templates. If the new template is similar to an existing template, you can click the Duplicate icon to copy another template.
• Edit a template: Click the row of the template to update the basic template data (see Settings for rich text templates), change the template content (see Writing rich text templates) or modify its availability, see Defining the availability of rich text templates.
• Disable a template: Click the Deactivate icon to disable a template. Disabled templates cannot be used anymore. They are displayed in gray italics in the overview.
• Enable a template: Click the Activate icon to enable a template.
• Delete a template: Click the Delete icon of to delete a template which is not needed anymore. Templates which are in use, either by the workflow or because they are referenced by other templates, cannot be deleted.
• Set the default templates for comments and emails: Click the Set standard templates button above the list of templates to define which templates should be inserted automatically into the editor when a user writes a comment or an email. For emails, this is usually the email signature. This setting can be overwritten by queue, see Scripts and templates

You can manage the template groups and subgroups by clicking the Manage groups button. It opens a modal window which allows to add and remove groups, and to localize the group names.

Writing rich text templates

You can perform the following steps to write a rich text template:

1. Create a template of the type Template. You can enter text and format it using the rich text editor in the Content tab. In addition, you can insert variables by clicking the Insert variable button, see Using variables in rich text templates. If the template should only be available in specific queues or if specific data fields are filled out in the case, you can restrict the template accordingly in the Availability tab, see Defining the availability of rich text templates.
2. Optional. Add attachments to the template. When selecting the template in the comment or email editor, the attachments are preselected. They are attached to the case upon saving the comment or sending the email. When an email template with attachments is used by the workflow, the attachments are ignored.
3. Optional. Create a template of the type Text block. You can enter text and format it using the rich text editor. See Using variables in rich text templates.
4. Optional. Create a template of the type Include. You can enter text and format it using the rich text editor. In addition, you can insert variables by clicking the Insert variable button, see Using variables in rich text templates. You can use all kinds of variables except for text blocks and other includes. A common use case for includes is the email signature, which is added to all templates used for emails.
5. Optional, administrator permissions required. Create a template of the type Script. You can enter text and use Freemarker code to add logic. If you select the Interpret HTML when rendering the template checkbox, you can use HTML tags to format the script content.
6. Optional. Reference text blocks, includes and scripts in the template, see Using variables in rich text templates.

Executable code

It is not possible to use executable JavaScript code in rich text templates. Any <script> tags are escaped automatically by the system.

Source code

You can view the source code of the template by clicking the Code view button in the rich text editor.

Using variables in rich text templates

There are different kinds of variables:

• References to other rich text templates (includes, text blocks, scripts): The referenced templates are included automatically. The only case where there is user interaction are text blocks, which the user can select or deselect.
• References to case and contact fields: The referenced fields are automatically replaced by their values in the current case / case contact. If the field is empty, it is omitted in the template. No user interaction is required.
• References to users: The referenced fields are automatically replaced by their value in the current user or assignee of the case.
• Variables to be filled out by the user: There are two kinds of variables: text input and selection from enumerated list. The user needs to fill out the variable when using the template.
• Links: Links to the current case are automatically replaced by a hyperlink to the case in the Web Client or CM/Track.

Please proceed as follows to insert variables:

1. Place the cursor at the desired position within the text.
2. Click the Insert variable button
3. Locate the desired variable in the modal window. You can use the search field, and / or apply a filter by queue or customer group to narrow down the results.
4. Double-click the desired variable to insert it. In case of variables for manual user input, this opens another modal window where you need to enter a name. For variables for selection from enumerated list, you also need to select the list.

Implications of the usage of variables

The usage of variables affects the template's availability:

• Case fields: The template is only available in cases whose queue has the respective field group assigned.
• Contact fields: The template is only available in cases whose main contact belongs to a customer group whose data model includes the respective fields.
• Links: Links do not work on the case creation page. The system properties cmas-core-server, url.track.auth and cmas-core-server, url.webclient must be set because they determine the system URL used in the hyperlinks.
• Manual elements: If the template contains text blocks and variables for manual input, it should not be used in the workflow. Such templates have a red badge in the overview table which indicates that they are intended for manual usage.

Defining the availability of rich text templates

The context determines in which cases a rich text template is available. The availability of a template depends on the two factors:

• Context settings: In the Availability tab, you can limit the availability of templates depending on the queue and case fields. The following settings are available:

  • Queue: Select the queue which the case has to be in.
  • Data field: Select the value which needs to be set for a case field (only fields of the type Sorted list).

  You can add several criteria. The following rules apply when combining several criteria:

  • Queue: Several queues are combined with OR, i.e. the case needs to be in one of the queues.
  • Case field: Several case fields are combined with AND. Several values of the same case field are combined with OR. This means that the case needs to have one of the specified values for each of the case fields.
  • Queue and case field: Queue and case fields are combined with AND, i.e. the case needs to be in the selected queue and have the specified value in the given case field.

  There are two kinds of context: fixed and overridable. Fixed means that the template is only available if the criterion is met. Overridable means that the Web Client users can click the Show more button in the template selector to display the template.

• Variables: If case or contact fields are selected as variables, the template is only available if the current case and its main contact have a data model which contains the respective fields, see Using variables in rich text templates

Using rich text templates

Rich text templates can be used in the comment and email editor of the Web Client and in the workflow. Rich text templates which are used in the workflow work in the same way as technical templates (see Using templates in scripts).

The following section describes how users work with rich text templates in the Web Client.

The user can select the desired templates in the Insert template content selector of the comment and email editor. He can edit the template text before saving the comment or sending the email. If a default template is used, the user can remove or edit the content of this template. The template is inserted as text, the text which belongs to variables has the same color as in the template administration. The purpose of the colors is to highlight the parts which are dynamically retrieved, the sent email or saved comment does not have these colors.

You can configure several editor settings regarding templates in the page customization of mailTemplate.

Advanced tasks

Using scripts in rich text templates

Scripts allow to add logic to the templates. Using scripts you can implement for example customized salutations depending on contact fields.

Script templates are written in Freemarker (see https://freemarker.apache.org/). If you select the Interpret HTML when rendering the template checkbox, you can use HTML tags to format the script content.

Bracket style

You have to use square brackets [] instead of the angle brackets used in standard Freemarker notation.

Links

Scripts with the option Interpret HTML when rendering the template can include links. The links have to start with one of the allowed protocols (http, https, ftp, ftps, file, mailto), otherwise they are removed.

Therefore, you cannot directly use a script function within a link to dynamically retrieve a complete link from a case or contact field. The following code using a function within the link tags in a script will not work:

<a href="${ticket.get('fieldgroup.field')}">My Link</a>

Instead, the field value must not include the protocol. You can use a variable which stores the return value of the function:

[#assign link=ticket.get('fieldgroup.field')!]
<a href="https://${link}">My link</a>

Special case: script which includes template with images

If the script is used to include templates which contain images, you need to proceed as follows:

• Create the included template before you reference it in the script.
• Reference the included template using its name without locale, i.e. the syntax is <#include "template name">. You cannot use variables for the template name.
• The included template must be the same language as the letter.

Case history

If the script is used in a template for an automatic email, and the email content should be written to the case history, use the method workflowApi.addTicketTemplateText(String pTemplateName).

Coding example: queue-specific signatures

The following example shows a script template used to include a specific signature depending on the current queue of the case. This way, you can use different signatures for different departments of the company.

[#if ticket.queue.name??]
  [#if ticket.queue.name=="ServiceDesk"]
    [#include "Signature ServiceDesk"]
  [#elseif ticket.queue.name=="HelpDesk_1st_Level"]
    [#include "Signature Helpdesk"]
  [#else]
    [#include "Default signature"]
  [/#if]
  [#else]
    [#include "Default signature"]
[/#if]

Coding example: using lists and tables in templates

Data fields of the type List or Columns cannot be selected directly as variables. Instead, you need to create a script and include it in the template. The Interpret HTML when rendering the template checkbox needs to be selected for the script template. The following example shows how to write a script which displays the content of the table order_list in the case field group helpdesk_standard. The table header is displayed in bold font and contains the field names.

[#if helpdesk_standard.order_list?has_content]
  <table>
    [#list 0..helpdesk_standard.order_list?size-1 as i]
    <tr>
      [#list helpdesk_standard.order_list[i] as value]
        [#if i==0]
          <td style="border:1px solid #d9d9d9; padding: 0 2px;font-weight:bold;">${value}</td>
        [#else]
          <td style="border:1px solid #d9d9d9; padding: 0 2px;">${value}</td>
        [/#if]
      [/#list]
    </tr>
    [/#list]
  </table>
[/#if]