Documentation

What you need

• Jira Cloud (Jira Software or Jira Service Management).
• The app installed on your site. Installing an app needs a Jira site administrator.
• Word, or any editor that saves .docx files, to write templates.

The app works with the permissions of the person using it. The first time it is opened, Atlassian shows a consent screen. Approve it once.

Your first template in ten minutes

1. In Word, write the document as you always do. Wherever a value from Jira should appear, type a tag in curly braces, for example {issue.key} and {issue.summary}.
2. Save it as a .docx file.
3. As a Jira administrator, open Jira settings, Apps, Document templates, choose Add a template and upload the file.
4. Open an issue, open the ••• menu and choose Generate document….
5. Choose your template, select Preview tags to check every value, then select Generate document.

The document is attached to the issue and offered for download.

Generate a document from an issue

In the dialog Generate document:

• Template: search the library, or pick one of the two built-in samples for a single issue (Issue report and Customer handover and SLA summary). The third sample, Release notes, is made for a list of issues and is used on the Bulk tab.
• Values for this template: fields that people fill in when they generate. Each {params.name} tag in a template becomes one of these fields.
• Output: Word (.docx), PDF (.pdf) or both, and whether to attach the document to the issue.
• File name: a name pattern. Tags work in it, for example Handover {issue.key}. Leave it empty to use the name pattern of the template.
• Language of dates and numbers and Time zone: leave them empty to use your own, or choose others.

Select Preview tags before you generate. It lists every tag of the template with the value it gets for this issue, and marks the tags that found no data. A typo or an empty field is caught before the file reaches a customer.

After Generate document, each file shows whether it was attached to the issue, and you can download it from the dialog. A file larger than about 2.4 MB is too large for that, and the dialog then points you to the attachments of the issue. If you may not attach files to that issue, the file shows Not attached with Jira's message, and the download still works.

You can also generate for any issue from Apps, Documents, Generate by pasting the address of the issue.

Writing templates

A tag is a path into the data of the issue. Everything the issue has can be reached, and empty values give empty text. The Guide tab in the app has more examples, and every example in it is tested against the real engine.

Values from the issue

Issue {issue.key}: {issue.summary}
Status {issue.status.name}, priority {issue.priority.name}, type {issue.type.name}
Assigned to {issue.assignee.displayName | default:"nobody yet"}
Created {issue.created | date:"d MMMM yyyy"}, due {issue.dueDate | date}
Story points: {issue.fields.customfield_10010}
Story points: {issue.fieldsByName["Story Points"]}
Customer: {params.customer}
Made by {user.displayName} on {now | date:"yyyy-MM-dd"} at {site.name}

• Custom fields are reached by their id (for example customfield_10010, which you find in Jira's custom field settings), or by their name with fieldsByName.
• user is the person who generates, now the clock, site the Jira site, and params the values people type in.
• default fills in a text when the value is empty.

Formatted text

Descriptions and comments are formatted text in Jira. {@issue.description} puts the formatting (headings, lists, tables, bold) into your document. The tag must be alone in its paragraph. Use the filter plain to get only the words.

Repeating things

A block starts with {#something} and ends with {/}. It repeats once for every item of a list: subtasks, comments, work logs, linked issues, history.

{#issue.subtasks}
{key}  {summary}  ({status.name})
{/}

• Put the opening and the closing tag in paragraphs of their own to repeat the paragraphs between them.
• In a table, put the opening tag in the first cell and the closing tag in the last cell of a row. The whole row repeats.
• Inside the block, names refer to the item. {$number} counts from 1. There are also $index, $first, $last, $count, $odd and $even.

{#issue.comments | where:"public" | take:3}
{$number}. {author.displayName}: {body | plain}
{/}

Showing and hiding text

{#condition} shows its block only when the condition is true. {^condition} shows it when the value is empty or false. Comparisons, and, or, not, in and contains work.

{#issue.priority.name == "High"}
Escalated to the duty manager.
{/}
{^issue.resolution}
Still open.
{/}

Filters

A filter changes a value: {value | filter} or {value | filter:argument}. Filters can follow each other, and arguments are separated by colons.

Dates and numbers follow the language you choose when generating. Set a language on the template to always use the same one.

Tips

• Type a tag in one go. If Word splits it into pieces (after a spell-check or a format change inside the tag), the app puts it back together.
• Curly braces start and end a tag. To print one, write {chars.open} for { and {chars.close} for }.
• Straight and curly quotes both work inside tags. Spaces around the pipe are fine.
• Tags work in the body, in headers and in footers. For page numbers use Word's own page number field.
• A tag that finds nothing leaves its place empty. The preview lists such tags, so a typo does not go unnoticed.
• Pictures in the template are kept. Pictures from issues are not inserted.

Templates for lists of issues

A template used with a JQL query (on the Bulk tab) starts from {issues}, the list, and {count}. The issues are also grouped for you: byType, byStatus, byPriority, byAssignee, byProject, byComponent and byFixVersion. Blocks can be nested.

{count} issues found.
{#byStatus}
{name}: {count}
{#issues}
- {key} {summary}
{/}
{/}

The template library

Jira administrators manage templates under Jira settings, Apps, Document templates. The Templates tab lists them. Everyone who uses the app can read the list.

• Add a template uploads a Word file in pieces, so large pictures work. A template can be up to 10 MB.
• On upload, the app checks the tags. If a tag is broken, for example a block that is opened and never closed, a banner names it and nothing is saved.
• Details shows the tags a template reads, what it is used for (one document per issue, or one document from a list of issues), and lets you edit the name, description, file name pattern, language and the explanations of the values people fill in.
• Download the Word file and Replace the Word file let you change the template in Word.
• Three built-in samples ship with the app: Issue report, Release notes from a JQL result, and Customer handover and SLA summary. Use Copy to my templates to get one you can change.

Files are refused as templates when they are macro-enabled, old .doc files, password-protected, zip bombs, over 10 MB or structurally broken.

Bulk documents

On Apps, Documents, Bulk, choose what to make:

• A document for each issue: every issue gets its own file, attached to the issue.
• One combined document: a report over all issues, such as release notes for a fix version. It can also be attached to one issue of your choice.

Enter a JQL query and select Check query. Jira's own message tells you what is wrong with a query. Choose the template, set At most how many issues to use, and select Start. The job runs in the background. You can close the page.

• A job handles up to 5,000 issues (1,000 by default), and a site can have five active jobs at a time.
• Open Jobs to follow progress. Stop the job stops it and Resume continues where it stopped. No file is attached twice.
• Jobs show what happened to every issue. Administrators can choose Show the jobs of everyone. Delete the job removes its records and files.
• Combined documents and spreadsheets stay available for download on the Jobs page for 3 days. Job records are kept for 14 days after their last change.

Excel export

On Apps, Documents, Spreadsheet, enter a JQL query and choose the Columns: search the fields of your site, add standard and custom fields, and change the order. Choose a Sheet name and a File name, then Start export.

The workbook has a bold header row that stays in place when you scroll, filters, real Excel dates in your time zone, and links on the issue keys. A second sheet, Query, keeps the JQL. Cells that look like formulas are stored as text.

Jira Automation

In Jira Automation, add the action Generate document from template to a rule, for example when an issue is transitioned, created or commented. Its inputs are:

The document is attached to the issue. Errors, for example an unknown template name, appear in the audit log of the rule together with up to ten of the template names that exist.

The action runs as the user the platform runs the rule as. When the platform has no user for that run, it runs as the app itself, and the app is then the author of the attachment.

About the PDF

The PDF is made from the finished Word file, inside Atlassian, with no external conversion service. It is a clean rendition, not a pixel-perfect copy.

• Included: styles, lists, tables with merged cells and repeated header rows, pictures (PNG and JPEG), links, headers and footers with page numbers.
• Left out: text boxes, shapes, footnotes and columns. The Word file keeps them.
• The font is Roboto, embedded in the PDF (monospace text uses Courier).
• Page size and margins come from the Word file.

Limits

• Templates are written in Word. There is no template editor inside Jira.
• Pictures from issues are not inserted into documents.
• A template can be up to 10 MB, and a bulk job handles up to 5,000 issues.
• The PDF leaves out text boxes, shapes, footnotes and columns.
• Support for your own templates is limited to explaining how the tags and filters work.
• Microsoft Word and Excel are trademarks of Microsoft Corporation. This app does not use Microsoft software and is not affiliated with Microsoft.

Permissions and data

The app reads Jira data as you, and its only write is adding files to issues. Templates and job records are kept in Forge storage on your site for the periods listed in Security. See also the Privacy Policy.

Need help?

See the support page for how to reach us, what to include and answers to common questions.