Customizing Widget templates

BigTemplate allows you to create an unlimited number of templates as well as modify the pre-defined ones and upload them again.

Preparing templates

If you prepare or edit your template in Google Docs, MS Word or OpenOffice file, you need to use the following style name: #BT.task.<fieldname>

Identifiers provided in your template will be replaced with values from Jira issues during the export operation. The formatting used in the file will remain unchanged.

Find out more about the supported fields below. To export attachments, you need to upload a mock image and insert a proper identifier into a mock image.

Preparing templates using styles 

When you open an exported Jira issue document using a document editor such as MS Word or Open Office Writer, you will notice that new styles are available, and you can modify them.

Click here to expand...

A style is a set of formatting characteristics, such as font name, size, color, paragraph alignment, and spacing. Some styles include borders and shading.

Using styles to format your document, you can quickly and easily apply a set of formatting choices consistently throughout your document.

For example, instead of taking three separate steps to format your heading as 16-point, bold, Cambria, you can achieve the same result in one step by applying the built-in Heading 1 style. You do not need to remember the characteristics of the Heading 1 style. For each heading in your document, just click on the heading.

For more information about styles, read this article.

The list of styles can be presented in a separate pane. The Styles task pane can be opened with the keyboard shortcut Alt+Ctrl+Shift+S.

The styles listed in the pane start with the prefix #BT.task. The first word always starts with lowercase and the following ones depending on how they were named in Jira. There are no spaces between words.

You can add a space after the name of a style to add a description to help you identify the desired style:

• #BT.task.summary header
  
  

• #BT.task.summary footer

Supported field types

Jira standard fields

You can find a list of Jira system fields in Jira Administration > Issues > System fields. Creating style names is relatively simple. Let's have a closer look at a few examples:

You can find a list of styles with examples here.

E-mails

Assignee and reporter e-mail support are supported. To make them appear in a document, use the identifiers:

#BT.task.assignee$email

#BT.task.reporter$email

QR codes

Image identifier #BT.task.key$qr generates a QR code with a link to the issue.

Date and format

It is possible to add an identifier to the template, which will be converted into the date and time when the export is generated. Examples:

• for the current date: #BT.task.currentD (-> 31-12-2021)

• for the current date and time: #BT.task.currentDT (-> 31-12-2021 1:47 PM)

The dates exported from the Jira task are saved in the format set in the Jira system (except for the Cloud version).
Dates can be formatted using the following modifiers:

• #BT.task.createdDate$yyyy-MM-dd (-> 2021-12-31)

• #BT.task.createdDate$dd-MM-yyyy (-> 31-12-2021)

• #BT.task.createdDate$MMM/dd/yyyy (-> Dec/31/2021)

Attachments

To export a full list of attachments, you need to add the following identifier to your template: #BT.task.attachments

Custom field types

• Number

• Select List (multiple choice)

• Select List (single choice)

• User Picker (single line)

• User Picker (multiple choice)

• Date Picker

• Labels

• Text Field (multi-line)

• Text Field (single line)

For custom fields, you need to find out how a given field is named in your JIRA instance - the field ID is used for this. To do so, go to JIRA Administration->Issues→Custom Fields:

To obtain the ID, you need to right-click a custom field on your JIRA issue screen and hit Inspect Element - the Id will be clearly shown as a numerical value (10400 as an example below for field 123):

The pattern is #BT.task.custom.<ID-here>. e.g. #BT.task.custom.customfield_10001

Image operations

To export an image from a Jira issue attachment, you need to prepare a template and upload mock images that will be replaced with attached pictures. 

Alignment, boundary, text wrapping, and other settings are preserved even after you replace the image with a different file (the file on a given task).

To connect a mock image to a file from an attachment, it is necessary to insert a link with the identifier to a mock image. 

The identifier convention is: #BT.task.attachments$N where N is a consecutive position of attachment that is an image in the attachment list.

You can modify a template in Google Docs, as presented below. To do so, click on the image attachment and insert the correct identifier. 

Avatars

Use the following identifies to tell the plugin where the avatar should be displayed in the documents:

#BT.task.assignee$avatar

#BT.task.reporter$avatar