Using data fields in scripts

Accessing data fields

The basic methods for accessing data fields are the same for cases, contacts and resources.

Cases

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

• Retrieve data:
  

  ticket.get("<group name>.<field name>")

• Write data to a field:

  ticket.set("<group name>.<field name>", <value>)

• Add a value to a field (add a new line to a list field or calculate with dates):

  ticket.add("<group name>.<field name>", <value>)

• Remove a field value (set the value to null):
  

  ticket.remove("<group name>.<field name>")

Contacts

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

• Retrieve data:
  

  unit.get("<group name>.<field name>")

• Write data to a field:

  unit.set("<group name>.<field name>", <value>)

• Add a value to a field (add a new line to a list field or calculate with dates):

  unit.add("<group name>.<field name>", <value>)

• Remove a field value (sett the value to null):
  

  unit.remove("<group name>.<field name>")

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

When working with contact data, you also need access to the different contact objects.

• Retrieve the main contact of a case:

  Unit mainContact = ticket.mainContact

• Retrieve the company of a person:

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

• Set the company of a person:

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

• Retrieve the persons who belong to a company:

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

• Retrieve the cases of a contact:

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

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

• Retrieve the name of the contact data model used for the contact:

  mainContact.customerDefinition.name

• Retrieve the type of a contact (person or company) and the name of the definition:

  mainContact.definition.name

  mainContact.definition.type

Resources

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

• Retrieve data:
  

  resource.get("<group name>.<field name>")

• Write data to a field:

  resource.set("<group name>.<field name>", <value>)

• Add a value to a field (add a new line to a list field or calculate with dates):

  resource.add("<group name>.<field name>", <value>)

• Remove a field value (set the value to null):
  

  resource.remove("<group name>.<field name>")

The content of a data field depends on the data type, it can be either a value or an object. See section Working with different data types for details about handling the different data types.

Working with different data types

The following section shows examples of working with data fields of different data types. The examples refer to case fields. Nevertheless, the handling is the same for contact and resource fields.

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 Scripts of the type Text autocomplete
• 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 hierarchical list 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 case field to use it in a decision script:

Code example 24: Decision 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 25: Decision script where a boolean value is checked, short version

The following example shows how to set a value in a case 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 26: Setting a case 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 27: Adding one to the number of orders

Searching by field values

You can search for cases, contacts and resourced by values in their data fields using getByCriteria methods in the respective services (ticketService, unitService and resourceService).

Code example 28: Search for all cases from the Helpdesk 1st Level queue with the priority “high”

Code example 29: Search for all open cases from the Helpdesk 1st Level queue with the priority “high”

Retrieving and setting enum values

An enum field is a field where the value is one of the predefined list values, for example, a list with priorities. To retrieve the value of an enum field, you can use the same syntax as for simple data types. The get method returns an object of the class EnumValue. Use the getName() method, or .name in Groovy, to retrieve the technical name of the value.

Code example 30: Retrieving an enum value for a case field

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

Code example 31: Retrieving a localized enum value

When setting an enum value, the second parameter must be the technical name of an existing enum value of the enum referenced by the case field.

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

Code example 32: Setting an enum value

Retrieving hierarchical list values and paths

Hierarchical lists are handled like regular enums when it comes to retrieving and setting values.

The following examples show the basic methods:

• Retrieve a hierarchical list value:

  def myEnumValueName = ticket.get("group name.field name").name

• Set a hierarchical list value:

  EnumValue enumValue = enumService.getValueByName("enum name","value name")

  ticket.set("group name.field name", enumValue)

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 field of the type struct which consists of several fields of simple data types. A list field can contain several values. There is one row for each value.

Lists

Each row of a list contains a value of a simple data type. In the following example, this is a case field of type date, which has the parameter Belongs to pointing to the list.

• Retrieve all values of the list:

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

  conv ->

  log.info "NEXT DATE is :" + conv

  }

• 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. The list is the parent object which contains rows. Each row is an instance of a struct. The struct contains as many data fields (table columns) as required.

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

• the case field orders_list represents the list.
• the case field orders_list is located within the case 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)

• 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);