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.

Changing the default behavior is simple:

  1. Login to Jira as administrator.
  2. Go to Administration → Add-ons → PDF Templates.
  3. Click issue-fo.vm. It opens in the built-in template editor.
  4. In the top part the file (around line 17), there is a configuration variable originally set to false. Modify this and set to true: 
    #set($embedAttachments = true)
  5. The template contains another configuration variable to specify a maximum filesize for the attachments to be embedded. If an attachment is larger than this limit (default: 50 megabytes), it will not be embedded. It aims to prevent unwantedly creating exports that would embed gigabyte-sized attachments. Set the configuration variable in this line: 
    #set($embeddedAttachmentMaxFileSize = 52428800)
  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 reader application supports the embedded attachments. For example:

  • Adobe Reader supports it. (And, generally speaking use Adobe Reader for the best overall experience.)
  • The built-in PDF reader extension of Firefox supports it.
  • The built-in PDF reader extension of Chrome does not support it.

Impact on memory usage

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. This is because the app temporarily needs that amount of memory to render the PDF.

The configuration variable $embeddedAttachmentMaxFileSize prevents embedding files larger than the configurable limit. Therefore, it effectively prevents the memory related problems.

It's also important to understand that after the export is completed, the memory used for this will be freed again.

Questions?

Ask us any time.