Working with data fields

Introduction to data fields

The access to data fields is an essential part of ConSol CM programming. It is potentially required in all scripts of the system, workflow as well as Admin Tool scripts, no matter of which type. Here, we will set the focus on workflow programming, but the access to data fields is basically the same in all scripts.

There are three types of data fields:  

• Ticket fields
  Used to define ticket data, managed in ticket field groups
• Customer fields
  Used to define customer data in the customer data model. Managed in customer field groups.
• Resource fields
  Only if CM/Resource Pool is in operation. Used to define resource data as part of the resource data model. Managed in resource field groups.

Data types for data fields

A data field is always of a certain data type. As for any variable in programming, it depends on the data type how you have to handle the value of the field, e.g. a string field cannot be used for calculating numbers, an enum field needs a specific access method.

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 the ConSol CM Administrator Manual, section Admin Tool Scripts, 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 Enum Administration in the Admin Tool. 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 116: Scheme: List of structs

  Technically spoken, the list is an array which contains a map (= key:value pairs) in each field.

  

  Figure 117: 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 MLA Administration in the Admin Tool. 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!

Details about string fields: use annotations to fine-tune strings

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 Scripted Autocomplete Lists in the Administrator Manual.

... 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.

... 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.

Methods for accessing data fields

The basic methods for accessing data fields are the same for tickets, customers and resources. The following sections provide a short introduction to each object type and describe the available methods.

Ticket data

In the Admin Tool, the ticket fields are defined in the navigation group Tickets, navigation item Ticket Fields.

Figure 118: ConSol CM Admin Tool - Ticket field administration for ticket data

You need four methods of the class Ticket to work with ticket fields:

• Ticket.get()
  For retrieving data from a ticket field. Syntax:

  ticket.get("<ticketFieldGroupName>.<ticketFieldName>")

  Depending on the type of data field, this method returns either a value or an object.

• Ticket.set()
  For setting data in an already existing ticket field. Syntax:

  ticket.set("<ticketFieldGroupName>.<ticketFieldName>", <value>)

• Ticket.add()
  For adding a value to a ticket field. Syntax:

  ticket.add("<ticketFieldGroupName>.<ticketFieldName>", <value>)

  This method is used for:

  • Calculating with a value within a ticket field, i.e. to add a certain time range to a date field.
  • Adding a new line to list fields (simple lists and tables).

• Ticket.remove()
  For emptying a field, when its value should be set to null. Syntax:

  ticket.remove("<ticketFieldGroupName>.<ticketFieldName>")

  Alternatively, you can set the field value to null.

  ticket.set("<ticketFieldGroupName>.<ticketFieldName>", null)

See section Coding examples with different data types for details about handling the different field types.

Customer data

The customer data model contains customer field groups and customer fields. They are both defined in the Admin Tool, navigation group Customers, navigation item Data Models.

Figure 119: ConSol CM Admin Tool - Customer field administration for customer data

You need four methods of the class Unit to work with customer fields:

• Unit.get()
  For retrieving data from a customer field. Syntax:

  unit.get("<customerFieldGroupName>.<customerFieldName>")

  Depending on the type of data field, this method returns either a value or an object.

• Unit.set()
  For setting data in an already existing customer field. Syntax:

  unit.set("<customerFieldGroupName>.<customerFieldName>", <value>)

• Unit.add()
  For adding a value to a customer field. Syntax:

  unit.add("<customerFieldGroupName>.<customerFieldName>", <value>)

  This method is used for:

  • Calculating with a value within a customer field, i.e. to add a certain time range to a date field.
  • Adding a new line to list fields (simple lists and tables).

• Unit.remove()
  For emptying a field, when its value should be set to null. Syntax:

  unit.remove("<customerFieldGroupName>.<customerFieldName>")

  Alternatively, you can set the field value to null.

  unit.set("<customerFieldGroupName>.<customerFieldName>", null)

Alternatively, you can separate the field group name and the field by a colon.

See section Coding examples with different data types for details about handling the different field types.

When working with customer data, you also need access to the different customer objects. The following examples show the convenience methods provided by the ConSol CM API for this purpose.

• Retrieve the main customer of a ticket:

  Unit mainContact = ticket.mainContact

• Retrieve the company of a contact:

  Unit company = mainContact.get("company()");

• Set the company of a contact:

  mainContact.set("company()", company);

• Retrieve the contacts who belong to a company:

  List contacts = company.get("contacts()");

• Retrieve the tickets of a company or a contact:

  List tickets = company.get("tickets()");

  List tickets = mainContact.get("tickets()");

• Retrieve the name of the definition, i.e. the name of the used customer data model, of the customer:

  mainContact.customerDefinition.name

• Retrieve the type of customer (contact or company) and the name of the unit definition:

  mainContact.definition.name

  mainContact.definition.type

It is possible to chain the methods, for example to get the number of tickets of the first contact of a company:

Integer count = contact.get("company().contacts()[0].tickets()[count]");

Coding examples using the ConSol CM Action Framework are provided in the ConSol CM Administrator Manual, section Scripts for the Action Framework.

Resource data

The optional module CM/Resource Pool allows to extend the CM database and store resource objects. These can be various objects like IT assets, contracts, shop items or whatever is required in the respective company. The resource data model is defined in the navigation group Resources, navigation item Data Models of the Admin Tool.

Figure 120: ConSol CM Admin Tool - Definition of the resource data model

You need four methods of the class Resource to work with resource fields:

• Resource.get()
  For retrieving data from a resource field. Syntax:

  resource.get("<resourceFieldGroupName>.<resourceFieldName>")

  Depending on the type of data field, this method returns either a value or an object.

• Resource.set()
  For setting data in an already existing resource field. Syntax:

  resource.set("<resourceFieldGroupName>.<resourceFieldName>", <value>)

• Resource.add()
  For adding a value to a resource field. Syntax:

  resource.add("<resourceFieldGroupName>.<resourceFieldName>", <value>)

  This method is used for:

  • Calculating with a value within a resource field, i.e. to add a certain time range to a date field.
  • Adding a new line to list fields (simple lists and tables).

• Resource.remove()
  For emptying a field, when its value should be set to null. Syntax:

  resource.remove("<resourceFieldGroupName>.<resourceFieldName>")

  Alternatively, you can set the field value to null.

  resource.set("<resourceFieldGroupName>.<resourceFieldName>", null)

See section Coding examples with different data types for details about handling the different field types.

When programming with resources it is often required to retrieve the resources which are linked to a certain ticket or customer. This topic is treated in detail in the section Working with resource relations.

Coding examples using the ConSol CM Action Framework are provided in the ConSol CM Administrator Manual, section Scripts for the Action Framework.

Coding examples with different data types

The following section shows examples of working with data fields of different data types. The examples refer to ticket fields. Nevertheless, the handling is the same for customer and resource fields. The fields are always referenced by their technical names using the following pattern:

<ticket|unit|resource>.<get|set|add|remove>("<technical name of the field group>.<technical name of the field>")

Simple data types

Simple data types are data fields which contain a single value or object. The following list shows the available simple data types with the classes of their values:

• autocomplete: AutocompleteValue, see chapter Scripted Autocomplete Lists in the ConSol CM Administrator Manual for details about handling autocomplete values.
• boolean: java.lang.Boolean
• date: java.sql.Timestamp
• enum: EnumValue, see Retrieving and setting enum values
• fixed-point number: java.math.BigDecimal
• MLA: EnumValue, see Retrieving MLA values and paths
• number: java.lang.Long
• string: java.lang.String

Retrieving and setting simple field values

The following example shows how to retrieve a boolean value of a ticket field to use it in a precondition script:

Code example 29: Precondition script where a boolean value is checked

The same behavior can be achieved by directly returning the value:

return ticket.get("am_fields.vip")

Code example 30: Precondition script where a boolean value is checked, short version

The following example shows how to set a value in a ticket field. As the field has the data type date, it requires a Date object, which can be created directly in the statement.

ticket.set("fields.reaction_time", new Date());

Code example 31: Setting a ticket field value for a field of type Date

When you work with number or date fields, you can even calculate with the field values in a very comfortable way, see following example.

ticket.add("fields.orders_number", 1)

Code example 32: Adding one to the number of orders

Retrieving and setting enum values

An enum (sorted list) field is a field where the value is one of various list values. For example, a list with priorities is the basis for an enum field. To retrieve the value of an enum field, you can use the same syntax as for simple data types. The get method provides an object of the class EnumValue. Use the getName() method to retrieve the string with the technical name of the value. The .name notation is the Groovy version of the getter method.

Code example 33: Retrieving an enum value for a ticket field

If you want to retrieve the localized value of an enum, you have to use LocalizationService.

To set an enum value, use the technical value with the following syntax. The new value has to be present in the enum which is referenced by the ticket field.

ticket.set("helpdesk_standard.priority", "URGENT");

Code example 34: Setting an enum value

Retrieving MLA values and paths

The Java class for MLAs (Multi Level Attributes) is MultiEnumField. MLAs are handled like regular enums when it comes to retrieving and setting values.

The following examples show the basic methods:

• Retrieve an MLA value:

  def myEnumValueName = ticket.get("GROUP_NAME.MLA_FIELD_NAME").name

• Set an MLA value:

  EnumValue enumValue = enumService.getValueByName("ENUM_NAME","ENUM_VALUE_NAME")

  ticket.set("GROUP_NAME.MLA_FIELD_NAME", enumValue)

The following example shows how to retrieve the entire path to the selected MLA value: 

Code example 35: Retrieving the entire path to the selected MLA value

Lists and tables

Lists and tables are “containers” for other data fields. A data field of the type list contains either one field of a simple data type or a struct which consists of several fields of simple data types. A list field can contain several values.

Lists

Each line of a list contains a value of a simple data type, a date in our example. The ticket field of type date has to have the parameter Belongs to which points to the list.

Figure 121: ConSol CM Admin Tool - Ticket fields for a list of date fields

Figure 122: ConSol CM Web Client - List of date fields in a ticket (edit mode)

The most important methods for working with lists are shown in the following section using the list from the above example:

• Retrieve all values of the list:

  def convs = ticket.get("conversation_data.conversation_list").each() {

  conv ->

  log.info "NEXT DATE is :" + conv

  log.info "CLASS of NEXT DATE is " + conv.getClass()

  }

• Retrieve the value at a certain list position by using its index:

  def mydate = ticket.get("conversation_data.conversation_list[1]")

• Add a new line to a list:

  ticket.add("conversation_data.conversation_list", date)

• Replace a certain value of the list by using the index of the list position:

  ticket.set("conversation_data.conversation_list[last]", date)

Tables (lists of structs)

The data construct list of structs is the technical basis for a multi-column table structure in the Web Client. The list is the parent object which contains lines. Each line is an instance of a struct. The struct contains as many data fields (table columns) as required. Please see the figures in the introductory part of this section.

To retrieve the data from a list of structs you can work with an iteration over the lines. In the following example, we work with a table where ...

• the ticket field orders_list represents the list.
• the ticket field orders_list is located within the ticket field group order_data.
• the iterator str represents the struct.
• the struct has three fields:
  • orders_hardware
    which represents the article that should be ordered (enum)
  • orders_contact
    which represents the contact person (string)
  • orders_number
    which represents the number of articles that should be ordered (integer)

Figure 123: ConSol CM Admin Tool - Ticket fields for a multi-column list (= table)

Figure 124: ConSol CM Web Client - Ticket with filled-in table

• Retrieve data from a list of structs by iterating over the list.

  def structs = ticket.get("order_data.orders_list").each() { str ->

  log.info("Hardware is " + str.orders_hardware.getName())

  log.info("Contact is " + str.orders_contact)

  log.info("Number is " + str.orders_number)

  }

• Add a new line by building a new struct and setting the required values in the struct.

  ticket.add("order_data.orders_list", new Struct()

  .set("orders_hardware", newhardware)

  .set("orders_contact", newcontact)

  .set("orders_number",newnumber)

• Set a new value in a certain table row by providing the index of its position in the list:

  ticket.set("order_data.orders_list[0].contact", "John");

• Remove a row from the table by setting the corresponding list position to null.

  ticket.set("order_data.orders_list[last]", null);

Fading in and out of data field groups

Data field groups can be faded in (made visible) and faded out (made invisible) depending on the process requirements. This helps to keep the objects concise, as the engineers only see the data fields which are relevant at the respective process stage.

A typical use case is a ticket field group which is invisible at first (ticket field group annotation group-visibility = false) and is faded in when the engineer needs to work with the data in the process. For example, a ticket field group which contains feedback of the customer is only displayed when the engineer has clicked the workflow activity Feedback received ... because this information is not needed before. In the same way, ticket field groups which are not required anymore can be faded out.

The following methods can be used for controlling the visibility of ticket field groups:

• Fade in a ticket field group

  workflowApi.setGroupProperty("ticket field group",GroupPropertyType.VISIBLE,"true")

• Fade out a ticket field group

  workflowApi.setGroupProperty("ticket field group",GroupPropertyType.VISIBLE,"false")

In addition, GroupPropertyType.VISIBLE can have the value open, which means that the tab of the field group in the Details section is selected/opened.

The same mechanism can be used for customers and resources. In these cases, the methods are:

• Update the visibility of a customer field group

  def fieldGroupDefinition = fieldDefinitionService.getGroupByName("customer field group")

  unit.getGroupsConfiguration().setProperty(fieldGroupDefinition, GroupPropertyType.VISIBLE, "true")

• Update the visibility of a resource field group

  def fieldGroupDefinition = fieldDefinitionService.getGroupByName("resource field group")

  resource.getGroupsConfiguration().setProperty(fieldGroupDefinition, GroupPropertyType.VISIBLE, "true")

Using data fields for variables

Sometimes it is necessary to work with variables which are required for workflow programming but should not be visible on the GUI. Depending on the object for which they are needed, you can use ticket, customer or resource fields for these variables.

Create the data fields with the required data type and make them invisible by assigning the annotation visibility = none.

If you want to control the values of the variables during the development stage, you can leave the field visible and assign the annotation once development is completed.