Technical templates

Introduction to technical templates in ConSol CM

Templates are boilerplates consisting of text and code. They are used in several places in ConSol CM, most importantly to define display names and draft emails.

Concepts, terms and definitions

Concept	Other terms	Definition
template		Generic concept which includes display templates, text templates and document templates.
display template	data representation template	Template which determines the display names of contacts, resources and users.
email template		Template used for emails. This can be a technical template if it is intended to be used in automatic emails only. Otherwise, it must be a text template.
system template		Technical template created automatically during system setup or update
Freemarker		Template engine used for creating templates in ConSol CM.

Purpose and usage

Templates have several purposes in ConSol CM. They are used to define the display name of contacts, resources and users, and to store boilerplates for automatic emails sent by the system.

A ConSol CM standard installation already contains system templates and some example templates which help you to define new templates for your special use cases.

Templates are written in Freemarker (see https://freemarker.apache.org/). Some types of templates can include HTML tags.

This section describes the technical templates which are managed in the Web Admin Suite. You can find information about the templates which are managed in the Web Client in Text templates. The following template lists the available template types:

Type	Description
Email	Used for emails, both manual emails written in the Web Client and automatic emails sent by the workflow. See Text templates for manual emails. Templates for automatic emails are described in Editing email templates.
Contact	Determines the display name of the contacts, see Adding contact and resource templates.
Resource	Determines the display name of the resources, see Adding contact and resource templates.
User	Determines the display name of the users, see Editing system templates.
Password reset	Used for the email which is sent when a user resets his password for the Web Client or CM/Track, see Password reset.
Representation	Used for the emails which are sent to the affected users when there are changes to representations, see Editing system templates.
Assignment	Used for the emails which are sent to the users when they are assigned to cases, see Case assignment.

Available settings for templates

A template has three settings:

• Name: This is the name by which the template is referenced.

• Group: The group indicates the area where the template is used. You can set a group to make your templates more manageable.

  You can either select an existing group from the list of autocomplete suggestions or create a new group by entering the desired group name and clicking the Create option which is displayed instead of the autocomplete suggestions.

• Type: The type determines the usage of the template. Possible values:

  • Contact: Display template for contacts, see Defining contact templates

  • Email: Template for automatic emails, and manual emails written using the Web Admin Suite

  • Generic: Template with any other purpose

  • Resource: Display template for resources, see Defining resource templates

  • User: Display template for users

• Last modified: This is the date when the template was modified for the last time.

Basic tasks

Finding a template

The list of templates is displayed directly after accessing the Templates page of the Web Admin Suite. You can filter the list to locate a template more easily:

• Text search: Perform a free text search in the template name or content.

  Enter a text in the Search field and select In name to search in the templates’ name or In content to search in the source code of the templates.

• Template group: Choose to display only templates of a certain group.

  Select the template group in the All groups drop-down list.

• Modification date: Sort the templates by modification date.

  Select Last modified in the column selector and sort the list of templates by modification date to display recently changed templates first.

Working with templates

You can perform the following actions on templates:

• Create a new template
  Click the New template button above the list of templates. Enter a unique name for the template and select a group. See Available settings for templates for details. Use the drop area to import template content from a file.

  If the new template is similar to an existing template, you can create a copy of the template by clicking the Duplicate icon in this template’s row. You need to provide a unique name for the template, and you can change the template group.

• Edit the template name or group
  Click the Edit icon to change the name or group of a template.

• Edit the source code of a template
  Click the row of a template to open its source code. The source code can be edited directly. The source code panel allows the following actions:

  • Save changes: Save your changes
  • Discard changes: Undo your changes.
  • Import: Replace the template by the content of a file.
  • Export: Save the template to a file.
  • Full screen: Open the template in full screen mode, so that the whole browser window is used for the source code. Click Return to leave the full screen mode.
  • Language: Select the language of the template. You can create a different template for each language configured in ConSol CM. A template always has to be provided at least for the default language.

  See Using the template editor features for details about the capabilities of the template editor.

• Delete a template
  You can delete a template by clicking the Delete icon.

  When deleting a contact or resource template, the customer groups or resource types which reference the template are mentioned in the confirmation dialog. For the rest of the templates, it is not checked if the template which you delete is in use.

Adding contact and resource templates

The display name of contacts and resources in the Web Client needs to be defined using templates. The template determines which data fields are used for the display name.

Data fields are referenced by their field group name and field name:

• Contact template:

  ${MyContactObject.getFieldValue("field_group","field")!}

  MyContactObject needs to be replaced by the contact object (person or company). You can use data fields of the company in the template for the person.

  See Defining contact templates.

• Resource template:

  ${resource.getFieldValue("field_group","field")!}

  See Defining resource templates.

You can create the code with the template generator by clicking the Template generator icon in the editor header and selecting the desired fields.

Do not use line breaks inside the statements which define the display name.

The templates are assigned to the contact objects and resource types in the respective data models.

Advanced tasks

Using the template editor features

The template editor has the following features:

• Syntax highlighting
  The editor uses syntax highlighting for Freemarker.

• Template examples
  Press CTRL + SPACE to insert a template stub or an example of available methods.

• Keyboard shortcuts
  There are keyboard shortcuts for common operations. Examples:

  • Undo: CTRL + Z
  • Find: CTRL + F
  • Find next: CTRL + G
  • Replace: Shift + CTRL + F
  • Replace all: Shift + CTRL + R

• Template generator: generate and insert code for display templates for contacts and resources based on selections made in a modal window

• Text highlighting
  You can double-click a word or mark some text to highlight all its occurrences within the template.

You can see where a template is used by clicking the Usage button. The popup window lists the places where the template is referenced and provides links to jump to the referencing objects.

Using templates in scripts

You can use the following methods to reference templates in scripts, for example to send an automatic email in a workflow activity.

• workflowApi.renderTemplate() for simple templates used from the workflow
• workflowApi.renderMailTemplate() for templates which include images used from the workflow
• templateService.merge() for simple templates
• templateService.mergeAndInlineImages() for templates which include images which should be Base64-encoded

Editing system templates

A default ConSol CM installation comes with several system templates:

• attachment-type-error-mail-template
  Body of the email which is sent to the email administrator (see system property cmas-nimh-extension, mail.on.error) if the attachment type of an incoming or outgoing email is not supported, so that the email cannot be processed.

• engineer description template name
  Renders the user name. You can define another name for the template in system property cmas-core-server, engineer.description.template.name.

  The following example shows how to use the user name, as determined by the template, in scripts:

  engineerService.getDisplayName(engineer, new Locale("de"));

• mail-process-failure-template
  Body of the email which is sent to the administrator when the processing of an incoming email fails. Contains details about the email and the reason for the failure.

• mail-receive-attachment-too-large
  Body of the notification email which is sent when an incoming email could not be processed due to the size of its attachments. The sender of the email receives a notification which shows the size of the attachments which he tried to send and the maximum allowed size.

• mail-receive-too-large
  Body of the notification email which is sent when an incoming email could not be processed due to its size. The sender of the email receives a notification which shows the size of the email which he tried to send and the maximum allowed size.

  Add the parameter From: with the desired email address to use another address than the value of the system property cmweb-server-adapter, mail.from as a from address.

• mail-send-failure-template
  Body of the notification email which is sent when a manual email could not be sent due to problems with the email server.

  Add the parameter ${failedEmailInfos} to include additional information, as the sender, recipient and subject of the email.

• missed-notification
  Body of the email which is sent if the user selected to receive an email for each notification which was sent while he was offline (option One email for each missed notification with its text in the Missed notifications selector in the user profile).

• password-reset-template
  Body of the email which is sent when a user requests a password reset on the login page of the Web Client. The following variable included in the template is configured using system properties:

  • urlWebclient
    Value of the system property cmas-core-server, url.webclient.

• representation_info_email_html
  Configures the text in HTML format which is added to emails which are forwarded to a user due to a representation (see Configuring representations).

• representation_info_email_plain_text
  Configures the text in plain text format which is added to emails which are forwarded to a user due to a representation (see Configuring representations).

• representation-create-email
  Body of the email which is sent when a new representation has been configured (see Configuring representations). The email is sent to both the new representing user and the user who is represented.

  Add the parameter From: with the desired email address to use another address than the value of the system property cmweb-server-adapter, mail.from as a from address.

• representation-delete-email
  Body of the email which is sent when a representation has been removed (see Configuring representations). The email is sent to both the old representing user and the user who was represented.

  Add the parameter From: with the desired email address to use another address than the value of the system property cmweb-server-adapter, mail.from as a from address.

• today-notifications
  Body of the email which is sent if the user selected to receive a summary with the number of unread notifications at the end of the day (option One email per day with the number of missed notifications in the Missed notifications selector in the user profile).

• track-password-reset-template
  Body of the email which is sent to the user who requests a password reset for CM/Track. The following variables included in the template are configured using system properties:

  • expirationDate
    By default, the link expires 24 after the password reset request was made. To change this value, create the system property cmas-core-security, resetCode.expirationPeriod with the desired expiration date.
  • urlTrack
    Value of the system property cmas-core-server, url.track.

• user-profile-info-template
  Defines which user data from the Users page is shown in the user profile of the Web Client.

• workflow-timer-failure-template
  Body of the email, which is sent to the administrator when the processing of a workflow timer fails. Contains details about the affected case and the reason for the failure.

The following variables are available in the notification when a representation is created or deleted. “representing” indicates the user who represents another user and “represented” indicates the user who is represented by another user.

• Last name: ${representing|represented.lastname}
• First name: ${representing|represented.firstname}
• Login: ${representing|represented.name}
• Email: ${representing|represented.email}
• Fax: ${representing|represented.fax}
• Mobile: ${representing|represented.mobile}
• Phone: ${representing|represented.phone}

Editing email templates

There are a number of occasions where emails are sent automatically by ConSol CM. The content of these emails is defined in email templates. The following sections describe the email templates which need to be defined in the Web Admin Suite. You can define more email templates for your specific use cases in the Web Admin Suite or Web Client.

Email templates which should be available for manually sent emails need to be defined in the Web Client.

Case assignment

Users are notified in automatic emails when a case is assigned to them or they are unassigned from a case. There is a template for each event (assign and unassign) which is referenced in the respective queue (see Queues).

By default, the email address of the CM administrator (see system property cmas-core-security, admin.email) is used as From address. You can set the From address explicitly within the template (see following example).

The following example shows a case assignment template:

Code example 17: Content of an assignment template

Password reset

If database authentication is used (see Authentication), the users can reset their passwords in both the Web Client and CM/Track. An email template containing a link to the password reset page needs to be defined for each client.

Web Client

When a user has forgotten his Web Client password, he can request a new password by using the Forgot your password? link on the login page. An email with a link to an URL where the user can set the new password is sent to the user.

A valid email address must be set for the user on the Users page.

The template with the email content has to be called password-reset-template. The following example shows a simple template to reset the Web Client password.

Code example 18: Template to reset the password for the Web Client

The following variable is configured using system properties:

• urlWebclient
  Value of the system property cmas-core-server, url.webclient.

The From address of the email is defined in the system property cmas-core-security, password.reset.mail.from.

CM/Track

When a contact has forgotten his CM/Track password, he can request a new password by using the Forgot your password? link on the login page. An email with a link to an URL where the contact can set the new password is sent to the contact.

A valid email address must be set for the contact in the respective data field in the Web Client.

The template with the email content has to be called track-password-reset-template. It needs to be created manually. The following example shows a simple template to reset the CM/Track password.

Figure 8: Template to reset the password for CM/Track

The following variables are configured using system properties:

• expirationDate
  By default, the link expires 24 after the password reset request was made. To change this value, create the system property cmas-core-security, resetCode.expirationPeriod with the desired expiration date.
• urlTrack
  Value of the system property cmas-core-server, url.track.

Syntax examples

Localizing list values

It is possible to display localized values of enumerated lists in templates by using the localize() method. This method retrieves the localized list value as defined in the Web Admin Suite to display it in the Web Client. Otherwise, the internal list value would be displayed.

The following example shows a template for a resource. The resource field SLA_country is an enumerated list containing countries. The localize() method is used to display the country name in the browser locale.

${localize(resource.getFieldValue("SLA_Fields_basic","SLA_country"))!}

Abbreviating values

It is possible to abbreviate the values retrieved by a template using the abbreviate() method. In this way, long values are shortened, so all fields are displayed even if the first field contains a long value.

The abbreviate() method needs two parameters:

• The value which should be abbreviated.
• The number of characters to be displayed. This is the number of all characters which are displayed, i.e., including the three dots. Thus, for example, to display five letters and three dots, use 8 as a parameter. The minimum value is 4.

The following example shows the template for a company and how the abbreviated company name is displayed in the case list.

${abbreviate(ResellerCompany.getFieldValue("ResellerCompanyData","company_name"),8)!} - ${ResellerCompany.getFieldValue("ResellerCompanyData","company_number")!}

Using links

You can use the methods linkInWebClientTo() and linkInTrackTo() to add links to cases, contacts and resources to a template. The following methods are available:

• Link to a case in the Web Client : ${linkInWebClientTo(ticket)}
• Link to a contact in the Web Client: ${linkInWebClientTo(unit)}
• Link to a resource in the Web Client: ${linkInWebClientTo(resource)}
• Link to a case in CM/Track: ${linkInTrackTo(ticket)}

The following example shows how to use these methods:

Handling missing values

You can use if statements in combination with the ?? operator or the ?has_content operator to check if an object exists or a field has a value.

<#if ResellerCustomer.getFieldValue("ResellerCustomerData","customer_name")?has_content &&
ResellerCustomer.getFieldValue("ResellerCustomerData","firstname")?has_content>
${ResellerCustomer.getFieldValue("ResellerCustomerData","customer_name")!},
${ResellerCustomer.getFieldValue("ResellerCustomerData","firstname")!}
<#else> ${ResellerCustomer.getFieldValue("ResellerCustomerData","customer_name")!}</#if>

Code example 19: Example of a contact template with if statement (has to be written in one line!)

Alternatively, you can specify a default value using the ! operator to avoid exceptions due to missing values. The default value can be empty.

${ResellerCompany.getFieldValue("ResellerCompanyData","company_name")!} - ${ResellerCompany.getFieldValue("ResellerCompanyData","company_number")!}

Code example 20: Example of a contact template with empty default value (has to be written in one line!)

Setting number format patterns

Freemarker allows to set a number format pattern. The following example shows a pattern which displays two decimal places for numbers.

<#setting number_format="0.##"/>${customerModelCompany.getFieldValue("groupName", "numberValueField")!}

Code example 21: Setting a number format, so only two decimal places are displayed