FAQ

General

Can Dataplane report on issues created before it was installed or only on those issues created or modified after installation?

Arsenale Dataplane reports on the entire history of your Jira instance, providing a comprehensive analysis of even those issues created or modified before Dataplane was installed.

When Dataplane is first installed, it automatically indexes your entire Jira instance history including every issue creation, workflow transition, and field value change ever made. Once the initial index is complete, all subsequent changes in your Jira instance are tracked by Dataplane in realtime.

So with Dataplane you get the same detailed insight into past project and team performance and metrics as you have going forward.

How current is the data I'm viewing in Dataplane reports?

After Arsenale Dataplane does an initial index, upon installation, of your Jira instance history, all subsequent changes in your Jira instance are then tracked by Dataplane in realtime.

So all Arsenale Dataplane reports reflect the most current state of your Jira issues.  There is no delay between Jira issue changes and those changes being reflected in Dataplane reports, whether those reports are viewed within Dataplane, on Jira dashboards, or in Confluence via a Dataplane gadget.

Does Dataplane modify Jira project or issue data?

No. All Jira project and issue data is treated as read-only by Arsenale Dataplane.

For its performance-optimized reporting and storing of saved reports and other app user data and settings, Dataplane creates and maintains its own separate database tables within the Jira database.

Is Dataplane subject to the same 1000 issue export limit as the Jira Issue Navigator?

No. Dataplane works completely independent of the Jira Issue Navigator and is not subject to this limitation.

If you have not yet run into this limitation in the Jira Issue Navigator, it refers to trying to do an Excel export of the results of a Jira search and being limited to a maximum of 1000 issues (rows) that can be exported at any one time. This can make it difficult to pull comprehensive Jira data into Excel for additional analysis. The limit built into the Jira Issue Navigator is due to potential performance and memory issues with larger exports.  You may increase this limit via a Jira configuration parameter but should carefully monitor instance performance and memory usage in making any changes. Any changes made to Jira's export limit is independent of Arsenale Dataplane and has no effect on your export of issues from Dataplane.

With Dataplane you can easily run reports on and export results containing tens of thousands of issues. Dataplane's Issues Table Report is an excellent substitute for viewing and exporting issues from the Jira Issue Navigator. 

Dataplane's report queries are run directly against the Jira database rather than Jira's internal issue cache.  So that Dataplane's database queries are not completely unbounded in result size, Dataplane places a soft limit on database query results of 20 million result items (20,000,000 rows x columns of data). While we expect this limit should be more than sufficient for the majority of Jira instances, if running a Dataplane report produces an error indicating this limit has been reached, you may tune the limit with the following JVM parameter:

-Dcom.arsenalesystems.dataplane.query.result.limit=30000000

Dashboard Gadgets

When using Dataplane dashboard gadgets in Confluence, why do users get an authentication prompt?

On some systems, after you add a Dataplane report to a Confluence page, users see a message similar to the following at the top of the gadget in Confluence:

This message instructs users to confirm their identity to the Jira server. (The confirmation is performed using the industry-standard OAuth protocol.) When the user clicks "Login & Approve", they will be sent to the Jira server in order to confirm the connection, and they are then returned to Confluence to see the Dataplane report. This authentication prompt is a general feature of all Atlassian Gadget that require user authentication, so it is not specific to Dataplane.

In general, users should only have to perform this approval once. If users need to continually approve the gadget, or if even performing one approval is too much, some alternate solutions are listed below.

Solution 1: Switch to Trusted Application authentication

The easiest way to work around the problem is to configure the Application Link between the two applications to use Trusted Applications authentication. When Trusted Applications authentication is in use, authentication is automatic and users will never be asked to approve the gadget. To enable Trusted Applications:

1. In Jira, go to Toolgear » Add-ons » Application Links.
2. Find the Application Link corresponding to your Confluence server, then click "Edit".
3. Click on "Outgoing Authentication".
4. Click on the "Trusted Applications" tab (or ensure that it is already selected), then click "Enable".
5. Click on "Incoming Authentication".
6. Click on the "Trusted Applications" tab (or ensure that it is already selected), then click "Enable". You may need to scroll to the bottom of the dialog window to find the Enable button.

This procedure will enable Trusted Applications authentication for all gadgets, and the confirmation dialog should no longer appear.

Solution 2: Diagnose and Fix OAuth Configuration

If you do not wish to use (or cannot use) Trusted Applications for your Application Links, but you still receive the approval confirmation dialog more than once per user session, something is likely broken with your OAuth configuration.

Some of the following issues are known to cause problems with the OAuth confirmation:

• accessing Confluence (or Jira) with a URL other than the base URL configured in the application's configuration page. For example, if Jira is configured with a base URL of "http://jira.mycompany.com" but users typically access Jira using a shortcut of "http://jira", OAuth may not work properly. To correct this issue, ensure that the base URL is configured correctly in the Jira system configuration, and then ensure that all users are accessing it with that name. (If you run Jira behind a web server, you may wish to configure your web serfver to redirect all nonstandard URLs to the canonical URL.)
• configuring both Confluence and Jira on the same hostname, only differentiated by a context path or port. OAuth may not always work as desired if (say) your Confluence server is accessible at http://tools/confluence and Jira is accessible at http://tools/jira. Similarly, trying to access Jira as http://tools:8080 and trying to access Confluence as http://tools:8090 may also cause problems. In this scenario, consider creating different hostnames for each applications. (Both services can still continue to be run on the same physical or virtual machine, but they should be given their own distinct hostnames and URLs.)

One additional tool for investigating OAuth problems is the OAuth authentication tokens page in the user's profile. To access this tool:

• First, log onto Confluence as one of the users who is having authentication problems.
• Try to display pages containing Dataplane gadgets a few times. Make sure that you authenticate the gadgets more than once.
• Next, log into Jira as the same user.
• Click on the user profile icon in the top right corner and select "Profile".
• Click the "Tools" dropdown in the top right corner of the page, and select "View OAuth Access Tokens".

The subsequent OAuth Tokens page will show a list of all of the approved OAuth Access Tokens for the specified user. If you see a large number of tokens that were all approved at around the same time, you may need to go back and double-check the URL configurations.

When viewing Dataplane gadgets on a Confluence page, why do users get a PermissionException error?

When viewing a Dataplane gadget in Confluence, users may get a message such as the following, even though they are correctly logged into both Confluence and Jira:

This typically happens when using Application Links that are configured with Trusted Applications, but you are using incompatible versions of Jira and Confluence. In particular, Atlassian published a number of security advisories on 2014-02-26 that impact the following versions of Jira and Confluence:

• Confluence 5.4.1 and below (official Atlassian security advisory)
• Jira 6.1.3 and below (official Atlassian security advisory)

If either your Confluence instance or your Jira instance fall into the above version range, you need to apply the official patches to both systems in order for the Trusted Applications link to work properly. For example, patching only Jira but not Confluence can lead to the above PermissionException errors, and it is likely that other parts of the Application Link will not work correctly either.

If only one of your applications falls into the above version range, that application still must be patched, since the Application Links in later versions of Confluence and Jira are not compatible with earlier versions in the above range that do not have the patch.

When viewing Dataplane gadgets on a Confluence page, why is the gadget blank or why can it not be configured?

We are aware of two possibilities:

Long-Running Reports Cause Timeouts and Blank Gadgets in Confluence

If your Dataplane report requires a long time to generate, the gadget may appear to be loading on your Confluence page for the first few seconds, but it will then stop and render as a blank gadget. This issue is caused by a short timeout built into the HTTP relay functionality in Confluence.

To solve the problem, edit the JVM system parameters for Confluence. For Linux installations, this is done by editing the CATALINA_OPTS variable in $JIRA_HOME/bin/setenv.sh. For Windows installations, please instead follow Atlassian's documentation for instructions on editing JVM system parameters.

For Confluence 5.x and below, add the following to your CATALINA_OPTS. The default timeout for Confluence 5.x is 15 seconds.

-Dhttp.socket.timeout=60000

For Confluence 6 and above, you must add the following parameter instead to CATALINA_OPTS. The default timeout for Confluence 6+ is 5 seconds.

-Datlassian.http.connection.timeout=60000

The above change will increase the HTTP relay timeout from the default to 60 seconds. If your reports require more time, you may adjust this value accordingly. Please note that the timeout specified by this parameter is in milliseconds.

Gzip Compression Causes Issues and Blank Gadgets with Jira 5.1 to 6.2.4

If you are using Jira 5.1 through 6.2.4 inclusive, a Jira bug (JRA-29795) requires that you disable Jira's built-in gzip compression feature in order to use the Dataplane gadget in Confluence. Jira 5.0.x and Jira 6.2.5+ are not impacted.

Atlassian already recommends disabling gzip compression if you are using Jira behind an Apache httpd server with mod_proxy, and they indicate that you may actually experience a performance gain by turning it off.

To disable gzip compression, access the Jira administration panel and select System » General Configuration » Edit Configuration, and then disable the "Use gzip compression" feature. Failure to disable Jira's gzip compression will result in Dataplane gadgets failing to display in Confluence.

If you use Jira behind a web server proxy, you may still be able to leave gzip compression enabled on the proxy.

I'm still having problems with rendering Dataplane gadgets in Confluence. Help!

Some customers have reported issues with the Application Links configuration when one application is configured to connect over regular HTTP, but the other application is configured to connect over HTTPS, and that this problem is not specific to Dataplane. Ensuring that both Confluence and Jira use the same protocol may make it easier to set up a working application link.

Jira Issue Fields

What Jira issue fields are supported by Arsenale Dataplane?

Dataplane reports on a wide variety of Jira field types including:

• the majority of built-in Jira fields
• the majority of standard Jira custom fields
• custom fields from a number of third-party apps including Valiantys nFeed and ScriptRunner
• all other third-party custom fields that are "stattable" (have been implemented using the Jira CustomFieldStattable class)

For complete details, see the Dataplane Supported Jira Fields page.

Why is my custom field not in the list of fields that can be reported on?

The most common reason for this is, after adding a new custom field to Jira that is supported by Arsenale Dataplane, you must:

1. click the "Sync Index" button on the Dataplane Administration page to inform Dataplane about the new field, and
2. rebuild your Jira index so that the custom field is useable by Jira 

Additional reasons the custom field may not be available in Dataplane are:

1. your custom field may not be in the list of Dataplane's Supported Jira Fields, including supported third-party app custom fields.
2. your custom field may be supported by Dataplane, but not in the context in which you are trying to use it in a Dataplane report. For example, historical reports like the Issues Value by Date Report, support a different set of fields than reports based only on an issue's current field values, since not all Jira fields are indexed historically by Dataplane. Additionally, only numeric fields can be used in Dataplane report configuration options that require a numeric value, as with the Value option in the Sum Numeric Field by Date Report.

Calculations and Values

When reporting on time durations, are the calculated total, average, max and min times adjusted for non-working hours?

No. All reports that include time duration statistics—such as the Closure Time Report, Time in Status Report or the Sum Numeric Field Report—currently use a raw calculation of hours that makes no consideration for non-working hours.

For example:

• 21.25 hours in an Issues Work Log Table Report is exactly 21.25 hours of actual work completed, regardless of time of day, weekend or holiday
• in a Closure Time Report or Time from Status to Status Report, a display of 36 hours for the average transition time in a reporting interval means 36 hours on a regular 24 hour clock, or 1.5 calendar days, rather than 4.5 working days of 8 hours each.

Fonts

Why are Dataplane charts displaying unreadable font characters for axis labels and values? 

Under some circumstances, after installing a new Jira instance or upgrading an existing Jira instance, the font characters displayed on Dataplane chart axes and labels are unreadable.

Dataplane assumes there is a font named "Dialog" installed and available to Java, or "LucidaSans" if on a MacOS server. These are default fonts that come with Java. The Java runtime may be unable to locate this font, or a mangled alternate version is overriding the default installed with Java. If you search your Jira server log file (logs/catalina.out) there may even be a mention of not finding this font.

One of the following solutions should fix the problem:

Solution 1: For Linux Servers, the Font Cache is Corrupted and Must Be Reset

If running Jira on a Linux server, occasionally the Linux font cache is corrupted and must be reset.  To do so:

1. Enter the following command on the server: fc-cache -s
2. Restart Jira

Solution 2: For Linux Servers, Install the Dejavu Font Packages

For Linux systems, some of Atlassian's Jira installer packages do not include the correct font families.  To fix the problem:

1. Install the "yum" command on your Linux server if not already present

2. Enter the following commands on the server:

   yum install dejavu-fonts-common
   yum install dejavu-sans-fonts
   yum install dejavu-sans-mono-fonts
   fc-cache -s

3. Restart Jira

Solution 3: Verify Java's Default Fonts are Installed

1. On your Jira server, copy the following code to a text file and name the file "ListFonts.java":

   import java.awt.GraphicsEnvironment;
   public class ListFonts {
       public static void main(String args[]) {
           GraphicsEnvironment e = GraphicsEnvironment.getLocalGraphicsEnvironment();
           for(String font:e.getAvailableFontFamilyNames()) {
               System.out.println(font);
   }}}

2. Compile the Java code using the following command: javac ListFonts.java
3. Run the code with the following command: java ListFonts

4. Review the output to make sure the font "Dialog" is installed for Java (or "LucidaSans" if on a MacOS server):

   cmex10
   cmmi10
   cmr10
   cmsy10
   Dialog
   DialogInput
   esint10
   eufm10
   Lucida Bright
   Lucida Sans
   Lucida Sans Typewriter
   Monospaced
   msam10
   msbm10
   rsfs10
   SansSerif
   Serif
   stmary10
   wasy10

5. If the required font is not installed you’ll need to install that font. A reinstall of the Java JRE might be the most simple way.
6. Restart Jira

Administration

What does Sync Index do and when is it necessary?

In order to provide high performance historical reporting, Arsenale Dataplane builds and maintains its own optimized index of every change made to the issues in your Jira instance. Once Dataplane's index is built—after initial installation, on upgrade or after manually clicking the Build Index button in Dataplane Administration—all subsequent issue changes in your Jira instance are tracked by Dataplane in realtime.

There are a couple unconventional situations, however, where Dataplane's index of the state of your Jira instance may not be completely up-to-date: 

• if you've added issues to your Jira instance unconventionally, such as with the Jira Importers Plugin, a third-party issue migration tool, or a command-line interface
• if you've added a new custom field to your Jira instance

Under any of the above circumstances, the new issues or custom field will not be available within Dataplane until you click on the Sync Index button on the Dataplane Administration page.

Sync Index tells Dataplane to re-synchronize its realtime indexing with the current state of your Jira instance, picking up any new custom fields or unconventionally created Jira issues. This incremental synchronization is very fast and should complete in under a minute on most instances.  

How do I disable the user feedback links in Dataplane?

Arsenale Dataplane includes a number of links in the application to allow users to easily open a support ticket with Arsenale: to suggest new features or product improvements, to request help with a feature or report, or to file a bug.

If you wish to disable this feature, hiding all product feedback links in Arsenale Dataplane:

1. Go to Jira Administration -> Add-Ons, and click on Manage add-ons.

2. Scroll down until you find the listing for Arsenale Dataplane, and click on it to expand the add-on listing.

3. Click on the link labeled "xx of yy modules enabled" on the right-hand side of the listing. Then scroll down to see the list of individual components ("modules") of the Dataplane add-on.

4. Find the "Issue Collector Web Resources (issueCollectorWebResources)" module and click on the Disable button that appears when you hover your cursor over that module listing.

The feedback module is now disabled, and Arsenale Dataplane product feedback links are no longer visible to users.

Does uninstalling Dataplane delete any app user data or settings?

No. Uninstalling Dataplane is perfectly safe, and does not delete any Dataplane user data or settings.

Dataplane user data and settings are stored in an app-specific set of Active Objects tables in the Jira database, which are left untouched when Dataplane is uninstalled. Upon reinstallation of Dataplane, all app user data and settings are available again within Dataplane.

Licensing

Why is Dataplane no longer available upon expiration of my paid license maintenance period?

If you are running Dataplane 1.8 or lower, a bug in the Atlassian Add-On Manager (UPM) (UPM-4565) causes Jira to stop Dataplane from running upon license maintenance expiration, rather than letting you continue using Dataplane outside of your maintenance period (as your perpetual license allows). This also affects impacts users who are in the process of upgrading from Dataplane 1.8 or lower to a more recent release. We apologize for this inconvenience.

To resolve the issue while running Dataplane 1.8 or lower, you will need to:

1) Upgrade to Dataplane 1.9 or newer, and
2) Remove and reinstall your Dataplane license. This will correct the licensing condition immediately. 

If you are already running Dataplane 1.9 or later, these special instructions do not apply and no action is needed.

To resolve the licensing bug, after upgrading to a new version of Dataplane, visit the Manage Add-ons section of Jira Administration:

• 1. Click on the Arsenale Dataplane listing.
  2. Click the "pencil" icon next to the License Key text box to edit your existing license.
  3. Copy the Dataplane license string from the License Key text box to a temporary text file.
     
     

  4. Delete your license string so that the License key text box is empty, and click Update.

  5. Paste your Dataplane license back into the text box, and click Update to apply it.
  6. Verify the License Status field shows your license is now "Valid".