Documents add-on version 1.1.x

The content of this page applies to the following version(s) of the Documents add-on:

v. 1.1.x for JIRA 5.0 or later

On this page:

Documents add-on version 1.1.x

What's new in this version?

The Key of the documents displayed on the "Documents" tab of the project
Each document has its own (numerical) key which uniquely identifies it within the JIRA system. The key is now displayed on the "Documents" tab of the project and will be used in other places to reference documents.

The Key of the document displayed on the "Documents" tab

Activity Stream posting
A summary of any create, update or delete operation performed against the documents is posted and can be visualized in the Activity Stream gadget. A description showing the modified fields of the document is displayed in case of document update operations.

Operations against documents visible in Activity Stream gadget

The title of the posted activity references the document by <Key> - <Title>. Only the first 40 characters of the Title are displayed.

You can configure your Activity Stream gadget to show only the activities related to Documents by selecting "JIRA - Documents" as a filter. Activity Stream gadget configuration

Confirmation messages for document operations

Right after performing an action (create, edit or delete) against a document, the "Documents" tab will display a message indicating if that action was successful or not.

Confirmation message

What Documents add-on does?

This JIRA add-on adds an additional tab named Documents to the project dashboard where you can post documents related to that project, making them available to other project members. You can post files along with specific details such as title, description or revision. Or, you can post URLs that link to a web page or to a document hosted by an external system such as Confluence or Google Docs. The files that you attach are stored in JIRA, more exactly in a sub-folder of the JIRA attachments folder, thus simplifying your administrative and backup procedures. The access to the Documents tab and different operations on the posted documents are configurable via permissions settings.

Why Documents add-on?

Makes the documents quickly accessible for the project members.
No more project-related documents stored on people’s workstations. Everyone will know that the latest version of a specific document will be found on the Documents tab of the project.
The documents are hosted in JIRA providing common interface for all the project related work-items such as tasks, issues and documents.

Working with Documents

Accessing and viewing documents

The documents of a JIRA project can be accessed from the “Documents” tab of that project. The project’s documents are listed in a table, as shown in the picture below.

The Documents tab of the project

Note: The document tab is visible only if the current JIRA user has View permission.

The table above shows details about the columns of the documents table.

Item	Description
Icon	Shows the icon of the document. The add-on has its own icon set which contains icons for the common file extensions. Every File type document will have the icon specific to the extension of its attached file. If the extension is not in the icon set of the add-on, the default icon is displayed. The URL type document will always have the URL icon. By clicking the icon of a File type document the user will download the file attached to the document. On the other hand by clicking the icon of a URL type document the user will open the URL using the default browser of the system.
Key	The key of the document. It uniquely identifies the document within the JIRA system. It has numeric value and is automatically generated during document creation.
Title	The title of the document. If the title is too long it will not be entirely displayed. The title is fully displayed in the tooltip that is shown when moving the mouse cursor over it. By clicking the title of a File type document the user will download the file attached to the document. If the user is clicking the title of a URL type document, he will open the URL in the default browser of the system.
Revision	Shows the value of the Current Revision attribute of the document. A tooltip is shown when moving the mouse pointer over it. This tooltip displays a text that consists of the concatenation of the following document properties : Revision Date, Revision Author(s) and Revision Notes.
File size	The size of the file attached to the document. This column only applies for File type documents. It is always empty for URL type documents.
Posted by	Shows the JIRA user that posted the document.
Updated by	Shows the JIRA user that made the latest update of the document. It will be empty if the document was never updated.
Date updated	Shows the date and time of the latest update of the document. It will be empty if the document has never been updated. The date is displayed in the format and time zone of the current JIRA user.
Actions	The actions available for each document. Possible actions are: Download – use this action to download the file attached to the document. It is only available for File type documents if the current user has View permission. Open URL – use this action to open the URL of the document. It is only available for URL type documents if the current user has View permission. Edit – use this action to edit the document. It is available for both File and URL document types if the current user has Edit permission. Delete – use this action to delete the document. It is available for both File and URL document types if the current user has Delete permission.

Adding a new document

Follow the next steps to add (post) a new document on the “Documents” tab of a project:

In JIRA, go to Projects.
Make sure you are on the right project.
Click the Documents tab.
Click the Add Document button. The Add Document page will open.
NOTE The Add Document button is available only if the user has permissions for creating documents.

Adding a document of type File

Choose the Type of the document that you want to add:
File – choose this type if the document that you want to add is a file.
URL – choose this type if the document that you want to add is a link (URL) to a web page or to a document hosted by an external system accessible through web. Also, choose this in case you want to specify an FTP path.
NOTE Once the document was added, its type cannot be changed.
Enter a Title (or a name) for your document. The Title is used to identify the file. This field is mandatory.
Optionally, enter a short Description for the document.
If you choose to add a File type document, you must attach a File. Use the Choose file button to upload the file. The file that you select cannot exceed the maximum file size configured by the JIRA administrator.
If you choose to add an URL type document, you must specify the URL of the document. The URL that you specify must include the protocol (“http://”, “https://” or “ftp://”).
Optionally, if you use a version numbering for your documents, enter the current version of the document in the Current Revision field. You can also specify additional info about the current version of the document:
Revision Date – the date when the version of the added document was created.
Revision Author(s) – the name of the person(s) who created the version of the added document.
Revision Notes – a short description of the changes made to the version of the added document.
Click Add. If all the required fields were properly completed, the document is added and displayed on the “Documents” tab of the project.

Editing a document

Follow the next steps to edit a document from the “Documents” tab of a project:

In JIRA, go to Projects
Make sure you are on the right project
Click the Documents tab
Locate the document that you want to edit and click on its Edit link under the Actions column. The Edit Document page will open.
NOTE The Edit link is available only if the user has permissions for editing documents.
Make the necessary changes and click Save.
NOTE The Type of the document cannot be changed.

Deleting a document

Follow the next steps to delete a document from the “Documents” tab of a project:

In JIRA, go to Projects.
Make sure you are on the right project.
Click the Documents tab.
Locate the document that you want to delete and click on its Delete link under the Actions column.
NOTE The Delete link is available only if the user has permissions for deleting documents.
You will be asked if you really want to delete the document. If you are sure that you want to delete the document, click OK. The document is deleted and is no longer displayed on the “Documents” tab of the project.
NOTE The document is permanently deleted; you cannot restore it after deletion.

Installing add-on

This add-on is composed of a single JAR file and can be installed directly from the Universal Plugin Manager (UPM).

If you manually downloaded the JAR file, follow the next steps to install it:

Log on to JIRA as an administrator
Go to Administration
Go to add-ons menu and click add-ons to open UPM page
Go to Install tab
Click Upload add-on
Select the JAR file
Click Upload to start the installation. When the installation is done, a confirmation message is displayed.

The add-on is not fully functional at this time. You must obtain and then activate a trial or commercial license in order to use it. See Activating the add-on license.

Activating the add-on license

In order to run this add-on you need a trial or a commercial license. You can purchase the Documents add-on on the Atlassian® Marketplace or through the Universal Plugin Manager (UPM). Once you obtained the license code, you must activate it. License activation steps depend on the version of Universal Plugin Manager (UPM) installed on your JIRA instance.

License activation for UPM 2.0 or newer version

If you have Universal Plugin Manager (UPM) 2.0 or the newer version, follow the next steps to activate the add-on license:

Log on to JIRA as an administrator
Go to Administration
Go to add-ons menu and click add-ons or Manage Add-ons to open UPM page
Locate and expand the Documents add-on under User-installed add-ons
Enter the license code in the License key field
Click Update. If your license is valid a confirmation message is displayed on top of the page.

License configuration in UPM

License activation for an earlier version than UPM 2.0

If you have a version of Universal Plugin Manager (UPM) older than 2.0, follow the next steps to activate the add-on license:

Log on to JIRA as an administrator
Go to Administration
Go to add-ons menu and click License under Documents add-on Configuration
On the License tab enter the license code in the Enter a new license field

License configuration

Click Update. If your license is valid a confirmation message is displayed on top of the page.

Configuring the add-on settings

Follow the next steps to configure the add-on settings:

Log on to JIRA as an administrator
Go to Administration
Go to add-ons menu and click Settings under Documents add-on Configuration
On the Settings tab, change the settings to suit your preferences. See the table below for a complete description of the available settings.

add-on settings

Click Save to apply the changes.

Setting	Description
Maximum file size	The maximum size allowed for an uploaded file, in MB. The default value is 10 MB. JIRA administrators should keep in mind that the necessary amount of disk space is directly proportional to the number and size of files introduced into the system.

Configuring the add-on permissions

You can restrict the access to the "Documents" tab or restrict specific document actions (create, edit, delete) through add-on permissions configuration. Follow the next steps to configure the add-on permissions:

Log on to JIRA as an administrator
Go to Administration
Go to add-ons menu and click Permissions under Documents add-on Configuration
On the Permissions tab, check the actions that you want to allow for each project role. See the table below for a complete description of the available actions.

add-on permissions

Click Save to apply the changes.

Permission	Description
View	Check this option if you want the project role members to view and download the documents posted on the “Document” tab. The “Documents” tab will be hidden for the users that do not have this permission.
Create	Check this option if you want the project role members to be able to post documents on the “Document” tab. The “Add Document” button will be hidden for the users that do not have this permission.
Edit	Check this option if you want the project role members to be able to edit the documents from the “Document” tab. The “Edit” option will be hidden for the users that do not have this permission.
Delete	Check this option if you want the project role members to be able to delete the documents from the “Document” tab. The “Delete” option will be hidden for the users that do not have this permission.

NOTE If a JIRA user is member of a project role that has a specific permission but he/she is also member of another project role that does not have that permission, it is considered that the user in question has that permission.

Activity Stream posting

A summary of any create, update or delete operation performed against the documents is posted and can be visualized in the Activity Stream gadget. A description showing the modified fields of the document is displayed in case of document update operations.