Troubleshooting

In this page

Logging

The Better Excel Exporter app records its internal activities to a so-called log. The log helps you to understand the activity of the app when diagnosing problems.

Viewing the log

The Better Excel Exporter app writes its own log lines to the Jira log:

Find the logfile named atlassian-jira.log (see the guide by Atlassian).
Search for the text "com.midori" to find the lines written by Better Excel Exporter.
If you can't see any log line written by the app, check if DEBUG logging is configured correctly, then use the corresponding app function again.

If you can't interpret the log lines you found, report it to our support. We are there to help you!

Configuring logging

When investigating a run-time problem, you may need to increase the logging level for the Better Excel Exporter app. Doing so, it will write more details about what it does to the log, which helps you understand the problem.

How to enable DEBUG-level logging

To turn on DEBUG logging from the web interface without stopping Jira:

Login to Jira as administrator.
Go to Jira Administration → System → Logging and Profiling.
Click Configure logging level for another package under Default Loggers.
Enter "com.midori" to Package Name and choose "DEBUG" in Logging Level.
Click Add.
Check if this new package was correctly added to the Default Loggers list.

Now execute the app function that you think fails, then check the log for the details.

How to enable TRACE-level logging

In some rare cases, you may need to turn on TRACE logging, the most detailed logging level. For that, just follow the DEBUG-level logging guide but choose "TRACE" as logging level (instead of "DEBUG").

Warning: TRACE logging can produce a very high number of log lines. Therefore, it should be turned off as soon as possible!

How to enable cell-level logging

Sometimes during troubleshooting you need see what is inserted to what cell and what beans are available in the rendering context at that moment. This is where cell-level logging helps.

To turn on cell-level logging, just turn on TRACE-level logging and it will automatically activate the cell-level one, too.

From now, two lines will be written to the log for each cell. One before processing the cell:

Processing cell "Issue Navigator!A5" (issue=..., column=...) with old value: ... (beans: ...)

...and one after that:

Cell "Issue Navigator!A5" set to new value: ...

Please note that if the output file is rendered to N cells, then cell-level logging alone will produce 2*N log lines! Therefore, remember to turn it off if it is not needed any longer.

This section gives you practical hints to find the root cause when investigating problems in Excel templates and Groovy scripts.

Reduce data

If you see a problem that occurs when exporting a large data set, it is hard to find the precise root cause because of the sheer volume of data. Does it occur for every issue, for Story-type issues only or for the issue FOO-123 only? Similarly, does it occur for every field, for date-type fields only or for the "Due date" field only?

The following techniques help you re-produce a problem with a smaller scope, what is key to find the solution.

Reduce issues

It is helpful when the problem is related to one or more specific issues.

It's a simple idea that you can apply in several ways:

If you fail to export a large number of issues, export only the first one! If it fails as well, then you have a single issue to reproduce the problem. To verify if the problem appears for any issue, repeat the test using a few other randomly chosen issues.
Or, if you see the problem with a smaller number of issues, start removing issues one by one (or in small batches) and repeat the test after each removal. If the problem disappears, then it is caused by the most recently removed issue (batch).
Or, the previous technique in reverse direction: start adding issues one by one (or in small batches) and repeat the test after each addition. If the problem appears, then it is caused by the most recently added issue (batch).
Or, find a single or small number of problematic issues in a large dataset with "bisection":
1. Split up the issues to two similarly-sized partitions (using JQL, for example).
2. Test with the first partition.
3. Test with the second partition.
4. If the problem appears only with one of the partitions, then split that partition again, test those two halves again, and so on.
5. Repeat this until you have a small scope.

These can be used in combination, be creative!

Reduce fields

It is helpful when the problem is related to a specific field.

The idea is the same as reducing the number of issues, but with fields. Basically, you just systematically add or remove fields and repeat the test until you reach a small scope that reproduces the problem. (You can add or remove fields to the Excel export typically by adding and removing columns in the Issue Navigator.)

Reduce features

It is helpful when the problem is related to a specific feature (e.g. exporting comments).

Obviously, disable the suspicious feature and test. If the problem disappears, then it is caused by that feature.

Reduce code

It is helpful when the problem is related to a specific code part in the Excel template or in the Groovy script.

Comment out the code part and test. If the problem disappears, then it is caused by that code part.

Other troubleshooting techniques

Advanced techniques in this section can give further help find problems in Groovy code.

Using getter-based expressions instead of property-based ones

Although these are identical when they succeed, the template expression that uses the getter method name may show more details about a problem than its property name based equivalent. Therefore, if you have a problem in the method that calculates the value "baz", replace ${fooBar.baz} with ${fooBar.getBaz()}.

Wrapping problematic code in a try-catch block

When you have a problematic code block, used through a template expression like ${fooBar.getBaz()} or ${fooBar.baz} and it mysteriously breaks the export, wrap it in a try-catch block!

See this example (that deliberately throws an exception to demonstrate "problematic code"):

import org.apache.log4j.Logger

fooBar = new FooBarTool()

public class FooBarTool {
	def log = Logger.getLogger(this.getClass())

	def getBaz() {
		try {
			throw new NullPointerException() // <- this is here just to demonstrate the technique

			// ... problematic code comes here

		} catch (Exception ex) {
			log.error(ex)
			return ex.message
		}
	}
}

Why does it help in troubleshooting?

The exception will be caught, but the export will not stop!
The exception will be written to the log.
The exception message will be returned to the template. It will appear exactly where the actual value should, giving you a "very visual" way of locating the problem.

Typical problems and their solutions

I cannot export more than 1000 issues in one turn.

To prevent overloading the server, Jira exposes a limit on the number of issues that can be exported in one go. The Better Excel Exporter fully obeys this limit.

The limit is set to 1000 by default, but can be overridden by configuring the following settings in jira-config.properties:

jira.search.views.default.max This is the default soft limit. Soft means that this value will be automatically added as a URL parameter called tempMax to each export request. You can manually increase the default value by changing the URL in your browser's address bar, or even remove the tempMax request parameter from the URL. You cannot exceed the value defined by the next configuration setting this way.
jira.search.views.max.limit This is the absolute hard limit. You cannot set tempMax to values greater than this, as you will get a 403 HTTP error. However, you can grant some users the permission to even break this limit - see next setting!
jira.search.views.max.unlimited.group If you select a group here, any of its members can export an unlimited number of issues. Note that you still need to override the tempMax URL parameter by hand. Also be careful, as these users will be potentially generate huge load on the server.

For more detailed explanation of these settings, please see the official Atlassian documentation.

Please note that in modern Jira versions these settings are configurable also through the UI!

I see the "Failed to load Excel views: check the browser's Javascript console!" error in the "Export" menu.

This typically happens in the backlog screen and in the Tempo Timesheets screens when you have a lot of issues (500 or more) to export. That makes the generated export URL very long, which then exceeds the max URL length accepted by the server.

To fix the problem, increase the max URL length limit in Jira:

Go to the conf folder in your Jira installation directory, and edit the server.xml file.
Go through all the lines that start with <Connector. (Search for term "Connector" in the file, or look at the example below.) You're interested only in those connectors whose protocol is HTTP or HTTPS (not AJP).

Add maxHttpHeaderSize="20000" to the connector properties. For example:

<Connector port="8080" protocol="HTTP/1.1"
	connectionTimeout="20000"
	redirectPort="8443" maxHttpHeaderSize="20000" />

Restart Jira.
If the problem is still present, increase maxHttpHeaderSize even further and try again. Beware: tuning this setting can increase the memory usage of Jira, as well.

Alternatively, you can export the issues in your backlog from the Issue Navigator screen! This screen works differently and completely avoids the problem with the URL length.

Steps:

Open the backlog, click the Board dropdown in the top right, then Configure.
Click the Edit Filter Query button.
It will show you the JQL used for this board. Note that it will return also the issues that are not open or are not in the backlog (but a sprint)! The JQL will be something like this:
```
project = FOO ORDER BY Rank ASC
```

Go to the Issue Navigator. Take the previous JQL, and add these additional filters in front of the ORDER BY clause:

AND issuetype NOT IN subtaskIssueTypes() AND issuetype != Epic AND resolution = Unresolved AND (Sprint = EMPTY OR Sprint NOT IN (openSprints(), futureSprints())) AND status != Resolved

The resulting JQL will look something like this:

project = FOO AND issuetype NOT IN subtaskIssueTypes() AND issuetype != Epic AND resolution = Unresolved AND (Sprint = EMPTY OR Sprint NOT IN (openSprints(), futureSprints())) AND status != Resolved ORDER BY Rank ASC

Execute the JQL query, and you should get the issues in the backlog. (If there are differences, you may need to polish the JQL a bit.)
Export the issues.

I see the "Cannot open PivotTable source file..." error when I open the exported Excel file.

This problem can happen when the export contains a pivot table or pivot chart. Pivot tables and pivot charts have a reference to the input named range. If this reference is prefixed with the template's(!) filename and the output filename is different (which is very likely), then the reference is broken in the output file. We noticed that sometimes Excel is trying to be smart and inserts that prefix in the background for whatever reason.

To solve this, follow these steps:

Open your template in Excel.
Go to File → Info screen.
Click the Allow this information to be saved in your file link under Inspect Workbook section.
Click inside a pivot table.
Select Pivot Table Tools → Analyze → Change Data Source.
If the Table/Range field contains the filename as prefix, remove that (e.g. change 'my-template.xlsx'!issues to issues).
Repeat the previous steps for all pivot tables.
Save the file.
Upload the file to your templates in Jira.
Try another export.

I see the "java.lang.LinkageError: com/midori/jira/plugin/commons/util/RenderingResult" error when Excel automation actions are executed.

This is a defect in Jira's OSGi class loading mechanism that should happen only on Jira 6.x, when you have multiple of our products installed. It should not occur in Jira 7.

To fix:

Uninstall all the following Midori products (if you have them installed): Better PDF Exporter, Better PDF Automation, Better Excel Exporter, Better Excel Automation. (Disabling them is not sufficient!)
Install the apps (only those that you had installed previously) strictly in this order:
1. Better Excel Exporter
2. Better Excel Automation
3. Better PDF Exporter
4. Better PDF Automation

Questions?

Ask us any time.

Troubleshooting

Better Excel Exporter for Jira Server

Useful links

Inspiration

Resources

Tutorials

Documentation