Data fields

Introduction to data fields in ConSol CM

Data fields are used to store the information needed for the business process in the objects. They are part of the data model for cases, contacts and resources. Every data field belongs to a field group, which is assigned to one or several data models. These are queues for cases, contact models for contacts and resource models for resources. Several data types are available for data fields, depending on their purpose and the expected data, see Types of data fields.

Concepts, terms and definitions

Concept	Other terms	Definition
case field	ticket field, custom field	Date field of a case
case field group	ticket field group, custom field group	Set of date fields for cases
queue	process	Instance of the business process; links the used workflow to the stakeholders
contact field	unit field	Date field of a person or company
contact field group	unit field group	Set of date fields for persons or companies
resource field		Date field of a resource
resource field group		Set of date fields for resource types
setting	annotation	Advanced settings for date fields or field groups

Purpose and usage

The field groups are listed in the main table. After selecting a field group, the details panel with four tabs is shown on the right:

• Fields: Shows the fields which belong to the group.

• Group data: Shows the basic settings for the field group, see Basic settings for data field groups.

• Settings: Shows the advanced settings for the field group, see Defining advanced settings.

• Field positioning: Allows the define the position of the fields within the field group and the number of columns or rows which are occupied by each field, see Defining the layout.

After selecting a field from the field group, two tabs are shown on its right:

• Field data: Shows the basic settings for the field, see Basic settings for data fields.

• Settings: Shows the advanced settings for the field, see Defining advanced settings.

• Usage: Shows the items which reference the field and allows to jump to the respective places.

  • Usage in runtime data (cases, contacts or resources in the Web Client)

  • References in forms (activity forms and action forms)

  • References in scripts

  • References in address autocomplete

  • Child fields

Data field groups can be hidden and shown during the process so that only fields which are relevant for the current process step are displayed in the Web Client. A common use case for this is hiding a case field group until it is filled out in an activity form, see Hiding fields until they are filled in a form.

The display of the data fields depends on the field type. In addition, a huge variety of customizations is possible. Defining the layout describes the steps which are required for most systems. See Defining advanced settings for further customizations.

Data fields are managed in the same way for cases, contacts and resources. The differences between the three object types are listed in the below sections.

Specifics for cases

Cases have some default fields which are always present:

• Subject: Mandatory field used as a headline for the case.

• Queue: Field which indicates the current queue of the case. Read-only unless the user has specific permissions, see Permissions for cases.

• Scope: Read-only field which indicates the current scope of the case.

• Assignee: Currently assigned user who is taking care of the case.

• Creation date: Read-only field which shows when the case was created.

The page where the data fields for cases are managed is called Case fields. It is located in the Cases menu. There is a filter by queue which shows the field groups assigned to a certain queue.

The order of display of case field groups in the cases depends on their order on the Case fields page.

Specifics for contacts

The page where the data fields for contacts are managed is called Contact fields. It is located in the Contacts menu. There is a filter by data model which shows the field groups used in a certain contact model.

The order of display of contact field groups depends on their order in the contact model.

Specifics for resources

The page where the data fields for resources are managed is called Resource fields. It is located in the Resources menu. There is a filter by resource type which shows the field groups used in a certain resource type.

The order of display of resource field groups depends on their order in the resource model.

Basic settings for data field groups

The following basic settings are available for data field groups:

• Internal name: Technical name used to reference the data field group in scripts.

  The internal name cannot be changed once a field of the group is filled out in an actual object.

• Localized name: Display name of the field group in the configured languages. If the field group is shown in the Details section, the localized name is used in the tab of the field group (tab mode), or as a header (pill mode).

• Automatically assigned to all queues: Only for cases. Select this checkbox if the field group should be assigned to all queues automatically. This applies to both existing queues and newly created queues.

• Assigned to queues: Only for cases. Select the queues to which the field group should be assigned.

• Assigned to contact objects: Only for contacts. Select the contact objects to which the field group should be assigned. The group is added at the end. You can click the chip icon to open the contact object and change the order of the groups in the Field groups section.

• Assigned to resource types: Only for resources. Select the resource type to which the field group should be assigned. The group is added at the end. You can click the chip icon to open the resource type and change the order of the groups in the Field groups tab.

• Scripts: Assign dependent enum scripts which should be executed to define hierarchical lists, where the value selected in the first list determines the available values in the second list, and so on, see Scripts of type Dependent enum.

Basic settings for data fields

The following basic settings are available for data fields:

• Internal name: Technical name used to reference the data field in scripts.

  The internal name cannot be changed once the field is filled out in an actual object.

• Type: Data type of the field. Depending on the type, some additional settings might be shown, see Types of data fields.

  The data type cannot be changed after creating the field.

• Parent field: Select the List or Columns field which is the parent of the field.

• Localized name: Display name of the field in the configured languages.

• Localized description: Tooltip of the field in the configured languages.

Types of data fields

A data field always has a field type, which is determined when you create the field and cannot be changed afterwards. Some field types have additional settings.

The following field types exist:

• Text: Text field for up to 4000 alphanumeric characters.

  On Oracle databases, at most 4000 bytes can be saved in UTF encoding.

• Text (short): Text field for up to 255 alphanumeric characters.

• Text (long): Text field for special uses, e.g. rich text.

  The size limit depends on the database: MS SQL Server: 2GB; MySQL: 4GB; Oracle: 16 - 64 GB (depending on page size of tablespace).

• Integer number: Field for a number without fractional part.

• Fixed point number: Field for a number with fractional part. You must define the number of decimals and the number of digits.

  Up to 8 digits after the decimal point and 30 digits before the decimal point are supported, so the maximum total number of digits is 38.

• Boolean: Field which can have the values true or false. It can displayed as a checkbox, radio buttons or list, see Boolean display in the settings.

  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: Field holding a date or time. The accuracy and format are determined in the settings.

• Enumerated list: List where the user can select a value. You can either choose an existing list in the List field, or create a new one by typing the desired name in the field and clicking the create option. See Enumerated lists for further details about lists.
  

• Hierarchical list: Tree structure where the user can select a value. When creating a new field of this type, a new hierarchical list is created on the Hierarchical lists page automatically. It must be configured there.

• Autocomplete: Dynamic list with autocomplete feature based on a script. You must select a script of the type Text autocomplete in the Script field and select the object (case, contact, resource, user or text) in the Type field. See Scripts of the type Text autocomplete.

• List: Container for creating extendable lists or tables. For a list, you need to create a field and select the list in Parent field. For a table, you need to create a field of type Columns and select the list in Parent field. Afterwards, you need to create one or more fields and select the columns in Parent field. Each data field will be a table column.

  The user can add as many rows as needed in the Web Client and CM/Track.

• Columns: Container for defining a table row. The field must belong to a list field (Parent field setting). The data fields which form the row must have the Columns field selected in Parent field.

• Contact reference: Field used internally for referencing the contacts associated with a case. This field is not displayed.

Basic tasks

Locating a field

You can search for a field by entering its internal or localized name in a search field. If you use the search fields above the groups table, only the groups which contain a matching field are displayed in the table. If you already know which group a field belongs to, you can select the group and perform the search using the search field in the Fields tab.

Adding fields to the data model

Proceed as follows to add new fields to a data model:

1. Define autocomplete scripts, if required for the fields.

2. Add a new field group on the Case fields, Contact fields or Resource fields page by clicking the New field group button.

   • Enter the name and provide the basic settings in the Group data tab.

   • Optionally, you can already make advanced settings in the Settings tab.

   • Click the Create field group button to save the new group.

3. Select the field group and create the desired fields.

   • Click the New field button.

   • Enter a name and description for the field and choose a field type in the Field data tab.

   • Optionally, you can already make advanced settings in the Settings tab.

   • Click the Create field button to save the new field.

4. Define the layout of the field group in the Field positioning tab of the group, see Defining the layout.

5. Assign the field group to the data model.

   • For cases: This can be done either in the Group data tab of the field group (select the desired queues under Assigned to queues) or on the Queues page.

   • For contacts: This can be done either in the Group data tab of the field group (select the desired contact objects under Assigned to contact objects) or on the Contact models page.

   • For resources: This can be done either in the Group data tab of the field group (select the desired resource type under Assigned to resource types) or on the Resource models page.

You can directly check the outcome after reloading the page in the Web Client.

Removing fields from the data model

Field groups which are in use, i.e. they are assigned to a data model and some of their fields are filled out in actual cases, contacts or resources, cannot be deleted. Nevertheless, you can hide a field group from the Web Client and CM/Track by clicking the Deactivate icon in the respective row. The same applies to single fields: they can only be deleted if they do not contain values in any object. Otherwise, you must deactivate them instead.

Alternatively, you can unassign the field group from the queue, contact object or resource type where it is used. This hides the field group from the Web Client and CM/Track.

On development systems (see cmas-core-shared, system.flavour), you can remove data fields and data field groups which are in use. Click Force remove all to delete a field or a field group from the system. Child fields and references in data models, forms, address autocomplete and runtime data are removed as well.

Defining the layout

Data field groups can be displayed either in the header of the object or in the Details section. By default, field groups are shown in the header section. This can be changed in the setting Display in details section. By default, each group shown in the Details section has its own tab. You can change to the pill mode, i.e. display the groups underneath each other, using the page customization attribute customFieldGroupsDisplayType in customFieldGroupsSection.

The order of the field groups is determined by their position in the table. You can sort the groups with drag-and-drop or by using the Move up and Move down icons.

The position of the data fields within the field group is configured in the Field positioning tab. The layout is based on a grid, where the number of columns is determined by the system property cmweb-server-adapter, defaultNumberOfCustomFieldsColumns. You can drag-and-drop fields to the desired position. If a position should remain empty, you need to click the Insert empty position button and drag the empty position to the desired place. You can increase the width or height of a field by clicking the arrow buttons on the right side of the field.

For tables, it is recommended to use the full width, i.e. make the table span all three columns.

You can only use the Field positioning tab for standard layouts, i.e. layouts where each position is assigned to one data field only and there are no empty rows. If your layout contains special cases, e.g. two fields with the same position, one shown in edit mode and one shown in view mode, you need to set the position in the Settings tab.

The layout can be further customized by using specific settings, e.g. to display labels, tooltips and watermarks for fields, see Defining advanced settings.

Advanced tasks

Defining advanced settings

The advanced settings are made in the Settings tabs. The available settings depend on the object and field type. If a setting can be made both for the field group and for single fields, the setting applied to a single field overrides the setting of the field group.

By default, the checkbox Display configured settings only is selected, so that only the settings which have been changed for the field group or field are shown. You can unselect the checkbox to display all settings, grouped by area of usage.

To locate a setting, you can enter its name or its technical name (previously called annotation) in the search field.

The settings are grouped by area of usage, e.g. layout, field display, case list, history, search, validation, features, CM/Track, CM/Phone and DWH.

You can find a list of all available settings here:

• Group settings: List of settings for field groups

• Field settings: List of settings for fields

Only the settings which are relevant for the type of object and the selected field type are displayed. If a setting is only relevant if another setting is present, it is hidden until this setting is made.

Frequently used settings

The following settings are frequently used:

• Text display: Allows to display a text field as a text box, password, hyperlink, label or title.

• Rich text display in view mode: Allows to create a rich text field with an editor.

• Field value omitted from history: Prevents that a history is created for the field. Useful for fields which hold internal variables to avoid filling the database with unneeded history entries.

  This setting is set to true by default when creating a new field. Please remove it if the field history is needed.

• Required: Makes entering a value mandatory for saving.

Using field visualizations

You can display any content in a data field by using field visualizations. Create a script of the type Field visualization and select it in the setting Field visualization script, see Scripts of the type Field visualization.

Defining the visibility of fields in CM/Track

Only relevant for case fields. The visibility of fields in CM/Track depends on the system property cmas-rest-api, security.fields.customer.exposure.check.enabled, the client configuration and the settings Availability via REST on group and field level. See Defining data availability.

Defining the credentials for CM/Track

Only relevant for contact fields. You can define the fields for the user name and password for contacts which should have access to CM/Track.

The required fields depend on the authentication method:

• Database authentication: field for the user name (setting User name for CM/Track) and field for the password (setting Password for CM/Track)

• LDAP authentication: field for the user name (settings User name for CM/Track and LDAP ID for CM/Track)

• SSO authentication: field for the user name (setting User name for CM/Track)

There can be only one field with the User name for CM/Track setting and one field with the Password for CM/Track setting in a contact model. If the setting is removed from an existing field, the corresponding values (user names or passwords) are deleted from the database. The user name must be unique.

See Supported characters for passwords in ConSol CM for details about the allowed characters for passwords.