You are not logged in. Click here to log in.

codebeamer Application Lifecycle Management (ALM)

Search In Project

Search inClear

Tags:  not added yet

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:

For security reasons, you can only execute scripts, that have been approved and uploaded to config/scripts/workflow directory by System Administrators in your codeBeamer installation !

This directory is typically in $CB_HOMEt/tomcat/webapps/cb/config/scripts/workflow/ directory.

In release 9.3.0, the location for workflow scripts is $CB_HOMEt/tomcat/webapps/cb/WEB-INF/classes directory.

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

In codeBeamer 20.11 (Carmen) and newer:
  • 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:

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:

Name Type Description
applicationContext org.springframework.context.ApplicationContext The Spring framework's context, can be used to get access to DAO or Manager methods to execute queries and updates in the system
scriptWorkflowListener com.intland.codebeamer.event.impl.CustomScriptExecutor The CustomScriptExecutor instance running the script code
logger org.apache.log4j.Logger The log4j logger can be used to perform logging from the scripts
event com.intland.codebeamer.event.BaseEvent<ArtifactDto, TrackerItemDto, ActionData> The triggering event
user com.intland.codebeamer.persistence.dto.UserDto The user who triggered the event
source com.intland.codebeamer.persistence.dto.ArtifactDto The source of the triggering event, e.g. a state transition, escalation rule, etc.
transition com.intland.codebeamer.persistence.dto.WorkflowTransitionDto Only if the action is called from a state transition, otherwise null
subject com.intland.codebeamer.persistence.dto.TrackerItemDto The tracker item, that is subject of the triggering event
beforeEvent java.lang.Boolean Whether the script is called "before" or "after" the triggering event was processed on the subject item

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.