JIRA: Configuring file attachments

When attachments are enabled, your users can attach files and screenshots to Jira issues.

This requires space on the server for storing the attachments.

 Attachments are not stored in Jira’s database and so will need to be backed up separately. Learn more about how attachments are stored .

 

Attachments are enabled by default. You can configure the way Jira handles attachments, or disable attachments altogether. If you use a custom permission scheme, you might need to update the permissions to allow users to add and remove attachments.

Edit attachment settings

1. Choose   > System. 
2. Select Advanced > Attachments.
3. Click Edit Settings, which opens the Edit Attachment Settings dialog:
4. In Attachment Size, specify the maximum attachment size. The default is 10485760 bytes (10 MB). The maximum attachment size is 2147483647 bytes (2 GB).
5. In Attachment Path, choose Use Default Directory. If you see more attachment path options than what is shown in the screenshot above, refer to the note below.
6. (Optional) In Enable Thumbnails, choose ON to display image attachments as thumbnails on an issue. When this setting is on, Jira creates thumbnails of the following filetypes:
   • GIF
   • JPEG
   • PNG

   For more about thumbnails, see these notes.

7. (Optional) In Enable ZIP Support, choose ON to allow users to preview the contents of ZIP attachments and download all attachments on an issue as a single ZIP file.
8. Click Update.

  Choosing a custom attachment path:

• If you upgraded Jira with an XML backup from a Jira version prior to 4.2 and used a custom directory for your attachment path, you can choose between using this custom directory (which cannot be edited) or the default directory for your attachment path location. However, once you switch to using the default directory, you can no longer choose the custom directory option.
• The default directory location is the data/attachments subdirectory of the Jira home directory.
• To be able to change the default path, create a symbolic link to the new path.

  More information about thumbnails:

• You can configure the issue navigator column layout to display the thumbnails in an Images column.
• Thumbnail images are stored in JPEG format in the attachments directory, together with the original attachments. The thumbnail images are denoted by ‘ _thumb_ ‘ in their file names.

  Thumbnail image generation on Linux:

• Your system must have X11 support. This web page details the minimum set of libraries needed to use JDK 1.4.2 under RedHat Linux 9.0.
• The following java system property must be set: -Djava.awt.headless=true

Edit attachment permissions

If your project permission scheme has the Create Attachments (and Delete Own Attachments) permission, or if your project uses Jira’s built-in Default Permission Scheme, then you don’t need to update your project permissions.

If you use a custom permissions scheme, then make sure users have the following permissions:

• To attach files to issues: users, groups or project roles must have the Create Attachments permission for the relevant project(s).
• To delete their own attached files from issues: users must have the Delete Own Attachments permission for the project.

If you need to update these permissions, use the following steps:

1. Choose   > Issues. 
2. Select Permission Schemes. Jira lists all permission schemes in your Jira system and the projects that use each scheme.

   

3. For each relevant permission scheme:
   1. Click Permissions next to the scheme you want to update. Jira lists the permissions and users they are granted to.
   2. Next to Create Attachments, click Edit. The Grant permission dialog displays.
      
   3. In the Permission field, add Delete Own Attachments.
   4. In Grant to, select the user you want to grand the permission to.
   5. Click Grant.

Advanced configuration

You can implement the following advanced configurations to modify the way Jira handles attachments. However, these are not accessible through Jira’s attachment settings. One of these advanced configurations can be modified as an ‘Advanced Setting’ in Jira’s administration area, although the remaining two are implemented by defining properties in your jira-config.properties file.

Configuring thumbnail size

By default, thumbnails are 200 pixels wide and 200 pixels high. To change the dimensions of thumbnail images:

1. Stop Jira.
2. Edit the jira-config.properties file in your Jira home directory.
    See Making changes to the jira-config.properties file for more information.
3. Edit the values of the following properties:
   • jira.thumbnail.maxwidth — thumbnail width in pixels
   • jira.thumbnail.maxheight — thumbnail height in pixels
      If neither of these properties exist in your jira-config.propertiesfile, add them to the file. For example, specify the following for a thumbnails that are 100 pixels wide:
     
     jira.thumbnail.maxwidth = 100

     1	jira.thumbnail.maxwidth = 100

4. Delete all existing thumbnail images within the attachments directory (that is, those containing ‘_thumb_‘ in the filename).
5. Restart Jira.

After restarting Jira, all thumbnails will be recreated automatically using the new dimensions.

Configuring ZIP-format file accessibility

By default, Jira allows you to access common ZIP-format files, with file extensions like ‘.zip‘ and ‘.jar‘ (Java archive files). However, there are numerous other ZIP-format files to which Jira does not permit access by default. You can permit access to these files by doing the following:

1. Stop Jira.
2. Edit the jira-config.properties file in your Jira home directory.
    See Making changes to the jira-config.properties file for more information.
3. Remove the extensions from the jira.attachment.do.not.expand.as.zip.extensions.list property of the file types whose contents you wish to access in Jira.
    If this property does not exist in your jira-config.properties file, add the name of this property, followed ‘=‘, followed by the content of the <default-value/> element copied from your Jira installation’s jpm.xml file. Then, begin removing the extensions of file types whose contents you wish to access in Jira.
4. Restart Jira.

Configuring the number of files shown in the content of ZIP-format files on issues

By default, Jira shows a maximum of 30 files in the content of ZIP-format files attached to an issue. To change this maximum value:

1. Access Jira’s Advanced Settings page. (See Advanced Jira configuration for more information.)
2. Edit the value of the jira.attachment.number.of.zip.entries property by clicking the existing value and specifying the maximum number of attachments you want to show on an issue.
3. Click the Update button to save the new value in the Jira database.