Bulk Attachment Download

The Bulk Attachment Download plugin for Jira Cloud is a powerful tool designed to enhance your productivity by enabling the efficient download of multiple attachments from your issues. This documentation will guide you through the process of installing and using the plugin effectively.

Getting Started

To start using the Bulk Attachment Download plugin, you need to install it in your Jira Cloud instance. Follow these steps:

Visit the Bulk Attachment Download listing on the Atlassian Marketplace.
Click on the ‘Try it free’ button in the upper right corner.
Select the Jira Cloud instance where you want to install the add-on and click ‘Start free trial’.
The add-on will be automatically provisioned to your Jira Cloud instance.

Note: The installation process requires administrator rights for your Jira Cloud instance.

Once installed, the plugin integrates seamlessly into your Jira workflow, and you can access its features directly within the platform.

Searching for Issues

Navigate to the Jira issue navigator by selecting Filters > View all issues.
Use Jira’s powerful search functionality to filter and find the issues with the attachments you need.

Downloading Attachments

Once you have your list of issues:

Click Download all attachments to initiate the download process. You find this button within the Apps dropdown menu in Jira’s new issue navigator or directly on the page if you are still on the old issue navigator.
A modal will appear displaying three key statistics: The number of Issues matching your filter criteria, the total number of Attachments within these issues, and the cumulative file Size of all attachments. This information can help validate that your issue search has returned the relevant issues for download.
You will be prompted to choose how you would like the attachments to be organized and your preferred download mode.

The downloaded file will be a zip archive containing all attachments of any issues found. This includes not only the issues displayed on the first page of search results but also those on subsequent pages. There is no limit on the number of issues or attachments that can be included in the download.

Organizing Attachments

Choose how to organize your downloaded attachments:

Per Issue Folders: Each issue’s attachments are placed in a separate folder named with the issue key and summary. Folder names are kept short for compatibility.

If the issue summary contains characters that are illegal for file names in certain operating systems ( e.g. ", *, :, <, >, ?, /, \, |), they are replaced by _ in the folder name. This ensures that the folder names are valid and compatible across different operating systems.
Top-Level Attachments: All attachments are placed directly in the zip file without issue-specific folders.

Per Issue Folders	Top-Level Attachments

Handling Naming Conflicts

In cases where multiple attachments have the same name, the plugin automatically appends a dash and an incrementing number to the file name to avoid overwriting files. Here’s an example of how naming conflicts are resolved:

Attachment in Jira	File in zip
file-3.txt	file-3.txt
file.txt	file.txt
file.txt	file-1.txt
file.txt	file-2.txt
file.txt	file-4.txt
file-3.txt	file-3-1.txt

This ensures that all attachments are uniquely named within the downloaded zip file, preserving the original file names as much as possible.

Choosing Download Mode

The Bulk Attachment Download plugin offers two modes for downloading attachments: Direct Download and Server Download. Direct Download is the recommended mode and should be used in most cases.

Direct Download

Recommended Mode: Direct Download is the preferred mode and has been tested to work reliably in the latest versions of Chrome, Edge, Firefox, and Safari.

Eco-friendly and Efficient: By sending attachments directly from Jira to your browser, Direct Download minimizes energy consumption and CO2 emissions, contributing to a greener planet.
Enhanced User Interface: A dedicated interface will keep you informed about the download progress and promptly alert you to any issues encountered along the way.
Data Privacy: Direct Download ensures your attachments are transferred securely without involving any third-party servers, maintaining the privacy of your data.

Server Download (Legacy)

Server Download mode should be considered a legacy mode and only used if Direct Download fails, which should be rare. If you encounter a situation where Direct Download does not work, please inform our support team.

Robust and Reliable: Leveraging Pristine Bytes servers located in West Virginia (USA), this mode ensures a dependable download process, regardless of the browser you use.

Note: Server Download mode may be deprecated in the future as Direct Download has proven to be reliable in most modern browsers.

Filtering Attachments

The Bulk Attachment Download plugin allows you to filter the attachments to be downloaded based on specific criteria. This feature is particularly useful when you want to download only specific file types, attachments from certain issues, or files uploaded by a particular user.

To filter attachments:

Enter your query in the Filter text input field using the format described below.
As you type, the input field provides autocomplete suggestions to help you compose the filter query.
If any part of the filter query is not understood, it will be marked with a red squiggly underline. Hover over the underlined part to see details about the issue.
To apply the filter, press Enter in the text field or click the blue filter button, that becomes active as soon as something is typed into the input.
Once the filter is submitted without errors, the attachment statistics and preview table will update to reflect the matched attachments. This allows you to verify the intended result.
Only the filtered attachments will be downloaded. If the filter is empty, all attachments will be downloaded.

Filter query syntax:

Filter queries consist of one or more conditions that attachments must satisfy to be included in the download.
Conditions are formed by combining an attribute, an operator, and a value. For example: mediaType = “Doc”
Supported attributes:
- filename: The name of the attachment file
- mediaType: The general media type (Doc, Audio, Video, Image, Archive, Unknown)
- mimeType: The specific type of the file, such as “application/pdf” for PDF files or “image/jpeg” for JPEG images
- author: The name of the user who uploaded the attachment
- issueKey: The unique identifier of the issue the attachment belongs to, such as “PROJECT-123”
- issueSummary: The title or summary of the issue
Supported operators:
- contains: Checks if an attribute contains a specific word or phrase
- =: Checks if an attribute exactly matches a value
- !=: Checks if an attribute does not match a value
The filter ignores the difference between uppercase and lowercase letters when comparing text.
Multiple conditions can be combined using logical operators:
- AND: Both conditions must be satisfied
- OR: At least one of the conditions must be satisfied
You can use braces () to group conditions and specify the order in which they are evaluated.
Text values should be enclosed in quotation marks ” “. If a value consists only of letters and numbers, the quotation marks may be omitted.

Examples of filter queries:

Download only image attachments:
mediaType = Image
Download attachments from issues containing the word “bug” in the summary:
issueSummary contains “bug”
Download PDF and Word documents uploaded by a user named “John Doe”:
(mimeType = “application/pdf” OR mimeType contains “wordprocessingml”) AND author = “John Doe”
Download attachments from issues in a project with the key “PROJECT”:
issueKey contains “PROJECT-”

Note: The filter feature is only available in the Direct Download mode.

Previewing Attachments

Before downloading the attachments, you can preview them to ensure you are downloading the expected files. In the download modal, click the Preview Attachments button to open a panel displaying a table with all the found attachments and their metadata.

The table includes the following columns:

Name: Displays the file name of the attachment. You can switch this column to display the Path in ZIP, which includes the per Issue Folders, replaced illegal characters, and resolved naming conflicts.
Size: Shows the size of the attachment. You can switch this column to display sizes in the most fitting unit or display all sizes in megabytes.
Date Added: Indicates when the attachment was uploaded.
Type: Displays the media type of the file (Doc, Audio, Video, Image, Archive, Unknown). You can switch this column to display the MIME Type, which provides more detailed information about the file type.
Author: Shows the name of the person who uploaded the attachment.
Issue Key: Displays the key of the issue the attachment belongs to.
Issue Summary: Provides the title of the issue.

To sort the attachments by a specific attribute, click on the corresponding table header. If needed, you can resize the preview panel by dragging the upper border.

When a filter is applied, the preview table will update to show only the attachments matching the filter criteria. This allows you to verify that the filter produces the expected results before initiating the download.

Progress Indication and Download

After selecting the download button in the modal:

Server Download Mode: The modal will close, and your browser will begin the download immediately. This process is straightforward and similar to downloading any other file from the internet.
Direct Download Mode: The app displays a download progress bar within the modal, offering insights into the download progress.

Displayed data includes:
- The relative and absolute progress of the download.
- The total size of all attachments being downloaded.
- The names and sizes of the files currently being downloaded.
- Any issues encountered.
Note: These indicators only update when an attachment has been completely fetched. The striped pattern within the progress bar represents the sum of all file sizes currently in flight.

Navigating away from the page at this stage will leave the download in an unfinished state, requiring you to start the process again.

Extracting the Downloaded Files

After the download is complete, locate the zip file on your machine and extract it using your preferred file extraction tool to access your attachments. If you encounter issues extracting the zip file with the tools included with your operating system, we recommend using 7zip for Windows and The Unarchiver for Mac.

Troubleshooting and Support

If you encounter any issues or have questions, please contact our support team for assistance.