Move Attachments

Owned by Rosen Marinkov
Last updated: Sept 25, 2024 by Stanley Neychev
4 min read

On this page:

Introduction

The 'Project with Issues' snapshot type includes all issues and related data - comments, work log entries, issue links, issue history, and attachments.

The attachment metadata (filename, creator, create date, etc.) is small enough to always be included in the snapshot. However, including the attachment files can make the snapshot grow very large, which is why Configuration Manager allows two ways of handling attachments.

  1. Include attachment files in the snapshot. This is the preferred option for moving projects with fewer attachments (roughly less than 100 MB). A local copy of each file will be made during export regardless of their storage location (local or in Amazon S3). Therefore, you need to have sufficient space available during the export. Once the snapshot is created, these local copies will be deleted.

  2. Do not include attachment files in the snapshot. This option makes the snapshot size considerably smaller and makes deployment faster. Depending on what type of storage system you’re using, this option’s prerequisites may differ.

    • If you’re using the local file storage system…
      The attachment files for the exported projects will need to be manually copied and moved to a temporary folder. During deployment, Configuration Manager will copy and transfer them from the temporary folder to their correct place in Jira’s attachments directory using the metadata in the snapshot.

    • If you’re using an Amazon S3 storage system…
      You won’t need to copy anything. You’ll just have to provide the attachments directory during deployment. The attachments will be linked up with the help of the metadata in the snapshot.

Jira stores the attachment files in separate directories by project key.

  • An example of local file storage - $Jira_Home/data/attachments/

  • An example of Amazon S3 storage - $AWS_bucket/attachments/

Create a Project Snapshot with Issues

  1. Choose the cog icon at the top right of the screen, then choose Configuration Manager:

  2. Select Snapshots to open the Configuration Snapshots page and click on the Add Snapshot button.

  3. Select the Project with Issues button and enter a name for the snapshot. Here, you can select as many projects as you need to include in the snapshot. Optionally enter a description. The following screen will appear:

Create_Project_with_Issues_Snapshot.png

Deploying a Snapshot with Issues

When deploying a snapshot with issues, if the attachment files are not included in the snapshot, you can provide a path where the files reside. Configuration Manager will pick the files from there and attach them to their relevant issues.

Note that the option to import attachment files from either the file system or S3 will appear in the deployment wizard only when:

  • At least one issue in the snapshot has an attachment, and

  • The attachment files are not included in the snapshot.

To provide attachment path during deployment:

  1. Choose the cog icon at the top right of the screen, then choose Configuration Manager:

  2. Select Deploy on the left menu to open the Deploy Configuration Snapshot page.

  3. Choose a snapshot with issues from the current instance/linked Jira/snapshot file and click the Deploy button. (Read more about deploying snapshots)

  4. There is an option “Do not import issue attachments” in the Advanced Options on the deployment wizard’s Select Deployment Mode.

  5. Either provide a path to import the attachment files or enable the option to skip importing attachment files.

Store the attachment files in a temporary folder on your local system or use a cloud-based storage like Amazon S3. Avoid using Jira’s attachment directory.

Attachment-path.gif

Configuration Manager expects the attachment directories to follow the same structure as Jira’s attachment directory.

For example, when exporting projects PRA and PRB on the source server, copy the directories $Jira_Home/data/attachments/PRA and $Jira_Home/data/attachments/PRB, and move them to a temporary directory on the target server, as in the screenshot below:

When prompted by Configuration Manager, provide the path to the temporary directory. After the deployment, the temporary directory is not needed anymore and can be deleted.

Potential Errors

The provided path does not contain an accessible subdirectory for the project.

If the temporary directory does not contain sub-directories for some of the projects in the snapshot, Configuration Manager will show the following warning:

To fix this, you’ll need to either change the path you provided or check the directory’s access rights.

There was an unexpected error related to Amazon S3.

If Configuration Manager fails to authenticate your Amazon S3 storage account, the following error will appear:

To fix this, you'll need to check the Jira log, which will contain more detailed information about the error you encountered.