In this page

Typical problems and their solutions

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 fonts.

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 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 whether the font family name is correctly set to the font-family="myfont" attribute. (If the font file is not available at the URL you specify, you will get an error message in the PDF file instead of rendering the text with "Times" or "Times New Roman".)

I see "java.lang.UnsupportedOperationException: ... not yet supported" exceptions when using a custom font.

Certain fonts may use special features known as "complex scripts" which are not yet supported by the PDF renderer. For example, the Roboto font is known to cause this issue.

If you are working with European languages only, you can safely disable the "complex scripts" feature:

  1. Login to Jira as administrator.
  2. Go to AppsManage your appsPDF Templates.
  3. Open the fop-config.xml file.
  4. Apply the change explained at point 3 in the Disabling complex scripts section.
  5. Save your changes.

Other problems

I see "Quota reached!" and "Hardly any quota left!" messages.

Jira data exports are resource-intensive tasks in general. Even more so, if they require extensive network communication between the Jira Cloud app and the Jira REST API, or if they execute computation-heavy Groovy scripts. To protect resources, Better PDF Exporter implements a quota system.

In the quota system, two factors are limited:

  1. the number exports made within an hour
  2. the total duration of the exports made within an hour

It means that you can run long export tasks, but less frequently, or short export tasks, but continuously. The app notifies you when you are near to the end of your quota to avoid bad surprises. If you eventually run out of quota, you just have to wait until the next hour and try again.

Important: please note that paid licenses enjoy a much larger quota than evaluation ones! It is because by paying the subscription fee (after the evaluation period is over), you help us in paying the AWS operational costs, which in turn allows us offer you a larger quota.

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.