Templates for Customer Data

Introduction to Using Templates for the Display of Customer Data

In the ConSol CM Web Client, customer data sets are displayed in a short form, the so called display name of the customer, at various locations. The display name is based on the template for the respective location. In this way, it is possible to use a different display name for each location, for example to adapt to the available screen space.

The configuration of the display name is based on the following principle:

In the following paragraphs, the syntax and coding for templates and all possible template types are explained.

Please see Admin Tool Templates for a more generic description of how to use templates.

The following figure shows an example of a customer template to define the display name in the ticket list.

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

Coding Templates

General Principle

The templates are written using FreeMarker notation. For detailed information, please refer to the FreeMarker web site.

Within the templates, you work with three object types:

The customer templates must be single-row! They must not contain line breaks!

If you need the display name of a customer as determined by a template in scripts, you can use the method getDisplayName() from the class UnitService. The following example shows how to print the customer name as determined by the default template in German to the log files. It can be used for example in a customer action, where the unit object is available.

log.info unitService.getDisplayName(unit, UnitTemplateType.DEFAULT, new Locale("de"));

Examples of Templates

The following example shows a template for a Reseller company which includes company name and number.

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

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

How to Set the Format of Numbers

Freemarker allows to set a number format pattern.

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

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

How to Use Company Data in a Contact Template

In a two-level customer data model, you can also use data of the company in the template of the contact. The following example shows how to display the company name in parenthesis after the name of the contact.

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

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 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 122: ConSol CM Web Client - Abbreviated value in ticket list

Template Types

The following template types can be defined for the different locations where customers are displayed in the Web Client:

Standard (Default)

This template must always be defined. In a two-level customer data model, this has to be done for the company and for the contact level. If it is not, there will be an error in the log file and in the Web Client (-- unknown -- is displayed as name of the customers). The template is used for all locations in the Web Client for which no other templates have been defined and as REST template for CM/Track in case there is no dedicated REST template. The templates which are described in the subsequent sections override the default template for the specific locations.

REST

This template defines the display name of a customer when accessed using the REST API. This includes the display of the customer name in CM/Track. When retrieving a customer data set using the REST API, the display name is included in the mark tag of the output.

Drag-and-drop

This templates defines the display name of a customer when the data set is dragged, e.g., from the Customers section to the Favorites section.

Email

When selecting recipients for an email in a ticket, an autocomplete search is performed and the names of the matching customers are displayed in a drop-down list next to their email addresses. This template defines the name of the customers in this list and the sent email. Therefore, you need to make sure that the template returns an RFC-compliant name for the customer. Otherwise, problems with email processing might occur.

The following example shows an RFC-compliant email template:

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

Figure 123: ConSol CM Web Client - Email template

Please contact the ConSol CM support or your ConSol CM consultant for assistance regarding RFC-compliant email addresses.

Quick Search

This template defines the display name of the customers in the results of the Quick Search. The template is restricted to a single line of output.

Customer Search Result

This template defines the display name of the customers in search results in autocomplete fields. It is used, for example, when selecting a company for a ticket.

Ticket Search Result

On the results page of the Detailed Search, the tickets found by the search are displayed as a list. One column of this list contains the main customer of the ticket. This template defines the display name of the customers in this column.

Ticket Page

This template defines the display name of a customer on the customer page and in the Customers section of tickets. The following figure shows the locations affected by the ticket page template.

Figure 124: ConSol CM Web Client - Locations for ticket page template

In versions prior to 6.11, the first line of customer fields, i.e., fields with position (0,x), was used as display name on the customer page. Since CM version 6.11, the ticket page template is used, so you can determine the display name regardless of the fields’ position.

Ticket List

This template defines the display name of the customers in the ticket list.

The customer name is only displayed in the ticket list if the page customization attribute accordionTicketList.mainCustomerDescriptionVisible is set to true.

Ticket Relation

This template defines the display name of a customer in related tickets in the Relations section of a ticket. Please keep in mind that the customers of related tickets are only displayed in the visibility level extended.

Workspace and Favorites

This template defines the display name of a customer in the Favorites and the Workspace sections.

History

This template defines the display name of a customer in the ticket history. It is used for example in the history entries which are created when the customer of a ticket changes.

Suggestion

This template defines the display name of the customers in suggestions which are displayed in a small pop-up window where a contact can be selected for a ticket.

CM/Phone Customer Details

See section CM/Phone: CTI with ConSol CM.

CM/Phone Customer List

See section CM/Phone: CTI with ConSol CM.