Workflow Automation
One of the standout features of Power Scripts™ is the ability to tailor your workflows. Leveraging the power of SIL (Simple Issue Language), you can seamlessly incorporate conditions, validators, and post functions into any transition within your workflow.
SIL and JavaScript: An Introduction
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 post functions, 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 for external post functions to be triggered asynchronously within the workflow. This ensures that any failures in such post functions do not disrupt the transition process. Jira gains the freedom to silently retry post function execution as needed, especially when a post function fails to respond within a specified time or returns an error.
Additionally, Atlassian mandated coding conditions and validators in JavaScript, ensuring they can be safely executed on the Jira host. To mitigate potential performance concerns, the scope of conditions and validators was intentionally restricted.
To summarize:
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) | |
Post-functions (Actions) | SIL | asynchronous 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. |
Please be aware that even if a SIL to Jira Expression translator existed, you will remain limited by the predefined constraints and criteria established by Atlassian. Your translation tool will 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.
You cannot modify the workflow while it's active, therefore you have to create a draft workflow. Select your workflow and press on the edit menu:
.
The result should look like one of the images below.
Text View
The Diagram and Text buttons can be used to switch the view mode of the workflow.
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 mode you must first click a transition line to see the transitions options.
Once a transition is selected you can click the Conditions, Validators and Post Functions link for that transition.
Clicking a transition will show the transition triggers, conditions, validators, and post functions.
Remember!
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 is must return "true" or "false" and optionally the field and the error message you want to show in the user interface.
The post functions are called every time when a ticket advances from one state to another. Jira does not wait for them to finish, but rather triggers them on the remote extension / plugin (in our case Power Scripts). If post-function fails, it will be 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, post-functions 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 post functions, click the corresponding Add <object type> link at the top of the workflow management tab (Add condition / Add validator/ Add post function).
Postfunctions
The following image shows the creation of a post-function.
After you click the Add button, you will be presented with 3 options (see screenshot below):
Template - use the script template editor to create a new script
New Script - write a new script on the fly
Existing Script - use a script that has already been written and exists in the SIL Manager
For the purposes of this example, choose Existing Script and click Next.
Now, click the edit icon (pencil) next to the script input to select the script you wish to use for the post function.
Click next to apply the selected script as a post function.
You can create a new script or pick a script that was already created or even used for other purposes in the silprograms folder.
Return to the transition screen, you will see that your newly added post function is reflected in the view:
Updating the post-function
Note that to change the post-function you need to go through the above wizard, and this includes execution options. However, if you change the code of the post-function directly in the SIL Manager, the changes are immediate, the SIL Engine determines that the post-function has been changed and picks the changes, re-parses it and executes the new code.
Execution of Post-functions (Actions)
In case you defined multiple postfunctions 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 postfunction per transition action.
Post functions 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 post-function as asynchronous. This frees the thread to handle another request.
If the post-function takes too long, note that it will be retried by Jira. So even if your post-function 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 post-functions always use the asynchronous execution, or schedule the execution at a later time using one of the scheduler functions.
Conditions and Validators
Conditions and validators may be configured starting in the same point as for post-functions. 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.
Let’s open again the transition view, but this time we will select the “Conditions“ tab.
Let’s add a condition. Press on the “Add condition“ button so we can open up the next configuration screen, where you will 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:
Press “Next“ then the “Add“ button belonging to Jira:
If everything went according to the plan, you will be returned to the transition view screen:
Let’s add a validator, too. Choose the Validators tab and then press on the “Add validator“ button:
From the list of validators, choose Power Scripts validators. We will also write code for this one too, it’s the most flexible option
Press on the “Add” button and choose “Write your own“ . We’re going to fully customize this, right? so we will add this code, requiring 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, press on the “Add“ button for Jira to fully configure the validator:
It will return you to the transition view, where we will have 1 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:
That’s pretty much it, so have a chocolate !