Open topic with navigation

Data Object Group 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 Custom Fields: full flexibility.

The management of the ticket data model and GUI design is explained in section Custom 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 Data Object Group 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 data objects within the customer data model are called Data Object Group Fields. Data Object Group Fields are based on the same principles as ticket data fields (Custom Fields): data fields are managed in groups and the groups, as well as the single fields, can be annotated.

Figure 161: ConSol CM Admin Tool - Definition of Data Object Group Fields

Data Object Groups

Like the Custom Fields which you are already familiar with from previous CM versions, Data Object Group Fields are placed in groups, the Data Object Groups. Each data object within a customer data model can have as many Data Object Groups as required. For example, for a reseller company there can be a Data Object 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 Data Object Group with general data is defined.

Figure 162: ConSol CM Admin Tool - Customer data model with several data object 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 Data Object Group ...

• can be faded in and out in the GUI during the process, but only the whole group, not single fields (= Data Object Group 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 Data Object Group.
• is configured by group annotations.
• is placed in the GUI based on its position in the Data Object Group list (defines, e.g., the order of tabs).

Figure 163: ConSol CM Web Client - Company data organized in tabs (based on Data Object Groups)

Data Object Group Field Definition

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

A Data Object Group Field ...

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

Labels for Data Object Group Fields

In CM versions prior to 6.9.4, the labels for Data Object Group Fields (e.g., name, address) are displayed in the Web Client as watermarks per default. If a distinct label is required, a separate Data Object Group Field of type string with the annotation text-type = label has to be used, as shown in the following figures.

Figure 164: ConSol CM Web Client - Default display of Data Object Group Field labels in versions prior to 6.9.4

Figure 165: ConSol CM Web Client - Labels as distinct Data Object Group 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 Custom Fields (i.e., the data fields for ticket data). Furthermore, tool tips can be added. The display modes of labels for Data Object Group Fields is controlled by annotations. Annotations can be set on Data Object Group level and on Data Object Group 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 Data Object 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 Data Object Group Fields:

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

Figure 166: ConSol CM Admin Tool - Configuration for Reseller Data Object Group, one field configured field-specific

Figure 167: ConSol CM Web Client - View for Reseller Data Object Group, one field (company_number) annotated field-specific (edit mode)

Figure 168: ConSol CM Web Client - View for Reseller Data Object 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 169: Example for Data Object Group 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 Data Object 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 Data Object Groups and Data Object Group Fields

All new Data Object Groups will be rendered with the new default configuration. This means:

• standard labels
• watermarks disabled
• tool tip enabled

Figure 170: ConSol CM Web Client - Default display mode for Data Object Group Fields

Scripting Using Objects from the FlexCDM

In this book we will use the terms customer and customer definition. However, the corresponding scripts use the term data object and 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 Custom Field Group. The expression unit.get("name") was always valid because a Custom Field with a specified name could exist only once, for example "group1.name".

Starting with ConSol CM version 6.9, a data object (Unit) may have one or more Data Object Group 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 Custom Field "name" is unique. If another Custom Field with the same name is added, the code unit.get("name") will no longer work!

Use the following notation to retrieve unit field (Data Object Group 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 14: 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 (data objects: objects at the contact or company level). The improvements concerning units (data objects) 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
  • E-mail
  • Clone
  • Default values
  • Data object action
  • Data object 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 Custom Field type.

ActivityFormFieldsSet

Removed accessors with plain FieldDefinition, use ActivityFormElement instead.

ContentFile

Added size parameter to input stream methods.

ContentResource

Same changes as in ContentFile.

FieldLogEntry

Removed modification accessors.

Ticket

Removed renamed Custom Fields accessors and other changes.

TimerTrigger

Removed setDuedate method.

Unit

Removed renamed Custom Fields accessors.

New (Convenience) Methods

Examples of new methods:

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

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

Code example 17: 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: