In this page

Configuring app logging

In case of troubles, the most important is to increase the app's logging level so that it can write out more details about what it is doing.

To increase the logging level:

  1. Login to Jira as administrator.
  2. Go to Jira AdministrationSystemLogging and Profiling.
  3. Click Configure logging level for another package under Default Loggers.
  4. Enter "com.midori" to Package Name and choose "DEBUG" in Logging Level. (You can alternatively choose "TRACE", the most detailed logging level, but it may produce a very high number of log entries.)
  5. Click Add.
  6. Check if this new package was correctly added to the Default Loggers list.

Now execute the app function that you think fails, and check your Jira log to see the details.

If you can't understand the log lines, report what you have found to our support. We are there to help you.

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 PDF Exporter fully obeys this limit.

The limit is set to 1000 by default, but can be overridden by editing the configuration 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 an 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 consult the official Atlassian documentation.

Font related problems

I see '#' characters instead of Cyrillic / Chinese / Japanese / etc. characters in the PDF files.

The most typical problem with fonts is that your document contains a character, but its glyph (symbol) is not available in the supplied font. For example, your issue description contains a Chinese character, but the supplied font does not contain any Asian glyph.

When the glyph for a character is not found, the renderer will replace it with the hash character '#' in the final PDF document. It means that seeing unexpected hash characters in the document is the typical indicator of the problem. Please note that even with this, the PDF document will be successfully rendered and will be a valid file.

Depending on the number and importance of the missing glyphs:

  1. The document may be usable if only a single unimportant glyph was missing (like an emoji).
  2. The document may be unusable if a high number of important glyphs were missing (like all Kanji and Kana in a Japanese document).

If it is the latter, use automatic (easier) or custom fonts (more control).

I see "Times" or "Times New Roman" being used in my PDF instead of the custom font I set in the template.

When you are trying to use a font family in the FO template, but the corresponding font file is not found by the renderer, it will use "Times" instead. Unexpectedly seeing "Times" indicates that the custom font is not properly configured.

Review your custom font configuration and check the following typical problems:

  1. Whether the font directory is existing in the filesystem.
  2. Whether the font directory name is correctly set to the <directory> element in fop-config.xml.
  3. Whether the font file is existing in that directory.
  4. Whether the font family name is correctly set to the font-family="myfont" attribute.
I see "java.io.FileNotFoundException: .fop (Permission denied)" exceptions.

The font manager may use a cache file to speed up its operations. For this to work, the operating system user who started the Jira process must:

  1. Either have a home directory with a writable subdirectory called .fop in it (e.g. /home/jira/.fop).
  2. Or have write permission on the $JIRA_HOME_FOLDER/tmp directory.

The exception is thrown if none of these is true and the cache file cannot be created.

I see "Only 0 of the 4 expected font substitutions updated to font family Arial Unicode MS" warnings.

This occurs when you are using automatic fonts, but the configuration file fop-config.xml is broken. You have possibly removed some sections, which are required by automatic fonts, from that.

Solution: save a backup of your current fop-config.xml, restore the file to its factory default state, then re-apply your customization if there were.

Gadget-related problems

I get errors when exporting a dashboard that contains Sprint Burndown or Wallboard gadgets.

For the investigation of these kind of problems, we need to know more details about the board, the sprint, the issues and the changes during the sprint. Follow these steps:

  1. Open the problematic dashboard in your browser.
  2. Take a screenshot about the problematic gadget.
  3. Hit F12 to open the Developer Tools view (built to your browser).
  4. Click the Network tab and clear the logs if any is visible.
  5. Refresh the dashboard in the browser, and wait till it is completely finished loading.
  6. Search for scopechangeburndownchart.json (in case of Sprint Burndown Gadget problem) or allData.json (in case of Wallboard Gadget problem) in the list of URLs.
  7. Click it to show the request's details in the right, then click the Response tab.
  8. Copy the whole JSON string shown, and paste that into a new text file.
  9. Attach both the image file and the JSON file to the support ticket. This helps us to see the expected output (image) and the input (JSON).

The instructions above are made for Google Chrome, but very similar steps should be taken in other types of browsers. It should be trivial, but feel free ask our help any time.

Other problems

Table borders and underlines are blurred and are drawn with varying line thickness.

When viewing a PDF file in Adobe Reader, especially those with tables and lines, some lines may look thicker than other lines and even different sections of the same line may look somewhat blurry. It is caused by the "Enhance thin lines" feature of Adobe Reader, designed for lower resolution CRT monitors.

To enhance the look, turn off the feature in your Adobe Reader: navigate to EditPreferencesPage Display and uncheck the Enhance thin lines option. There is an additional option called Smooth line art that can make your lines laser-sharp, but can also cause other visual artifacts at line junctions (e.g. borders at the table corners). Find the combination that works best for you.

Unfortunately, these display settings are local (specific to your computer), not attributes of the PDF file itself.

Questions?

Ask us any time.