Using the Script Designer
Tailor-made functionalities for your app are quite common. In this article we cover the use of the Script Designer to create such features.
Last updated
Tailor-made functionalities for your app are quite common. In this article we cover the use of the Script Designer to create such features.
Last updated
A script is defined as a sequence of multiple statements. A statement is described as an Action or defines a Variable.
The Script Area contains the statements needed to implement your functionality. A statement has a data entry area, if parameters are needed, and several options in the Quick Action Menu at the top right corner.
The following operations for a statement are offered in the Quick Action Menu.
Functionality
Delete
Move Up
Move Down
Filter
Focus
Copy the action and all its children
Position
The script designer actions are numbered by the order of appearance, beginning by 1. The first filled parameter of an action with the number 1 would have the number 2. The second parameter would have the number 3 (if filled). The action after action number 1 would have the number 4. Constant parameter do not include an action and do not have a number.
The script designer allows to search for a number. Is an action with the number found the action is focused (visible through expanding parents and scrolled to. Additionally it flashes blue twice). The search input can be focused through the short cut 'G'.
Pressing the "Plus" button on the top left expands all elements in the script, while pressing the "Minus" button does collapse all items in the scope. These actions do not apply for the String constant.
The "Plus" button on the String constant expands the value text box so there is an overview of the content in the multiple lines format. The "Minus" button collapses back to the text box format.
Any errors in scripts are send as debug feedback messages with the following format:
With action name: Error in <Script-Location> at action <Action-Number> <Action-Type> '<Action-Name>'
Without action name: Error in <Script-Location> at action <Action-Number> <Action-Type>
Script locations are dependent one the occurrence:
Action-Pre: action '<Action-Name>' <Action-Key> pre
Action-Post: action '<Action-Name>' <Action-Key> post
Field-Default: field '<Field-Name>' <Field-Key> default
Field-Virtual-Get: field '<Field-Name>' <Field-Key> virtual get
Function: function '<Function-Name>' <Function-Key>
Selection: selection '<Selection-Name>' <Selection-Key>
SAML-Authorization: SAML authorization
Workflow-Step: workflow '<Workflow-Name>' <Workflow-Key> step '<Step-Name>'
Workflow-Transition: workflow '<Workflow-Name>' <Workflow-Key> transition '<Transition-Name>'
Template: template '<Template-Name>' <Template-Key>
Installer Application: installation '<Application Id>'
Execute script from script: execute script '<Script Id>'
ScriptController: script '<Script Id>'
There are two ways to add an action to the script. You click into Drop statement here and it opens the statement menu that contains both Actions and Variables. Click on a menu item and it will be added to the script.
Alternatively you choose and drag an Action or Variable from the corresponding menu and drop it in the Drop statement here area.
Statements can be nested and therefore create a hierarchy structure within a script.
The TIVITY platform provides an extensive collection of built-in Actions. However there are scenarios that would require a specialised functionality, a certain type of feature which is not offered by the TIVITY platform, or easy use of frequently used blocks of actions.
Such a scenario would be defined as a user-defined function in the Functions Designer.
To add a user-defined function to your script, use the ExecuteFunction action in the Actions Menu and choose the desired functionality in the drop-down menu.
A statement based on a user-defined function can be handled like any other built-in action.
A script action and all its children can be copied to the clipboard through the Quick Action Menu (see topic on top Manage script statements). To the right of the filter input is the copy button
The script action and all its children can be pasted from the clipboard to a statement or expression placement through the overlay script action filter. The insert button is located in the upper right corner next to the filter input.
If the script action is valid but cannot be copied (e.g. invalid content or due to missing script action types) an error is shown. If only children actions are invalid, only parents actions will be inserted. A message appears with the list of actions (statements and parameters) that could not be inserted.
Renaming statements can be helpful to organise the structure of a script.
Depending on the definition of an action you would have to provide more information in the statement. Primarily you would enter necessary values for the parameters of the action.
A parameter value can be provided by the return value of another action.
The return type of an action has to match the expected type of value used in a parameter.
Deleting a statement happens without confirmation and cannot be undone.
Setting a filter on a statement is used for conditional execution of the action. Only if the expression of the condition evaluates to true the action runs as part of the script.
For example, this could be used to run additional steps in the script based on certain information in an associated field only.
Click on Script restores the normal view and shows all statements in the Script area.
In order to make sure that scripts do not run indefinitely there is a possibility to set a time out in minutes for the script in the lower left corner of the script designer. Newly created scripts have a default timeout of 5 minutes.
If time out occurs error message is shown.
During the process of creating or editing a script you make a number of changes to your statements, like i.e. adding new actions and code blocks. With growing length and complexity of a script the probability to encounter any error is increasing.
A solid approach to handle such errors is to refer to the specification of the action. Navigate to the Action menu on the right-hand side and look for the action in question based on its name. Then click on the entry to show the Action Documentation. Check the list of required parameters and amend your script statement accordingly.
The example below adds a new variable to the script. Validation however reports that the Name parameter of the variable has to be set, otherwise validation will fail. Once a name has been given the error disappears and the script can be saved successfully. The second parameter Expression is optional and therefore does not do any harm.
Validation of scripts is important to guarantee carefree execution of functionality in your app. Always resolve any validation issues before closing a script.
The availability of the Move up and Move down action depends on the position of the statement, i.e. the first statement cannot be moved further up, similar the last statement cannot be moved further down.
The name of any statement in the script can be changed by either click on the info icon or click on the title. This opens the info and rename action view and allows you to enter a custom name for the action and see who created and modified the statement.
Click on Execute to confirm the new name of the action.
To remove a statement from the script click on the Delete icon. All statements contained inside the deleted element will be removed, too.
A statement can shifted around in the script. The buttons Move up, Move down, and Position can be used to change the location and the order of statements. Moving a statement up or down happens at the same level of hierarchy.
The Position statement feature allows you to move the statement freely. Therefore it can also be moved to a different hierarchy level.
A script can consist of numerous statements and therefore might have a certain length and complexity. The Focus feature allows you to change the scope of the script. It narrows the visible content down to a certain block of statements.
When you click on the Focus icon of any statement a new scope based on the name of the statement is added to the Navigation bar and the content of the Script area is reduced to the content of the statement.
When you click on Save to store the current state of a script the TIVITY platform performs a validation check and, if necessary, reports back any problems in the Validation area below the script.
