Scripts

Introduction to scripts in ConSol CM

Scripts are used for providing the logic for the processes which are modeled in ConSol CM. They are a key component for adapting the system to the required use cases. ConSol CM brings an extensive API which provides methods to access and modify ConSol CM objects.

Concepts, terms and definitions

Concept	Other terms	Definition
script		A script is a piece of code which is executed on the ConSol CM server or in the browser.
Groovy		Groovy is the programming language used for most of the scripts in ConSol CM. It is compatible with Java.
Java		Java is an object-oriented programming language which can be used in Groovy scripts.
JavaScript		JavaScript is a programming language which can be used in widget and field visualization scripts in ConSol CM.
ConSol CM API		The ConSol CM API provides methods to access and modify objects in the ConSol CM database.

Purpose and usage

Scripts are used for adding additional logic to the processes in ConSol CM. They define the behavior of the system in various areas, as for example emails, actions, widgets or workflows.

Most scripts are written in Groovy, an object-oriented programming language which is compatible with Java. You can use JavaScript for scripts which implement widgets and field visualizations in the Web Client.

Scripts which are used in the workflow can be saved either in the Admin Tool / Web Admin Suite or in the Process Designer. All other scripts are saved in the Admin Tool / Web Admin Suite.

Available settings for scripts

A script has three settings:

• Name: This is the name by which the script will be referenced.
• Type: The type indicates the purpose of the script. When creating a new script, the template of the selected type is automatically added to the source code. In addition, the type is used to filter the scripts which can be selected when referencing a script.
• Last modified: This is the date when the script was modified for the last time.

The following table shows the available script types:

Type	Description	Link
Action form condition	Determines if an action form for a contact action, resource action, or search action should be displayed. Is assigned to the action.	Control Forms
Action form prefill	Prefills the data fields in an action form. Is assigned to the action.	Control Forms
Calendar integration	Provides the connection information for the integration of Microsoft Exchange calendars. Is referenced in the page customization of the calendar section.	Microsoft Exchange Calendar Integration
Clone	Changes the values with which the newly created case is automatically prefilled when cloning a case. Is assigned to the queue.	Scripts of the type Clone
Contact action	Implements a contact action. Is assigned to the action.	Action scripts
Contact condition	Determines if a contact action is available. Is assigned to the action.	Action scripts
Default values	Prefills data when creating a new case. Is assigned to the queue.	Scripts of type Default values
Dependent enum	Defines hierarchical data structures for data fields. Is assigned to the data field group.	Scripts of type Dependent enum
Email	Manages incoming and outgoing emails. Some email scripts are part of the ConSol CM delivery. Is assigned to the queue.	Scripts of the type Email
Field visualization	Configures the visualization of data fields. Is assigned to the data field.	Scripts of the type Field visualization
Integration	Implements a service which uses the webhook interface of ConSol CM	Webhooks
News publisher	Configures the news feature.	Scripts of the type News publisher
Page customization	Provides settings for the page customization. Is referenced in the page customization section. The script type Widget can be used interchangeably with this type. We recommend to use the type Page customization for scripts which are referenced in page customization scopes or types, and to use the script type Widget for scripts which are used to implement dashboard widgets, so that you can distinguish the scripts easily.	Page customization
Relation graph	Configures the graph display of relations in the relation section of the Web Client. Is referenced in the page customization of the section.	Relation graphs
Resource action	Implements a resource action. Is assigned to the action.	Action scripts
Resource condition	Determines if a resource action is available. Is assigned to the action.	Action scripts
Search action for cases	Implements an action for a Detailed Search result containing cases. Is assigned to the action	Action scripts
Search action for contacts	Implements an action for a Detailed Search result containing contacts. Is assigned to the action	Action scripts
Search action for resources	Implements an action for a Detailed Search result containing resources. Is assigned to the action	Action scripts
Search condition for cases	Determines if an action for a Detailed Search result containing cases is available. Is assigned to the action.	Action scripts
Search condition for contacts	Determines if an action for a Detailed Search result containing contacts is available. Is assigned to the action.	Action scripts
Search condition for resources	Determines if an action for a Detailed Search result containing resources is available. Is assigned to the action.	Action scripts
System documentation	Configures the system documentation export.	Scripts of the type System documentation
Task	Implements a task which can execute any code in the system.	Creating a task script
Text autocomplete	Defines scripted autocomplete lists for data fields. Is assigned to the data field.	Scripts of the type Text autocomplete
Web form condition	Determines if a web form can be accessed by a client. Is assigned to the web form.	CM/Forms
Widget	Implements the widgets which can be displayed on the dashboards. Is referenced in the page customization section. The script type Page customization can be used interchangeably with this type. We recommend to use the type Page customization for scripts which are referenced in page customization scopes or types, and to use the script type Widget for scripts which are used to implement dashboard widgets, so that you can distinguish the scripts easily.	Scripts of the type Widget
Widget visualization	Implements generic widgets which allow visualizing any HTML content. Is assigned to the widget in the page customization.	Scripts of the type Widget visualization
Workflow	Scripts which are referenced from workflows.	Scripts of the type Workflow

Basic tasks

Finding a script

The list of scripts is displayed directly after accessing the Scripts section of the Web Admin Suite. You can filter the list to locate a script more easily:

• Text search: Perform a free text search in the script name or content.

  Enter a text in the Search field and select In name to search in the scripts’ name or In content to search in the source code of the scripts.

• Script type: Choose to display only scripts of a certain type.

  Select the script type in the All types drop-down list.

• Modification date: Sort the scripts by modification date.

  Select Last modified in the column selector and sort the list of scripts by modification date to display recently changed scripts first.

Working with scripts

You can perform the following actions on scripts:

• Create a new script

  Click the New script button above the list of scripts. Select the script type and enter a unique name for the script. See Available settings for scripts for details. Use the drop area to import script content from a file.

  If the new script is similar to an existing script, you create a copy of the script by clicking the Duplicate icon in this scripts’s row. You need to provide a unique name for the script and you can change the script type.

• Edit the script name or type

  Click the Edit icon to change the type or name of a script.

• Edit the source code of a script

  Click the row of a script to open its source code. The source code can be edited directly. The source code panel allows the following actions:

  • Save changes: Save your changes
  • Discard changes: Undo your changes.
  • Import: Replace the script by the content of a file.
  • Export: Save the script to a file.
  • Full screen: Open the script in full screen mode, so that the whole browser window is used for the source code. Click Return to leave the full screen mode.
  • Wrap text: Toggle between wrapping text, when a line of text exceeds the available space, and displaying a scrollbar.

  See section Using the script editor features for details about the capabilities of the script editor.

• Delete a script

  You can delete a script by clicking the Delete icon. If the script is already in use, for example because it is assigned to an action, an error message is displayed and you cannot delete the script.

Advanced tasks

Using the script editor features

The script editor has the following features:

• Syntax highlighting

  The editor uses syntax highlighting for Groovy.

• Code autocompletion

  As soon as you type a dot, the methods for the current object are suggested. You can continue typing to narrow down the results. Only methods for explicitly declared variables are displayed.

  You can press CTRL + SPACE to display suggestions for service classes.

• Code validation

  The code validation results are displayed below the source code. There are three modes:

  • No validation: The code validation feature is turned off.
  • Simple validation: A simple code validation is performed.
  • Strict validation: A more detailed code validation, which also checks if the invoked methods exist for the objects, is performed.

  You can set the frequency of the code validation checks using the system property cmas-app-admin-tool, script.validation.interval.seconds.

• Code snippets

  You can insert code snippets related to the following objects into your scripts:

  • Data fields: get and set values of case, contact and resource fields, get the technical and localized value of enum fields, iterate over list fields, add rows to list fields
  • Labels: insert a label with or without locale
  • Queues: insert a queue
  • Scripts: execute a script
  • System properties: insert a system property
  • Templates: insert a template with or without locale

  You can access the code snippets by selecting the >> Insert code snippet option from the autocomplete suggestions, by clicking the Insert code snippet button in the toolbar, or by using the keyboard shortcut CTRL + J.

  The Code snippets window includes a search field to search for the desired piece of code, e.g. search for a contact field to display the available snippets. You can apply additional filters by entering the type of object followed by a colon in the search field:

  • label: searches for labels
  • property: search for system properties
  • queue: searches for queues
  • resource: searches for resource fields
  • script: searches for scripts
  • template: searches for templates
  • ticket: searches for case fields
  • unit: searches for contact fields

• Keyboard shortcuts

  There are keyboard shortcuts for common operations. Examples:

  • Undo: CTRL + Z
  • Find: CTRL + F
  • Find next: CTRL + G
  • Replace: Shift + CTRL + F
  • Replace all: Shift + CTRL + R
  • Insert code snippet: CTRL + J
  • Autocompletion: CTRL + space

• Text highlighting

  You can double-click a word or mark some text to highlight all its occurrences within the script.

Using special actions

Depending on the script type, an additional button with a special action can be displayed in the upper left corner of the script editor. Currently, two special actions are available:

Script type	Action	Description
Integration	Webhook configuration	Opens the configuration page of the webhook which belongs to the script. See Webhooks.
Task	Execute task	Creates and executes a task with the given task script. See Tasks.

Saving workflow scripts in the Web Admin Suite

When using scripts in a workflow, you can either save the scripts within the workflow (in the Process Designer) or reference a script stored in the Admin Tool / Web Admin Suite from within the workflow.

Advantages of storing workflow scripts in the Admin Tool / Web Admin Suite:

• You can use the same script in several places, e.g., in different activities or workflows.
• You can change the script without having to deploy the workflow because changes in the Admin Tool / Web Admin Suite take effect immediately after saving.

Advantages of storing workflow scripts in the Process Designer:

• You do not need to switch between the Process Designer and the Admin Tool / Web Admin Suite when working on a workflow.

Please proceed as follows to save a workflow script in the Web Admin Suite:

1. Create the script with the type Workflow in the Web Admin Suite.

2. Reference the script from the desired place in the workflow in the Process Designer.

   scriptExecutionService.execute("myscript.groovy")

   Optionally, you can pass parameters to the script, e.g., the case or the main contact:

   def params = [ "myticket": workflowApi.ticket ]

   scriptExecutionService.execute("myscript.groovy", params)

   The variable myticket can be used in the script afterwards to access the case. Alternatively, you can retrieve it directly in the script using methods of the object workflowApi.