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.


General Handlebars helpers

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

Handlebars helpers developed for this solution

  1. Jira helpers
  2. Tempo Timesheet helpers
  3. Generic helpers for Jira and Tempo Timesheet

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

2. 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}}

3. 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

1. Jira helpers 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}}
{{{jLinks links option}}} The helper takes all issue links and shows it in a nice formate togheter with icons

Parameters
links - The issue links array
option - "issue" will show the links in a simple row. No option will show the links in a table structure (optional)

Example
{{#each jira.issues}}
{{{jLinks fields.issuelinks}}}
{{/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}}
{{jIcon name height width}} The helper shows the icon for a Jira issue type

Parameters
url - The name of a Jirra issue type
height - icon height with default value 16 (optional)
width - icon width with default value 16 (optional)

Example
{{#each jira.issues}}
{{{jIcon fields.issuetype.name "24" "24"}}}
{{/each}}
{{{jPB}}} Page break for the PDF

Parameters

Example
{{{jPB}}}
{{jHrs worklogs decimals}} In the Jira issue worklog the time is specified in a specific Jira format "4w 3d 4h 5m". This helper returns the number of hours for this format. Please note that one week is calculated as 5 days

Parameters
worklogs - issue worklog array
decimals - number of decimals with default value 1 (optional)

Example
{{#each fields.worklog.worklogs}}
{{jHrs fields.timespent 1}}
{{/each}}
{{jHrsTotal allIssues decimals}} The helper returns the total time spend in hours for all issues in the allIssues array. The work time used is the value set in fields.timespent which is the sum of all worklog items

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

Example
{{jHrsTotal jira.issues}}
{{jCost worklogs hourRate}} In the Jira issue worklog the time is specified in a specific Jira format "4w 3d 4h 5m". This helper cost caluclated by time multipled with hourRate. Please note that one week is calculated as 5 days

Parameters
worklogs - issue worklog array
hourRate - hour rate as integer (optional)

Example
{{#each fields.worklog.worklogs}}
{{jCost fields.timespent 14}}
{{/each}}
{{jCostTotal allIssues hourRate}} The helper returns the total cost for all issues in the allIssues array. The work time used is the value set in fields.timespent which is the sum of all worklog items

Parameters
allIssues - Jira issue array
hourRate - hour rate as integer (optional)

Example
{{jCostTotal jira.issues 14}}
{{jTaxTotal allIssues hourRate taxPerc}} The helper returns the total tax only for all issues in the allIssues array. The work time used is the value set in fields.timespent which is the sum of all worklog items

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
{{jTaxTotal jira.issues 14 15.5}}
{{jCostTaxTotal allIssues hourRate taxPerc}} The helper returns the total cost and tax for all issues in the allIssues array. The work time used is the value set in fields.timespent which is the sum of all worklog items

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
{{jCostTaxTotal jira.issues 14 15}}

2. 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}}

3. 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}}


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