Admin Tool Templates

Introduction to Templates in the Admin Tool

In ConSol CM, several types of templates are used:

• Email templates are stored in one of the following places:
  
  • the Text Template Manager, see section Text Templates.
  • the Templates section of the Admin Tool. Details on that topic are provided in this chapter.
• Document templates are stored in
  • the Document Template Manager (part of CM/Doc), see section CM/Doc
• Data representation templates are stored in
  
  • the navigation item Scripts and Templates of the Admin Tool. They are used for:
    
    • the definition of customer templates, see section Templates for Customer Data
    • the definition of resource templates, see section CM/Resource Pool - Templates for Resource Data
• General templates are stored in
  • the navigation item Scripts and Templates of the Admin Tool. They are explained in this chapter.

In this chapter, the general templates in the navigation item Scripts and Templates of the Admin Tool are explained.

Admin Tool templates are written using FreeMarker notation (see FreeMarker web site) and should only be edited by experienced ConSol CM consultants and administrators. A ConSol CM standard installation already contains system templates and some example templates which might help you, as an administrator, to define new templates for your special use cases.

The Admin Tool Template Editor

To work with templates, open the navigation item Scripts and Templates in the navigation group System and switch to the Template tab.

In the templates list, all templates are listed with:

• Name
  Mandatory. A template is referenced by its name when it is referenced by other objects.
• Group
  Optional. Groups help you temporarily sort the templates in the templates list. This setting does not have any technical implications and will be lost once you reload the data in the Admin Tool.

To open a template in the editor panel, mark it in the list and open it by clicking the Edit button. Each template must have a name, whereas the group name is optional.

If your system works with various languages, you can define each template for each language. Use the drop-down menu Language above the editor panel. The Web Client will display the template for the configured locale of the web browser. If there is no template for this language, the default language will be used. Every template has to be defined for the default language.

Figure 402: ConSol CM Admin Tool - System, Scripts and Templates: Template editor

The Templates screen shows the following items:

• Tabs to switch between scripts and templates (1)
• Language selector (2)
• Editor panel (3). Displays the template which is selected in the list.
• General buttons to add, delete or copy a template and to edit the template name and group (4)
• Buttons referring to the open template (5)
  • Edit the selected template
  • Save the template
  • Cancel (quit without changing the changes)
  • Upload a text file (as template) from the file system
  • Save the template as a file in the file system

Working with Admin Tool Templates

The Admin Tool templates represent a template pool. Each template can be referenced from different modules of the system and is always referenced by its name. In the following paragraphs, all modules where templates can be used are explained. Within a template, the data fields are referenced by group name and field name.

The following example shows how the field company_name within the customer field group ResellerCompanyData is referenced.

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

For a detailed explanation of working with ticket fields, please see section Ticket Fields (Setting Up the Ticket Data Model). Customer fields are explained in section Setting Up the Customer Data Model. Resource fields are explained in section CM/Resource Pool - Setting Up the Basic Resource Model.

Do not use line breaks in template statements!

System Templates

A default ConSol CM installation comes with several system templates. They are used in standard situations like error messages sent to an administrator. Please see the following list for an overview of the system templates:

• attachment-type-error-mail-template
  An email with this template is sent to the email administrator (email address given in system property cmas-nimh-extension, mail.on.error) when the attachment type of an incoming or outgoing email is not supported and thus the email cannot be processed.

• engineer description template name
  Template used to render the engineer label, e.g., ticket owner. The template name engineer description template name is the default value. You can define another name for the template which should be used to render engineer names by using the CM system property cmas-core-server, engineer.description.template.name.

  If you need the engineer name as determined by the template in scripts, you can use the method getDisplayName() from the class EngineerService. The following example shows how to print the engineer name in German to the log files.

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

• engineer profile description template name
  Template used to render the label on a header of the page, next to the logout button.
• mail-receive-too-large
  Template for 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 the template to use another address than the value of the system property cmweb-server-adapter, mail.from as a from address.

• mail-send-failure-template
  Template for the notification email which is sent when a manual email could not be sent due to problems with the email server.
• password-reset-template
  Template for the body of the email which is sent when a user requests a password reset (on login page).
• representation_info_email_html
  All emails sent by CM to the represented engineer are also sent to the representing engineer (see Global Permissions: Representation Permissions in section Roles). The template is used to configure the text which is added to the forwarded email.
• representation_info_email_plain_text
  Same as above, as plain text.

• representation-create-email
  The template for the email which is sent when a new representation configuration has been set up, e.g., when an engineer has selected a colleague of his as representing engineer, because he will be on vacation for some time. The email is sent to both, the new representing engineer and the engineer who is represented. All engineer-specific properties are available as variables in the template, for the representing engineer, e.g.:

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

  The variables for the engineer who is represented are built according to the same pattern, e.g., Last name: ${represented.name}.

• representation-delete-email
  The template for the email which is sent when a representation configuration has been stopped, e.g., when an engineer has deleted the representation configuration for a colleague of his as representing engineer, because he has returned from vacation. The email is sent to both, the old representing engineer and the engineer who was represented. For variables which are available, please see the previous paragraph.
  

Templates to Define the Display of Customer and Resource Data in the Web Client

The representation of customer data and resource data, the so called display name, used in the different sections of the Web Client can be defined using templates. The definition has to be made for each customer object and resource type. The template can use the available customer or resource fields for the respective object.

The following example shows the use of a template to format the contact name in the ticket list, so that the first name and last name of the contact are displayed.

Figure 403: ConSol CM Web Client - Example of a customer template (ticket list)

The following template is used:

${ResellerCustomer.getFieldValue("ResellerCustomerData","forename")!} ${ResellerCustomer.getFieldValue("ResellerCustomerData","customer_name")!}

Code example 79: Customer template

Please see Templates for Customer Data and CM/Resource Pool - Templates for Resource Data for detailed information about the available template types and the assignment of the templates.

Localizing Enum Values in Templates

It is possible to display localized enum values in templates by using the localize() method. This method retrieves the localized enum value as defined in the Admin Tool to display it in the Web Client. Otherwise, the technical enum value would be displayed.

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

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

Abbreviating Values in Templates

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. Please note that 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 ticket list.

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

Figure 404: ConSol CM Web Client - Abbreviated value in ticket list

Using Links

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

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

The following example shows how to use these methods:

Handling Missing Values in Templates

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 for the given customer or resource.

<#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 80: Example of a customer 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 81: Example of a customer template with empty default value (has to be written in one line!)

Setting Number Format Patterns in Templates

Freemarker allows to set a number format pattern.

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

Code example 82: Setting a number format, so only one decimal place is displayed

Ticket Assignment Templates

Engineers are notified in automatic emails when a ticket is assigned to them or they are unassigned from a ticket. The templates used for these emails are called ticket assignment templates.

These templates are defined per queue in the Queues. There are templates for the use cases assign and remove.

• The assign template (Assign) is used as text template for an automatic email which is sent by the system to the (new) engineer when a ticket is assigned to the engineer.
• The remove template (Unassign) is used as text template for an automatic email which is sent by the system to the (old) engineer when a ticket has been taken from the engineer.

You have to write and save the templates in the Template section first. Then they will be available in the drop-down menu in the Ticket assignment templates section of the queue details (see section Queues). You can define a name of your choice - we recommend using a name which describes the use of the template.

As default From address, the email address of the CM administrator (CM system property admin.email) is used. You can also set the from address explicitly within the template (see following example).

The following example shows a ticket assignment template as defined in the Templates section.

Code example 83: Content of an assignment template

Password Reset Templates

When users forgot their passwords, they can request a new password using ConSol CM standard functionality. The user might be an engineer who works with the Web Client or a customer who has a login to CM/Track. For both cases, the administrator has to configure ConSol CM in a way that an email can be sent to the user who needs a new password. This email is based on a template which is stored in the Admin Tool, in the Template section. The email contains a hyperlink to a page where the password reset can be performed.

Password Reset Template for Engineers in the Web Client

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

Please note that this can only work if a valid email account is available for this engineer and if the respective value has been entered as email address for the engineer in the engineer data!

The email which is sent to the engineer is based on the template password-reset-template. This template name is mandatory, required for the password reset to work. The template could look like the following example:

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

The From address of the email which is sent to the engineer is defined by the CM system property cmas-core-security, password.reset.mail.from.

Figure 405: ConSol CM Web Client - Password reset by an engineer

Please note that the password reset in the Web Client is only possible if the standard mode is used. It is not possible if LDAP or Kerberos authentication is in operation. See section Authentication Methods in ConSol CM for an explanation of all possible authentication modes.

Password Reset Template for Customers Using CM/Track

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

Please note that this can only work if a valid email account is available for this customer and if the respective value has been entered as email address for the customer in the respective customer field.

The email which is sent to the customer is based on the template track-password-reset-template. This template name is mandatory, required for the password reset to work. The template has to be created/added manually, it will not be present in the system by default.

The template should be formatted like the following example (you can add any text you would like to send to your customers, but please note the resetCode variable and the URL!):

Figure 406: 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.

Figure 407: CM/Track - Password reset by a customer

Please note that the password reset in CM/Track is only possible if the DATABASE mode is used. It is not possible if LDAP authentication is in operation. See section Authentication Methods for Customers in CM/Track for an explanation of all possible authentication modes.

Custom-Defined Templates

You can define any template that is required and store it in the Templates tab. The API methods renderTemplate() and mergeAndInlineImages() can be used to reference a template when used in automatic emails which are sent in a workflow activity. However, most email templates should be managed using the Text Template Manager (see section Text Templates). There are only very few use cases which might require that email templates, or parts of email templates, have to be stored in the Templates tab of the Admin Tool.