Introduction

Xporter is a useful Jira plugin that allows you to create fully customizable templates of various formats for exporting Jira issues.

Templates are based on regular, e.g. word and excel, files in which variables in Javascript representing Jira fields are inserted. All formatting is done in Word/Excel itself giving an intuitive what you see is what you get experience. It can then be exported as PDF, if desired.

Furthermore, some simple calculations, conditions and loops can be realized with a bit of Javascript – except these, no coding knowledge is required.

Walkthrough: Creating a Template

As an example, we will create a template for creating a regular employment contract. We assume, all relevant data of the company, the salary, the employee, etc. is stored in Jira somwhere.

Mark dynamic elements

Contracts usually contain static sections, e.g. the escapce clause, some variables, e.g. name and address of the employee, and some conditional static sections, e.g. company car compensation starting at a certain level. At the beginning, analyse the template and mark all dynamic elements, i.e. variables and conditional sections, and make a list of all variables.

Check and map variables

As exports will mostly be done of single issues, we have to make sure that the respective issue we are creating the template for contains all the dynamic information we would like to include. With the list of variables, check the issue for their existence. In case an information is not yet present in the issue, create a new custom field and add it to the issue’s screens.

For the existing custom fields, we have to determine their exact name (original name and not the translation).

Insert variables

After having gathered all relevant information in regards of dynamic input, variables with names and IDs, we will insert the variables in the template.  Generally, a variable is inserted with the following notation:

${<FieldName>}

If you have two different custom fields with the same name (which should be strictly avoided), you may add the field Id in brackdts as well:

Custom Field ID can be extracted by search the custom field an then clicking on the configure option (see the screenshot ebove). In the URL, there is your CustomFieldID.

Insert all variable in the template and make sure to use the correct formatting of numbers, dates, and various other types of custom fields. As this is a more complex topic, it is covered in the section XPorter#Formatting for different types of fields.

Information regarding the address of a new employee might for example look like this – also note the static elements:

Add the template

Having saved the finished template, go to Administration / Add-ons / Xporter / Templates and click “Add Template” in the top right. Give the template a speaking name and if you know already where it should be used choose the respective scope. Note, that this action requires administrator’s rights.

Manage permissions

On the same screen, navigate to “Xporter Permission Schemes”. Here we can define:

• in which projects Xporter will be available in general,
• which project roles are allowed to use it,
• and which templates are available for which issue types within these projects.

Make sure to correctly configure these three permissions and to have the correct roles, otherwise you won’t see either the Xporter Plugin on the issue page or the template.

Export an issue

Navigate to any concrete issue of the type you just defined the template for. In the top right is a small Box titled “Xporter” where a template and an output format may be chosen. With a click on “Export” the respective document will be created and can be checked for correctness. In case you do not see the box, you may have not have the general permission to use Xporter.

Advanced Features

Formatting for different types of fields

Most of the custom fields have to be formatted, i.e. specifying how the output should be display. Formatting is often a bit tricky because of syntax issues. The following table provides an overview of the field type and their respective formatting.

Issue Links and Linked Issues Values

See this tutorial:

https://confluence.xpand-it.com/display/public/XPORTER/Iterations#Iterations-IteratingIssueLinks

Conditional Blocks, Iterations and further JS Operations

Conditions can be implemented via the following if-clause:

A concrete example might look like this:

Note, that JS operations generally use the following syntax:

All other operations and modifications of Javascript should be possible to implement here as well. The official Xporter documentation provides a good starting point for some functions like iterations, loops etc. but does not limit them.

OR with ||

AND with &&

Negation with ! after {

Example: #{if (%{!’${IssueChecklist[n].Description}’.equals(”)})}

Simple if then else blocks.

Iteration

You can iterate the issues like this

&{for issues}

Key: ${Key}

Description: ${wiki:Description}

&{end}

Example: Listing Attachments (Cloud)

#{if (%{${AttachmentsCount} > 0})}

Name

Size

Creation Date

#{for attachments}

${Attachments[n].Name}

${Attachments[n].Size} Kb

${dateformat(“dd-MM-yyyy”):Attachments[n].Created}

#{end}

#{end}

Example: Listing Comments (Cloud)

#{for comments}

${Comments[n].AuthorFullName} added a comment- ${dateformat(“dd-MM-yyyy”):Comments[n].Created}

${wiki:Comments[n].Body}

#{end}

Automatic Export via Post-Functions

An export can be automatically triggered via a post-function of a transition. The export might then be saved locally, added to the issue as an attachment, or send by email. The post-function is called “Xporter Multi-Action” and provides the option to specify the template, its output format, a dynamically generated filename and the aforementioned actions. Within these actions, further configuration options, esp. for emails, are available.

Iterating through Subtasks of Certain Issue Type

Reading Parent Issue’ Fields

Use ${Parent.Summary} or ${parent.<name of custom field>} if the current issue that is being exported is of type sub-issue (e.g. sub-task).

Useful Links and References

• Xporter Academy
• Xporter Documentation, esp. interesting Formatting