Using Release API in Scripts

Release has an API that you can use to manipulate releases and tasks.

You can access the API from Jython Script tasks and from Release plugin scripts. This is an example of a simple Jython script in a Script task. It uses a script to add a comment to the task.

1. Go to the release overview and click New release (because this is a simple example, you can create an empty release that is not based on a template).

2. In the release properties, set the Release Name to Script example.

3. Click Create to create the release.

4. In the release flow editor, click the name of the first phase and change it to Test.

5. In the Test phase, add two tasks:

   • A Jython Script task called Add a comment
   • A Gate task called Check result

   

6. Click the Add a comment task and add the following Script:

   task = getCurrentTask()
   comment = Comment()
   comment.setComment("Hello World!")
   taskApi.commentTask(task.id, comment)

7. Close the task and click Start Release.

   The Add a comment task fails. Click the task to see the reason for failure in the Comments section:

   

   This message indicates that you must specify the user name under which to run the script. This is because the API gives you access to releases and tasks, so Release needs to check the user's credentials to verify if certain operations are allowed.

8. Close the task and select Properties from the left navigation bar.

9. Enter your user name and password in the Run automated tasks as user and Password boxes.

note

For a production configuration, it is recommended that you create a global "script runner" user that can be used for this purpose, rather that using your own credentials.

1. Click Save to save the release properties.

2. Select Release flow from the left navigation bar.

3. Open the Add a comment task and click Retry.

   

   The task succeeds and the release waits at the Gate task, giving you time to inspect the script result.

   

4. Open the Add a comment task and check the Comments section for the "Hello World!" comment:

   

Script details

The first line of the sample script uses the getCurrentTask() method to get a reference to the task that is currently executing (the Add a comment Jython Script task) and store it in a variable called task.

task = getCurrentTask()

To set a comment on the task, the script uses the taskApi.commentTask endpoint. The commentTask method takes the task ID and a Comment object as parameters. The Comment object is a simple wrapper around a string.

comment = Comment()
comment.setComment("Hello World!")

The script calls the commentTask() method to add the comment to the task:

taskApi.commentTask(task.id, comment)

note

For any call to an API endpoint, such as taskApi or releaseApi, you must set the Run automated tasks as user property on the release. The scripts will be executed with the permissions that that user has on that particular release.