Checklist before installation
The latest eazyBI version supports Jira versions from 6.0 to 7.13, as well as the upcoming version 8.0. In addition, you will need MySQL 5.5 - 5.7, PostgreSQL 9.x or 10.0, MS SQL Server 2008 or later, or Oracle 10g or later database. The eazyBI plugin should work on Linux, Windows, and macOS. Please contact eazyBI support if you have questions about supported versions or if you have any issues with your specific environment.
For Jira versions from 6.0 to 6.2 only Java 7 is supported. For Jira versions 6.3 and 6.4 also Java 8 is supported by Atlassian (and is bundled with Windows and Linux installation packages). Starting from Jira version 7.0 only Java 8 is supported.
Only Oracle JDK / JRE or OpenJDK JVMs are supported.
Jira memory settings
Please review your current Jira memory settings before installing eazyBI. If your Jira server will not have enough available memory then eazyBI might fail to start as well as overall Jira performance could be affected.
To ensure better performance of eazyBI it is recommended to set Jira Java VM available memory to 1 GB or more (if using Java 8 then the recommended setting is 2 GB or more) and Total PermGen memory to 384 MB or more (512 MB recommended when you have many Jira plugins). See Increasing Jira Memory for detailed instructions how to do it in your Jira installation.
JVM_MAXIMUM_MEMORY=1024m (if using Java 8 then specify
2048m or more) as well as
JIRA_MAX_PERM_SIZE=384m (do not set PermGen memory size if using Java 8) in your
setenv.bat file (if you run Jira as Windows service then please follow Increasing Jira Memory / Windows service instructions instead). Later while using eazyBI check Jira Administration / System / Troubleshooting & Support / System Info / Java VM Memory Statistics page to see how much available memory is used and if it is necessary to increase it more.
If eazyBI plugin startup fails and you get
SystemStackError: stack level too deep errors in
localhost.*.log file (please see Troubleshooting for file location) then you have specified too low
-Xss max stack size setting for Java VM. You can see if this
-Xss option is used in Jira Administration / System / Troubleshooting & Support / System Info / JVM Input Arguments. Please either remove
-Xss option or increase it (recommended setting is
-Xss1024k) until eazyBI plugin starts without “stack level too deep” error.
It is possible to run eazyBI report queries in a separate JVM process. Please read more about the Child process option if you would like to enable it.
You can check your current JVM default encoding in Jira Administration / System / Troubleshooting & Support / System Info / System Encoding.
Download the eazyBI add-on from the Atlassian Marketplace page or install using Jira Add-ons Manager.
You should have Jira system administration rights to install add-ons. Go to main Administration screen and then go to the Add-ons link. Then either find and install the eazyBI add-on from Atlassian Marketplace, or if you have downloaded the add-on then go Manage Add-ons page and upload the downloaded eazyBI add-on file.
After eazyBI add-on installation click the Configure link to navigate to the eazyBI settings page. Or if you click Exit Administration then you should see the eazyBI link in the top navigation bar (next to Dashboards, Projects and Issues).
It might take about half a minute while eazyBI is loading for the first time. If you selected the eazyBI link then you should see the eazyBI welcome page. You should be logged in as a Jira user with system administration rights to set-up eazyBI. Click Set up eazyBI to continue.
eazyBI will store data in an additional MySQL, PostgreSQL, Microsoft SQL Server or Oracle database. You can use the same database server which is used by Jira or you can also use a different database server. It is recommended that you create a separate database user for eazyBI needs (by default with the name
eazybi_jira) which will then create additional databases in a specified database server.
Please make regular backups of the additional eazyBI database in the production environment. eazyBI database contents will not be included in the standard Jira XML backup or in the Jira database schema backup.
The following are database server specific instructions for eazyBI database setup.
If there will be any issues with establishing the database connection or with the database creation then you will see the corresponding error messages after clicking the Update button.
Please read more about the Child process option which is recommended for larger Jira Server instances.
Select license type Atlassian Marketplace (if you created a trial license key there) or eazybi.com (if you received a beta tester license key).
Enter corresponding license key (and also organization name in case of eazybi.com license type). If there will be any issues with entered license name or key then you will see corresponding error message.
If you are using Atlassian Marketplace license and latest versions of Add-ons Manager then license information will be entered in Add-ons Manager and in this screen you will only see current license information.
After you have entered database connection and license information click Update database and license settings to continue.
If you need to return back to eazyBI Settings screen then log in as Jira user with system administration rights and in any eazyBI page click on System Admin link on top right corner and then select Settings.
Perform the first Jira data import
If database connection and license information were correct, then eazyBI database will be created as well as first eazyBI account (with default name “Jira reports”). In one eazyBI account, you can import one or several Jira projects, create reports, charts and dashboards and give access to selected Jira users and groups. If in your Jira server you have many different projects which are used by different user groups then most probably you will need to create several eazyBI accounts and in each account import related subset of Jira projects.
After clicking Create, a new Jira source application will be created and you can
- select which Jira projects you would like to import in first eazyBI account
- select if you would like to import status transitions history
- how frequently a regular issue import should be scheduled (by default once per day)
- select custom fields which to import (read more about supported custom field types)
Click Import to start the issues import.
Check import results
After the import is completed, go to Analyze tab and try to open sample reports.
Export to PDF
If you would like to export dashboard pages to PDF or send regular emails with eazyBI dashboards as PDF attachments then please install the headless Google Chrome browser and Microsoft's Core Fonts on your Jira server (starting from the eazyBI version 4.4.0).
Export of large tables to Excel or CSV
If you will need to export to Excel or CSV tables with many thousand rows then please see Jira server configuration instructions.
REST API request error
eazyBI Jira import will perform REST API requests from the Jira server to itself (which is necessary for Jira Agile and Tempo Timesheets data import). If you see an error
Failed to make a REST API request to the Jira Base URL ...
in the settings page then it means that there are Jira server setup problems which do not allow to make such REST API requests. Potential causes for these problems are the following:
If your Jira server uses an HTTPS connection and you also see the following message:
Please install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files to enable SSL certificate validation for REST API requests
If your java version is >= than 1.8.0_151 then you can set the unlimited policy in the
<JAVA_HOME>/jre/lib/security/java.securityfile search for the line
#crypto.policy=unlimitedand remove the
#character to uncomment it and save the file. You will have to restart Jira to take this into action.
For older versions you need to download the file from the given link (JAVA7 - http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html, JAVA8 - http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html) and copy files US_export_policy.jar and local_policy.jar to the directory <JAVA_HOME>/jre/lib/security (or for even older version in <JAVA_HOME>/lib/security), where JAVA_HOME is the java.home in Jira Administration / System / System Info.
For Java >= 9 this is enabled by default.
The Jira server name (from Jira Base URL) is not resolved to the correct IP address on the Jira server. If you are using a Linux server then try to test it with the following command from the Jira server:
where JIRA_BASE_URL is the Base URL in Jira Administration / System / System Info. Please send the output of this command to eazyBI support if you need help to resolve this issue.
Other potential cause can be port mapping using
iptableswhich probably is mapping ports just for incoming connections and not for local connections.
- You are using Jira version 6.1.4, 6.1.5 or 6.1.6 which have a bug JRA-36276 which prevents local REST API requests. Please upgrade to the later Jira version in this case which have a bug fix for this issue.
Please see the Local REST API requests section in advanced settings documentation to learn more how to disable local REST API requests or to specify a different Jira base URL for local REST API requests.
Microsoft's IIS data import error
If you are using Microsoft IIS web server which proxies the incoming requests to Jira, then you might get an error message when clicking the Import button in the Source Data tab. The potential cause for this error is that IIS can be configured to return custom error messages and IIS is discarding the body of HTTP requests with the HTTP status code 422. To ensure that the HTTP body is returned for these error messages, you need to set the <httpErrors> element attribute existingResponse value to PassThrough.
Please read more about the IIS error page configuration.
If the initial eazyBI page does not open or opens with an error message, then check in the Jira installation directory
logs subdirectory log files with name
localhost.*.log. Please provide these log files to eazyBI support.
After eazyBI has started it will create own log files.
Sometimes after reinstalling add-ons, Jira is not releasing all memory and it might cause slowdown. In this case, try restarting Jira server process.
Please contact eazyBI support if you have any issues with eazyBI installation and setup.