Here are some common approaches you can use to visualize your work breakdown structures.

Top-Down Approach

Common use cases:

Such approach works best when you need to visualize the complete hierarchy of issues, starting from the most high-level elements all the way down. For example, a work breakdown structure for multiple projects, with some high-level initiatives on top of tasks that implement those initiatives, which are then broken down into smaller tasks. Such an overview works well for tracking progress across a large project, where it's important to roll-up data such as estimates, time spent and progress from low levels all the way to the top. Once built, you can then drill down to see the particular details - for example, find the tasks which are hindering the progress of an initiative.

Performance considerations:

Because of the nature of the use case, such structures can get pretty big. We are visualizing the entire scope of work. It's not necessarily a problem, but these structures are usually more performance heavy than smaller structures, especially if you have many levels connected by links. It's perfectly fine to use them when a full overview is needed, but it may not be the best approach for a general-use structure utilized by many users on a daily basis.

It's best to keep these structures visible to the appropriate users only - for example, project or program managers. It's not recommended to build such structures for individual teams, which are interested only in a sub set of the structure (we'll cover what to do for them below). Additionally, this type of structure should not be used as a default structure. Default structures are opened by default on the issue page, which means every time a user opens an issue, this whole structure is loaded and then filtered to only show the part of it related to the issue.

How to build:

Start by adding top-level items using an Insert generator, and then use a number of Extend generators to pull in related items. Here are the common steps:

1. Add the Insert generator that will add the top level items. The JQL Inserter is the most flexible option, but it may be desirable to add issues from a particular Agile board.
2. Add Extend generators to pull in child issues. Depending on your setup, you may have to add several extenders to visualize different types of relationships. For example, you could build a 4-level structure as follows:
   • First level - add all Initiatives using a JQL Inserter
   • Second level - add epics under those initiatives with an Issue Link Extender 
   • Third level - add stories using a Stories Under Epics Extender
   • Fourth level - add sub-tasks using the Sub-tasks Extender

Limitations:

Since such a structure is built top-down, we will only see issues that have an incoming link. This may not be convenient when we want to visualize the entire set of issues in the form of a hierarchy. For example, we may want to visualize issues from a number of Scrum Boards. In this case, stories which do not have an epic defined will not be shown in such a structure.

There are several ways to resolve this. One approach is to take the Visualizing the Entire Scope approach.

Another approach is to use the secondary panel to identify the missing issues. Open the secondary panel, select the JQL option and specify the JQL which describes the scope you want to see in a structure. Click the Diff button in the toolbar () to hide issues which are already present in your structure. This will give you all the orphans, which you can now drag-and-drop into the correct positions in your structure.

Focus on a Specific Level

Common use cases:

Often you have a multi-level hierarchy, but are primarily interested in issues on a particular level. For example, you are managing a team that works together with a number of other teams, and you want to see how the scope you are responsible for fits into the full hierarchy. So you would like to see a set of issues you are interested in, and then show the child issues below them and the parent issues above. For example, in a hierarchy where you have Initiative -> Epic -> Story -> Sub-task, you want to see the Stories from a certain sprint and all the related issues - both parents (epics and initiatives these stories belong to) and sub-tasks.

Performance considerations:

One of the options would be to build a full hierarchy as described in the Top-Down Approach and then filter it to show only the part relevant to the user. This approach has one significant drawback - it means you would need to build a really large structure first, and then hide part of it. Even though the issue count in the resulting structure may be low, it will still have a significant impact on performance.

A better approach in this situation would be to start by pulling in the scope you want to see and then use Group generators to show the levels above. This will produce a much smaller structure straight away, and Groupers are more efficient in terms of CPU usage than Extenders.

How to build:

Use an Insert generator to add the initial scope - the issues you are focused on - and then use Group generators to show the parents and Extend generators to show the children. Let's look at an example where we want to build a structure using an Initiative -> Epic -> Story -> Sub-task hierarchy, but only with stories from a particular sprint:

1. Use an Insert generator to add the initial scope. For example, you can use the JQL Inserter to pull in issues from a certain sprint.
2. To add children (in this case sub-tasks), add a Sub-tasks Extend generator (don't forget to set the correct level settings - in this case, Current level only).
3. Next, add a Group by Epic generator to show the direct parents. The stories will be distributed between the epics they belong to. Any stories without an epic will end up in the "No Epic" folder. If the parents are connected to children with issue links instead of epic links, use Group by Issue Links, and select the link type and direction.
4. To include Initiatives above your epics, add a second Group generator. There are two important things you need to do here:
   1. As you add this second Grouper, make sure you select the "Consider other groups" option. Without this option, the generator will try to group not the level we've just created, but the issues that were added by the original Insert generator.
   2. Once the generator is added, reverse the order of these two Group generators in the generators list, so that the one you want to group by first is higher.
5. If there are more levels above - keep adding more Group generators, until you get the highest level you want.

Visualizing the Entire Scope

Common use cases:

In some situations, you need to see a specific scope of issues arranged into hierarchy. For example, you need to arrange issues in a similar manner as we used above (initiatives > epics > stories > sub-tasks), but only from a particular project, component, version, team, etc.

Performance considerations:

The approach to building this kind of structure is very similar to the top-down approach we discussed above. If you make sure to use the correct level settings, the performance impact will be comparable, so the implications are the same.

How to build:

Unlike the top-down approach we used above, where we started with just our top-level issues, in this case we want to start by inserting our entire scope of issues. Then we will use other generators to organize them into the hierarchy. Here is how to build it:

1. Use an Insert generator to pull in all the issues you want to see.

2. Add an Extend generators to pull in the child issues like we've done before. The important difference in this case is that as you add Extenders, you will be getting duplicate issues - one instance of the child issue is added to the top level by the Inserter and then another is added by the Extender. To hide the duplicates, proceed to the next step.

   It's very important to set level parameters for extenders in this configuration - even more so than in the top-down approach. Failing to do so can seriously affect performance. If you do not restrict the scope of Extenders by setting correct levels, you will end up with not just 2 instances of all child issues, but with an instance per level, which can be a lot of issues if you have 4-5 levels. To illustrate, let's use the same example (Initiatives, Epics, Story, Sub-Task). If you do not set the levels for extenders, here is what you will get: On the top level you will see the results of the Inserter. On the second level, you will see the results of each Extender - epics under initiatives, stories under epics, sub-tasks under stories - all duplicates. On the third level, you will see stories under epics and sub-tasks under stories - the third time we see them. And on the forth level you will see the sub-tasks for the fourth time under stories. Even though all the duplicating items can be hidden (see the next step), we still had to build a really large structure first, which will negatively affect performance. If you do set the levels, we'll only get one set of duplicates for each Extender.

   
   

3. Add the Remove Inserter/Extender Duplicates Filter generator - this will hide the issues added to the top level by the Inserter, if they were also added later by an Extender. Any issues that are not duplicated will remain on the top level.
4. The Extenders we have added could pull in some issues which are outside of the original scope we defined. For example, epics in our project can have some stories from other projects too, which the Stories Under Epics Extender would pull in. If we only want to see issues from our original scope, we'll need to add a JQL Filter generator with the same query we used originally.