Skip to main content

Scripts

Introduction to scripts in ConSol CM​

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

ConSol CM brings an extensive API which provides methods to access and modify ConSol CM objects. 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 the following 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.
  • Last executed: This is the date when the script was executed for the last time.

Script types​

The following script types are available:

  • 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. See TODO.
  • Action form prefill: Prefills the data fields in an action form. Is assigned to the action. See TODO
  • Calendar integration: Provides the connection information for the integration of Microsoft Exchange calendars. Is referenced in the page customization of the calendar section. See TODO
  • Clone: Changes the values with which the newly created case is automatically prefilled when cloning a case. Is assigned to the queue. See Clone scripts.
  • Contact action: Implements a contact action. Is assigned to the action. See Action scripts.
  • Contact condition: Determines if a contact action is available. Is assigned to the action. See Action scripts.
  • Default values: Prefills data when creating a new case. Is assigned to the queue. See Default values scripts.
  • Dependent enum: Defines hierarchical data structures for data fields. Is assigned to the data field group. See Dependent enum scripts.
  • Email: Manages incoming and outgoing emails. Some email scripts are part of the ConSol CM delivery. Is assigned to the queue. See Email scripts.
  • Embedded in workflow: Script which is attached to a workflow element. See Managing workflow scripts.
  • Field visualization: Configures the visualization of data fields. Is assigned to the data field. See Field visualization scripts.
  • Integration: Implements a service which uses the webhook interface of ConSol CM. See TODO.
  • News publisher: Configures the news feature. Is assigned to the widget in the page customization (usage in the Web Client) or in the portal configuration (usage in CM/Track). See News scripts.
  • 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. Use the type Page customization for scripts which are referenced in page customization scopes or types, and the script type Widget for scripts which are used to implement dashboard widgets, so that you can distinguish the scripts easily. See TODO.
  • Page visualization: Configures the visualization of a page. Is assigned to the page type in the page customization. See Page visualization scripts.
  • 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. See TODO.
  • Resource action: Implements a resource action. Is assigned to the action. See Action scripts.
  • Resource condition: Determines if a resource action is available. Is assigned to the action. See Action scripts.
  • Search action for cases: Implements an action for a detail search result containing cases. Is assigned to the action. See Action scripts.
  • Search action for contacts: Implements an action for a detail search result containing contacts. Is assigned to the action. See Action scripts.
  • Search action for resources: Implements an action for a detail search result containing resources. Is assigned to the action. See Action scripts.
  • Search condition for cases: Determines if an action for a detail search result containing cases is available. Is assigned to the action. See Action scripts.
  • Search condition for contacts: Determines if an action for a detail search result containing contacts is available. Is assigned to the action. See Action scripts.
  • Search condition for resources: Determines if an action for a detail search result containing resources is available. Is assigned to the action. See Action scripts.
  • System documentation: Configures the system documentation export. See System documentation scripts.
  • Task: Implements a task which can execute any code in the system. See TODO.
  • Text autocomplete: Defines scripted autocomplete lists for data fields. Is assigned to the data field. See Text autocomplete scripts.
  • Web form condition: Determines if a web form can be accessed by a client. Is assigned to the web form. See TODO.
  • 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. Use the type Page customization for scripts which are referenced in page customization scopes or types, and the script type Widget for scripts which are used to implement dashboard widgets, so that you can distinguish the scripts easily. See Widget scripts.
  • Widget visualization: Implements generic widgets which allow visualizing any HTML content. Is assigned to the widget in the page customization (usage in the Web Client) or in the portal configuration (usage in CM/Track). See Widget visualization scripts.
  • Workflow: Scripts which are referenced from workflows. See Workflow scripts.

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: 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: Select the script type in the All types except embedded drop-down list to display only scripts of a certain type.
  • Modification date: Sort the scripts by last modification to display recently changed scripts first.
  • Last execution date: Sort the scripts by the last execution to display recently executed scripts first.
  • Unsaved changes: Select Only modified in the All types except embedded drop-down list to display only scripts which have unsaved changes.
  • Usage: Select In use or No known uses in the All usages drop-down list to display only scripts with or without usage.
Favorites

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.
  • 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. See Using the script editor features for usability features. The following actions refer to the script as a whole:
    • 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.
  • 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:

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

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

    tip

    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 must 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 underlined. You can click the script name to open it.

  • Code snippets: You can insert code snippets into your scripts 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 following snippets are available:

    • 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

    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

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

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

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.

tip

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, special actions are available for the following script types:

  • Integration: Opens the configuration page of the webhook which belongs to the script. See TODO Webhooks.

  • Task: Creates and executes a task with the given task script. See TODO Tasks.

    note

    On development systems (system property cmas-core-shared, system.flavour set to dev), 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.

Versioning

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.
Development mode

If the development mode, see TODO 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 TODO Workflows.