Document toolboxDocument toolbox

This article is for Data Center. Visit Cloud

Structure Best Practices

Owned by Jaramy Conners
Last updated: May 16, 2024
11 min read

Because all organizations are different, and teams within those organizations are different still, Structure was designed to be versatile and flexible enough to handle a diverse range of unique use cases.  Therefore, there is no single, best strategy to rolling Structure out across an organization. However, there are best practices which can be utilized to reduce disruption and maintain peak performance levels.

We will review these best practices, collected from our experience as well as customer feedback.  It is important to understand that the best practices referenced here were developed with optimal system performance at the core.

Important information regarding Performance Considerations can be found below.

Initial Considerations

Organizations New to Jira

If you have Structure as part of your Jira solution and your organization is still new to Jira, it may be best to consider the solution as a whole. That is to say, include it in your basic Jira onboarding process. A lot of our training material and resources are well suited to this.  There are plenty of solutions consultants who can help with training as well.

Organizations Established in Jira

It is highly recommended to proceed with an incremental rollout in this situation.  By utilizing Structure configurations, you can select specific groups and/or projects that will have access to Structure initially.  You can then expand the access as your teams become more familiar.  To add an additional layer of control to the roll-out, you can also limit the type of access each user or role has to read or edit structures.  Typically, the first groups should be your champions - those who may have recommended Structure in the first place and whom you will rely on to guide additional users through best practices.

For detailed instruction on how to adjust permissions, read Global Permissions


Basic Terms & Principles

Automation

Automation uses generators, i.e. special rules, that tell a structure what issues to show you from Jira and where to place them within the structure. Whenever a structure is open, these generators are running and rebuilding your structure as changes are happening to the associated Jira data.  In this way, you know that your structure is always up-to-date and relevant

To learn more about Automation a good how to video can be found here: Generators

Generators

  • Insert - pulls in an initial set of issues, from which the rest of the structure is built
  • Filter - hides some issues, or certain levels, from the structure
  • Sort - reorders issues by the values in a specified field
  • Group - organizes issues under the values of a field
  • Extend - adds additional issues based on links to the issues already in the structure

Generators can only be added under a “static” part of the structure.  In other words, anything that was not populated by another generator.  Below are the two most common locations & their use case.

  1. At the top of the structure - this will apply the generator to the entire structure. This is the best option if you need to organize the entire structure in the same way.

  2. Under a folder or issue - this limits the generator to just the items beneath that folder or issue. This allows you to combine several sets of issues in one structure and organize them differently by adding different generators under each folder.

Learn more about how to set up Generators here: Adding a Generator

Reminder: In order to add additional generators, you must first select the top line of the structure (to apply it to the entire structure) or the folder or static issue (to apply it to only a part of the structure).


Things to Keep in Mind

Before we get started setting up a structure, there are a few key items to keep in mind as you get going.  These are important to maintaining desirable performance levels. 

  1. Extend generators should have limited levels .  The default is set from 1-10.  We recommend adjusting for 1-2.

     Click here to read more...

    When added to a structure, an Extend generator checks every configured level in the structure to determine whether issues at that level need to be extended. For example, a Linked Items Extender will check every issue in every configured level to see whether or not a specific link type is present, and add linked issues whenever necessary. Checking an individual issue for links doesn't take long, but checking thousands of issues may.

    When configuring extenders, we recommend limiting the scope to just those levels that need to be extended. This will prevent your structure from checking unnecessary issues and can provide a significant performance improvement for large structures.

    See Generator Scope for more information

  2. Use Filter generators sparingly .  Adjust the initial insert generator query instead.

     Click here to read more...

    It’s not only the final number of issues in a structure that is important. It's also important to check the number of issues before any filter generators are added. 

    For example, if you add an Insert generator with several Extend generators, they may pull 100k issues into the structure, but then a Filter generator may remove most of those, so you only see a few thousand issues. Even though it looks like a small structure, it still has to add all those original issues (and then put extra effort in to remove most of them), which could result in very poor performance

  3. Aim for multiple, specialized, structures .  Avoid large “all encompassing” structures.

     Click here to read more...

    Some structures are simply too large or too complex to be loaded as fast as desired. This may be fine for infrequently-used structures, but for structures that are used every day by multiple users, we recommend either decreasing the size of the structure (see above) or splitting the large structure into two or more smaller structures. 

    For example, instead of having a global structure used by all teams, create several smaller structures specific to each team for day-to-day use, and reserve the larger global structure for cross-team planning sessions.

Common Approaches to Building

Top Down

We recommend utilizing this approach when a full overview is needed. Specifically where it is important to roll-up data such as estimates, time spent and progress from lower levels all the way to the top. It is strongly recommended to limit access to the appropriate users, such as project and program managers. We do not recommend using this method for a team's main structure for daily work or as the default structure.

 Click here to read more...

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.

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

It is strongly recommended to set the Levels option for all Extend generators - this will make everything more consistent and help with performance (especially in larger structures). In the example above, you'd set the Levels to Current level only for the first Link Extender. To pull in stories under epics, you will set the levels option: 2 to 2, since the Epics are on the second level, and we don't need to check if there are any stories under stories. The sub-tasks extender would then be applied to levels 3 to 3.

Focus on a Level

This approach is best for when you want to see how the scope of issues you are responsible for fits into the full hierarchy.  For instance, you want to view the stories from your sprint and visualize which Initiatives and/or Epics they fall under, as well as the sub-tasks they are comprised of.

 Click here to read more...

You may be wondering why this scenario would not call for the Top Down approach as well. You are, after all, trying to view a Parent > Child > Grandchild hierarchy. The difference here is in the focus. We are primarily interested in the Child, or middle level of the hierarchy. For performance reasons, we would not want to pull in all of the top level, Parent, issues, just to filter some or most of them out.

A better approach in this situation is 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. In this case, we would 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 Group generator, 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 need.

Visualize the Entire Scope

When you are in a hurry, but also want to make sure you didn't leave anything behind, this approach will come in handy.

 Click here to read more...

This is a very quick and easy solution. It can also be very resource intensive. We recommend utilizing it only in situations where you are limited on time and are looking to populate from a particular project, component, version, team, etc. In other words, the more specific the focus the better.

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 generator to pull in the child issues like we've done before. The important difference in this case is that as you add Extend generators, you will be getting duplicate issues - one instance of the child issue is added to the top level by the Insert generator, and then another is added by the Extend generator. To hide the duplicates, proceed to the next step.

  3. Add the Remove Inserter/Extender Duplicates Filter generator - this will hide any issues added to the top level by the Insert generator if they were also added later by an Extend generator. Any issues that are not duplicated will remain on the top level.
  4. The Extend generators 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.

It is very important to set level parameters for extend generators 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 Extend generators 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.

Performance Considerations

Automation

When evaluating Automation performance, there are several factors that come into play

  1. The size of structures (the number of issues in each structure).
  2. The complexity and the depth of structures. The more levels a structure has, the more calculations need to be done to build it.
  3. Number of concurrent users editing large structures.
  4. The frequency of usage. If you have a really large structure that is used on a daily basis or is set as the default structure, this may have a negative effect on the server performance. On the other hand, a very large structure that is only used by a small group of managers when they really need it would have minimal impact.

The number of structures with generators does not affect the performance - if a structure is not opened, its generators are not running.

To reduce the risk of Automation affecting Jira performance, we have introduced the Automation Timeout feature. This feature stops generation if it exceeds a certain, user-defined time period. The user is then able to adjust the generator settings. See Automation Paused for more details.

Progress, Totals and Formula Columns

The Jira fields used in columns, by themselves, have little impact on performance. They are loaded only for the structure elements which are currently displayed, in addition to a number of items below and above (to ensure smoother scrolling).

However, for progress, totals and some formulas, the values are loaded for the entire hierarchy. This is due to the fact that such columns aggregate data across the entire hierarchy. For structures with thousands of issues, this can become noticeable. This is still far less of an impact when compared to loading the hierarchy itself.

Structure on Issue Page

Users can see structures on the main Structure Board, on Jira dashboards, the project page and on the issue page.  A structure which is visible in any of those locations requires generation of the structure.

For high traffic projects, this could affect performance significantly. It is recommended to use smaller and simpler structures as your default structures. To learn more about selecting the default structure for the Issue Page, see Structure Options for the Issue Page.

You can also remove the Structure widget from the Issue Page completely.

S-JQL

S-JQL is an extension for JQL that allows you to run structure-based queries. Every time such a query is executed, the structure that is used in the query will be loaded. If you create a saved filter with S-JQL for a large structure and use it heavily somewhere, performance may begin to suffer.

Monitoring & Troubleshooting Structure Usage

The best way to check statistics on Structure usage, see structure sizes and assess load time is by reviewing the Performance Audit Log (PAL). For detailed information on the type of data which can be found in the PAL, as well as how to interpret it, additional information can be found here: Monitoring and Troubleshooting Structure Usage

Additional Resources