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 on the Scripts page or directly in the workflow, see Managing workflow scripts. All other scripts are saved on the Scripts page.

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.	Action forms
Action form prefill	Prefills the data fields in an action form. Is assigned to the action.	Action 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 calendars
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 the 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
Embedded in workflow	Script which is attached to a workflow element.	Managing workflow scripts
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
Page visualization	Configures the visualization of a page. Is assigned to the page type in the page customization.	Scripts of the type Page visualization
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 page 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 except embedded 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.

• Unsaved changes: Choose to display only scripts which have unsaved changes.

  Select Only modified in the All types except embedded drop-down list.

• Usage: Choose to display only scripts with or without usage:
  

  Select In use or No known uses in the All usages drop-down list.

You can mark scripts which you use frequently as favorites by clicking the star icon next to the script name. Afterwards, you can move the favorites to the top of the table by clicking the icon in the table header. If the header icon is enabled, the favorites are always shown at the top of the table, even if the script does not match the applied filters in the search field or the script type selector.

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.

    You can choose the Save all changes action to save all modified scripts, which are indicated by a pink name and an asterisk, at once.

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

  If you call a script inside your script by using code like def utilityScript = scriptExecutionService.execute("utilityScript") or def utilityScript = workflowApi.runScript("utilityScript"), the public methods defined on the top level of the utility script are suggested when typing utilityScript followed by a dot.

  The utility script mus include the statement return this.

• Code validation
  The code validation results are displayed when hovering the line with the error. 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.

• Method and variable list
  You can click the Show navigator icon to open a panel on the right which contains a list of the methods and global variables defined in the main scope of the script. Click a method or variable to jump to its definition in the script.

• Referenced scripts
  Scripts which are called from a script are underlines. You can click the script name to open it.

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

  • Script generators: generate and insert code for email or search scripts based on selections made in a modal window
  • 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:

  • Save: CTRL + S
  • Undo: CTRL + Z
  • Find: CTRL + F
  • Insert code snippet: CTRL + J
  • Autocompletion: CTRL + space
  • Jump to line: CTRL + L
  • Jump to the referenced script: CTRL + click
  • Open a preview of the referenced script: CTRL + ALT + click
  • Open a preview o the script template: ALT + T
  • Format code: ALT + F

  The shortcuts related to referenced scripts are available once the user has selected the script name in the code.

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

You can compare the current unsaved script with the last saved version of the script by clicking the Compare with last saved version button. The changes are highlighted in a side-by-side view.

You can see where a script is used by clicking the Usage button. The popup window lists the places where the script is referenced and provides links to jump to the referencing objects.

If someone else saves the script which you are currently working on, a red warning message is displayed above the editor and you can compare your changes with the new server version of 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.

On development systems (see cmas-core-shared, system.flavour), you can start a task using the inline icon Execute task in the row of a task script.

Managing workflow scripts

When using scripts in a workflow, you can either save the scripts directly within the workflow or reference a script stored on the Script page from within the workflow. Scripts saved in the workflow can be viewed and searched on the Scripts page by selecting the option Embedded in workflow in the type filter.

For embedded scripts, only the deployed version of the script is displayed, i.e. if the script has been modified in a workflow version which is saved, but not yet deployed, the script content belonging to the last deployed version of the workflow is shown.

Advantages of storing workflow scripts on the Script page:

• 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 on the Script page take effect immediately after saving.

Advantages of storing workflow scripts in the workflow:

• You do not need to switch between the pages when working on a workflow.
• The scripts are versioned, i.e. each workflow version contains the script deployed with this version.

If the development mode, see Deployment mode, is selected on the Workflows page, you can also edit the scripts which are saved in the workflow only on the Scripts page. The changes become effective immediately and there is no versioning.

Please proceed as follows to save a workflow script on the Script page:

1. Create the script with the type Workflow on the Script page.

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

   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.

You can find more information about embedded scripts on the page of the respective workflow element, see Workflows.