Skip to main content

Scripting and REST API improvements

The following improvements to the ConSol CM API and REST API have been made.

Searching for fields without a value (#647122)​

The API has been extended by methods which allow to search for data fields which do not have a value set in cases, contacts or resources. This allows the user to identify objects with missing data more easily.

This is done by adding a null criterion to the search criteria created using CustomFieldCriteriaBuilder. The following objects are available to represent null for the different data types:

  • NOT_SET_BOOLEAN: To be used for boolean fields
  • NOT_SET_DATE: To be used for date fields
  • NOT_SET_DECIMAL: To be used for fixed-point number fields
  • NOT_SET_ENUM_VALUE: To be used for enumerated and hierarchical list fields
  • NOT_SET_NUMBER: To be used for integer number fields
  • NOT_SET_STRING: To be used for text fields

The criteria object is built as follows:

TicketCriteria ticketCriteria = new TicketCriteria();
ticketCriteria.fields = new CustomFieldCriteriaBuilder()
    .set("fieldGroup:booleanField", CriteriaWithCustomFields.NOT_SET_BOOLEAN)
    .build();
info

The search for missing values only work for regular fields. Nested fields, such as fields which belongs to lists or structs, can only be searched if the criteria object contains at least one other criterion which searches for a non-empty field belonging to the same parent.

Method to copy cases modified (#658062)​

The behavior of the API methods copy() and copyFrom(Ticket pTicket) from the class Ticket has been modified so that the created cases can be persisted. Two changes have been made:

  • The case name is not copied anymore to avoid errors due to the violation of the unique constraint on the case name.
  • The main contact is not copied anymore because it needs to be provided in the method which persists the case.

The following piece of code can now be used to copy a case:

def copy = ticket.copy()
ticketService.createWithUnit(copy, ticket.mainContact)
client.goToTicket(copy)
warning

If you need a copy which includes the case name and contact, you need to set this data explicitly.

New REST API endpoint (#660570)​

A new REST API endpoint has been introduced to retrieve the cases which are shown on the welcome page of CM/Track V3. The endpoint is called /tickets/dashboard. It retrieves the cases which are assigned to the current contact, the cases which are assigned to other contacts of the contact's company, and the FAQ cases, provided that the contact has the corresponding permissions. The cases are ordered descendingly by creation date.

The following parameters can be used:

  • pattern: provide a search pattern
  • pageSize: limit the number of cases in a page to the given value

Example request using CURL:

curl -N -X GET -vv -u huber:consol 'http://localhost:8888/restapi/tickets/dashboard?pageSize=10&pattern=*'

Deleted attachments filtered out from attachment list (#661019)​

The methods getAttachmentList() and getAttachmentList(Ticket pTicket) from the interface WorkflowContextService have been modified so that they do not return attachments which have been marked as deleted but not yet removed. This allows you to simplify your script code because code which checked if the returned attachments have been deleted is not needed anymore.

Autocompletion of methods of referenced scripts improved (#661193)​

The autocomplete features of the script editor have been extended by allowing autocompletion of methods which are defined in scripts called inside the current script. This is helpful if utility scripts which contain common methods are used, because the user can insert methods from utility scripts directly without switching to the script in order to copy the name of the method.

The following conditions have to be met for the autocompletion to work:

  • The utility script includes the statement return this.
  • The script calls the utility script using one of the following methods:
    • def utilityScript = scriptExecutionService.execute("utilityScript")
    • def utilityScript = workflowApi.runScript("utilityScript")

When typing utilityScript. all public methods defined on the top level of the utility script are suggested.

New methods for time calculations (#661698)​

The ConSol CM API has been extended with new methods to facilitate working with time triggers and business calendars. It is now possible to calculate the required milliseconds automatically and to iterate over business days instead of using business hours.

The following methods have been added:

  • calculateDueTime(int pMonths, int pWeeks, int pDays, int pHours, int pMinutes) in TimerUtil: Adds months, weeks, days, hours and minutes to the current date and returns the delta to the calculated future timestamp in milliseconds.
  • calculateDueTime(Date pDate, int pMonths, int pWeeks, int pDays, int pHours, int pMinutes) in TimerUtil: Adds months, weeks, days, hours and minutes to the provided date and returns the delta to the calculated future timestamp in milliseconds.
  • getBusinessDate(Date pRefDate, int pNumberOfBusinessDays) in BusinessCalendar: Iterates over business days starting from the provided date and returns an escalation date on the same hour of the future business day.

Example 1: Set a trigger for 1 week from now:

trigger.setDueTime(TimerUtil.calculateDueTime(0, 1, 0, 0, 0));

Example 2: Calculate the escalation date with business calendar after 8 working hours:

Date escalationDate = BusinessCalendarUtil.getEscalationTime(calendar.getTime(), calculateDueTime(0,0,0,8,0), businessCalendar);

Example 3: Set the escalation date to the next business day at the same hour:

Date escalationDate = getBusinessDate(now(), 1)

Input validation for trigger.setDueTime method (#661707)​

The behavior of the method setDueTime(Long pDueTime) of the class TimerTrigger of the ConSol CM API has been modified to improve its robustness. Previously, passing a negative value to this method would cause the trigger to fire immediately, which could lead to unintended behavior. Now, the method throws an IllegalArgumentException, which helps to handle such situations correctly.

Method to set email headers in outgoing email script (#661847)​

The ConSol CM API has been extended by a method which allows to set a header for an email in the outgoing email script of the queue. The method setHeader() has been added to the classes MailEntry and MailSendHolder for this purpose.

Example to set a high priority for an email:

mail.setHeader("Importance", "High")

This allows for example to mark manual emails sent from the Web Client as important based on case fields.

Deprecated class removed (#662002)​

The deprecated class TicketCriteria.HistoryCriteria has been removed to improve the clarity of the ConSol CM API.

warning

Scripts which used this class need to be adjusted to use ticketLogService instead.