Conditions Tutorial

Your Jira workflows define the business processes associated with working on different issue types. Workflows can be simple or complex, and they can include several or few workflow functions. Depending on what your organization requires, you may want to use enhanced workflow conditions provided by ScriptRunner. These script conditions allow you to do more in your workflow, providing extra control or information.

All of the ScriptRunner workflows functions are found on the normal Workflows page of Jira Administration (Administration>Issues>Workflows). Edit an existing workflow and click on the transition you wish to add a condition to, then Conditions>Add Condition>Script Condition [ScriptRunner].

What is a Script Condition?

A script condition is a version of a workflow condition that allows you to extend the functionality you find in a basic Jira workflow condition. A condition checks to make sure that a requirement has been met before you can see the next workflow transition. So, a scripted condition gives you more options to control this part of the workflow. There are several ways you can enhance your workflow using script conditions, including conditions that relate to sub-tasks, users, and issue history.

ScriptRunner does include built-in scripted conditions that you can use right away, but you can also create your own from scratch.

When you select Script Condition [ScriptRunner], you see several options on the Select Script page.

These options include pre-built scripts, a simple scripted condition, and a custom script option.

Pre-built Script Condition

ScriptRunner includes several pre-built script conditions that you can use without copying or pasting any scripts. These scripts allow you to simply select options via drop-down menus without needing to use any scripts. For example, you can use the All Sub-Tasks Must Be Resolved built-in script and customize it using drop-down menus. The built-in script conditions include:

• Allows the Transition if this Query Matches a JQL Query: this condition restricts the next transition to items that match JQL you add to the JQL Query field when setting up the script condition. For example, you could set an issue not to be transitioned to In Progress if the assignee is empty. So, in the JQL here, you use Assignee is not EMPTY on the In Progress transition.

• Simple Scripted Condition: this condition runs a simple embedded script to find out whether to show the action or not.

• All Sub-tasks Must be Resolved: this condition restricts the next transition on a parent issue with sub-tasks. For this built-in script condition, all sub-tasks must be set to Done for you to move the primary issue to done. We look at this example in-depth shortly.

• Check the Issue Has Been in a Status Previously: this condition makes sure that the issue has made it to a previous status before being transitioned to the next status. Sometimes you have to make sure you Crawl before you Walk.

Simple Scripted Condition

For the simple scripted condition option, you can paste inline scripts that are less complicated than the custom script option. For this script condition, you want to use code that returns something true/false. More nuanced returns are better served in the final option.

Custom Script Condition

Custom script conditions are precisely what they sound like, an opportunity to customize your conditions using an inline script box. These scripts are more complicated than simple scripted conditions. If you aren’t quite a Groovy writer yet, you can copy and paste some example scripts found in Adaptavist’s ScriptRunner documentation and use them, or you can create your own.

Examples of Script Conditions

Let’s look the two different use cases of script conditions, along with basic examples of how you would achieve the desired results using a script condition. The first example uses a built-in script, while the second is a quick overview of using a custom script condition.

All Sub-Tasks Must be Resolved

This script condition makes sure that all sub-tasks have been resolved before a transition is available. You can customize this condition to specific subtasks of a particular issue type.

Great Adventure has an onboarding process that requires several steps for a new employee’s first day. Those steps are all represented as sub-tasks for the onboarding issue and include: meeting with the manager, attending company orientation, setting up their workstation, and updating their calendar.

The next part of the process is for the new employee to meet with their entire team for an update on current projects. Before that part of the process happens, the new employee must complete all of the sub-tasks associated with the first day portion of the workflow. They can do that by using the All Sub-Tasks Must be Resolved scripted condition.

Add a Scripted Condition

1. Access the project where you want to edit a workflow.

2. From the project, click Project Settings>Workflows from the links on the side, or from the Summary page under Workflows.

   You can also get to the Workflows page from the Issues section of the Jira administration menu.

3. On the Workflows page, look for the workflow you want to edit, and click the pencil icon under Actions.

   1. On the Edit page, you see a good view of the workflow. In Diagram view, hover over the transition lines to see their names or select Show Transition Labels to display them permanently.

      If you want to work in Text view, you can see the transitions listed instead of appearing as lines between statuses.

4. Click the transition you want to edit to open the Options window.

5. Click Conditions.

6. Click Add Condition.

7. Now you see the Add Condition to Transition page. From the list, select Script Condition [ScriptRunner], and then click Add.

8. On the Select Script page, select All Sub-Tasks Must be Resolved.

   1. Now, you see some options for this built-in script. In the Note field, type a note for your (and other admins') reference.

   2. From the Resolution menu, select Done.

   3. Click Preview to see a statement that references what this script condition achieves.

   4. Click Add to add the script condition. Once you click Add, you see the Workflow Edit screen with your new condition.

9. The next step is to Publish the workflow and test it.

Test the Scripted Condition

1. At the top of the workflow edit screen, click Publish. A message appears about saving a backup of the current workflow.

   1. For this demo you may not need to, but we recommend you save backups in your daily work.

2. Select Publish to publish the workflow.

3. Now, you want to run some issues through to test this new process. Log in as a test user with access to the project that has your updated workflow.

4. Create an issue (and subtasks attached to it) that uses that workflow. Transition the issue to the status just before where you added the scripted condition.

5. The button for that transition should not be available, since the sub-tasks are not resolved.

6. Work through the sub-tasks associated with the issue, marking them complete.

7. Return to the initial issue and review the transition buttons available at the top of the issue screen. The transition should now be available.

If everything was as described, you know that the script condition was successful, as we did not see the review button until the condition was met.

You can customize this script by defining an issue type or another field related to the issue, such as a component or assignee. For example, you may want to check out only QA type sub-tasks. If you plan to specify something in the script condition like issue type, you need to work with the Custom Script Condition option. This is how the condition would look in that case:

groovy
passesCondition = true
def subTasks = issue.getSubTaskObjects()

subTasks.each {
if (it.issueTypeObject.name == "QA" && ! it.resolutionObject)
passesCondition = false
}

All Depending Issues Resolved

This script condition checks that all issues that depend on the parent issue have been completed and is not a built-in condition. If you or a member of your team has not moved the dependent issues to Done or Resolved, you won’t be able to move the parent issue to Done. This script condition should be placed on the transition that closes an issue.

To add this condition, simply copy/paste the code into the box that appears when you select the Custom Script Condition option on the Select Script page.

groovy
import com.atlassian.Jira.component.ComponentAccessor
import com.atlassian.Jira.issue.link.IssueLink

def linkType = ["Blocks"]

def linkMgr = ComponentAccessor.getIssueLinkManager()
for (IssueLink link in linkMgr.getInwardLinks(issue.id)) {
if (linkType.contains(link.issueLinkType.name)) {
if (! link.sourceObject.resolutionId) {
passesCondition = false
}
}

}

Because this is a custom script, you can change items. For example, you could change the linkType to "Duplicates" or "Causes" to define a different relationship and a different script situation for this scripted condition. If you want to dive deeper into the world of scripting, there’s plenty of great resources available online to learn how to program in Groovy.