Structure Integration

In this page

What is Structure?

(supported since Better PDF Exporter 8.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 PDF documents 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 detailed PDF documents using the issue-fo.vm template:
  • A hierarchical Table of Contents section is exported to the first page.
  • The structure index "1.2.1" is exported for each item.
  • A title-like element is exported for folder items.
  • Memo description is exported for memo items.
• You can export structures to table-format PDF documents using the issue-navigator-fo.vm template:
  • 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 the PDF.
• You can export structures to IEEE-standard Requirements Specification documents using the requirements-specification-fo.vm template:
  • A cover containing the project logo (from the first issue item), structure name, author (current user), revision (current date), and abstract (the structure's description) is exported to the first page.
  • A hierarchical Table of Contents section is exported to the second page.
  • The structure index "1.2.1" is exported for each item.
  • A title-like element is exported for folder items.
  • Memo description is exported for memo items.
  • Issue type, priority, status and links are exported for issue items.
• You can export structures to Release Notes documents, by exporting the unique issue items with the release-notes-fo.vm template.
• You can export structures to timesheets and invoices, by exporting the unique issue items with the timesheet-fo.vm 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 PDF exports

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

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

• It supports PDF automation.
  You can export, email and attach PDF 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 PDF templates.
• It supports all the powerful PDF features.
  You can use custom calculations in Groovy (sorting, complex math, data integration, etc.), embedded attachments, PDF bookmarks, charts, graphics (in Groovy, SVG, QR codes and barcodes, etc.), among others.
• It is integrated with all the popular Jira apps.
  You can freely combine Structure data and other apps' data in the same PDF 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

Jira issues — even issues managed by third-party apps — can be exported from Structure to different types of custom PDF documents with Better PDF Exporter:

Structure PDF export samples

Configuration

Exporting structures

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

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

Configuring the Structure PDF templates

There is a new configuration parameter in the top part of the issue-fo.vm, the issue-navigator-fo.vm, and the requirements-specification-fo.vm templates, which selects between exporting all supported structure items or the issue-type ones only:

## set to "true" to export issues only from the structure (skip folders, memos, etc.)
#set($exportOnlyIssuesFromStructures = false)

When exporting from Structure, issue-fo.vm behaves differently in the following aspects:

1. Exporting structure items will not add a page break after each item. (This is because there are item types that have very little information to export, like folders having nothing else, but an index and a name. If the template exported these to their own page, it would result in near-blank pages.)
2. It exports a Table of Contents section to the first page.
3. It uses the structure's title as the document title.

Like everything else, these can configured in the template:

#if($structure)
	#set($startIssuesOnNewPages = false)
	#set($exportToc = true)
	#set($title = $structure.name)
	#set($issues = $structure.getItems($exportOnlyIssuesFromStructures))
#end

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 PDF 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 PDF templates

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

For that, add this code snippet to the top part of your template (before iterating over $issues):

#if(($pdfViewContext == 'STRUCTURE') || ($automationRuleId && $title.contains('structureId')))
	$scripting.execute('structure-tool.groovy')
	#if($structure)
		#set($title = $structure.name)
		#set($issues = $structure.uniqueIssues)
	#end
#end

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 $title is set to the structure name, while $issues is overwritten with the structure items.

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

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

Possibly, the most typical problem is if the template uses the issue keys as IDs of the document elements for bookmarking or internal linking purposes. With duplicated issues, the document will break, because the same issue key is assigned to multiple IDs which are expected to be unique, obviously. To fix this, use issue key plus the Velocity loop counter to guarantee uniqueness:

<fo:block id="$xmlutils.escape($issue.key)-$velocityCount">
	Hello world!
</fo:block>

Automating Structure exports

In many situations, you want to export the structures automatically (without manual actions) and email, save the exported PDF documents, 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 PDF Exporter offers powerful automation for any type of PDF exports, also including the exports related to Structure data. Automation rules are explained in details in the PDF 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 PDF 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-fo.vm template, 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)