Configuring file attachments
When file attachments are enabled, your users will be allowed to attach files and screenshots to JIRA issues. This requires space on the server for storing the attachments.
File attachments are enabled by default. If you wish, you can configure the way JIRA handles attachments, or disable this feature altogether.
Attachments are not stored in JIRA's database and so will need to be backed up separately.Note:
- Your users must also have the Create Attachments permissions to attach files to issues.
- To allow users to attach a file when creating a new issue, you need to ensure that the Attachment field is not hidden within the field configuration(s) associated with the specific issue type(s).
- For all of the following procedures, you must be logged in as a user with the JIRA Administrators global permission.
Configuring attachment settings
- Choose
> System. - Select Advanced > Attachments to open the Attachment page, which states whether attachments are on or off.
- Click the Edit Settings button, which opens the Edit Attachment Settings dialog box:
- In the Attachment Path field, choose the Use Default Directory option. If you see more attachment path options than what is shown in the screenshot above, please refer to the note below.
As mentioned above, if you have not logged in as a user with the JIRA System Administrators global permission, then this option will not be available to you. - In the Attachment Size field, specify the maximum attachment size. The default (per file) is 10485760 bytes (10 MB). The maximum attachment size (per file) is 2147483647 bytes (2 GB).
- (Optional) In the Enable Thumbnails field, ensure that ON is selected if you wish to display image file attachments as thumbnails (or miniature previews) when viewing an issue. When this setting is enabled, JIRA automatically creates thumbnails of the following types of image attachments:
- GIF
- JPEG
- PNG
Please refer to the info note below for more information about thumbnails. If you use Linux, please refer to the Linux note below. - (Optional) In the Enable ZIP Support field, ensure that ON is selected if you wish to view the contents of zip files attached to an issue and allow all files attached to an issue to be downloaded as a single ZIP file.
- Click the Update button to update JIRA's attachment settings.
To attach files to issues, the appropriate users, groups or project roles must first be assigned the Create Attachments permission for the relevant project(s).
To allow these users or group/project role members to delete their own attached files from issues, they must also be assigned the Delete Own Attachments permission for these projects too.
There is no need to proceed any further if:
- the permission schemes used by your project(s) already have the Create Attachments (and Delete Own Attachments) permission, or
- your project(s) use JIRA's built-in Default Permission Scheme.
However, if you wish to configure these permissions, proceed with the steps in the section below.
Configuring create/delete attachment permissions
- Choose > Issues.
- Select Permission Schemes to open the Permission Schemes page, which displays a list of all permission schemes in your JIRA system and the projects that use each scheme.
- For each relevant permission scheme:
- Click the Permissions link associated with the relevant permission scheme to edit that scheme's permissions.
- On the Edit Permissions page, locate Create Attachments within the Attachment Permissions section and click the Add link.
- In the user selection options on the right of the Add New Permission page, select the relevant (groups of) users or roles and then click the Add button.
To allow these users or group/project role members to delete their own attachments, do not forget to assign them the Delete Own Attachments permission too.
- Click the Permissions link associated with the relevant permission scheme to edit that scheme's permissions.
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/attachmentssubdirectory 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
Imagescolumn. - All thumbnail images are stored in JPEG format in the
attachmentsdirectory, 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
Advanced configurations
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:
- Stop JIRA.
- Edit the
jira-config.propertiesfile in your JIRA home directory. See Making changes to the jira-config.propertiesfile for more information. - Edit the values of the following properties:
jira.thumbnail.maxwidth— thumbnail width in pixelsjira.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
- Delete all existing thumbnail images within the
attachmentsdirectory (that is, those containing '_thumb_' in the filename). - 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:
- Stop JIRA.
- Edit the
jira-config.propertiesfile in your JIRA home directory. See Making changes to the jira-config.propertiesfile for more information. - Remove the extensions from the
jira.attachment.do.not.expand.as.zip.extensions.listproperty of the file types whose contents you wish to access in JIRA. If this property does not exist in your jira-config.propertiesfile, add the name of this property, followed '=', followed by the content of the<default-value/>element copied from your JIRA installation'sjpm.xmlfile. Then, begin removing the extensions of file types whose contents you wish to access in JIRA. - 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:
- Access JIRA's Advanced Settings page. (See Advanced JIRA configuration for more information.)
- Edit the value of the
jira.attachment.number.of.zip.entriesproperty by clicking the existing value and specifying the maximum number of attachments you want to show on an issue. - Click the Update button to save the new value in the JIRA database.