How I built a Forge app to keep Jira issue hierarchy in sync

[#1]

Hello! I’m Dave, a software engineer from the Ecosystem Platform team.

In 5 years I’ve been at Atlassian I’ve previously worked in the Portfolio for Jira Server, Advanced Roadmaps and Design System teams and this article brings together my experiences from working in all those different spaces.

I’m going to describe how I’ve recently built an application on Forge to solve a particular use case in our organisation and have released it to the Atlassian Marketplace so that others can benefit from it.

The application is fairly simple but addresses a specific feature gap in Jira to help with the program management of cross team projects in Ecosystem Platform.

The scenario

There are over 20 teams that work in Ecosystem Platform. Each team owns different parts of the platform but often have to come together to deliver a cross-cutting feature. Often relating to a broader company wide initiative.

We use Advanced Roadmaps to capture the work relating to each cross-team project in a single plan. We’ve added additional issue hierarchy levels of “Program”, “Workstream” and “Initiative” above the standard “Epic” level and all the work for a cross-team project will typically have a single Program level issue as root ancestor. This allows us to build a plan based of a JQL filter using the portfolioChildIssuesOf query.

The problem

Program Managers can use these plans to get a simple visualisation of progress, how much work remains, when the work is expected to complete and can identify blockers between teams.

However we find that individual engineers working at the story level issue often forget to update the epic level issues they belong to (and sometimes aren’t even aware of the initiative level and above issues they relate to).

The result is that plans often show inaccurate status at the high level.

Imagine this fictitious, but realistic example (Please Note - the following examples and screenshots are of fake projects and plans created to illustrate the problem. I used GDPR as an example of a previous project that would be understandable as a cross-cutting concern).

Atlassian needs to support GDPR across it’s portfolio of products. This is what the plan looks like:

At first glance it appears that the project has not yet started. There are no dates on the roadmap and all the issues are still in the "TO DO" status.

However, the progress bars for "PP-1" and "JIRA-1" are suggesting that some work within the hierarchy has already been completed.

Expanding the initiatives and epics indeed reveals that some story level issues are
"IN PROGRESS" and another has already been "DONE". The engineers have not remembered to update the parent issues and dates are not appearing (this might be because the start and end dates cannot be inferred - perhaps because the team is using Kanban rather than Scrum!)

The solution

The outcome of this behaviour was that there was a lack of trust in the roadmaps and although it was easy to spot these discrepancies and manually fix them it was a time consuming process.

I decided to try to automate the changes and after initially experimenting with Jira Automation I decided it was a good opportunity to build a Forge application to solve the problem.

My idea was to create an application that would detect when an issue was changed and then see how it’s own status compared with that of it’s siblings and parent.

So when the first story in an epic is started the epic should be started (and if that epic is the first epic in an initiative to be started, the initiative should be started, etc). When the last story in an epic is completed the epic should be marked as complete.

I also wanted to start setting start and end dates when the transitions occurred in order to help build an accurate roadmap of past events to help plan the remainder of the delivery.

Before jumping into how I built the application, let’s look at what the output looks like with it running.

At a glance you can now see that Jira has started work and when the work was started (if not yet when the work is planned to complete). The information is readily available without needing to expand all of the issues that descend from the initiative level issues.

Comments are also added to an issue when it is changed to help reporters, assignees and watchers understand what is happening.

How the application was built

The application is built using Forge and uses two modules:

• trigger
• jira:adminPage

The trigger module is invoked whenever a product event is fired and in this case the event the application is listening for is a transition change in any issue.

Jira workflows can be complicated though and it is not always possible to automatically determine which status to transition an issue to. Therefore I wanted to create a page for Jira admins to be able to to configure which projects should automatically update and which transitions and date fields to use.

The "jira:adminPage" module adds a link to the side-navigation of a the “Manage Apps” page that loads a Forge UI extension that can either be defined using UI Kit or Custom UI (I used Custom UI in this case but in the future it should be possible to create the interface using UI Kit 2)

The configuration page looks like this:

The interface for the application configuration is entirely built from Design System components and heavily leans on the new “primitives” (which at the time of writing are in Open Beta - but when you read this might be generally available!).

Using these primitives enabled me to quickly build a complex layout without needing to write any custom styles. Everything was created using a combination of the Box, Inline, Stack and Grid primitives and uses space token values to ensure consistency the Jira

Building the interface with Design System components meant that the application immediately supported dark mode with close to zero effort:

Fetching the project, issue type and status data from Jira was easily achievable using the REST APIs called using the "requestJira" function available in Forge Custom UI.

The user preferences for project enablement, status transitions and date fields were saved and retrieved using the Forge Storage API.

Building the application was a very quick process and I had it up-and-running on in less than a week and it’s already having a positive impact on our cross-team Advanced Roadmaps plans.

Conclusion

Hopefully this article will encourage you to reach for Forge when you need to address a particular gap in an Atlassian product that you need to fill in order to unleash the potential in your team!

Forge application development is a great gateway into the Atlassian developer platform and our powerful REST APIs and Design System will help you quickly meet your specific needs!

Please comment below if you have any additional questions or would like more detailed information on any specific aspect of building the app!

If you want to try the Issue Status Helper its available for free on the Atlassian Marketplace.

[Roi Fine]

Amazing Dave!

[Tomislav Tobijas _Koios_]

Wow, really cool! This definitely goes to my list of resources for Forge use cases. Cheers for sharing! :)

[Nicolas Grunberg]

Great work Dave!

[Beau Williams]

This is awesome Dave!

[Rudy Holtkamp]

Hey @Dave , that is really helpful.

I've immediately tested it out and the instant it was used, I also got a complaint about the comments... 😫
Could you please add the possibility to toggle the (type of) comments that are used?

[Dave]

Hey @Rudy Holtkamp , thanks so much for the feedback - I really appreciate it!

Can you give me a little bit more detail on how you'd like it to behave and what you'd like to toggle? I'm assuming when you say type of comment you mean for status changes versus date setting / clearing?

I'm looking at making some updates to the application as we have our ShipIt coming up so would be happy to make improvements!

I'll be honest that I made the app intentionally "chatty" because part of my aim was to help reinforce the message across our org that keeping things in sync was important - I'm actually surprised that no-one has complained to me about it though! 😉 ...I also like to make sure people understand *why* an attribute on an issue has changed, but that's obviously just a personal preference!

I'll look to provide some options for toggling comments globally (I'm not sure if you wanted this on a project-by-project basis) as well as comments relating to date vs status.

The other things I'm going to be looking at were setting an estimated end date when an issue is moved into an "In Progress" category status if it is in a sprint with dates.

I also wanted to trigger updates based on re-parenting (i.e children being added or removed).

Very happy to keep iterating on the app, it's proving very useful for our org and I'm keen to keep tweaking it to help others!

Thanks again for reaching out!!

Regards,

Dave

[Rudy Holtkamp]

Hi Dave,

Thank you for responding so swiftly.

I do understand the educational intent (I support it) of the chattiness.
Because every team wants something different, I would prefer a global setting for comments, where I can set the comment myself (this will also solve a part of the language disclaimer (Currently only supports English on the marketplace.)

And a per project setting as well. Where you can choose, no comment, global comment settings or the project comment settings. 

Since you use the fieldnames and status names, maybe add a help text for the variables that may be entered, e.g. 'start date', 'end date', status-from, status-to, trigger issue, name of the person that triggered the action.

I also wanted to trigger updates based on re-parenting (i.e children being added or removed).

I did not even consider that one, but it will be a great addition.

The other things I'm going to be looking at were setting an estimated end date when an issue is moved into an "In Progress" category status if it is in a sprint with dates

You can also argue that every issue which is added to a sprint (with date) should have the same start and end date, independent of the issue status and if the sprint has started. When the sprint is done and issues are not resolved yet, they either move to a new sprint (and get new dates) or move to the backlog (which clears the dates). What's your opinion on this?

Good luck with ShipIt! 👍

[Dave]

Hey Rudy,

No worries - I'll look to get as much of that added as I can! 

You can also argue that every issue which is added to a sprint (with date) should have the same start and end date, independent of the issue status and if the sprint has started 

This is actually possible in Advanced Roadmaps in the plan settings under "Scheduling". You can choose to infer dates from sprints and then they are rendered on the roadmap exactly as you're describing.

You can also have dates "rolled up" to higher level issues so that Epics, etc are also displayed.

However, in practice I found a few problems with this:

1. Depending on your plan config, resolved issues will not be shown so the higher level dates are based just what is shown in the plan
2. Higher level issues aren't assigned to sprints (as the work might be split across teams)
3. Not all teams use Scrum, some use Kanban
4. Some teams "abuse" the sprint entity and don't set dates correctly, so this has the impact of corrupting the visualisation of the timeline when inferred dates are used

These are the issues that inspired me to create the app. If teams are all using scrum and are using the sprint entity correctly then it's not so necessary.

So for my team you'll typically see the issues start and end date inferred from the sprint until it is moved into an In Progress state.... so the future roadmap is "blocky" (expanded to the future sprint) but the history of completed work is accurate to the day. The change I'm hoping to make will therefore address the middle ground of current work.

Hope that makes sense!

Regards,

Dave

[Rudy Holtkamp]

Your explanation make perfect sense.

One remark about:

This is actually possible in Advanced Roadmaps in the plan settings under "Scheduling". You can choose to infer dates from sprints and then they are rendered on the roadmap exactly as you're describing.

Not all sites have a premium license, so I see a lot of customers use Gantt apps (in any shape or form), but they all rely on a kind of start date field and end date field to show them on the Gantt chart. They mostly don't take sprints into account. Users of these apps will also benefit from syncing of the date fields with sprint dates.

[Dave]

Thanks Rudy, that's a great point about not everyone having a premium license - you're absolutely right that I shouldn't assume that - my apologies.

So do you think that setting start and end dates on assignment to a sprint would be a valuable addition to the app for non-premium customers? 🤔

[Rudy Holtkamp]

It good be, but point 4 will definitely screw up the timeline. So it is a real tricky one.

Maybe implement it in the way you already had in mind and wait for feedback from customers.

[Dave]

Hey @Rudy Holtkamp ,

A quick update - you might have seen that there's a new version of the app on the marketplace... unfortunately I didn't have as much time as I'd hope to work on it, but you can now toggle both setting dates by sprint and commenting on and off on a per project basis.

I'll try and get the custom comments added this week, but can't make any promises - and won't be able to work on it for a few weeks after that, but will resume on it as soon as I can!

Regards,

Dave

[Rudy Holtkamp]

Hi @Dave ,

Great to see the new features. And knowing this is a side project, there is no rush. I appreciate any effort you have put into the app and listening to the feedback .

Regards,

Rudy

[Dave]

Another quick update on this... the code for this project is now available here: https://github.com/atlassian-labs/issue-status-helper 

The idea is that it could be a useful reference for other developers in the community, as this was a side-project you definitely shouldn't expect the code to be perfect, but I'm very happy to discuss any of implementation decisions I made, and this is also a good place to raise issues and suggestions!

Thanks!