Working with Scripts

Overview

Scripts can be mangaed from the Editing suite page, from within the script editor or directly from workflow activities.

Adding a New Script

A new script can be added from the scripts tab of the configuration. Scripts can only be added to a single configuration.

Click the Add New Script button. Enter the path and the script file name, with a .js extension, then click the Submit Form and Create Script button.

The script will be created relative to the root where the configuration file (config.xml) is stored. This will be relative to the root of TB_HOME when exported.

New scripts can also be created from within the script editor, see below.

Uploading a Script

Scripts can be uploaded to a configuration. This allows for sharing of scripts between different TrustBuilder Administrator installations or different configurations. To upload a script click the Upload Script button from the Scripts tab at the top of the Scripts table list in the desired configuration console.

A form will then be displayed. Provide a name for the script once it has been uploaded, also a directory if desired. Then select the physical Javascript or JSON file from the local computer. Then click the Upload button. The script file will be uploaded, renamed to the given name and placed in the configuration directory. If no directory is specified in the Script File Name of the form then the file will be uploaded to the root of the configuration directory.

Importing a Script

If a configuration is related to a TB Server then the option to import will be available.

Individual scripts can be imported by clicking the Import button in the specific script row in the scripts table. When a script is imported the copy currently in the Administrator is overwritten.

This import is final there is no undo.

All scripts can also be imported from a TB Server.

If the configuration is related to more than one server then the desired server should be selected. The import can only be made from one server.

Deleting a Script

To delete a script check the box beside each script that is to be deleted. Then click the Delete Selected button.

If a script is still referenced by a workflow then a warning will be displayed listing the script and the workflows that still reference this script.

Deleting a script is final there is no undo.

Editing a Script: Script Editor

The script editor can be accessed by clicking the Edit button in a row or from an Edit Script button from a workflow activity. This will open the Script Editor in a new window.

If accessing the script editor from a workflow activity the function that is selected in that activity, if there is one, will be highlighted and brought into view once the script editor is open.

Script Editor Features

File Actions

New scripts can be created from within the script editor here: File > New.

Enter the full directory path and the name of the script to create then hit the Submit Form and Create Script button. The script will then be created and visible in the file tree on the left.

Double clicking a file in the Files tree will open that file.

Exporting

Scripts can be exported directly from the script editor by clicking the Export Script button in the top right of the script editor.

This button will only be available if the configuration that this script belongs to has been related to a TB Server.

On clicking the export button the servers that the script will be exported to are listed.

The engine will still need to be restarted for the changes to the script to be implemented.

Code Completion

Hitting CTRL+SPACE together will open a code completion drop down. This includes any local variables in the script and access to the reqeust API functions.

The code completion drop down will update as you type showing the relevant results.

Code completion showing local variables listed.

Code Completion API Access

To access the TrustBuilder scripting API functions first type tb. and then hit CTRL+SPACE. A list of all the TrustBuilder request functions will then be displayed that updates as you type.

Hitting the F2 key whilst a function is highlighted in the code completion list will display the documentation related to that function.

To turn off the documentation hint hit F2 again. F2 can be used to toggle between on and off.

Code Completion XML API

To access the TrustBuilder scripting XML API functions first type xml. then hit CTRL + SPACE

Call Hierarchy

To see where a function is being called from, where are any references to this funciton.

Select the function name then hit CTRL+ H. This will search all the script files within TBA for references to this function and list them in the Call Hierarchy tab:

Clicking a file that is listed in the call hierarchy tab will open that file and highlight the reference to our originating function:

Find Function

Highlight a reference to a function then hit CTRL + F3. The file containing the function will then be opened and the function will be brought into focus.

Mark Occurrences

To make occurrences of a variable within a script double click the variable and occurrences are highlighted.

The image below shows workItem occurences highlighted:

Validation

The script editor constantly validates your code. If there is an error with the code or a warning is present icons will be displayed in the left hand gutter.

Moving the mouse over the icons in the gutter will display the error or warning.

The issue is also highlighted in the script by underlining the code in red or yellow:

Duplicate Function Names

Function names are advised to be unique over all scripts within one configuration. If they are not then the function written in the last script that is loaded is the one that is used.

If a function is created with a name that is already in use a warning will be displayed when the script is saved.

Others

A list of all available actions can be found by mousing over the Help/Shortcut Keys menu

Working with Templates

Overview

Templates are generally pages that are displayed such as HTML login form for instance. But can also be a JSON page though these kind of templates would normally be created in script files.

Add a New Template

A new template can be added from the configuration screen on the Templates tab above the table of templates.

To add a template click the Add New Template button. This will display a form. Enter the path and script file name ending with one of the accepted extensions.

The template will be created relative to the root where the configuration file is stored (config.xml). When it is exported with will be relative to the root of TB_HOME.

A template can also be added from the template editor by clicking File  New

Import a Template

If the configuration is related to a TB Server then the ability to import a single template or import all templates from that TB Server is available by clicking the Import or Import All Templates buttons.

If the configuration is related to more than one TB Server then one server must be selected to import the template(s) from.

If a template already exists in TBA then it will be overwritten.

Edit a Template

Click the template row to open the template in the template editor. The Template Editor will open in a new window.

Delete a Template

To delete a template check the box beside each template to be deleted and then click the Delete Selected button.

All scripts within TBA will be read to check if this template is referenced by any script. If this template is used by a script a warning box will be displayed listing the template and the script file that references it.

To delete the template click the Delete the file button. If the cancel button is clicked at this stage then no file will be deleted.

Deleting a template is final there is no undo for this action.