CM/Resource Pool - Templates for Resource Data
Introduction to Using Templates for the Display of Resource Data
In the ConSol CM Web Client, resource data sets are displayed in a short form, the so called display name of the resource, 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. Templates are defined by resource type.
The configuration of the display name is based on the following principle:
- A template for a specific location in the Web Client is assigned to a resource type in the resource model definition (navigation group Resources, navigation item Data model).
- The referenced template must be stored in the Admin Tool, navigation group System, navigation item Scripts and Templates. The name of a template is user-defined, but it needs to match the referenced template name in the resource type definition.
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 resource template to define the display name on the resource page.
Figure 487: ConSol CM Web Client - Example of a resource template (resource page)
Coding Templates
General Principle
The templates are written in FreeMarker notation. For detailed information, please refer to the FreeMarker web site.
Within the templates, you work with three object types:
- the current resource (referenced as resource)
- the technical name of the resource field group
- the technical names of the resource fields
The resource templates must be single-row! They must not contain line breaks!
If you need the display name of a resource as determined by a template in scripts, you can use the method getDisplayName() from the class ResourceService. The following example shows how to print the resource name as determined by the default template in German to the log files. It can be used for example in a resource action, where the resource object is available.
log.info resourceService.getDisplayName(resource, ResourceTemplateType.DEFAULT, new Locale("de"));
Examples for Templates
The following example shows a template for resources of the resource type PC.
PC: ${resource.getFieldValue("PC_Desktop_Fields_basic","name")!} - ${resource.getFieldValue("PC_Desktop_Fields_basic","modell")!}
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 92: 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 93: 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 94: Setting a number format, so only one decimal place is displayed
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 488: ConSol CM Web Client - Abbreviated value in ticket list
Template Types
The following template types can be defined for the different locations where resources are displayed in the Web Client:
Default
This template must always be defined. If it is not, there will be an error in the Web Client (unknown is displayed as name of the resource). 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.
The template is always used for the display name of the resource on the resource page, the display name when the resource is dragged, and the resource name in the Workspace and Favorites.
Quick Search
This template defines the display name of the resources in the results of the Quick Search.
Search
This template defines the display name of the resources in search results in autocomplete fields or suggestion lists. It is used, for example, when creating a relation to a resource.
REST
This template defines the display name of a resource when accessed using the REST API. When retrieving a resource data set using the REST API, the display name is included in the mark tag of the output.
History
This template defines the display name of the resource in the ticket, customer and resource history. It is used for example in the history entries which are created when a relation to or from a resource was added.