Scripting

The Script Designer of the TIVITY platform adds custom functionality to your app. Scripts are used to process your data in workflows.

Introduction

The Script Designer or Scripting feature gives you the ability to extend and customise your apps with the functionalities and procedures you would rely on in your business activities.

The Script Designer lets you create, edit and manage your app's business logic from a bird's eye view. A typical script is built using a couple of predefined Actions and optionally a set of Variables. If needed, user-defined actions can be created in the Function Designer and then used in a script.

Although the functionality of the Script Designer is always the same independent of the calling context, there are differences in regards to the available options.

On the TIVITY platform the Script Designer is accessible at different locations. Refer to the article Accessing the Script Designer to learn more about the various options to add scripts in your app.

Overview

The Script Designer is divided into multiple areas.

	Area Designation
	Actions Menu
	Script Area
	Variables Menu

Advanced Mode of the Script Designer

Each area provides different features and might have additional areas. Each section of the Script Designer is described in more details below.

Actions Menu

The Actions Menu contains all available actions to create a script. Because of the large number actions are organised in groups based on their core functionality.

The return type of an action is displayed on the right-hand side of each entry.

The Actions Menu provides functionality for a script

An Action always has a return type. If no value is returned the return type is Void.

Any available, built-in action with its parameters and return type is documented in the Reference: Actions article.

Action documentation area

When you click on an action is open the Action documentation area at the bottom. This shows you the details of the action like its description and purpose, the expected Parameters and the Return Type provided.

Detailed information about the signature of an action

Quick access an Action

The Filter input field allows you to quickly access an action based on its name.

Use the Filter to access an action quickly

Script Area

This area contains the actual statements and instructions of a script. It is the editor where actions are added to and where the functionality of the script can be configured.

Script Navigation bar

The navigation bar of a script is located at the top of the Script area. There you can either expand or collapse all items in the active scope of the script, you can navigate between focused scopes, and switch between different view modes.

Script navigation bar to access scoped parts

The two buttons and on the left-hand side allow you to expand and collapse all script elements. The eye icon on the right-hand side lets you change the View Mode of the Script Designer.

Validation area

Validation is located at the bottom of the Script area. It provides information about the current state of a script, i.e. whether it contains severe Errors, Warnings, or general Info.

Validation area provides information regarding errors

When you click on Save the script is validated and any unresolved issues will be shown in the Validation area. More information about Handling of Validation issues is described at the end of this article.

It is good practice to resolve any errors and optionally warnings before closing a script and leaving the Script Designer.

Variables Menu

The Variables Menu provides access to all available variables. The number of variables varies depending on the calling context, i.e. Workflow Designer or Function Designer, etc.

The Variables Menu offers a list of variables available in the context

A variable can be added into the script via drag and drop.

Quick access a Variable

Here, the Filter input field also allows you to quickly access a variable based on its name.

Both Filter controls - Actions and Variables - search the available entries using the Contains comparison operator and are case-insensitive.

Switch the View Mode

Depending on the selected view mode different features are available. The following matrix shows the details of each view mode.

Feature shown in ...	Simple Mode	Advanced Mode
Actions Menu	✅	✅
Script Area	✅	✅
Variables Menu	❌	✅

To change between Simple and Advanced view mode, click on the View Mode icon in the Script navigation bar and choose an option.

Switch between view modes

Simple Mode

The Simple view mode provides access to a reduced number of Actions and shows the Script area only. This view allows you to focus on the script content and might be a good choice for simple functionalities.

Advanced Mode

In Advanced view mode the platform provides you with all available Actions and Variables. While writing a sophisticated or complex script this view mode might offer best options to work efficiently.

Architecture of a Script

Following section provides suggestions and good practices on how to organise and structure a script.

The Problem

A script can be of different length or complexity and might appear confusing. There are numerous statements to assign values to variables, to process data from various data sources, and possibly interactions with other systems in regards to integration and interactions.

Scripts can grow quickly and contain complexity

On first sight the above sample looks overloaded and confusing. Let's see how it would be possible to give a cleaner appearance and a better approach to organise a script.

A common Approach: Use of Block elements

The Block action can be used to create groupings of multiple statements and to separate the script into logical scopes. Therefore it is common practice to split a script into multiple blocks of statements. Additionally, use the Rename feature to give your block elements relatable names.

A typical structure of a script would work with at least two scopes.

1. Definition of variables

2. Operations

Clean script architecture using multiple Block elements

You can use any number of Block elements to structure a script, even in a nested hierarchy.

This is related to the separation of concerns or any other kind of criteria to provide you with a better overview and focused areas of functionality.

Using multiple block elements enables you to make use of the Focus quick action. Narrow down the visible content of a script and only work on the most relevant parts at a certain time. This approach shall give you a better experience editing your scripts.