FAQ

How do I install a license provided by Xpand IT?

Once you have a license provided by Xpand IT, you should perform the following steps:

• Go to "Manage Xporter for JIRA", section "License Management"
• Click on the button "Click here to install a license directly from Xpand IT"
• Put your license in the text box. Remember, this should be a license provided by Xpand IT and not via Atlassian Marketplace
• Click on add
• After the executing the previous steps, your license should be installed.

How can I replace my marketplace license with a license provided by Xpand IT?

If you need to replace your marketplace license with a license provided by Xpand IT, you should perform the following steps:

• On your JIRA Administration, select the option "Manage Add-Ons"
• Click on the Add-On "Xporter Plugin for JIRA". Detail about the plugin will be shown
• Edit the license key, and remove all the text, then click on "Update". Your marketplace license has been removed.
• Go to "Manage Xporter for JIRA", section "License Management"
• Click on the button "Click here to install a license directly from Xpand IT"
• Put your license in the text box. Remember, this should be a license provided by Xpand IT and not via Atlassian Marketplace
• Click on add
• After the executing the previous steps, your license should be installed.

How to externally use the Xporter for JIRA as an API to generate documents from Issues

You can directly call the Xporter for JIRA servlet which generates the Documents. An example of such request is:

http://jirahost:8080/plugins/servlet/jiraxporter?issueKey=ELECTRIC-3&outputType=pdf&template=Sample.docx

Just replace issueKey and template parameter values with the ones that you need.

In issueKey, you can set several issues separated with ;. Example:

http://jirahost:8080/plugins/servlet/jiraxporter?issueKey=ELECTRIC-1;ELECTRIC-2;ELECTRIC-3&outputType=pdf&template=Sample.docx

You can also provide a JQL statement as an input parameter, instead of providing a list of issues. Example:

http://jirahost:8080/plugins/servlet/jiraxporter?outputType=rtf&template=AgileCard&jql=project%20%3D%20DEMO%20AND%20issuetype%20in%20(Bug%2C%20Story)%20ORDER%20BY%20summary%20ASC

It is also possible to specify the break type, use breakissues=on and breaktype=(break option). Example:

http://jirahost:8080/plugins/servlet/jiraxporter?outputType=pdf&template=Sample.docx&breakissues=on&breaktype=issues&jql=project%20%3D%20DEMO%20AND%20issuetype%20in%20(Bug%2C%20Story)%20ORDER%20BY%20summary%20ASC 

Also, please certify that you are performing this request on behalf of a user that has the correct permissions to use the plugin. If you need to authenticate with a specific username and password, just add the parameters os_username and os_password to the request. Example:

http://jirahost:8080/plugins/servlet/jiraxporter?issueKey=ELECTRIC-3&outputType=pdf&template=Sample.docx&os_username=joe&os_password=secret

Cannot open in Microsoft Word the templates that I download from the plugin administration. What is the problem?

There is a known incompatibility between the Xporter for JIRA Plugin and the Field Security Plugin for JIRA. For some reason, unknown to the Xporter for JIRA Plugin Team, the Field Security Plugin for JIRA is corrupting the files that are downloaded in the Administration.

If you have this problem, and you want to download your templates, just temporarily disable the Field Security Plugin for JIRA, download your templates, and re-enable the Field Security Plugin for JIRA.

Converting Time Fields to Days or Hours

Time fields (OriginalEstimate RemainingEstimate and TimeSpent)  are stored internally by JIRA in seconds. If you need to convert those fields into units of days or hours, you can make use of Javascript.

Example to convert from seconds into hours:

%{${RemainingEstimate}/(60*60)} 

Example to convert from seconds into days (replace 8 with the number of working hours per day as defined in your JIRA Configuration:

%{${RemainingEstimate}/(8*60*60)} 

Iterating more than one level of links

Xporter for JIRA only allows to directly iterate one level of Links for an issue. If you want to iterate the linked issues of the linked issues, you should do it as provided in the example below:

Issue ${Key} has ${LinksCount} links. Below is the list.
#{for j=LinksCount}
   Linked Issues of ${Links[j].Key}:
#{for m=JQLIssuesCount|clause=issuekey in linkedIssues (${Links[j].Key})}
      Linked Issue ${JQLIssues[m].Key}
#{end}
#{end}

Rollback to a previous version of the plugin

If you need to rollback you installation to a previous version of the plugin, perform the following steps:

• Uninstall your current version of the plugin: Navigate to your JIRA administration, section Manage Add-ons, select the "Xporter for JIRA Plugin" and click on "Uninstall".
• Download the version that you want from https://marketplace.atlassian.com/plugins/com.xpandit.plugins.jiraxporter/versions (Click over the version and choose "download this version")
• After executing the previous step, also in the Manage Add-Ons page, select "Upload Add-on", browse to the file downloaded in the previous step.
• The plugin should now be installed with the previous version.

How to enable debug logging

If you need to enable logging for the plugin, you should perform the following steps:

• Go to the JIRA Administration, section System
• Selection option "Logging & Profiling"
• In section "Default Loggers", click on "Configure logging level for another package"
• Set the Package name to com.xpandit and Logging Level to DEBUG and click on Add.

Once you performed the previous steps, you should reproduce your problem and retrieve the atlassian-jira.log file. To find the location of this file, go to your JIRA Administration, option System > System Info. In the section "File Paths", you have a location in the field "Location of atlassian-jira.log".

Installing manually a version of the plugin

Whenever you need to install manually, by file upload, a new or old version of the plugin, download the plugin .obr file and perform the steps explained in https://confluence.atlassian.com/display/UPM/Installing+Add-ons#InstallingAdd-ons-Installingbyfileupload.

How to export a number custom field with thousands of separators 

You can export a number custom field with thousands separator using JavaScript. Example:

%{'${NumberCustomField}'.replace(/\B(?=(\d{3})+(?!\d))/g, ".")}

When used in bulk export, my template provides incorrect results. Why?

Most likely you are hitting a known limitation of the add-on. Check this FAQ and this issue.

How to retrieve issues from the parent issue

If you want to get fields from the parent issue of a subtask, we will need to use JQL Iteration. The iteration will only be made for a single issue. Example below:

#{for i=JQLIssuesCount|clause=key = ${ParentIssueKey}}
  Parent Key - ${JQLIssues[i].Key}
  Parent Summary - ${JQLIssues[i].Summary}
  Parent CustomField - ${JQLIssues[i].MyCustomField}
#{end}

Finding your Support Entitlement Number

Before you begin: To see the SEN in the Universal Plugin Manager, you must log in with JIRA Admin permissions.

1. Go to the Manage Add-ons Administration Screen
2. Click over Xporter for JIRA
3. On the Add-on details get the SEN in the section highlighted bellow.

Common Troubleshooting

Javascript not being correctly evaluated

If your javascript placeholders are not being correctly processed, try to look to your JIRA log files, they should display the reason for the error. There are some common causes for this kind of problems:

• You have line breaks in the middle of the Javascript code
• You have not used the correct quote character for Javascript Strings. Please assure yourself that you always use the single quote character and not other similar characters. Sometimes Microsoft Word replaces the single quote with curly quotes.

Some Unicode characters are not appearing in the export result

Most likely the fonts that you are using are not installed in the JIRA server machine which is running under Linux.

Most of the DOC and DOCX documents that you will convent were probably created by people using Microsoft Word on Windows or Mac OS operating systems. Those people used fonts that were available to them to format the documents. Therefore most fonts that are used by DOC and DOCX documents will be "Windows fonts" or "Office fonts" e.g. the fonts that are installed with Microsoft Windows or with Microsoft Office. These fonts include Arial, Calibri, Cambria, Century Gothic, Courier New, Garamond , Tahoma, Verdana, Wingdings and many others

There is a number of Linux packages that contain Microsoft TrueType fonts that you can download and install onto your Linux machine. The exact steps might be different on different Linux distributions.

On Ubuntu, go to the Synaptic Package Manager. Find and install the ttf-mscorefonts-installer package. 
On openSUSE, go to Yast2, Software Management. Find and install the fetchmsttfonts package. 
Use Liberation Fonts which are licensed under OFL and are an alternative to standard Windows fonts: Arial, Times New Roman, and Courier New. 
For font packages for other Linux distributions, please search the documentation and the internet.

After installing the fonts, you may need to restart JIRA.

Images referenced in wiki markup or HTML are not correctly rendered in the document

This problem usually happens when your JIRA instance is running in HTTPS and JIRA's Java Runtime is not able to download the images due to problems with the SSL Certificate. To resolve this problem, please try the solution available at https://confluence.atlassian.com/display/JIRA/Connecting+to+SSL+services.

When making a bulk export, the resulting document has incorrect content

There is a known limitation that can be causing this problem. To be correctly used in bulk export, the templates cannot have more than one section. We are working on a solution for this problem, take a look into this issue.

Missing Application Accesses for Xporter for JIRA Cloud

In order to work properly, Xporter for JIRA Cloud requires the following Application Accesses ( when they're available): JIRA Core and JIRA Software. Any other Application Accesses are optional. When Xporter for JIRA Cloud does not have the required application accesses and a user tries to make an exportation, an error message will be thrown and no document will be generated. We are working on a friendly solution for this problem, take a look into this issue.

An example of an Application Accesses configuration for Xporter for JIRA Cloud is shown bellow: