Wiki
Clone wikiDocuments Add-On / 200
Documents add-on version 2.0.x
The content of this page applies to the following version(s) of the Documents add-on:
- v. 2.0.x for JIRA 5.0 or later
On this page:
- Documents add-on version 2.0.x
What's new in this version?
Folders hierarchy
Starting with this version you can better organize and group your documents in folders. You can add as many folders as you need by using the Add Folder button available on the Documents tab of the project. A folder can contain an unlimited number of documents or other folders.
You can navigate from one folder to another by using the navigation bar available on top of the Documents tab.
The actions that a user can perform on folders (create, edit, delete, move) can be restricted via add-on permissions settings.
Version history
An internal versioning mechanism was introduced in this version. When a document is updated (for example, its associated file is replaced or its properties are changed), its internal version is incremented and the previous version is saved in the version history.
You can visualize the previous versions of a document by using the Previous Versions action, which is available in the actions menu of that document.
Click the View action of a version to select it and to visualize its data. You can restore the selected version by clicking the Restore Version button.
By restoring a version, a new version is created with the data from the version that you chose to restore.
Documents watching and email notifications
Starting with this version you can choose to watch a particular document, signing up for email notifications of any updates relating to that document. You can choose to become the watcher of the document right during document creation, by checking the Make me watcher of this document option available in the Add Document screen.
Also, you can start watching a document by using the Watch action available in the actions menu of the document. If you are already watcher of a document, you can stop watching that document by using the Stop watching action.
The format (HTML or Text) of the notification email is the one from the watcher's JIRA user profile, configured under Email Type field. The My changes option from the watcher's JIRA user profile is also considered when notifying the watchers.
NOTE: Emails are sent to watchers only if JIRA is properly configured to send email notifications.
Ability to move a document or folder
You can move a document or a folder to another folder or in the root folder of the project by using the Move action available in the actions menu. This menu action is only available for those users that have Move permission.
To move the document you have to first choose the destination folder and then click the Move button.
UI changes and improvements
There are some UI changes and improvements in this version, which include:
- Displaying the confirmation messages on top of the browser's window
- Pop-up menu for the document actions
- Better error handling
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 and folders
Accessing and viewing documents
The documents of a JIRA project can be visualized on the Documents tab of that project. The project’s documents and folders are listed in a table, as shown in the picture below. To display the content of a folder, simply click the folder's icon or its name.
Note: The Documents tab is visible only if the current JIRA user has View permission.
The navigation bar displayed on top the Documents tab allows you to determine which folder is currently displayed. Also, it allows you to navigate to another folder by simply clicking the folder's name.
The table below shows details about the columns of the documents table.
Item | Description |
---|---|
Icon | Shows the icon of the document or folder. 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. By clicking the icon of a folder the page will display the content of that folder. |
Key | The key of the document or folder. It uniquely identifies the document within the JIRA system. It has numeric value and is automatically generated during document or folder creation. |
Title | The title of the document or folder. 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 clicks the title of a URL type document, he will open the URL in the default browser of the system. By clicking the title of a folder the page will display the content of that folder. |
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. It is always empty for folders. |
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 or folders. |
Posted by | Shows the JIRA user that posted the document or created the folder. |
Updated by | Shows the JIRA user that made the latest update of the document or folder. It will be empty if the document or folder was never updated. |
Date updated | Shows the date and time of the latest update of the document or folder. It will be empty if the document or folder 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 or folder. 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 and for folders if the current user has Edit permission. Delete – use this action to delete the document or folder. It is available for both File and URL document types and folders if the current user has Delete permission. Move – use this action to move a document or folder to another folder within the same JIRA project. It is available for both File and URL document types and for folders if the current user has Move permission. Watch – use this action to start watching a document. It is available for both File and URL document types if the current user is not already a watcher of the document. Stop Watching – use this action to stop watching a document. It is available for both File and URL document types if the current user is already a watcher of the document. Previous Versions – use this action to access the previous versions of a document. It is available for both File and URL document types if the current user has View permission. |
Adding a new document
Follow the next steps to add (post) a new document:
- In JIRA, go to Projects.
- Make sure you are on the right project.
- Click the Documents tab and navigate to the folder where you want to add the document.
- Click the Add Document button. The Add Document page will open.
NOTE The Add Document button is available only if the user has Create permission.
- Choose the Document Type for 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. 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://", "ftp://" or "file:").
NOTE From security reasons, most of the browsers do not allow opening links of type "file:". This means that you will not be able to open the file by clicking the links available on the Documents tab. Be aware of this limitation when using URLs of type "file:"!
- Optionally, if you use a version numbering for your documents, type 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. - Keep Make me watcher of this document checked if you want to become watcher of the document.
- Click Add. If all the required fields were properly completed, the document is added and displayed in the Documents table. A message with the result of this action will pop-up on top of the page.
Adding a new folder
Follow the next steps to add a new folder:
- In JIRA, go to Projects.
- Make sure you are on the right project.
- Click the Documents tab and navigate to the folder where you want to create the folder.
- Click the Add Folder button. The Add Folder page will open.
NOTE The Add Folder button is available only if the user has Create permission.
- Enter a Title (or a name) for your folder. This field is mandatory.
- Optionally, enter a short Description for the folder.
- Click Add. If all the required fields were properly completed, the folder is added and displayed in the Documents table. A message with the result of this action will pop-up on top of the page.
Editing a document
Follow the next steps to edit a document:
- 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 menu. The Edit Document page will open.
NOTE The Edit action is available only if the user has Edit permission. - Make the necessary changes and click Save. A message with the result of this action will pop-up on top of the page.
Editing a folder
Follow the next steps to edit a folder:
- In JIRA, go to Projects
- Make sure you are on the right project
- Click the Documents tab
- Locate the folder that you want to edit and click on its Edit link under the Actions menu. The Edit Folder page will open.
NOTE The Edit action is available only if the user has Edit permission. - Make the necessary changes and click Save. A message with the result of this action will pop-up on top of the page.
Deleting a document
Follow the next steps to delete a document:
- 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 menu.
NOTE The Delete action is available only if the user has Delete permission. - 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. A message with the result of this action will pop-up on top of the page.
NOTE The document is permanently deleted along with its version history; you cannot restore it after deletion.
Deleting a folder
Follow the next steps to delete a folder:
- In JIRA, go to Projects.
- Make sure you are on the right project.
- Click the Documents tab.
- Locate the folder that you want to delete and click on its Delete link under the Actions menu.
NOTE The Delete action is available only if the user has Delete permission. - You will be asked if you really want to delete the folder. If you are sure that you want to delete the folder, click OK. A message with the result of this action will pop-up on top of the page.
NOTE The folder is permanently deleted along with its content; you cannot restore it after deletion.
Moving a document
Follow the next steps to move a document to another folder:
- In JIRA, go to Projects.
- Click the Documents tab.
- Make sure you are on the right project.
- Locate the document that you want to move and click on its Move link under the Actions menu.
NOTE The Move action is available only if the user has Move permission. - In the Move window, select the destination folder in the folders tree hierarchy.
- Click Move. A message with the result of this action will pop-up on top of the page.
NOTE: You can move documents only to folders of the same JIRA project.
Moving a folder
Follow the next steps to move a folder to another folder:
- In JIRA, go to Projects.
- Click the Documents tab.
- Make sure you are on the right project.
- Locate the folder that you want to move and click on its Move link under the Actions menu.
NOTE The Move action is available only if the user has Move permission. - In the Move window, select the destination folder in the folders tree hierarchy.
NOTE: You are not allowed to select as destination folder the folder that you want to move or one of its sub-folders; these folders are disabled and cannot be selected.
- Click Move. A message with the result of this action will pop-up on top of the page.
NOTE: You can move folders only to folders of the same JIRA project.
Watching documents
You can choose to watch a particular document, signing up for email notifications of any updates relating to that document. As a watcher of a document, you will be notified each time one of the following events occur:
- The document was updated
- The document was deleted
- Someone stopped or started watching the document
- A previous version of the document was restored
- The document was moved to another folder
The format (HTML or Text) of the notification email is the one from the watcher's JIRA user profile, configured under Email Type field. The My changes option from the watcher's JIRA user profile is also considered when notifying the watchers.
The watching options are only available for documents; watching a folder is not possible.
NOTE Emails are sent to watchers only if JIRA is properly configured to send email notifications.
Start watching a document
Follow the next steps to start watching a document:
- In JIRA, go to Projects.
- Make sure you are on the right project.
- Click the Documents tab.
- Locate the document that you want to watch and click on its Watch link under the Actions menu. A message with the result of this action will pop-up on top of the page.
NOTE If the Watch menu-option is not present, it means that you are already a watcher of that document.
Stop watching a document
Follow the next steps to stop watching a document:
- In JIRA, go to Projects.
- Make sure you are on the right project.
- Click the Documents tab.
- Locate the document that you want to watch and click on its Stop watching link under the Actions menu. A message with the result of this action will pop-up on top of the page.
NOTE If the Stop watching menu-option is not present, it means that you are not a watcher of that document.
Version history
An internal versioning mechanism was introduced in this version. When a document is updated (for example, its associated file or properties are changed), its internal version is incremented and the data of the previous version is saved in a version history table.
You can visualize the previous versions of a document at any time or you can download the file that corresponds to an older version of the document. Also, if you have Edit permission, you can restore one of the previous version of a document.
By restoring a version, a new version is created with the data from the version that you chose to restore.
NOTE Version history only applies to documents; folders do not have internal versioning.
Viewing the previous versions of a document
Follow the next steps to view the previous versions of a document:
- In JIRA, go to Projects.
- Make sure you are on the right project.
- Click the Documents tab.
- Locate the document and click on its Previous Versions link under the Actions menu.
The Previous versions for... window will be displayed showing the list with the previous versions of the document in the left side and data of the selected version in the right side (see the picture below).
NOTE If the document has no previous versions a message will be displayed on this matter. - In the list with the versions from the left side, click View to select a version and visualize its data in the right side of the window.
- In case of a File type document you can download the file associated with the selected previous version by clicking the link with the name of the file.
Restoring a previous version of a document
Follow the next steps to restore a previous version of a document:
- In JIRA, go to Projects.
- Make sure you are on the right project.
- Click the Documents tab.
- Locate the document and click on its Previous Versions link under the Actions menu.
The Previous versions for... window will be displayed showing the list with the previous versions of the document in the left side and data of the selected version in the right side.
NOTE If the document has no previous versions a message will be displayed on this matter. - In the list with the versions from the left side, click View to select a version and visualize its data in the left side of the window.
- After selecting the version that you want to restore, click the Restore Version button. A message with the result of this action will pop-up on top of the page.
NOTE The Restore Version button is not visible if the user does not have Edit permission.
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 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
- 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.
- Click Save to apply the changes.
The table below shows details about the available settings.
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 actions (create, edit, delete, move) regarding documents or folders through the 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 permissions.
- Click Save to apply the changes.
The table below shows details about the available permissions.
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 add documents and folders. 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 documents and folders or to restore a previous version of a document. 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 documents and folders. The “Delete” option will be hidden for the users that do not have this permission. |
Move | Check this option if you want the project role members to be able to move documents and folders to another folder. The “Move” 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 the actions performed on 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.
Activity Stream is updated each time one of the following events occur:
- A document or folder was created
- A document or folder was updated
- A document or folder was deleted
- Someone stopped or started watching a document
- A previous version of a document was restored
- A document or folder was moved to another folder
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.
File storage
The files attached to the documents are stored in a newly created sub-folder named "documentsaddon" located in the JIRA attachments folder.
NOTE Do not delete or rename this folder!
Updated