Issue Linking has proven to be a very powerful feature for teams using JIRA. However, as an Atlassian Expert Consultant who often works with newer users or teams that are just starting to use JIRA, I find that the Issue Linking feature is not as prominent or easily accessible within the UI as it should be. I’ve worked with JIRA users who have been using the software for years who still had not stumbled upon the Issue Linking features.
In a recent client engagement, the organization’s proposed JIRA structure (following Scaled Agile Framework methodology) necessitated heavy use of Issue Linking. The problem I was faced with was how to prevent users from creating incorrect Issue Links between certain Issue Types, all the while ensuring that the user experience remained as simple as possible. Having to always use the More drop-down to access the Link dialog was problem enough (well at least for the first link for an issue), but on top of that, the user was then confronted with a whole slew of different link types (inward and outward) and would need to be relied upon to know what selection needed to be made in order to convey the correct reason for the linkage.
What I really wanted was a custom field that I could label appropriately, enter multiple issues keys into and automatically create the appropriate issue link using the correct issue link type (whether it be inward or outward). After some extensive reading/research into marketplace add-ons that could help me accomplish this and some deep thought, I came up with what I think is a perfect solution!
Finding the right Issue Picker
If my idea was going to work, I needed to identify a way to allow a user to enter multiple JIRA issue keys into a single field. Restricting the entry to just one issue wasn’t the user experience I was hoping to accomplish. Unfortunately, JIRA does not come with a built-in Issue Picker custom field. While there are a number of Issue Picker fields available as add-ons within the Atlassian Marketplace, a free add-on Query Issues Custom Fields add-on for JIRA Server fit the bill perfectly. Not only does this add-on provide a custom field that allows for multiple JIRA keys to be entered at once, it also provides the ability to restrict which keys can actually be entered into the field via a JQL filter. On top of that, the custom field allows for auto-complete functionality which was icing on the cake.
Configuring the Issue Picker
Once, the Query Issues Custom Fields add-on was installed, creating the custom field was fairly straightforward. You must first add the custom field, which you will find in the Advancedsection. This add-on provides three custom fields, for this post we will be focusing on the Query Issue Multi Linker Custom Field type. Once selected, name the field appropriately. In this post I will demonstrate how to set up a field that automatically creates “is blocked by” issue links, so this field will be aptly named “Blockers”. When presented with which screens to add the new field to, select the appropriate Create screen(s) but no others for now.
Once the field has been created, we can now configure the field using the add-ons configuration screen. The location of the configuration screen is non-standard. You can find it by going to the System page, and then locating the Configure Query Issue Custom Fields link on the left hand navigation menu. You will then see your newly created custom field within the Multi Linking Fields table.
Clicking on the Configure action link, pops up a dialog where you can restrict the JIRA keys that can be entered into the field via JQL (here I’ve restricted the keys to a single project), add auto-complete functionality, as well as providing some JIRA issue field data to the user as they enter keys. For this example I have selected: Key, Status, Assignee, Due, Priority.
Once you click apply, you are brought back to the table that summarizes your fields configuration.
The field is now setup for use, but we now have to tie it into the workflows that we want it to operate with.
Automating the Linking Process
The first step in automating the issue link creation process is to identify which workflows will be using the newly created issue picker field. For this example I am using one of the built in JIRA workflows and have added two post functions to the Create transition which I’ve highlighted in the workflow diagram below.
The first post function to add is the Create Issue Link function that is bundled with the JIRA Workflow Toolbox add-on for JIRA Server. Once this add-on is installed in your JIRA instance, the post function will be available for you to select.
The available configuration options for the Create Issue Link post function are vast, but for this example the setup is extremely simple and straightforward. There are three sections that you need to be concerned about: Issues at source end, Issue Link Type, and Issues at destination end.
For the Issues at source end configuration, simply leave the default selection of “Current Issue”. This tells the post function that the issue being created is the Inward link, or in this case, the issue that is being blocked.
For the Issue link type configuration, select the type of link that you want to create. For this example, we want the “is blocked by” issue link type which happens to be the default selection.
For the Issues at destination end configuration, select the Issues in field option, and choose the custom field that you created earlier. For this example we will select the custom field we created earlier named Blockers.
Once you have completed the above configuration and have added the post function to the transition, you will see an entry like below.
Next, we need to add another post function, Clear Field Value which is available via the JIRA Suite Utilities add-on. If this step gets missed then there is potential for the custom field to appear on the issue view screen. We don’t want that though. We only want to use the custom field as a temporary holder of JIRA issue key data so that the workflow post function that creates the issue links can do its work. Once the links are created the Blocker custom field should be cleared.
Once you have added the two post functions, your list of post functions for the Create transition should look similar to the screenshot below. Notice that the “Creates the issue originally” built-in post function has been moved up to the top of the list. This needs to be in that order otherwise the issue link creation will not occur.
The configuration is done. Ensure that you have published your workflow so that your JIRA users can take advantage of the new functionality!
Issue Linking Simplified!
Now when users create issues, they can quickly create issue links using the custom field that we created and the workflow post functions take care of the heavy lifting. Users, no longer need to know which Issue Link Type they should select and only Issues that should be linked to are allowed to be linked to. I’ve provided screenshots to compare the built-in behavior versus the Simplified Issue Linking behavior that I have provided you with in today’s post.
Both methods of issue linking, whether you use the built-in behavior or the simplified behavior, result in issue links getting created and displayed in the expected Issue Links panel.
Note: In order to simplify the example, I’ve only discussed using this custom field within the Create issue dialog. The same configuration process can be used within any workflow transition, or within a circular transition (source and destination status are the same). A custom screen could be created to only display this particular field during the transition, or you could have a circular transition display a dialog with multiple versions of the custom field (e.g Blockers, Blocks, Relates To, or any custom issue link type).
Jamie Saliga is a Senior Atlassian Expert Consultant at Avant, he has been using JIRA for more than 6 years and has vast experience in JIRA administration and training. Stay tuned for more great JIRA stories.