In this page

Embedding attachments

Since version 1.5.0 of Better PDF Exporter, it is possible to embed the binary content of issue attachments in the exported PDF documents. After distributing those PDFs, readers can open the attachments directly from the PDF and even save it for further use. This happens totally offline, so readers don't need to have access to Jira.

This is how a document with embedded attachments appears in your PDF reader:

This is a very efficient way of generating and distributing self-containing snapshots of your issues. Why and when should you activate this feature?

Archiving

If you use the app to make PDFs from your issues and then put to an external document management system, then it is a very good idea to include the attachments, too. First, your issues will carry all the additional information coupled with them (like screenshots for bug reports). Second, modern search systems shall index not only the PDF text, but also the content of the embedded files, thus your attachments will remain available and searchable for ever.

Exporting issues to distribute them to external parties

If you have any component delivered to your project by a third party vendor, you probably want to report issues found in their deliverables right out of Jira. Say, you want them to fix bugs in their software. In this case, this is crucial that you send them the full bug report including the application logs, screenshots and any other attached files.

Activating embedding attachments

By default, attachments are not embedded in the PDFs. This is due to security reasons: you don't want to get your attachment "invisibly sneak" into the PDF that you may send to external parties later.

Enabling this feature is simple:

  1. Login to Jira as administrator.
  2. Go to AdministrationAdd-onsPDF Templates.
  3. Click issue-fo.vm. It opens in the built-in template editor.
  4. In line 16 of that file, there is this statement, which is originally set to false. Modify this and set to true:
  5. #set($embedAttachments = true)
    
  6. Save your changes.
  7. Test if the attachments appear in the exported PDF documents:
    1. Check if the file size is actually bigger than without the attachments.
    2. Open the PDF with your PDF reader, and check if the attachment links are rendered in blue. Click them and make sure that attached files are properly opened with the default application associated with the file type of the attachment.
    3. Open the PDF with your PDF reader, and check for the PDF attachments. The way readers present the PDF attachments is different at different readers. Adobe Reader gives you access to them by clicking the Attachments tab in the left.

I still can't see the attachments list in my PDF reader... Why?

Note that not every PDF reading application supports displaying the attachments! Use Adobe Reader for the best experience.

Impact on memory usage

Important! If you export a large number of attachments (typically bulk-exporting issues with lots of attached files) or just very large attached files (think of hundreds of megabytes in total filesize), you may encounter memory problems, due to a technical limitation in Jira core. Reason: the app needs that amount of memory temporarily to render the PDF. It's important to understand that after the export is completed, the memory used for this will be freed again.

Overall, this will not affect your server's health.

Questions?

Ask us any time.