This documentation relates to version 4.0 of the Structure Plugin for JIRA and subsequent patch releases. Documentation for previous versions is available via Documentation Index.

Skip to end of metadata
Go to start of metadata

26th of April, 2017

Structure 4.0 brings Excel-like functionality to JIRA with the new Formula column.

Download the latest Structure and Extensions
Structure Demo Server 


1. Version Highlights

  • Formula column

  • Work Logged column for a specific user

  • Making content static when copying or cloning a structure
  • Exporting structures to other add-ons

2. Changes in Detail

Sample Calculated Column configuration

2.1. Formula Column

With Formula column, any user can perform some calculation on every item in a structure and display the result in the Structure grid. It is very similar to how formulas are used in Excel or other spreadsheet software.

To add a formula to your Structure view, click "+" at the top right corner of the grid, just like when adding a new column of other type. Scroll down to the bottom of the list and select "Formula..." to write your own calculated expression, or select one of the metrics from "Calculated" section.

When configuring Formula column, you can define the calculated expression using Expr Language. It allows you to use values coming from issue fields, Structure-provided attributes (like totals) and other formulas. The values can be combined together, using arithmetic operators and more than 70 functions, to arrive at a single numeric or text value. Not only is that value displayed in the Structure grid, but it can also be used to sort the structure (just click on the column header) or to group items with the same value together, using Text Attribute grouper.

The potential applications for Formula column are truly limitless – from all kinds of metrics to status reports to cramming different information into a terse text. Structure 4 comes with just a few examples like "Percentage of Bugs" and "Weighted Shortest Job First" metric, but any user (not necessarily a JIRA administrator!) can set up their own formulas.

Documentation: Formula Column, Expr Language, Expr Function Reference

Keyboard shortcuts:

  • Ctrl+| (or Command+| on Mac) to add a new column.
  • Shift+Enter when editing a formula to have it saved and verified; hit Enter to continue editing.

2.2. Work Logged by User

The Work Logged column has been around for a while already – it shows total amount of time logged during a specific period (for example, during last week).

In Structure 4, this column has an additional "Author" option. By default, it is empty and the column shows the total work during the selected period for all users – as it did before. If a user is selected, then only work performed by that user is considered.

This lets you build a work distribution report for a small team – just add several Work Logged columns and select a specific user in each.

Oh, and, by the way, you can use the value from Work Logged column in a formula!

Documentation: Work Logged Column

2.3. Making Static Copy of a Structure

Manage Structure page in Structure 3 lets you create a copy of a structure. Additionally, you can opt to create clones of all issues in the structure and populate the new structure with clones. See Copying Structure and Cloning Issues for details.

Starting with Structure 4, you have an additional option that governs what happens with Generators and the dynamic content that they produce. (As a reminder, dynamic content is something that gets updated automatically when things change in JIRA. It is created by generators – see Automation feature description and Structure 3 Quick Start Guide.)

You can decide to leave the same generators in the new structure (so they would provide similar content), remove generators altogether (which means removing dynamic content as well), or to remove generators but replace the dynamic content with a "static" copy. The latter option is especially interesting as it allows you to "freeze" a structure in time so that further changes in JIRA do not affect the composition of the structure.

Documentation: Copying a Structure

2.4. Exporting Structures to Other Add-ons

We have made it possible for other add-ons to provide additional options in the Export menu on the Structure Board.

At the moment, we have integrations with the following products:

  • Pivot Report add-on can be used for additional analysis of your issue data. The latest version already has integration with Structure, just open Structure Board and select Export | Pivot Report.
  • Xporter is a solution for exporting your issues to various formats, including Word documents and PDF. Starting with version 5.1, Xporter will add Export | Xporter for JIRA menu on the Structure Board that will let you create nice-looking documents with all issues from the structure. Headings in the document are arranged according to the hierarchy in the exported structure.

We are also working with a few other add-on vendors on more integrations.

2.5. Notable Fixes and Improvements

There are a number of issues addressed and improvements added in Structure 4.0. The following are worth mentioning:

  • Fixed: "Show all sub-items of matching items" option for Filter Transformation doesn’t work.

  • Fixed: JQL Completion doesn’t work in the query input.

  • Fixed: "Exclude duplicates" setting is ignored during Export.

  • When migrating from Structure 2.x, avoid long-running backups by turning off the "Backup History" option.

3. Supported Versions

Structure 4.0 and all extensions support JIRA versions from 7.1 to 7.3.x. All editions of JIRA (JIRA Core, JIRA Software, JIRA Service Desk) are supported. JIRA Data Center is supported.

This release is backwards-compatible with Structure 3.4–3.6. Structure extensions – Structure.Pages, Structure.Testy, as well as Colors plugin and other plugins that integrate with Structure 3.4 or later should work with the new version.

4. Installation and Upgrade

4.1. Installing Structure

If your JIRA server does not have Structure yet, the installation is simple:

  1. Download and install Structure add-on, either from Atlassian Marketplace or from Download page. Pick the correct version based on your JIRA version!
  2. When Add-on Manager reports about successful installation, click Get Started to visit a page with important guidance for the JIRA administrator. You may want to also check out the user's Get Started page, available under "Structure" top-level menu.
  3. Monitor catalina.out or jira-application.log for log messages from Structure.

4.2. Upgrading Structure

If you're upgrading from version 2.11.2 or earlier, please read Structure 3.0.0 Release Notes.

Upgrade procedure from versions 3.x is simple:

  1. Consider backing up JIRA data. Use Administration | System | Backup System. (If you have a large instance and have proper backup strategy in place, you may skip this step.)
  2. Back up Structure data. Use Administration | Structure | Backup Structure menu item. If you have a lot of structures and a large JIRA, consider turning off "Backup History" option to avoid long backup process.
  3. Install the new version of the plugin.

  4. Monitor catalina.out or jira-application.log for warnings or errors.

5. Enterprise Deployment Notes

Structure 4.0 does not have a lot of core changes compared to Structure 3.6.

5.1. Formula Column Notes

The largest feature – Formula Column – is completely new and will not affect how the rest of the product is working. However, the feature itself is open to all users – anybody can add a formula and start calculating the values for structures. The Expr language engine is very fast, however, a lot of calculations on large structures may result in general slowdown due to constant retrieval of issue values. This is an unlikely event though, and if there's a really large structure that could cause such trouble (100,000 issues or more), it would produce the load on JIRA server regardless of the Formula column.

5.2. Access to User Properties

Structure 4 has the ability to extract custom user properties, defined in the JIRA's user management section. In a vanilla JIRA installation, there are no properties, but one can use them for defining, say, the hourly rate of a user or a category of a customer. These properties can be used in Formula columns, based on some user field.

The side effect of this improvement is that user properties become visible to everybody, because anyone can use Formula or Attribute column to display them. If you'd like to keep the users from gaining access to these user properties and disable attributes that provide them for the formulas, you can turn on structure.userPropertyAttribute.disable system property. (Add -Dstructure.userPropertyAttribute.disable=true to startup script and use System.setProperty("structure.userPropertyAttribute.disable", "true") in Script Runner on a running JIRA, then re-enable Structure.)

5.3. Copying and Cloning Structures

The updated Copy / Clone feature provides more opportunities to start cloning a large number of issues. Like in other cases, this may be a problem if a structure is large enough or has an unbounded generator that produces a lot of issues.

The feature has sufficient warnings to the user, notifying them about the number of issues that are about to be cloned. If, however, you need to turn Copying/Cloning off for your JIRA instance, please let us know and we'll provide instructions about how to do that.

5.4. Backup

Please create Structure backup before upgrading. Turn off Backup History option unless you really need it.

5.5. Testing on Staging Environment

You can try load testing and stress testing Structure 4.0 and JIRA on a staging environment before upgrading.

It makes sense to test the following parts:

  • Open large structures and add multiple predefined columns from Calculated section. (See the description above about Formula Column feature.) Do that from a number of client computers using different user accounts.
  • Run a copy & clone of a large structure with dynamic content.

The usual load and stress testing can also be applied.

Should you have any questions on Enterprise Deployment, let us know at