Documentation Overview
- Introduction
- Rich text editor
- PDF document layout
- Handlebars inject Jira issue data in template
- Handlebars helpers introduction
- Handlebars helpers list
- Jira issue JSON structure
1. Introduction
Easy Exporter to Documents 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.
- Enter the issue numbers for preview and download in the input field e.g. MO-1,MO-2
- Press the "Toggle Preview" button to see the rendered template in the editor
- Press then "Download PDF" button to download a rendered PDF file
- Press the "</>" editor button to switch the editor from text mode to html mode
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.
- Handlebars basic usage
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 attachments
{{{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)
- Jira helpers single issue
- Jira helpers sprints
- Jira helpers multiple issues
- Tempo Timesheet helpers
- Generic helpers
General Handlebars 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)
|
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.
- fields - Contains all data of the Jira issue e.g. name, priority, summary...
- renderedFields - How the jira issue is displayed in the browser e.g. the description is html
- changelog - Contains the change log of the issue
- tempo - Contains the Tempo timesheet data (if Tempo Timesheet is installed and token is set in settings)
Below is an example of the top level issue JSON structure. The solution gives you full support browsing through the structure.
