How do I install a license provided by Xpand IT?
Once you have a license provided by Xpand IT, 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 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 App "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 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
You might need to specify the template context.
Just replace issueKey and template parameter values with the ones that you need.
In issueKey, you can set several issues separated with ;. Example:
You can also provide a JQL statement as an input parameter, instead of providing a list of issues. Example:
It is also possible to specify the break type, use breakissues=on and breaktype=(break option). Example:
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:
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 and the Field Security Plugin for Jira. For some reason, unknown to the Xporter 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 to hours:
%{${RemainingEstimate}/(60*60)}
Example to convert from seconds to 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 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 your 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.jiraxporter 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".
Is there any task that should be done when Jira is Upgraded?
If the Jira home folder is changed, you have to make sure that the folder named "ExporterTemplates" exists there. This folder contains all the templates created on Xporter, if the folder does not exist, Xporter won't be able to generate reports.
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, ".")}
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.
- Go to the Manage Apps Administration Screen
- Click over Xporter for Jira
- On the App details get the SEN in the section highlighted bellow.
Xporter is disabled when installing on Jira 8.16.0
This happens because the Jira Cloud Migration Assistant app needs to be updated.
- To update the app, select All apps and then search for Jira Cloud Migration Assistant.
- Then you have to click on update request and wait for the request to be accepted
- While the request is not accepted, you can disable the Jira Cloud Migration Assistant app and activate Xporter
- Xporter is compatible with Jira Cloud Migration Assistant 1.5.1
What should I do whenever I move my Jira platform (not to cloud) and use Jira backup
Whenever you install Jira again because you migrated to the data center or changed the infrastructure where Jira is running and to put the data in Jira we use Jira Backup, to take all data from Xporter, we recommend that before deleting the Jira home from your old environment copy the ExporterTemplates folder and place it in the same place in the new infrastructure or use Xporter's Export and Import functionality to backup your Xporter data and then import it into your new Jira.
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.
If you are using Javascript with fields that contain special characters (line breaks, quotes, etc...) you will need to use the escape function along with that field mapping.
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 at this issue.
How can I add comments to my template (aka code comments)?
There is no Xporter Mapping representing comments, but you can use Word Comments to workaround this.
This way you can have a self-explaining template.
