Customer Field Management and GUI Design for Customer Data

Introduction

One feature of ConSol CM is the great flexibility as far as customer data model and GUI design are concerned. You, as an administrator, can define any data field which is required and place it in the user interface wherever it is suitable. The basic principle is now the same as the one you know for ticket fields: full flexibility.

The management of the ticket data model and GUI design is explained in section Ticket Fields (Setting Up the Ticket Data Model). The management of objects within the customer data model is explained in section Setting Up the Customer Data Model. Please refer to those sections for a detailed explanation. In this chapter, we assume that you have a working knowledge of those topics.

Defining Customer Fields for Customer Data Using the Admin Tool

Admin Tool GUI

The data field definition for customer data is part of the definition of the entire customer data model, see section Setting Up the Customer Data Model. The data model is defined on the navigation item Data Models in the navigation group Customers, in the Admin Tool.

Data fields for customer objects within the customer data model are called customer fields. Customer fields are based on the same principles as ticket data fields (ticket fields): data fields are managed in groups and the groups, as well as the single fields, can be annotated.

You reach this screen by opening the navigation item Data Models in the navigation group Customers.

Figure 111: ConSol CM Admin Tool - Customers, Data Models: Definition of customer fields

The Data Models screen consists of six sections:

Customer data models (1)
Annotations for the selected customer field group (2)
Labels for the selected customer field group (3), i.e., the localized values for the name of the customer field group
Customer fields of the selected customer field group (4)
Annotations for the selected customer field (5)
Labels for the selected customer field (6), i.e., the localized values for the name of the customer field

Customer Field Groups

Like the ticket fields which you are already familiar with from previous CM versions, customer fields are placed in groups, the customer field groups. Each customer object within a customer data model can have as many customer field groups as required. For example, for a reseller company there can be a customer field group for the general data, one for the contract data, and one for the persons who are responsible for this reseller. For contacts within the reseller data model, one customer field group with general data is defined.

Figure 112: ConSol CM Admin Tool - Customers, Data Models: Customer data model with several customer field groups

The organization of data fields in groups has several implications. Please keep them in mind to make sure your data model design meets the users' needs.

A customer field group ...

can be faded in and out in the GUI during the process, but only the whole group, not single fields (= customer fields).
can be displayed as a tab or in the customer data section. The title (and mouse-over) of the tab is the (localized) name of the customer field group. For details about localization of customer field groups, please refer to section Localization of Data Fields.
is configured by group annotations.
is placed in the GUI based on its position in the customer field group list (defines, e.g., the order of tabs).

Figure 113: ConSol CM Web Client - Company data organized in tabs (based on customer field groups)

Customer Field Definition

The definition of customer fields (i.e., data fields like name, address, or phone number) is based on the proven concepts which have been used for ticket fields since the first CM6 version.

A customer field ...

is defined by a data type.
is configured using field annotations (e.g., position or field-indexed), as described in Annotations.

Types of Data Fields

The following data types are available for ticket fields, customer fields and resource fields.

autocomplete
A data field which contains a text autocomplete field. This is a dynamic list which is based on a script of type Text Autocomplete. A detailed explanation of text autocomplete fields is given in section Scripts of Type Text Autocomplete.
boolean
Values: true/false. Depending on the annotation boolean-type, the value is displayed as checkbox, radio buttons, or drop-down list.
If a boolean field has not been touched, its value is NULL. If it is checked, its value is true, and if it is unchecked again, its value is false.
date
Format and accuracy can be set by annotations.
enum
For sorted lists. The engineer can choose one of the enum values in the Web Client. Enums and values have to be created previously within the Managing Sorted Lists: Enums. Select the desired Enum type and Enum group in the fields below.
list
A data field of this data type is the first step to creating a list (one column) or a table (multiple columns) of input fields in the Web Client.
- For a table the next step will be to create another field of type struct (see below) to contain the input of the individual list fields (which will become the columns of the table). So, if you want to create a table you have to define a field of the type struct first (see below) before you can add the fields for the table columns.
- For a simple list, the next step will be to create fields which belong to the list. No struct is required.
For all fields belonging to a list or table you have to set the dependencies in the field Belongs to (see below). For example, a table field (which is a regular data field) always belongs to a struct, a struct always belongs to a list.
struct
A data field of this type defines a data structure (line of a table) which groups one or multiple fields. It is the second step to building a table after you have created a field of the type list. Add the fields for the columns of the table in the next step. The dependencies have to be set for each field in the Belongs to field (see below), i.e., a struct always belongs to a list.
Figure 114: Scheme: List of structs
Technically spoken, the list is an array which contains a map (= key:value pairs) in each field.
Figure 115: List of structs, technical principle
number
For integer values.
fixed point number
For numbers with a fractional part, e.g., currencies. You have to enter the total number of digits (Precision) and the number of digits that fall to the right of the decimal point (Scale) in the respective fields below.
string
For up to 4000 alphanumeric characters.
Restriction when using an Oracle database: at most 4000 bytes can be saved in UTF encoding. Starting with Oracle12c.
long string
For large objects.
For long strings the limit depends on the database system used for ConSol CM: MS SQL Server: 2 GByte; MySQL: 4 GByte; Oracle: 16 - 64 GByte (depending on page size of tablespace).
short string
For up to 255 alphanumeric characters.
For string fields, you can use specific annotations to fine-tune the field definition. For example, a string field can be defined to contain a URL which will automatically be displayed as hyperlink or can be the hook for an autocomplete list. Please read the following section.
contact data reference
Special data type used internally for referencing the contacts associated with a ticket. This data type is not displayed but only used internally in the CM system.
MLA field
This data type is used for fields that contain hierarchical lists with a tree structure called MLA (Multi Level Attributes). The name of the field is the name of the new MLA that has to be defined within the MLAs. The group of the field has to be referenced when the MLA is created.

The data type you choose on creating a data field cannot be changed afterwards!

Using Annotations to Fine-Tune Data Fields

String fields are widely used for customer, ticket, and resource data and strings can be used to contain various content, for example, a text box with a comment, a simple input field with only 20 characters, a URL or a password. The fine-tuning of string fields is implemented using specific annotations which are all listed on the Annotations page. However, since work with these annotations is an every-day task of CM administrators, the most important and most commonly used annotations will be explained here as well.

How can I ...

... insert a text box instead of a single line?

Value for annotation text-type: textarea

The size of the text box can be adjusted, displayed as standard text box depending on web browser. Use the field-size annotation in case a specific size of the text box is required.

... hide the input of the fields for passwords?

Value for annotation text-type: password

Only dots will be displayed. This annotation does not define the field to contain a password! It only defines the display mode! Use the password annotation to define a string field to contain the CM/Track password.

... display a hyperlink, display the name instead of the link?

Value for annotation text-type: url

Input will be displayed as a hyperlink in view mode. String has to match a specific URL pattern:

"^((?:mailto\:|(?:(?:ht|f)tps?)\://)1\S+)(?: (?:\| )?(.*))?$"

First part of the string is the link (url), second part is the name which should be displayed.

Example: "http://consol.de ConSol"

... display a file link?

Value for annotation text-type: file-url

Input will be displayed as a link to a file on the file system. The web browser has to allow/support those links!

Example: Enabling file:// URLs in a Firefox browser

Add the following lines to either the configuration file prefs.js or to user.js in the user profile. On a Windows system usually in a folder like C:\Users\<USERNAME>\AppData\Roaming\Mozilla\Firefox\Profiles\uvubg4fj.default

user_pref("capability.policy.localfilelinks.checkloaduri.enabled", "allAccess");
user_pref("capability.policy.localfilelinks.sites", "http://cm-server.domain.com:8080");
user_pref("capability.policy.policynames", "localfilelinks");

Alternatively a Firefox browser add-on like Local Filesystem Links can be installed for better access to the referenced files and folders.

The link will also be displayed as tooltip.

The URL is correctly formed if the following conditions are met:

It starts with file: followed by regular slashes:

three slashes "///" for files on the same computer as the browser (alternatively "//localhost/") or
two slashes followed by the server name followed by another slash for files on file servers accessible from the computer running the browser.

These are followed by the full path to the file ending with the file name.
The path on Microsoft Windows systems is also written with forward slashes instead of backslashes.
The drive letter of a local path on Microsoft Windows systems is noted as usual, for example C:.
Paths with spaces and special characters like "{, }, ^, #, ?" need to be percent encoded ("%20" for a space for example) for Microsoft Windows systems.

Example URLs:

file://file-server/path/to/my/file.ext
file:///linux/local/file.pdf
file:///C:/Users/myuser/localfile.doc

See also the explanation about file-url in the section text-type

... define a label?

Value for annotation text-type: label

This will be a read-only field which is displayed in gray, use the label-group annotation to link label and input fields which belong together. Please take a look at the annotations for labels (show-label-in-edit, show-label-in-view) before implementing special label fields!

... define a field for the valid email addresses?

Value for annotation email: true

The field may only contain valid email addresses. Input will be validated according to standard email format <name>@<domain>.

... define a scripted autocomplete list?

Value for the annotation text-type = autocomplete

Optional: value for the annotation autocomplete-script = <name of the respective script>

A scripted autocomplete list is used to provide a drop-down menu which is filled dynamically using the input the engineer has provided so far. For example, when the user types "Mil", the possible values "Miller", "Milberg", and "Milhouse" are displayed as list and the engineer can select the one required for the field. You know this behavior from other autocomplete fields, e.g., the search for engineers for a ticket or the search for customers while creating a ticket. However, in these cases, CM generates the list automatically. The behavior cannot be influenced or customized. Scripted autocomplete lists, on the contrary, can be implemented by the CM administrator. The values are based on a result set which is dynamically created. The result set can contain strings, engineers, customers (Units), and resources.

A detailed description of scripted autocomplete lists is provided in section Scripts of Type Text Autocomplete.

... define a field for the CM/Track login?

Value for annotation username: true

Will be used for authentication against CM/Track server. Only for customer fields in a contact object.

... define a field for the CM/Track password?

Value for annotation password: true

Will be used for authentication against CM/Track server (in DATABASE mode). Only for customer fields in a contact object.

... define a field containing personal data?

Value for annotation personal-data: true

This annotation can be assigned to ticket and contact fields. Contact fields with this annotation will be deleted when a contact is anonymized. Ticket fields with this annotation will be deleted when the main customer of the ticket is anonymized. See Example 8: Removing Customer Data for information about how to anonymize a contact.

When defining a field to contain personal data, please take into account that the deletion of the field during the anonymization process is treated as a regular update. Therefore, business event triggers reacting on changes to ticket fields fire, and the contact update action script is executed.

This might lead to unwanted side-effects.

... define a rich text field?

Create a field of the type long string.

Value for the annotation string-content-type: html-inline (field content is directly displayed on the GUI in view mode) or html-link (field content is displayed in a pop-up window after clicking the Show content link in view mode)

A rich text field can contain images and formatted text. In the edit mode, it features a basic editor.

... define a tooltip for a data field?

Value of the annotation show-tooltip = true

When creating or editing a data field, you can enter a text in the Description field. This text is used as a tooltip in the Web Client. You can enter a localized description using the globe icon. For details, please refer to section Localization of Objects in General, Type 1.

This does not apply to date fields and fields containing phone numbers and URLs, as they have special tooltips.

... optimize the data field layout?

Use three columns to display the data fields.

Display data fields which most likely have a value on the left in order to avoid gaps.

Add the annotations position = 0;0 and colspan = 3 to all tables. Remove the colspan annotations from other types of data fields.

Show the labels for all data fields (annotation show-label-in-view should be true).

Labels for Customer Fields

You can decide whether watermarks or labels (or both) should be used. Labels are implemented similar to the labels for ticket fields. Furthermore, tooltips can be added. The display mode of labels for customer fields is controlled by annotations. Annotations can be set on customer field group level and on customer field level. The field annotations overwrite the group annotations.

If no annotations are set, the customer field groups are rendered with the default configuration. This means:

standard labels
watermarks disabled
tooltips enabled

Figure 116: ConSol CM Web Client - Default display mode for customer fields

You can set annotations to modify the behavior of a field group or one or more single fields, as demonstrated in the example below.

Annotations for customer field groups:

layout:show-labels-in-view (true if not set)
layout:show-labels-in-edit (true if not set)
layout:show-watermarks (false if not set)
layout:show-tooltips (true if not set)

Annotations for customer fields:

layout:show-label-in-view
layout:show-label-in-edit
layout:show-watermark
layout:show-tooltip

Figure 117: ConSol CM Admin Tool - Customers, Data Models: Configuration for Reseller customer field group, one field with special configuration

Figure 118: ConSol CM Web Client - View for Reseller customer field group, one field (company_number) annotated field-specific (edit mode)

Figure 119: ConSol CM Web Client - View for Reseller customer field group, one field (company_number) with special configuration (Example: No influence on view mode)

The labels are inserted automatically, so in the end there might be, at most, six columns. In the following example, two columns are used.

Figure 120: Example for customer field positions in the grid

Scripting Using Customer Objects

In this book we will use the terms customer and customer definition. In previous versions of ConSol CM, the term data object was used to refer to customers. However, the names of the corresponding Java classes are Unit and UnitDefinition. All other Java classes which deal with customer objects are also still named Unit... Please keep that in mind if you work as both a ConSol CM administrator and programmer. Please refer to the ConSol CM Java API Doc for details.

Use the following notation to retrieve unit field (customer field) data:

For one field:
unit.get("group1:name")
For numerous fields:
unit.get("group1:field1.group2:field2")

unit.get("contactFields:companyReference.companyFields:name")

Code example 2: Example to get the name of the company's contact

You can access the customer data model objects from different scripts:

Workflow:
- Scripts in workflow activities
- Scripts in workflow conditions
Admin Tool (AT) scripts of type:
- Dependent enum
- Email
- Clone
- Default values
- Customer action
- Customer condition
- Workflow

Convenience Methods

Examples of convenience methods:

Object.Method	Explanation
def contacts = unit.get("contacts()") List contacts = company.getContacts()	Using CFEL ("contacts()") a list of all contacts is retrieved for the company (unit).
Unit company = mainContact.getCompany()	For a contact, the company can be retrieved easily.
newContact.set("company()", newCompany)	For a (new) contact, the company is assigned the CFEL expression "company()", provides easy access to the company object.
List tickets = company.get("tickets()")	For a company, all tickets are retrieved.
Ticket ticket = getTicket(); Unit mainContact = ticket.getMainContact() List tickets = mainContact.get("tickets()")	For a contact, all tickets are retrieved.
Integer count = contact.get("company().contacts()[0].tickets()[count]");	A chain of expressions is used to get the number of tickets for a specific contact.

TicketCriteria ticketCriteria = new TicketCriteria();

Unit patternContact = new Unit("contact", customerGroup);

mdcmCriteriaBuilder.setReferencedContactCriteria(ticketCriteria, patternContact);

Code example 3: Example 1: Search for the tickets of a contact or of a company

TicketCriteria ticketCriteria = new TicketCriteria();

Unit contactPattern = new Unit("contact", customerGroup);

mdcmCriteriaBuilder.setReferencedContactCriteria(ticketCriteria, contactPattern);

Unit companyPattern = new Unit("company", customerGroup);

companyPattern.setFieldValue("name", „ConSol");

mdcmCriteriaBuilder.setReferencedCompanyCriteria(contactPattern, companyPattern);

Code example 4: Search for the tickets of the contact who is member of a certain company

UnitCriteria unitCriteria = new UnitCriteria();

Unit companyPattern = new Unit("company", customerGroup);

mdcmCriteriaBuilder.setReferencedCompanyCriteria(unitCriteria, companyPattern);

Code example 5: Search for contacts of a certain company

For detailed information about the methods, including input parameters and output data type (method signatures), please refer to the ConSol CM Java API Doc.

Important Objects

The objects which are available in the script obviously depend on the script's context. The following examples demonstrate some of the possible use cases:

Startig point	Script	Objects	Example
Company page	customer action script	unit, represents the company	def contacts = unit.get("contacts()")
Contact page	customer action script	unit, represents the contact	List tickets = unit.get("tickets()")
Workflow activity	workflow action or condition script	ticket	def id = ticket.getId()
Workflow activity with script in AT	workflow action or condition script	ticket not present implicitly!	import com.consol.cmas.common.model.ticket.Ticket def id = ticket.getId()

Using Scripted Field Visualization for Customer Fields

Using scripted field visualization, you can enhance the display of data in customer fields. Please see section Scripts of Type Field Visualization for details.