Scripts of the type Text autocomplete

Scripts of the type Text autocomplete can be used to implement text autocomplete fields. These are text fields which display a list of suggestions according to the entered text

Text autocomplete fields offer a number of advantages:

reference cases, contacts, resources or users saved in ConSol CM
search within the list values
add custom logic to determine the selectable values

Examples for the use of text autocomplete fields:

Create a field which contains the responsible user of a contact.
Provide text autocomplete fields as a helper for creating relations within an activity form.
Save the name of the user who should receive notifications about a case.

Steps to use a text autocomplete script:

Write a script of the type Text autocomplete on the Scripts page, see Creating the text autocomplete script.
Create the data field for which the script should be used, see Creating the data field.

Creating the text autocomplete script

Text autocomplete fields store two values:

Internal value
The internal value depends on the field type. For fields of the type Case, Contact, Resource, or User, it is the reference to the respective object. For fields of the type String, it is the string itself.
Display value
The display value is the value which is shown to the users in the Web Client or CM/Track. There are two options for the display value:
- Dynamic
  The display value is retrieved from the referenced object itself. If there are changes to the referenced object, the display value is updated accordingly.
- Static
  The display value is a string which is defined by the script. This can be a value from the referenced object or any other text. The display value does not change when there are changes to the referenced object.

Dynamic display values use templates to render the list values in the drop-down list with the suggestions, and the data field after a value has been selected. The following templates are used:

Users: engineer description template name
Contacts: Customer search result template. If it is not present, the Default template is used.
Resources: Search template. If it is not present, the Default template is used.
Cases: Fixed internal template containing the case name and subject.

Structure of the script

The script has to implement the method onSearchInput. This method has two signatures, one for regular data fields and one for data fields which belong to lists. When you create a new script of type Text autocomplete, the method template is inserted automatically, so you can easily locate the correct method.

The script has to return an object of the class ScriptAutocompleteResult which contains the search results. The objects added as search results need to match the object type defined for the data field (see Creating the data field), i.e., you can add either cases, or contacts, or resources, or users, or strings.

The default message displayed if the search does not return any results is No matches found. You can use the method noResults('String') to customize this message, e.g.:

return ScriptAutocompleteResult.noResults('No matching engineers found')

Methods to add values to the list

The type of display value (static or dynamic) depends on the method used to add values to the list.

First, you create an object of the class ScriptAutocompleteResult.

ScriptAutocompleteResult resultset = new ScriptAutocompleteResult();

Then you use one of the following methods to add the values to the list.

Static display values
Add new items to the list by passing the object and a string with the display value as parameters:

resultset.add(ticket, ticket.getSubject());

resultset.add(ticket, "my display value");
Dynamic display values
Add new items to the list by passing the object as a parameter:

resultset.add(ticket);

Please see the ConSol CM API Documentation of the class ScriptAutocompleteResult for details about the method signatures.

Uses cases for returning strings

There are two additional use cases for ScriptAutocompleteResult objects which contain strings:

Search in external sources, e.g. an external database
Display a message that the user has to enter a certain number of characters to start the search

Working with the context

You can use the pContext variable to retrieve the object which the data field belongs to. The content of pContext depends on the type of object.

Case:
pContext.ticket contains the current ticket object
Contact:
pContext.unit contains the current unit object
Resource:
pContext.resource contains the current resource object
All objects:
controlForm and formFields contain the action or activity form, and a map with the data fields and their values in the form

This allows you to influence the search results based on the actual case, contact or resource which the text autocomplete field belongs to.

Creating the data field

Text autocomplete fields can be used in case, contact, and resource fields. Please proceed as follows to create a new text autocomplete field:

Open the Case fields, Contact fields or Resource fields page.
Create a field of the data type Autocomplete.
Select the desired object from the Type drop-down list. The available options are Case, Contact, Resource, User, or Text.
Select the script in the Script drop-down list. Only scripts of the type Text autocomplete are available. See Creating the text autocomplete script.

Coding example

The following example script implements a text autocomplete field containing resource search results. The variable pSearchStr is used to check how many characters have been entered. In this example, the drop-down list shows a message that at least 3 characters are required if the user does not enter enough characters to start the search. If no results have been found, a customized message is displayed. Otherwise, the drop-down list contains the search results. The script works with dynamic display values.

import com.consol.cmas.common.model.autocomplete.script.*

/**

* This method is called by web client when the user clicks or types into the autocomplete field

* @param pSearchStr the search String types or NULL if user clicked into field without typing

* @param pKey fieldKey

* @param pContext (Ticket/Unit/Resource) holder. More about this later in the specification (Context section)

ScriptAutocompleteResult onSearchInput(String pSearchStr, FieldKey pKey, Context pContext) {

ScriptAutocompleteResult resultset = new ScriptAutocompleteResult();

// Add matching resource when entering more than 2 characters

if (pSearchStr.length() < 3) {

return new ScriptAutocompleteResult("NOTE: Please enter at least 3 characters!");

} else {

ResourceCriteria criteria = new ResourceCriteria();

criteria.setPattern("*"+pSearchStr+"*")

def resources = resourceService.getByCriteria(criteria)

if(resources.size() < 1){

return ScriptAutocompleteResult.noResults('No matching resources found')

} else {

resultset.add(resources);

}

return resultset;

}

Code example 9: Script of a text autocomplete field for a resource field

Retrieving and setting values of text autocomplete fields

The value of a text autocomplete field belongs to the class AutocompleteValue. It can be retrieved using the methods getInternalValue() and getDisplayValue() of this class.

The following example shows how to write the value of the text autocomplete field engineers_autocomplete to the log file. The field contains a reference to a user and belongs to a case.

// display engineer of ticket field (not engineer field in header!)

def ticket = workflowApi.ticket

AutocompleteValue myAutocompleteValue = ticket.get("serviceDesk_fields.engineers_autocomplete")

def intValue = myAutocompleteValue.getInternalValue()

log.info 'The internal value is ' + intValue

def dispValue = myAutocompleteValue.getDisplayValue()

log.info 'The display value is ' + dispValue

Code example 10: Script which writes values of a text autocomplete field to the server.log file

To set the values of a text autocomplete field, you need to create an object of the class AutocompleteValue with the internal value and the display value. Use the method setDynamicDisplayValue(true) to create a field with a dynamic display value.

The following example shows how to reference the user Susan ServiceDesk with the ID 26 in the case autocomplete field engineers_autocomplete using a dynamic display value.

def ticket = workflowApi.ticket

myAutocompleteValue = new AutocompleteValue()

myAutocompleteValue.setInternalValue("26")

myAutocompleteValue.setDynamicDisplayValue(true)

ticket.set("serviceDesk_fields.engineers_autocomplete", myAutocompleteValue);

Permissions in text autocomplete fields

Permissions are checked during the execution of the text autocomplete script when a field is edited in the Web Client and CM/Track, i.e., the user can only see and select entries referring to objects which he is allowed to view according to his assigned roles. When viewing text autocomplete fields, permissions are not checked. Therefore, the user might see labels referring to objects for which he has no permissions in text autocomplete fields and history entries.

Note regarding permissions in CM/Track:

Permissions related to text autocomplete fields work the same way as for the Web Client. CM/Track-specific restrictions, namely the limitation that a user only sees his own cases (and cases of other persons of his company, if configured) and persons of his company, are not part of the default configuration. This means that, by default, the user has permissions to see and select entries referring to cases belonging to queues for which the CM/Track profile has at least read permissions and contacts belonging to contact groups for which the CM/Track profile has at least read permissions. In short, the contact would see data belonging to other contacts.

Adapting the permissions for CM/Track

The class customerSecurityCriteriaBuilder provides methods to adapt the behavior of text autocomplete fields to the standard permissions in CM/Track, so that the users can only see results which refer to their cases or to persons which belong to their company.

The following example shows how to limit the search results of a text autocomplete field used in CM/Track to cases belonging to the current user.

ScriptAutocompleteResult onSearchInput(String pSearchStr, FieldKey pKey, Context pContext) {

def result = new ScriptAutocompleteResult();

def criteria= new TicketCriteria();

criteria.setPattern(pSearchStr+ "*");

customerSecurityCriteriaBuilder.setMyCaseCriteria(criteria);

for (Ticket ticket : ticketService.getByCriteria(criteria)) {

result.add(ticket);

}

return result;

}

Code example 11: Script of a text autocomplete field which can be displayed in CM/Track

General information about text autocomplete fields

This new way of configuring text autocomplete fields replaces the previous method, which used the setting Display with the value Autocomplete. Existing fields which use the old method will remain functional. These fields are not modified during an update. The previously used method onEditDisplayEntered still works for existing fields. Nevertheless, it is not needed anymore and will be removed in a future version of ConSol CM.

The following limitations exist when using the new way of configuring text autocomplete fields:

No transfer to the DWH. Text autocomplete fields are not transferred to the DWH and cannot be used in reports.
No support for ETL. Import and export of text autocomplete fields using ETL is not supported.
Text autocomplete fields cannot be indexed. Therefore they are not available for search.
If an object which is referenced in a text autocomplete field is deleted, the field might point to a non-existing object. This has to be considered in case the field value is later used in scripts.
Text autocomplete fields cannot be used in text templates and document templates.

Please refer to the ConSol CM Administrator Manual version 6.11.1.0 for information about the previous way of configuring text autocomplete fields.