How I built a Forge application to map teams to boards in Jira

[#1]

I previously published a post about a Forge application that I’d written called the "Issue Status Helper" and thought it might be useful to share another example of how I've used Forge to help Jira meet our specific project management needs.

This application has a number of similarities with the Issue Status Helper application but touches on a few different modules and capabilities that are worth exploring. In particular these are the new and improved UI Kit, Jira Custom Fields and GraphQL.

The application is called “Jira Board Buddy” and allows you to map teams to boards for a project and enforce that mapping for issues within the project. First let’s dive into the problem that I was using Forge to solve…

The problem

I’ve been part of a long term project involving multiple teams working together to deliver a number of different milestones.

We’re using Jira Plans (formerly known as Advanced Roadmaps) to plan and track progress on the project. We’re using a combination of Release and issue hierarchy to track milestone progress. Each milestone is mapped to a higher level issue (2 levels above Epic) and we’ve set up an automation rule that automatically updates the Release field as issues are moved between hierarchies. This means that we can get an accurate reading of milestone progress and quickly identify any issues that put delivery at risk.

We decided to ask teams to share a single company-managed project as the Release field is scoped to projects. With more than 10 teams contributing to the project we wanted to give each of them their own scrum board to work from.

Each board was configured with a JQL that mapped issues in the project to the team that they were assigned to.

Although a recent change means that the team field will now be automatically set when creating an issue on a board that uses the team field in its JQL filter, this doesn’t cover all issue creation paths that aren't initiated from a board.

Unfortunately the Team field cannot be made mandatory on issue creation and this meant that quite often there would be confusion as to why created issues couldn’t be found on boards and who would be responsible for the resolving the issue.

I decided to create a Forge application to address this problem. Although I couldn’t do anything to make the Team field mandatory I was able to create a new custom field (called “Workstream”) that could be made mandatory.

The “Workstream” field isn't just be a simple alias to the existing Team field but also provides some additional benefits:

• It constrains Team field assignment to teams that are actually working on the project

• It ensures that issues are only assigned to sprints associated with the board that the assigned team work from

• It provides better visibility of what the assigned team are responsible for (particularly important since many of the team names at Atlassian have no relation to what the team owns or does!)

Installation and setup

This app is now available on the Atlassian Marketplace if you’d like to try it out (and I'd particularly welcome feedback on it!)

To get the most out of it requires a little bit of post-installation configuration, so let's dive into that first...

The “Workstream” field is not mandatory by default so you’ll need to update your configuration if you want to ensure users select a team (this isn’t essential, but is recommended).

I'd recommend that create a new “Field Configuration Scheme” and a new “Field Configuration” and associate that scheme with the projects that you want to use the Jira Board Buddy with. This will ensure that you don't impact other existing projects.

The Field Configuration allows you to make the “Workstream” field required and the Field Configuration Scheme allows you to map that field configuration to different issue types (for example you might not want this for all issue types).

Once you’ve created your field configuration and scheme you can associate it with the projects where the “Workstream” field is required.

Finally you need to add the “Workstream” field to each screen in the project.

Unfortunate it’s not possible for the application to do all of this on your behalf because it really requires an understanding of how the entire Jira instance has been setup.

Mapping Teams to Boards

You can now start mapping teams to boards (if you don't already have teams set up then you'll need to create some first).

Project the Project Settings page select "Board Buddy" from under the "Apps" expanding section in the sidebar and this takes you to the main mapping configuration screen (shown in the screenshot below):

Once you have created your team to board mappings and enabled “the enforcer” (using the toggle control) you can start to use the “Workstream” field.

If you already have an existing project that you’re enabling the Board Buddy for then you will have existing issues without the Workstream field set. The field will prompt users to set a value:

Any change to an issue in the project will trigger the enforcer to check the validity of the team and sprint and automatically correct any errors if it can.

When the enforcer is disabled any invalid sprint or team settings will be highlighted in the issue view:

When team and sprint settings are valid the issue view will just show the relevant information:

The end result should be that all issues created have a team set and can only be assigned to sprints on the board that the team uses. This should ensure that boards only contain the right issues and the right sprints and that issues are not assigned to teams that don't work on the project.

We've been using the application on our project and it has helped ensure that the right teams are connected with the right work. There is less confusion about which team to assign issues to when they are created.

How the application was built

This is another example of how you can use Forge to quickly address requirements that you have that Jira doesn’t currently satisfy (the bulk of the application was written during an Atlassian ShipIt day)

The application consists of 4 modules:

• jira:customField - Adds the “Workstream” Custom Field to Jira

• jira:projectSettingsPage - Adds a page on accessible to project admins for configuring the team to board mappings

• jira:projectPage - Adds a page that allows all project users to view the mappings

• trigger (listening for avi:jira:updated:issue and avi:jira:created:issue events) - to automatically enforce the configuration

For the custom field I used UI Kit and for the project pages I used Custom UI.

UI Kit

There is a lot of overlap with this application and the previous application that I built. However there are a few interesting differences worth diving into.

The Custom Field uses UI Kit to render the interface. This is the new and improved UI Kit and not the original UI Kit (now referred to as “UI Kit 1”) and offers a lot more flexibility. This is well worth exploring if you have been using Custom UI.

One of the main advantages of UI Kit is that it is reusing the same version of components that used on the host product. This means that this application will automatically update with the visual refresh changes that have been recently announced in particular the icons automatically update and be kept in sync with the design applied to the instance!

Custom Field

The main thing to consider when creating a custom field renderer is to ensure that you address both the edit and display requirements (which may be different) and will be displayed in different contexts. There are many different places where a custom field will be displayed and unfortunately not all of them are catered for yet but issue creation and the main issue screens are covered.

The edit UX is rendered in a modal dialog and allows you to not only select the team but also change the sprint.

Trigger

The trigger function is the enforcement of the mapping is handled. Both issue create and issue edit events are reacted to and this trigger leans heavily on the Jira REST API to check the issue data with the stored mapping and the existing Team and Sprint fields.

One of the interesting challenges is knowing exactly which fields you're working with and in particular the "Workstream" field will be registered with an unpredictable ID which means it's necessary to actually search for right ID. 

Learning how sprint values are both set and reported was also an interesting experience and I would recommend leaning heavily on both tools like Postman and the Developer Console when debugging during development.

GraphQL

The REST API isn't the only way to access data from Jira. Another option is to use the GraphQL API. This was actually essential for fetching the data for the Team picker in the mapping configuration page.

Teams are cross product and cannot be retrieved from product APIs directly so need to be fetched using GraphQL. One thing to be aware of is that you can't call the GraphQL API directly from Custom UI so you need to define functions in a Forge Resolver that you call from the Custom UI React code using the invoke bridge method. 

Summary

Hopefully this article provides another good example of how you can effectively use Forge to meet your specific needs that aren't otherwise fulfilled by Atlassian products.

I'd strongly encourage everyone to give Forge a try if they haven't already as I've repeatedly found it to be an invaluable way to tweak Jira to meet our project management needs.

Obviously the Jira Board Buddy is not an application that everyone will need, but if you find it useful then I'd love to get feedback on it or suggestions for how to improve it.

Thanks for reading!