Structure Integration

In this page

What is Structure?

(supported since Better Excel Exporter 5.2.0)

Structure helps project portfolio managers visualize, track and manage projects with an adaptable, user-defined, spreadsheet-like issue hierarchy.

Structure integration features

• You can export Excel spreadsheets directly from the Structure screen.
• Supported structure item types: folder, memo, issue, and all generators (also known as automation items).
• Dynamic structures are supported via generators. Generators are automatically executed before exporting. Then, the resulted issues are exported, the generators themselves are not.
• You can export structures to hierarchical Excel spreadsheets using the structure.xlsx template:
  • Excel rows are grouped to reflect the structure's hierarchy. (Grouping works up to 8 levels, the maximum depth supported by Excel.)
  • Columns are automatically detected from the current structure view. (If you make changes to the columns, don't forget to save those before exporting again.)
  • Supported columns: Issue Key, Summary, Icons, and all field columns (except the aggregation feature, like "sum" for spent time). Unsupported columns are silently skipped.
  • The Summary column displays the left-indented structure index next to the summary, like "1.2.1 My favorite folder", to represent the depth of the items.
  • The Issue Type column displays "Folder" or "Memo" for the folder and memo items.
  • The Description column displays the memo description for memo items.
  • The Icons column, which can display multiple icons (e.g. for the priority and for the assignee), is exported to separate columns in Excel spreadsheet.
• You can export the unique issue items plus their comments from structures to Excel spreadsheets, using the issue-navigator-with-comments.xlsx template.
• You can export the unique issue items plus their worklogs from structures to Excel spreadsheets, using the issue-navigator-with-worklogs.xlsx template.
• You can export the unique issue items plus their change history from structures to Excel spreadsheets, using the issue-navigator-with-history.xlsx template.
• You can export structures to Created vs. Resolved reports, by exporting the unique issue items with the created-vs-resolved-report.xlsx template.
• You can export structures to workflow reports (average and total time in status, SLA, etc.), by exporting the unique issue items with the workflow-report.xlsx template.
• You can export structures to worklog reports (average and total time per project, user, etc.), by exporting the unique issue items with the worklog-report.xlsx template.
• You can easily integrate structures and the hierarchy to any other default template and any custom template, using the structure-tool.groovy script.

(Need more features? Tell us in a support ticket!)

Structure integration vs. the Structure built-in Excel exports

You may want to ask: if Structure has a built-in Excel export feature, why would you use another app for the same?

While the Structure built-in Excel exports may be sufficient for basic use cases, the Better Excel Exporter integration is more powerful in, at least, these:

• It supports Excel automation.
  You can export, email and attach Excel files using Automation for Jira (visual automation rules), ScriptRunner (Groovy scripts), or the REST API (use your favorite language!).
• It is extremely customizable.
  Instead of accepting the pre-defined export types in Structure, you can define your own types via Excel templates.
• It supports all the powerful Excel features.
  You can use Excel formulas and functions, custom calculations in Groovy (sorting, complex math, data integration, etc.), charts, pivot tables, pivot charts, Visual Basic macros, among others.
• It is integrated with all the popular Jira apps.
  You can freely combine Structure data and other apps' data in the same Excel file.
• It comes with powerful templates optimized for Structure.
  You can use those "as is", or customize them to your needs.
• It is well-documented with the customization guide, the Expression Reference Manual, the recipes, and such.

If at least one of these is important for you, give the app a try.

Tutorial video

Generate native Excel reports from the Jira data you manage in Structure, right from the Structure UI:

Structure Excel export samples

Configuration

Exporting structures

There is nothing to do. Better Excel Exporter will add the Excel views enabled for the "Structure" context to the Export menu of the Structure screen. Therefore, you can export the current structure to Excel with one click.

For configuring automation actions to email, save, and attach structures as Excel spreadsheets, see the automation guide.

Limiting the exported Structure items

By default, only the first 1000 items are exported from a structure, in order to avoid unexpected load and memory consumption during the Excel export. The limit can be configured in the structure-tool.groovy script:

/**
 * Upper limit for the items to export.
 */
static def MAX_ITEMS = 1000

Note that the limit applies to all types of items, not to issues only! For example, if the first 1000 items contain 5 folders and the template exports only the issue-type items, then 995 issues will be exported. The final count can be even lower, if there are duplicated issues among those 995 and the template exports unique issues.

Exporting structures from custom Excel templates

Any template that iterates over the issues collection can be easily modified to support structures.

For that, execute structure-tool.groovy script in the top part of your template (before iterating over $issues),

<mt:execute script="structure-tool.groovy"
   test="${(xlsViewContext == 'STRUCTURE') || (automationRuleId && title.contains('structureId'))}"/>

Then change the main iteration like this:

| <jt:forEach items="${issues = (structure == null) ? issues : structure.getUniqueIssues()}" var="issue"> | ... | </jt:forEach> |

What it basically does is that it checks if you are manually exporting from the Structure screen or if you are exporting in an automation action. If so, then it executes the Groovy script which collects the structure items. If those are found, then $issues is overwritten with the structure items. (Note the assignment syntax in the expression at the "items" attribute: not only the result is passed to "items", it also overwrites $issues!)

There is one important detail to be aware of! Structure allows the same issue appearing multiple times within the same structure. Using structure.getUniqueIssues() will remove the duplicated issues, only keeping the first occurrence of each. It absolutely makes sense in most templates (e.g. in Created vs. Resolved reports).

If, for some reason, you want to keep duplicates, use structure.getIssues() instead. If you do so, make sure that the template doesn't break when exporting duplicated issues!

Automating Structure exports

In many situations, you want to export the structures automatically (without manual actions) and email, save the exported Excel spreadsheets, or attach those to Jira issues. It is possible to start automations either in regular intervals (ex: every weekday morning 8:00AM) or when some event happens (ex: a new critical-priority bug is created).

Better Excel Exporter offers powerful automation for any type of Excel exports, also including the exports related to Structure data. Automation rules are explained in details in the Excel automation tutorial.

Follow the guides in that article with one important distinction: when you configure the automation action, encode the structure ID and the structure view ID in the action's Title field. Steps:

1. Open the structure you want to export (automatically).
2. Select the structure view you want to use in the export.
3. Open the Export dropdown.
4. Click the Structure (Excel) menu item.
5. Check the URL in the browser's address bar. You will find a fragment like this: structureId=3&structureViewId=7.
6. Write this JSON string to the Title field of the automation action, using the two numbers you found in the URL:

   {"structureId":3, "structureViewId":7}

7. Save the automation action's configuration.

Doing so, the automation action will export the structure identified by structureId using the view identified by structureViewId.

Note that the structureViewId parameter is used only by the issue-navigator-with-comments.xlsx, issue-navigator-with-history.xlsx, issue-navigator-with-worklogs.xlsx and structure.xlsx templates, to export those columns that are visible in the given Structure view. Other templates are not working with the concept of the view and its columns, unless customized so.

Learn more about Structure

• Structure product information (at its own vendor)
• Structure documentation
• Structure app page (on the Atlassian Marketplace)