Boja Consulting - Maximise the value of Jira

PDF Issue Exporter - Documentation




Documentation Overview


  1. Introduction
  2. Rich text editor
  3. PDF document layout
  4. Handlebars inject Jira issue data in template
  5. Handlebars helpers introduction
  6. Handlebars helpers list
  7. Jira issue JSON structure


1. Introduction


PDF Issue Exporter for Jira Cloud enables you to export one or multiple Jira issues to pdf templates. Easily create your own templates using the rich text editor or select one of the many available in the template store.


The build in text editor has full support for adding images, tables, styling, fonts and many more features. Work in text edit mode or for power users directly in html. Inject Jira issue data with the powerful and popular template langauge handlebars.



2. Rich text editor


Easily edit the template or write new ones using the rich text editor. Add text, images and tables directly or for full control switch to html mode. Inject the Jira JSON data using the template language handlebars.



Jira issue structure

3. PDF document layout


The solution supports "a3, a4, a5, legal, letter, tabloid" paper size with "portrait, landscape" orientation. Simple add below meta tag to the top in the html view. If the meta tag is missing the default value is a4 and portrait.

<meta format="a4" orientation="landscape">


The solution also supports header and footer. Add the header at the top of the html view and the footer at the bottom.

<div id="pageHeader">Add your page header text here...</div>


<div id="pageFooter">Add your page footer text here...</div>



4. Handlebars inject Jira issue data in template


Jira issue data is injected with the popular template language handlebars. Please find below some examples and links to more information.


Simpel example injecting data

Issue data can be injected in the template both in the editor text mode as well as in html mode. Below examples injects the key of the first issue in the array


In text mode

{{jira.issues.[0].key}}

In html mode

<!--{{jira.issues.[0].key}}-->

Iterate over an array

Shows the key and summary for all issues on seperated rows.

{{#each jira.issues}}
{{key}} - {{fields.summary}}
{{/each}}

Select one issue in the array

Shows the key and priority for the first issue in the array

{{#with jira.issues.[0]}}
{{key}} - {{fields.priority.name}}
{{/with}}



5. Handlebars helpers introduction


Handlebar helpers allows you to execute logic on your data. A Handlebars helper call is a simple identifier, followed by zero or more parameters (separated by space). More then 200 helpers are available with a link below.


Shows the issue descriptor including any pictures or formating. Please note the tripple bracket {{{}}} which is needed if html is returned.

{{{jHtml jira.issues.[0].renderedFields.description}}}


Shows the issue assigne name truncated to max 5 characters

{{truncate jira.issues.[0].fields.assignee.displayName 5}}


Shows all attachments including a image thumbnail for image attachmeents

{{{jAttach jira.issues.[0].fields.attachment}}}


Shows todays date with specified format e.g 01/01/2018 09:00

{{moment date format="DD/MM/YY hh:mm"}}


Handlebars supports having helpers in helpers

{{outer-helper (inner-helper 'abc') 'def'}}


6. Handlebars helpers list


The solution supports 250+ handlebars helpers in the below two main areas.


Handlebars helpers developed for this solution (available with drag & drop)

  1. Jira helpers single issue
  2. Jira helpers sprints
  3. Jira helpers multiple issues
  4. Tempo Timesheet helpers
  5. Generic helpers

General Handlebars helpers

  1. Built-In helpers (part of the Handlebars template language)
  2. Time helpers
  3. Generic helpers

1. Jira helpers single issue Description
{{{jImg url height width}}} The helper shows an image

Parameters
url - image url
height - image height (optional)
width - image width (optional)

Example
{{{jImg "https://www.google.dk/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png" 100 100}}}
{{{jHtml html}}} The helper adds images and formating to the html code

Parameters
html - The html code

Example
{{#each jira.issues}}
{{{jHtml renderedFields.description}}}
{{/each}}
{{{jAttach attachement boxSeize}}} The helper shows the attachments links in a vertical list. If the attachement is an image a thumbnail is shown above the link

Parameters
attachement - The issue attachement array
boxSeize - box size of image thumbnail in pixel. Default is 50 (optional)

Example
{{#each jira.issues}}
{{{jAttach fields.attachment}}}
{{/each}}
{{{jPB}}} Page break for the PDF

Example
{{{jPB}}}
{{jHrs time 1}} The helper returns the issue time spend in hours and minute.

Parameters
time - in the format of numbers or jira time format in string e.g. 1w 4d 2h 10m
decimals - number of decimals with default value 1 (optional)

Example
{{jHrs fields.timespent 1}}
{{jHrsMin time}} The helper returns the issue time spend in hours and minute.

Parameters
time - in the format of numbers or jira time format in string e.g. 1w 4d 2h 10m

Example
{{jHrsMin fields.timespent}}
{{jCost time hourRate}} The helper returns the cost calculated with time multipled with the hourRate

Parameters
time - in the format of numbers or jira time format in string e.g. 1w 4d 2h 10m
hourRate - hour rate as integer (optional)

Example
{{jCost fields.timespent 14}}
{{jExtend key field}} The helper takes an issue key and returns that issue field value. This is needed since not all data of e.g. linked or subtask issues are included in the original issue JSON.

Parameters
key - Jira issue key e.g. MOON-12
field - The field to return

Example
{{#each fields.subtasks}}
{{key}} - {{jExtend key "fields.summary"}}
{{/each}}
{{{jBarcode text type scale}}} Helper that returns 100+ 1D and 2D barcodes. Complete lists of supported barcodes here!

Parameters
text - the barcode text as string
type - barcode type as string default is QR (optional)
scale - scale barcode 1, 2 or 3 as string with default 1 (optional)

Example (The default barcode size is 15*15 mm)
{{{jBarcode self}}}

Example all parameters
{{{jBarcode self "qrcode" "1"}}}
{{{jBarcodeSize text type height width}}} Helper that returns 100+ 1D and 2D barcodes with support setting the size of the barcode. Complete lists of supported barcodes here!

Parameters
text - the barcode text as string
type - barcode type as string default is QR (optional)
height - height in mm as string default 20mm (optional)
width - wisth in mm as string default 20mm (optional)

Example
{{{jBarcodeSize key}}}

Example all parameters
{{{jBarcodeSize key "qrcode" "30" "30"}}}
{{{jStatus status}}} Helper that returns the issue status in the corsponding Jira color.

Parameters
status - the Jira issue status field

Example
{{{jStatus fields.status}}}
{{{jIssueKey}}} Helper returns the issue key linked to the Jira issue.

Example
{{{jIssueKey}}}
{{{jIssueLinks}}} Helper returns a table with all linked issues including icon, description and resolution.

Example
{{{jIssueLinks}}}
{{{jEpicIssues}}} Helper returns a table with all issues inlcuded in the epic. Nothing is returned if the issue is not an epic.

The helper can be used without parameters where a default table is returned. Or 1-5 columns can be configured including column width.

Parameters
column width - column width as string (optional)
column value - issue field to show in column as string (optional)
column value - issue field to show in column as string (optional)
column value - issue field to show in column as string (optional)
column value - issue field to show in column as string (optional)
column value - issue field to show in column as string (optional)

Example One
{{{jEpicIssues}}}

The colums returned are:
Issue key, issue summary, issue assignee, issue priority and issue status

Example Two
{{{jEpicIssues "10,10,10,10,60" "key" "fields.project.name" "fields.priority.name" "fields.status.name" "fields.summary"}}}

2. Jira helpers sprints Description
{{jSprint customerField}} Returns the sprint number
Important - The customerField is unique for each user so you need of find your ID browsing the issue JSON.

Parameters
customerField - The customer field containing the sprint data

Example
{{jSprint fields.customfield_10018}}
{{jSprintGoal customerField}} Returns the sprint goal
Important - The customerField is unique for each user so you need of find your ID browsing the issue JSON.

Parameters
customerField - The customer field containing the sprint data

Example
{{jSprintGoal fields.customfield_10018}}
{{jSprintState customerField}} Returns the sprint state
Important - The customerField is unique for each user so you need of find your ID browsing the issue JSON.

Parameters
customerField - The customer field containing the sprint data

Example
{{jSprintState fields.customfield_10018}}
{{jSprintStart customerField}} Returns the sprint start date
Important - The customerField is unique for each user so you need of find your ID browsing the issue JSON.

Parameters
customerField - The customer field containing the sprint data

Example
{{jSprintStart fields.customfield_10018}}
{{jSprintEnd customerField}} Returns the sprint end date
Important - The customerField is unique for each user so you need of find your ID browsing the issue JSON.

Parameters
customerField - The customer field containing the sprint data

Example
{{jSprintEnd fields.customfield_10018}}
{{jSprintComplete customerField}} Returns the sprint complete date
Important - The customerField is unique for each user so you need of find your ID browsing the issue JSON.

Parameters
customerField - The customer field containing the sprint data

Example
{{jSprintComplete fields.customfield_10018}}
{{jSprintSequence customerField}} Returns the sprint sequence number
Important - The customerField is unique for each user so you need of find your ID browsing the issue JSON.

Parameters
customerField - The customer field containing the sprint data

Example
{{jSprintSequence fields.customfield_10018}}

3. Jira helpers multiple issues Description
{{jAllSum "field"}} Summarize all field values for all exported issues.

Parameters
field - number or string number
hourRate - hour rate as integer

Example
{{jAllSum "fields.timespent"}}
{jAllDiff "fieldOne" "fieldTwo"}} First summerize fieldOne and fieldTwo for all exported issues. Then substract fieldOne minuse fieldTwo.

Parameters
fieldOne - number or string number
fieldTwo - number or string number

Example
{jAllDiff "fields.timespent" "fields.timeestimate"}}
{{jAllTime "jiraTime"}} Jira time addition for all exported issues.

Parameters
jiraTime - String according to Jira time format e.g 1w 2d 14h 2m

Example
{{jAllTime "fields.timespent"}}
{{jAllHrs "field" decimals}} Summarize all field values for all exported issues and return as hours

Parameters
field - Number in seconds or string according to Jira time format e.g 1w 2d 14h 2m

Example
{{jAllHrs "fields.timespent" 1}}
{{jAllCost "field" hourRate}} Returns the caclulated overal cost for all exported issues based on field time.

Parameters
field - Number in seconds or string according to Jira time format e.g 1w 2d 14h 2m
hourRate - cost per hour

Example
{{jAllCost "fields.timespent" 14}}
{{jAllTax "field" hourRate, percentage}} Returns the caclulated overal tax for all exported issues based on field time.

Parameters
field - Number in seconds or string according to Jira time format e.g 1w 2d 14h 2m
hourRate - cost per hour
percentage - VAT in percentage

Example
{{jAllTax "fields.timespent" 14 15}}
{{jAllCostTax "field" hourRate, percentage}} Returns the caclulated overal cost and tax for all exported issues based on field time.

Parameters
field - Number in seconds or string according to Jira time format e.g 1w 2d 14h 2m
hourRate - cost per hour
percentage - VAT in percentage

Example
{{jAllCostTax "fields.timespent" 14 15}}
{{jAllProgress}} Returns the progress calucluated as fields.progress.progress divided with fields.progress.total for all exported issues.

Example
{{jAllProgress}}
{{jAllTimeEpicIssues "field"}} Summarize all field values for all issues in a epic

Parameters
field - issue field as string

Example
{{jAllTimeEpicIssues "fields.timespent"}}

4. Tempo helpers Description
{{jTHrs input decimals}} The helper returns the work hours logged for an issue with tempo timesheet. Please note that the input can be of two types

Parameters
input - Either a tempo array containing the issue tempo worklog items or a integer with seconds
decimals - number of decimals with default value 1 (optional)

Example 1 - Tempo is an array of worklog items. Will write out total worklog time for each issue.
{{#each jira.issues}}
{{jTHrs tempo 1}}
{{/each}}

Example 2 - timeSpentSecond is the time spent for one worklog item. Will write out the time of all worklog items.
{{#each jira.issues.tempo}}
{{jTHrs timeSpentSeconds 1}}
{{/each}}
{{jTHrsTotal allIssues decimals}} The helper returns the total time logged with tempo timesheet for all issues.

Parameters
allIssues - Jira issue array
decimals - number of decimals with default value 1 (optional)

Example
{{jTHrsTotal jira.issues}}
{{jTCost input decimals}} The helper returns the cost for all time logged with tempo timesheet. Please note that the input can be of two types

Parameters
input - Either a tempo array containing the issue tempo worklog items or a integer with seconds
decimals - number of decimals with default value 1 (optional)

Example 1 - Returns the cost for each issue in the jira.issue array.
{{#each jira.issues}}
{{jTCost tempo 1}}
{{/each}}

Example 2 - Return the cost for each worklog item. A issue can have multiple worklog items.
{{#each jira.issues.tempo}}
{{jTCost timeSpentSeconds 1}}
{{/each}}
{{jTCostTotal allIssues decimals}} The helper returns the cost for all logged done time with tempo timesheet.

Parameters
allIssues - Jira issue array
decimals - number of decimals with default value 1 (optional)

Example
{{jTCostTotal jira.issues}}
{{jTTaxTotal allIssues hourRate taxPerc}} The helper returns the tax cost for all issues.

Parameters
allIssues - Jira issue array
hourRate - hour rate as integer
hourRate - tax percentage with the value between 0-100 including decimals e.g. 15.5

Example
{{jTTaxTotal jira.issues 14 15.5}}

The helper first calulates all time logged with tempo timesheet for the issues in the allIssue array. It then calulates the total cost based on hourRate. It then returns the tax based on the percentage in taxPerc on total cost.
{{jTCostTaxTotal allIssues hourRate taxPerc}} The helper returns the total cost and tax for all issues in the allIssues array. This is calculated on all worklog items done in Tempo timesheet.

Parameters
allIssues - Jira issue array
hourRate - hour rate as integer
taxPerc - tax percentage with the value between 0-100 including decimals e.g. 15.5

Example
{{jTCostTaxTotal jira.issues 14 15}}

This equals to {{jTCostTotal}} + {{jTTaxTotal}}

5. Generic helpers Description
{{jMatch lValue rValue option}} Logic operation comparing left value with right value and executing block if there is a match

Parameters
lValue - left value of comparison
rValue - right value of comparison. If comma seperated each value will be compaired to lValue and return true if one or more matches

Example
{{#each jira.issues}}
{{#jMatch fields.issuetype.name "Story,Task"}}
Will be executed if there is a match
{{/jMatch}}
{{/each}}
{{{jColor sla}}} The helper will take a string and color it red if it starts with - othwerise it will color it green.

Parameters
sla - string value e.g. "5" or "-2.74"

Example
{{#each jira.issues}}
{{{jColor fields.customfield_10070.ongoingCycle.remainingTime.friendly}}}
{{/each}}
{{jDec num decimals}} The helper shorten a decimal or integer to the number of decimals specified

Parameters
num - this is the input value in integer or decimal
decimals - Max number of decimals

Example - Will return 12.5
{{jDec 12.567 1}}


6. Build-In helpers
Handlebars comes with a set of build-In helpers. Documentation available here!

7. Time helpers
{{moment date "YYYY"}}
{{moment date "MM"}}
{{moment date endOf="week" format="dddd, DD MMMM YYYY HH:mm:ss ZZ"}}
{{moment date format="dddd"}}-{{moment date add=daysadd format="dddd"}}
{{moment date format="dddd, DD MMMM YYYY HH:mm:ss ZZ"}}
{{moment date format="HH:mm:ss"}}
{{moment date isValid=true}}
{{moment date lang="fr" format="dddd, DD MMMM YYYY HH:mm:ss ZZ"}}
{{moment date lang="fr" format="MMMM"}}
{{moment date startOf="month" format="dddd, DD MMMM YYYY HH:mm:ss ZZ"}}
{{moment date subtract=fiveyearsago format="YYYY"}}-{{moment date format="YYYY"}}
{{moment date utc=null format="dddd, DD MMMM YYYY HH:mm:ss ZZ"}}
{{moment format="MMMM YYYY"}}
{{moment daysInMonth=true}}
{{moment diff=date}}
{{moment endOf="week" fromNow=true}}
{{moment date format="HH:mm:ss"}}
{{moment from=date}}
{{moment unixtimestamp format="HH:mm:ss"}}
{{moment}}

8. Generic helpers
189 helpers in 20 categories with full documentation available here! (search for Categories on the new page)

  • array
  • code
  • collection
  • comparison
  • date
  • fs
  • html
  • i18n
  • inflection
  • logging
  • markdown
  • match
  • math
  • misc
  • number
  • object
  • path
  • regex
  • string
  • url


7. Jira issue JSON structure


The JSON structor contains an array of Jira issues. Each Jira issue has the below four main parts where fields is the key one.




Below is an example of the top level issue JSON structure. The solution gives you full support browsing through the structure.

Jira issue structure


Do you have any questions?
We are happy to support you at support@bojaconsulting.com.

Value

Boja consulting develops Jira addon solutions that help companies increase satisfaction, efficency and output.

Company

Home

Predictable

PDF Issue Exporter

Support

Support

Terms of Service

Privacy Policy

Security

©2016-2018 Boja Consulting AB - Maximize the value of Jira

support@bojaconsulting.com