Valid since:
XL Release 4.5.0

Using the XL Release API in scripts

XL Release has an API that you can use to manipulate releases and tasks. You can access the API from Jython Script tasks and from XL 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

    Script test tasks

  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:

    Script test tasks

    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 XL Release needs to check the user’s credentials to verify whether certain operations are allowed.

  8. Close the task and select Properties from the Show menu.

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

    Tip: 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.

  10. Click Save to save the release properties.
  11. Select Release flow from the Show list.

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

    Script test tasks

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

    Script test tasks

  13. Open the Add a comment task and check the Comments section for the “Hello World!” comment:

    Script test tasks

Looking at the script

The first line of the sample script uses the getCurrentTask() method to get a reference to the task that is currently executing (that is, 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!")

Then, 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.