In this page

Embedding attachments

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. You will find a dedicated view to utilize the feature (PDF (Embedded Attachments)), or you can also hardcode the default embed behavior to enabled or disabled for all views.

Enabling this feature is simple:

  1. Login to Jira as administrator.
  2. Go to Apps → Manage your apps → PDF Templates
  3. Click issue-fo.vm. It opens in the built-in template editor.
  4. In the top part the file (aound line 18), there is a configuration variable originally set based on the view's name: if the view name contains the string "Embedded Attachments", the variable will be true, otherwise false. This logic works fine in most use cases, but you can modify it (like pretty much anything else in the app). Set to either true (always embed) or false (never embed): 
    #set($embedAttachments = true)
  5. Save your changes.
  6. 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.

Questions?

Ask us any time.