Introduction

Jira Issues can only be transition between states in a manner that resembles the Workflow of the parent project. In other words, before you begin trying to script the transition of a Jira issue, you must understand the workflow and what the available transitions actually are.

Further to that point, there’s more to transitions that simply changing the status of an issue. Some transitions have criteria.  For example, you may want to move an issue from Open to Pending.  In order to do so, you may need to select a Pending State, and add a comment.  How do you account for that in a script?

Using Groovy and ScriptRunner to transition Jira issues is a pretty straightforward process. So too is this process quite simple if you need to include transition criteria.  It’s simple, if you can find a guide on how to do it. As with most of the things I blog about, I couldn’t find instructions for accomplishing this simple task, so I’m writing my own.

Overview

The script we’re going to explore transitions a Jira issue from one state to another, and fills in the criteria required to make the transition a valid one.  As part of the transition process, it checks to ensure that the transition is valid.
The majority of this code isn’t actually mine, it’s a modification of an Adaptavist script.  But the script was incredibly difficult to find, and instructions were unclear, so I felt there was still merit in writing this blog post.

In order to make this script work, you’ll need a few things:

– A test issue

– Knowledge of the workflow, so that you know what is and is not a valid transition

– The transition ID (more about that in a moment)

About Transitions

As noted above, you’ll need two things from the project’s Workflow for this script. You’ll need knowledge of the transitions, and you’ll need the Transition ID.

You’ll need to be a Jira Administrator to edit the Workflow.   Open the Workflow in question for editing, and choose the Text view. What we’re presented with is a chart view of the Workflow.   The information you’ll need next depends on where your issue is going to start.  For example, you may have a section of the chart with a Linked Status called Open.  A ticket with a status of Open can be transitioned to any of the statuses under the Transition (id) heading.   Ultimately what we’re after is the transition ID of the target status.

In my case, the issue originated with a status of Open, and I wanted to transition it to Pending.  In my system, Pending has an ID of 501, and 501 is the piece of data we need to note.

The Script

Armed with the transition ID of the target status, we can now assemble the script. The entire script is below. As you can see, it’s not terribly complicated:

import com.atlassian.jira.component.ComponentAccessor
import com.atlassian.jira.issue.Issue
import com.atlassian.servicedesk.api.requesttype.RequestTypeService
import com.onresolve.scriptrunner.runner.customisers.WithPlugin
import com.atlassian.jira.issue.CustomFieldManager

def customFieldManager = ComponentAccessor.customFieldManager
def issueManager = ComponentAccessor.issueManager
def issue = issueManager.getIssueByCurrentKey("<>")
//Fill in an issue key here
def currentUser = ComponentAccessor.jiraAuthenticationContext.loggedInUser
def issueService = ComponentAccessor.issueService
def workflowManager = ComponentAccessor.workflowManager

def workflowActionId = 501
//Provide the transition ID of the target status for the issue

def issueInputParameters = issueService.newIssueInputParameters()
//Define a new input parameter object

issueInputParameters.setSkipScreenCheck(true)
//Skip the screen checks during transitions

issueInputParameters.setComment("This is a required comment")
issueInputParameters.addCustomFieldValue(<custom field ID>, "<value>")
//Provide a custom field ID, and a value to add to that field

def transitionValidationResult = issueService.validateTransition(currentUser, issue.id, workflowActionId, issueInputParameters)
//Create a transition object by giving it a user ID, an issue ID, the workflow action ID, and the set of parameters that we defined earlier

assert transitionValidationResult.valid: transitionValidationResult.errorCollection
def transitionResult = issueService.transition(currentUser, transitionValidationResult)
assert transitionResult.valid: transitionResult.errorCollection
//Check that the transition is valid

In the context of this simple example, there are only a few things you’d need to change to make this work for yourself.  You’ll need to fill in a proper issue key and transition ID.   In the given example you’d also need to provide a custom field ID and a value, but that’s not strictly necessary.

Let’s examine this a little more deeply.

Most of the setup of the script should be familiar if you’ve done any work with Groovy and Jira.  It’s only when we hit workflowActionID" that things might start to become unfamiliar.  

setSkipScreenCheck is a method that does pretty much what it says. In the words of Atlassian themselves: “By default, the Issue Service only allows setting values to fields which appear on the screen of the operation which you are performing (e.g. the Edit screen). By enabling this flag, the Issue Service will skip this check.”

Please do note that this method does not allow you to skip any of the parameters required for completing this transition. For example, if I ran the above script without declaring a comment as a transition parameter, I’d get this error message: Error Messages: [Comment: Please provide a comment for this transition].

We next come to the meat of the script.  This is the point at which you tell the script which fields to fill in or actions to take, as part of the transition. If you simply updated the value of a required custom field, the script wouldn’t have any idea that it was part of the transition and the transition check would fail.   For example, in my case the transition from Open to Pending requires that I include a comment about why the ticket is being set to Pending, and it also requires that I update a particular custom field with a value. 

You can add as many actions or parameters as you see fit, at this time.  Here’s the documentation for the method from Atlassian.

Having had declared as many parameters as you’d like, your customizing of the script is done.  The rest of the script defines a transition and uses the collection of parameters that we defined as one of its arguements.  The script then checks that the transition is valid, and if so completes the transition.