Customer Field Management and GUI Design for Customer Data
Introduction
One feature of ConSol CM versions 6.9 and later is great flexibility as far as customer data model (FlexCDM) 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 Field Administration (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 237: 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 238: 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 239: 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.
In contrast to ticket fields and ticket layout, where you can use three columns for data fields, you can use as many data field columns as you like for the definition of customer fields.
Please keep in mind that in CM versions 6.10.4 and below, the Business Card Feature will be active, i.e., in order to present all customer data aligned as on a business card, all fields of a line are presented left-aligned (i.e., starting with column #0), even if the first field in the line has the position column #2 (or other) according to the position annotation.
Labels for Customer Fields
In CM versions prior to 6.9.4, the labels for customer fields (e.g., name, address) are displayed in the Web Client as watermarks per default. If a distinct label is required, a separate customer field of type string with the annotation text-type = label has to be used, as shown in the following figures.
Figure 240: ConSol CM Web Client - Default display of customer field labels in versions prior to 6.9.4
Figure 241: ConSol CM Web Client - Labels as distinct customer fields in versions prior to 6.9.4
As of CM version 6.9.4, you, as an administrator, can decide whether watermarks or labels (or both) should be used. Labels are now implemented similar to the labels for ticket fields (i.e., the data fields for ticket data). Furthermore, tool tips can be added. The display modes 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. In this way, you can define a group display behavior but can modify 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 242: ConSol CM Admin Tool - Customers, Data Models: Configuration for Reseller customer field group, one field configured field-specific
Figure 243: ConSol CM Web Client - View for Reseller customer field group, one field (company_number) annotated field-specific (edit mode)
Figure 244: ConSol CM Web Client - View for Reseller customer field group, one field (company_number) annotated field-specific (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 245: Example for customer field positions in the grid
Label Mode after an Update from CM Version Prior to 6.9.4 to a Version 6.9.4 and Up
The layout of the customer data model will be preserved during the update! All annotations will be set accordingly and can be modified later.
For all existing customer field groups, the annotation setting layout:show-labels-in-edit = false (which will hide standard labels in edit mode) is applied during the update.
Default Mode for New Customer Field Groups and Customer Fields
All new customer field groups will be rendered with the new default configuration. This means:
- standard labels
- watermarks disabled
- tool tip enabled
Figure 246: ConSol CM Web Client - Default display mode for customer fields
Scripting Using Objects from the FlexCDM
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.
New Scripting Features Since ConSol CM Version 6.9
Up to ConSol CM version 6.8, a Unit could have only one ticket field group. The expression unit.get("name") was always valid because a ticket field with a specified name could exist only once, for example "group1.name".
Starting with ConSol CM version 6.9, a customer (Unit) may have one or more customer fields with the same field name, e.g., "name" can be represented as "group1.name" and "group2.name" . In such cases, the expression Unit.get("name") is not semantically valid and throws an exception.
For backwards compatibility the code unit.get("name") will work as long as the customer field "name" is unique. If another customer field with the same name is added, the code unit.get("name") will no longer work!
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 18: Example to get the name of the company's contact
Extension of the Custom Field Expression Language (CFEL)
Starting with ConSol CM version 6.9, the Custom Field Expression Language (CFEL) has been improved to provide simple access to many objects. This applies to scripting for tickets and other objects as well as objects from the customer data model, i.e., units (customer objects: objects at the contact or company level). The improvements concerning units (customers) are explained here. For a detailed explanation on how to write Java or Groovy code which uses customer data model objects, please refer to the ConSol CM Process Designer Manual.
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
- Clone
- Default values
- Customer action
- Customer condition
- Workflow
Changes in Scripting from ConSol CM Version 6.8 to Version 6.9
In ConSol CM version 6.9, some methods were declared deprecated and have been replaced by new methods. This is only relevant if you have scripts from version 6.8 or older. In this case, the scripts have to be refactored using the new methods.
AbstractField
Removed custom value accessors for each data field type.
|
Removed/changed method |
Replacement |
|---|---|
|
|
|
|
|
|
ActivityFormFieldsSet
Removed accessors with plain FieldDefinition, use ActivityFormElement instead.
|
Removed/changed method |
Replacement |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ContentFile
Added size parameter to input stream methods.
|
Removed/changed method |
Replacement |
|---|---|
|
|
|
|
|
|
ContentResource
Same changes as in ContentFile.
|
Removed/changed method |
Replacement |
|---|---|
|
|
|
|
|
|
FieldLogEntry
Removed modification accessors.
|
Removed/changed method |
Replacement |
|---|---|
|
|
|
|
|
|
Ticket
Removed renamed ticket fields accessors and other changes.
|
Removed/changed method |
Replacement |
|---|---|
|
|
Previously mixing groupName and fieldName parameters worked, now only the order groupName, fieldName is accepted. |
|
|
|
|
|
|
|
|
|
|
|
For workflow usage:
|
TimerTrigger
Removed setDuedate method.
|
Removed/changed method |
Replacement |
|---|---|
|
|
|
Unit
Removed renamed customer fields accessors.
|
Removed/changed method |
Replacement |
|---|---|
|
|
|
|
|
|
|
|
|
New (Convenience) Methods
Examples of new methods:
| Object.Method | Explanation |
|---|---|
|
|
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. |
|
|
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 19: 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 20: 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 21: 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.
New Objects in ConSol CM 6.9 and Up
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! |
|