Execute a custom script

Script action is a workflow action which executes a script on workflow transition.

Important: Security of the Workflow Transition scripts

The Workflow Transition scripts is a powerful tool, and as such "great power comes great responsibility": the System Administrators must carefully review the transition scripts: so they don't cause any malfunctions, malicious attacks or security problems in your codeBeamer System !

To enforce the security reviews the execution and location of the Workflow Scripts has been revised in codeBeamer 9.4. This means that:

Script execution

In codeBeamer 20.07 (Betty) and older:

• Custom scripts are always executed in a separate thread with a default execution timeout.
• The script execution timeout can be configured via System Admin → Application Configuration, e.g.:

  {
     "workflowAction" : {
        "scriptTimeoutInSeconds" : 2
     }
  }
  

• Scripts, that do not finish their execution within the configured timeout, will be cancelled, but the overall transaction will commence.

• Custom scripts by default are executed in the current thread/transaction without any execution timeout.
• In order to run scripts in an extra thread/transaction, you need to explicitly configure scriptTimeoutInSeconds to be greater than 0.
  

Handling errors when a legacy Script is rejected

When a legacy Script in a Workflow Transition is rejected because of the security settings that may cause that the users can not execute certain Workflow transition on items. This will appear like an error message:

To fix this problem a System Administrator do this:

• Carefully review the source-code of the Workflow script that was used in the Tracker
• Once the script is Approved, must upload the script source to a new file in config/scripts/workflow folder
• Reconfigure the Tracker to use this new Script file. For example using the "sample.groovy" needs this configuration:

After this is fixed the Workflow transition will work again.

It is important to note that if the "Veto on Exception" flag is set to "false" that means when the missing or insecure Script is NOT executed that will NOT prevent/Veto the transition, but the user will receive just a warning message about the missing or insecure Script. This situation can be same way corrected as described above !

Using scripts

First a System Administrator must carefully review and approve the Workflow transition script and then upload the script file to the "config/scripts/workflow" directory below your codeBeamer installation.

After this the uploaded can be used in the Tracker-configuration like:

The action has three parameters:

• Script Type
  is the script type/language
• Script Path
  is the file name of the script to execute
• Veto on exception
  whether a script execution error should abort the triggering event (true), or simply be logged (false)

Currently the following script languages are supported:

• Groovy
• Java Script (Server-side)

Writing the Workflow action as a script can have advantages

• Deployment is easier: no need to compile, deploy and restart the codeBeamer server for development
• Code is more compact: by using advanced features of Groovy your code can be shorter
• Quick to adapt: if the requirement changes it is easier to adjust by simply changing the Groovy script

but also has disadvantages:

• Scripts are a potential security risk
• No compile time errors/warnings. Errors can only be detected at run time.

Script execution context

Within a script, you have access to these context objects/variables:

Please note:
For each triggering event, the script is called twice!

• Once before the triggering event is processed on the subject item and
• Once after the triggering event was processed successfully on the subject item.

You can differentiate between the two executions by checking the value of the variable beforeEvent.

Throwing com.intland.codebeamer.event.util.VetoException by scripts is only allowed during the before phase and will be ignored in the after phase.

Example script

An (outdated) example for a custom script can be found here.