This post was written by
Pat Callahan who describes his current position at Hara Software as "a little of this... a little of that", and some of that involves digging into JIRA.
Do you have something JIRA-related that you would like to write about? Or a topic you want see an article about? If so please contact me at
mdoar@pobox.com.
Common Transitions
JIRA workflows can have
common transitions, which are transitions that are defined once but used from multiple statuses. The default JIRA workflow contains one common transition:
Close. If you change it in one place then all the other places it is used are also changed. JIRA displays the names of such transitions in
italics.
JIRA does not provide a way to define new common transitions. You can
vote for that feature, but until then the only way is to edit the workflow XML directly.
What's so great about common transitions?
If you have a transition you need to create which is accessible from multiple points in your workflow, you could end up creating multiple duplicate instances of that transition, all of which are different.
This quickly becomes a nightmare if you are setting up post functions or other sorts of validations in that transition because you'll need to edit the transition in multiple spots.
How to Create Common Transitions
It's not hard but you will need a decent text editor and a rudimentary understanding of XML, or even HTML.
Step 1: download the workflow you want to fix from the workflows page (Admin, Workflows) and open it in your editor.
Take a moment and look at the file. You'll see the XML has several sections up at the top. One key section to call out is the "common actions" section. The tag is
<common-actions>. In there, you'll see some sections like this:
<action id="2" name="Close Issue" view="fieldscreen">. This one represents the "Close Issue" transition and will show up in the UI in Italics because it is in the "common actions" section. Naturally that XML tag is only the opening tag, so you'll need to have the closing tag too, which looks like this
</action>. You should also note that this has an "id" value in the action tag. For "Close Issue" the ID is "2" in this example.
So now that we know "Close Issue" is a common action, you can scroll down through the XML to find an instance where it is used. Look for the section
<steps> and you'll see something like this:
<step id="4" name="Resolved">
<meta name="jira.status.id">5</meta>
<actions>
<common-action id="2" />
...
What this shows you with the last line is that in the "Resolved" step, there is going to be a close button. To do it, it's just referencing the common action for "Close Issue" by using the ID for it, e.g.
<common-action id="2" />
Tip: JIRA's built-in IDs tend to be lower digits than ones created after JIRA installation, which tend to be in the 700's or 800's. Here's an example from one of my workflows:
<action id="751" name="To Review" view="fieldscreen">
Common transitions are created in the "Common Actions" area of the XML file and they are later referenced in each workflow step. That's how you can simplify your workflows so that when you edit one transition that is shared across the workflow, it changes everywhere. You just need to edit the XML and move at least one instance of your transition into the common actions section, and then put in a new reference to it in each workflow step.
Let's walk through that last paragraph.
Step 2: Find the action you want to move within the workflow step and move it to the common actions section.
For my example, I am looking for an action called "Send To Test" so I can move it into a Common Action.
<step id="4" name="Resolved">
<meta name="jira.status.id">5</meta>
<actions>
<common-action id="2" />
<common-action id="3" />
<action id="781" name="Send To Test" view="fieldscreen">
Aha! The last line indicates which chunk of XML I need to move into common actions. Above it, you can already see other common actions referenced (ids 2 and 3 are for "close" and "reopen" in my workflow).
Cut the entire "action" tag, making sure to catch the closing tag as well. Move it into the Common Actions section at the top of the file. I wouldn't bother updating the ID because you won't be sure if any of those IDs are used in other JIRA workflows, so don't change it. Put it at the end of the Common Actions section just before the
</common-actions> tag.
Step 3. Add the reference to your new common actions in the workflow step where you removed the transition. For me, it looks like this::
<common-action id="2" />
<common-action id="3" />
<common-action id="781" />
You'll need to put this reference into any workflow step that needs it.
Save the file and upload the XML back to JIRA and you are done!
Acknowledgements
Neal Applebaum was an early contributor to how to do this on the
JIRA Forums.
