Installing Dataplane

Installation Checklist

Here is an administrator-level overview to get your system up and running with Dataplane Reports:

1. Make sure your Jira instance meets the system requirements.
2. Review Dataplane Reports' database configuration requirements before proceeding with the installation.
3. Install the Dataplane Reports app in your Jira instance as you would any standard Jira app.
4. Enable support for Asian character sets, if you use Jira with Chinese, Japanese or Korean text.
5. Run Dataplane's indexer to build its database of Jira issue states and transitions.
6. Configure Dataplane user permissions to enable those users you wish to have access to the application.
7. Enable any optional, experimental Dataplane Labs features you would like to try.

You are done!

Database Configuration

Before installing Dataplane Reports, check your Jira database server against the system requirements and recommendations.

Dataplane Reports stores all its data in the same database used by Jira.

MySQL Database Performance Tuning

MySQL's default installation is not particularly optimized for performing database-intensive reporting operations. In particular, a stock configuration of MySQL can cause performance problems.

Although Dataplane Reports will generally work without needing to perform any specific MySQL configuration, some reports can take an exceedingly long time to run if your Jira installation is large and MySQL has not been properly configured.

1. For best performance, the database user used by Jira needs to be granted the "CREATE TEMPORARY TABLES" privilege. To grant this privilege, connect to the MySQL console and execute the following statement, and then restart your Jira instance. (Substitute the same values into this query as you did when performing the original Jira database setup.) 

   GRANT CREATE TEMPORARY TABLES ON <JIRADB>.* TO '<USERNAME>'@'<JIRA_SERVER_HOSTNAME>';
   FLUSH PRIVILEGES;

2. Before installing Dataplane Reports, we strongly recommend that you check your MySQL installation to ensure that Jira is using the InnoDB database engine.  The InnoDB database is also the only MySQL storage engine officially supported by Atlassian for Jira.
3. In addition, we recommend that you configure the InnoDB buffer pool to use as much physical memory as you have available on your database server. For Jira installations with a few tens of thousands of issues, we recommend a minimum of one gigabyte, or more if possible. This cache will benefit Jira as well as Dataplane Reports.
4. We also recommend enabling the MySQL query cache and setting the query cache size to at least 10 megabytes.

An example configuration of /etc/my.cnf with these modified settings looks like this:

[mysqld]

innodb_buffer_pool_size=1024M
query_cache_type = 1
query_cache_size = 10M

Other Databases

No special database tuning is currently required for databases other than MySQL.

Dataplane Installation

Dataplane Reports is a standard Jira app, and can be downloaded and installed from within the Jira Add-On Manager.

Alternatively, you may download the Dataplane .jar file and upload it to your Jira installation manually via the same admin page.

Once installed, Dataplane is accessible from the Dataplane Reports menu in the main Jira navigation bar.

If your browser window is not wide enough, the Dataplane Reports menu may get collapsed into the More menu option:

Enabling Support for Chinese, Japanese and Korean Character Sets

In most cases, the default settings allow Dataplane to produce correctly-rendered output with Asian languages and you do not need to make any changes. However, Dataplane depends on the Java-standard system fonts and PDF fonts to render Asian characters, so if you are experiencing issues with text in charts or PDF exports, please see below.

Configuring Asian Fonts for Charts and Graphics

Dataplane renders charts on the Jira server, and normally uses the fonts bundled with Java for rendering the labels, titles and other text on charts. In many cases, Java will supplement these fonts with system fonts when rendering Asian languages (including Chinese, Japanese and Korean). If the required fonts are missing from the Jira server, Dataplane may render Asian language text as small squares ("◻") instead of the proper characters.

If the text on Dataplane charts is not displayed correctly, you will need to install some fonts on the Jira server. There are two methods for doing so.

Method 1: Installing Missing System Fonts

By default, most Linux installations support only Western languages. In order for Dataplane to render charts correctly in Asian languages, you must install a font pack.

For RedHat Enterprise Linux and CentOS systems, the following commands will install the correct fonts:

If you do not have system administrator privileges or are not able to immediately restart Jira, you can instead install fonts for Dataplane use only by using the Method 2 instructions that follow.

Method 2: Manually Installing Fonts for Dataplane

On the Jira server, font files for Dataplane use go in a Dataplane-specific sub-directory of the Jira data directory. The Jira data directory is where user data (such as issue attachments) for your Jira instance resides—not the directory where you have installed the Jira application itself. For Jira Data Center installations, these fonts must be stored in the shared data directory.

Dataplane supports separate TrueType fonts for regular and boldface text. These font files should be placed in the following locations:

For example, if your Jira data directory is located at "/usr/local/atlassian/jira-data", create "/dataplane/fonts" sub-directories and place the files there:

/usr/local/atlassian/jira-data
	/caches
	/data
	dbconfig.xml
	/dataplane
		/fonts
			chart-regular.ttf
			chart-bold.ttf
	/export
	/import
	.jira-home.lock
	/log
	/logos
	/plugins
	/tmp

Configuring Asian Fonts for PDF Exports

When Dataplane reports are exported in PDF format, Dataplane specifies in the PDF file which fonts should be used to render the report.

Since most popular PDF reader applications include Chinese, Japanese and Korean fonts in the application, to keep exported Dataplane reports to a reasonable file size, the PDF files identify fonts by reference rather than bundling the entire font within the file.

For Dataplane reports that contain Chinese, Japanese or Korean text, so long as the Jira user profiles of your Jira users are set to a matching locale, you should not need to do anything for those users to get the correct language fonts when generating report exports in PDF format.

In most scenarios, this works as desired for users. However if there is a mismatch in language between the text in Dataplane reports and the profiles of Jira users—for instance, users have an English-language Jira profile but still need to export Dataplane reports containing Japanese characters—it is possible, on a global basis, to override the font chosen for PDF exports.

To manually set the PDF export language and font choice, edit your <JIRA HOME DIRECTORY>/bin/setenv.sh file and add the following to JVM_SUPPORT_RECOMMENDED_ARGS (or on Windows, customize the JVM parameters in the Jira Tomcat Service) based on the desired language and font choice for report exports in PDF format: