Workflow Automation
Power Scripts lets you add custom conditions, validators, and post functions to Jira workflows by using SIL and Jira Expressions.
Introduction to SIL and JavaScript
Workflows within Jira Cloud operate in the same asynchronous manner as other Jira integrations. While Jira and Power Scripts function as distinct entities, this asynchronicity presents a challenge. While it was somewhat manageable for workflow actions, it proved infeasible for conditions and validators. In these cases, you need to determine the viability of a transition before it's executed.
To address this challenge, Atlassian introduced the capability to trigger external actions asynchronously within the workflow. This ensures that any failures in such actions do not disrupt the transition process. Jira gains the freedom to silently retry action execution as needed, especially when an action fails to respond within a specified time or returns an error.
Additionally, Atlassian mandated coding standards and validators for JavaScript, ensuring they can be executed safely on the Jira host. To mitigate potential performance concerns, the scope of conditions and validators was intentionally restricted.
Where | Language | Obs |
|---|---|---|
Conditions | JS (Jira Expressions) | https://developer.atlassian.com/cloud/jira/software/jira-expressions-type-reference/ synchronous, executed within the host product (Jira) |
Validators | JS (Jira Expressions) | |
Actions (Actions) | SIL | asynchronously fired; they may be retried if declared synchronous on SIL Engine or “fire and forget“ if declared asynchronous in execution on the SIL Engine. Run in the Power Scripts SIL engine. |
Even if a SIL to Jira Expression translator existed, you would remain limited by the predefined constraints and criteria established by Atlassian. Your translation tool would have inherent limitations, preventing it from performing beyond these defined parameters.
Configuring Conditions, Validators, and Post Functions
After you install Power Scripts for Jira, go to the Administration > Workflows page and create a workflow associated with a project.
Active workflows can't be edited. Create a draft workflow before making changes. Select the workflow and click Edit:
The workflow editor opens in one of the following views.
Text View
Use the Diagram and Text buttons to switch workflow’s views.
Click the transition name to edit the transition.
Diagram View
The Diagram and Text buttons can be used to switch the view mode of the workflow.
In Diagram view, click a transition line to see the transition options.
Once a transition is selected you can click the Conditions, Validators and Post Functions link for that transition.
Selecting a transition displays its transition triggers, conditions, validators, and actions.
The transition is made possible only if the conditions are fulfilled. They may be called multiple times, are always synchronous, and run within Jira. Extensions / plugins need to use the Jira Expressions. A condition must return true or false to signal whether the condition is met or not.
The validators must validate data before the transition is fired. Again, they may be called multiple times (for instance user corrects input errors on UI). Extensions / plugins need to use the Jira Expressions. A validator must return true or false and optionally the field and the error message you want to show in the user interface.
The actions are called every time when a ticket advances from one state to another. Jira doesn't wait for them to finish, but rather triggers them on the remote extension / plugin (in our case Power Scripts). If action fails, it’s retried.
An important consequence of the above model is that conditions and validators should not have side-effects. In fact, Jira Expressions are guaranteed not to have side-effects by construction. However, actions are allowed to make any changes to the issues, including advancing the issue in the workflow, and here’s where we shine.
To create conditions, validators and actions, click the corresponding Add <object type> link at the top of the workflow management tab (Add condition / Add validator/ Add action).
Post functions
The following image shows how to create an action.
After you click the Add button, you have 3 options:
Template - use the script template editor to create a new script
New Script - create a new script directly in the workflow editor
Existing Script - use a script that has already been written and exists in the SIL Manager
For this example, choose Existing Script and click Next.
Click the Edit icon (pencil) next to the Specify script input to select the script to use for the action.
Click Select to apply the selected script as a action.
You can create a new script or pick a script that was already created in the silprograms folder.
Return to the transition screen to see the newly added action in the view:
Important
It is advisable to move the action last, like in the above image. This ensures that the issue - on which the action is triggered - is fully updated by Jira prior to the execution of the action.
Publish the workflow
A common mistake is that workflow is not published and therefore the action is not active. Publish the workflow before testing the action.
Updating the action
To change the action you need to go through the above wizard, and this includes execution options. However, if you change the code of the action directly in the SIL Manager, the changes are immediate, the SIL Engine determines that the action has been changed and picks the changes, re-parses it and executes the new code.
Execution of Actions (Actions)
In case you defined multiple post-functions for the same action, note that the order of execution is heavily dependent on the moment of Jira triggering them and it cannot be guaranteed. Unlike the server/DC product, you should always favor one single post-function per transition action.
Actions always run in the same engine thread that receives the HTTP request. This ensures the best performance for a variety of use cases. However, if runtime exceeds 5 seconds, use schedule functions to run the code that is taking longer or declare the action as asynchronous. This frees the thread to handle another request.
If the action takes too long, note that it will be retried by Jira. So even if your action is happily running with no errors, you may encounter the same trigger because Jira does not yet received a response from the first run. For long running actions always use the asynchronous execution, or schedule the execution at a later time using one of the scheduler functions.
It is recommended to measure your script performance. To do this, go to Runtime -> Script Performance. If you notice longer runtime on actions, delay part of the processing using scheduler functions such as runScriptIn(), or better, declare it asynchronous.
Conditions and Validators
Conditions and validators may be configured starting in the same point as for actions. They serve different purposes, but the language they are expressed in is the Jira Expressions language. Power Scripts allows you to either configure a pre-defined condition or validator (i.e. built by us) or define your own. For the purpose of this document, we will show how to define your own so you can achieve the flexibility you need in your workflows.
Retain
Return type for Conditions and Validators is always a boolean.
Let’s open again the transition view, but this time we will select the Conditions tab.
Let’s add a condition. Click Add condition to open the next configuration screen. Select Power Scripts Condition.
The next screen will look familiar to you:
We will choose to write our own condition. Because we want to allow the transition to happen only if there are at least 2 comments, enter the following Jira Expression in the code box:
issue.comments.length > 1like this:
Click Next. Click Add when the Final step page opens.
Clicking Add too quickly results in an incompletely configured element in the workflow. Keep in mind that we do not control the elements outside the sandbox we’re showing the wizard above.
If everything worked correctly, you’ll return to the transition view screen:
Add a validator. Select the Validators tab and click Add validator.
From the list of validators, choose Power Scripts validators. We will also write code for this one too, it’s the most flexible option.
Click Add and select Write your own. To fully customize this, we add this code, requiring it to have at least one attachment.
issue.attachments.length > 0Enter a message for the validator. It will be shown in the UI when the expression on the right will return false.
Once again, click Add for Jira to fully configure the validator:
It will return you to the transition view, where we have one condition and one validator.
We are now ready to publish the workflow. After you published it, we are ready to test it. Choose an issue with at least two comments, otherwise you will not see the transition you configured (because it will be hidden by the condition that’s unfulfilled), and try to transition it. If you do not have any attachment, you will receive the error message from the validator:
However, if you attach something, the transition will succeed:
See More