Wiki
Clone wikiDocuments Add-On / 700
Documents for Jira 7.0.x
The content of this page applies to the following app version(s):
- Documents 7.0.x for Jira Server and Jira Data Center v7.1 or newer
- Documents 7.1.x for Jira Server and Jira Data Center v7.1 or newer
On this page:
- Documents for Jira 7.0.x
- What's new in this version
- Why Documents app?
- Working with documents and folders
- Accessing and viewing documents
- Searching documents
- Adding a new folder
- Adding a new document
- Editing a document or folder
- Deleting a document of folder
- Bulk documents deletion
- Moving a document or folder
- Bulk documents movement
- Copying (cloning) the structure of a folder
- Bulk documents download
- Locking/Unlocking Editing
- Watching documents
- Linking and referencing documents in Jira issues
- Version history
- Setting permissions over individual folders and documents
- Activity Stream posting
- Using the Documents gadgets
- Installation and configuration
- Bulk documents upload and migration from another Document Management System
- Documents REST API
- Obtaining the list of Jira projects
- Obtaining the list of documents for a Jira project
- Obtaining the attributes of a document
- Obtaining the list of previous versions of a document
- Obtaining the attributes of a previous document version
- Creating a new document or folder
- Uploading a file attachment
- Obtaining the Upload Token
- Updating an existing document
- Deleting an existing document
- Searching and retrieving documents by title
- Searching and retrieving documents by using advanced search options
- Retrieving document metadata
What's new in this version
GUI Refreshment
We redesigned the GUI a bit for a better user experience and better usability. As a user, you now can choose between multiple layouts and visualization modes applicable to the Documents tab of each Jira project.
While the tree panel and the list view did not change too much, the new right-side panel offers all the details of the selected document including the document meta-data, linked issues and a preview of the attached file. The preview is available for common file types like images, text, PDF, audio (MP3, WAV) and video files (MP4).
Also, you can now switch to icons view mode as an alternative to the "classical" list view mode.
Or, you can switch to split panel layout to see the content of two folders side-by-side.
The selection of the documents for bulk operations can now be done directly from the main view, a Bulk operations menu being displayed automatically if you select at least two items.
Adding files with drag & drop
Posting new files in Documents is now easier. You can simply drag & drop one or more files at once directly in the documents panel (list or icons view) and the files will be added in Documents.
Ability to customize what columns to be displayed in list view
As a Jira admin, you can now configure what columns to be displayed in the documents table. This can be done in the app's Configuration Settings page. Also, now you can choose to display the "Posted on" column in the list view.
Why Documents app?
- 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. They are dispayed according to the current layout and visualization mode.
The current layout and visualization mode can be changed by using the menus from top-right corner of the page.
Note: The Documents tab is visible only if the current Jira user has View permission.
The table below shows details about the columns of the documents table available in list view.
Note: The Jira admin can configure which columns to be displayed by the list view (see the "Configuring the app settings" section).
Item | Description |
---|---|
Preview icon | Clicking the preview icon ![]() This icon is available only for PDF files or images (JPG, JPEG, GIF, PNG and BMP) and only if the user has View permissions over the document. |
Type | Shows the icon of the document or folder. The app 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 app, the default icon is displayed. The URL type document will always have an URL specific icon. |
Icon indicators | The icon indicators are small icons displayed near the regular icon of the document that indicate specific states of the document. For instance, if the document is locked for editing or not. In this version the following indicators are available:![]() ![]() ![]() |
Key | The key (or ID) 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 hovering the mouse pointer 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. 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. |
Posted on | Shows the date and time when the document or folder was posted. The date is displayed in the format and time zone of the current Jira user. |
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. |
Updated on | 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 menu | An icon (![]() |
The actions menu is available in both list view and icons view. It is displayed when hovering the mouse over a document or folder.
Possible actions are:
Download – use this action to download the file attached to the document or the content of a folder. It is only available for File type documents and folders if the current user has View permission. When downloading a folder, its content will be downloaded as a ZIP archive. The URL type documents are not included in the ZIP archive.
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.
View – use this action to view document properties in a read-only page. It is available for both File and URL document types and also for folders 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 also for folders if the current user has Edit permission.
Lock Editing – use this action to lock the editing for the document. It is available only for File and URL document types if the current user has Edit permission.
Linked issues – use this action to see a list of Jira issues that have a link to that document or folder. It is available for both File and URL document types and folders if the current user has View 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 or project. It is available for both File and URL document types and also for folders if the current user has Move permission.
Copy Folder Structure – use this action to clone the structure of a folder into another folder or project. It is available only for folders.
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.
Set Permissions – use this action if you want to limit the access to the document or to deny specific operations like Edit or Delete for specific users or groups. It is available for both File and URL document types and also for folders if the current user has Set Permissions rights.
Show in Folder – opens the parent folder of the document or folder. It is available for both File and URL document types and also for folders but only in the context of a search result.
NOTE: The Project Lead can perform all the above actions on all the documents of the Jira project.
Searching documents
You can search for documents or folders by typing a text (and then pressing Enter) in the search box available on the Documents tab of the project.
Optionally, you can use the advanced search options to make the search operation more precise.
The search is text-based and covers the following properties of the documents: Key (document number), Title, Description, Current Revision, Current Revision Author(s), Current Revision Notes and the name of the attached file. Only the documents of the current Jira project are searched.
NOTE: The search does not include the content of the attached files. The previous versions (version history) of the documents are also not included.
The search results are displayed on the Documents tab of the project.
Follow the next steps to search documents:
- In Jira, go to Projects.
- Make sure you are on the right project.
- Click the Documents tab. You can also navigate to a folder belonging to that project.
- In the Document Search box, type the text or the document number that you want to search for and then press Enter. The search results are displayed on the page.
- Optionally, click the icon from the search input field and select the advanced search options. Press Enter or click Do search for the selection to take effect.
Adding a new folder
Follow these 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 > Add Folder. The Add Folder dialog will open.
NOTE The Add 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 Create. 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.
Adding a new document
Besides folders, the Documents app supports two document types:
- File – consists in a file that is uploaded and stored in Jira, plus data about that file like Title or Description.
- URL – consists in a URL (link) to a remote file or web-page, plus data about that remote file or web-page like Title or Description.
Follow these 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 Add > Add File if you want to add a File type document, of click Add > Add URL if you want to add an URL type document. The Add dialog will open.
NOTE The Add button is available only if the user has Create permission.
- 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 For 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 Create. 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.
Editing a document or folder
Follow these 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 option 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.
NOTE With the Documents app you can only edit the properties of your document and replace the file attached to the document. If you want to modify the content of the file attached to a document, you have to first download it locally on your computer, make the necessary changes locally with the appropriate program and then upload the new file to the document.
Deleting a document of folder
Follow these steps to delete a document or folder:
- 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 option 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.
Bulk documents deletion
Follow these steps if you want to delete multiple documents and folders at once:
- In Jira, go to Projects.
- Click the Documents tab.
- Make sure you are on the right project.
- Open the folder that contains the items that you want to delete.
- Select the documents and folders that you want to delete. The Bulk operations menu will appear.
- Click Bulk operations and then click Bulk Delete
- In the confirmation window, click Yes if you really want to delete the selected items.
NOTE: The delete operation cannot be undone.
Moving a document or folder
Follow these steps to move a document or folder 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 option under the Actions menu.
NOTE The Move action is available only if the user has Move permission. - In the Move window, select the Destination Project and the Destination Folder in the folders tree hierarchy.
NOTE: To be able to move a folder in another project, you must have View and Create permissions in that project.
Bulk documents movement
Follow these steps if you want to move multiple documents and folders at once:
- In Jira, go to Projects.
- Click the Documents tab.
- Make sure you are on the right project.
- Open the folder that contains the items that you want to move.
- Select the documents and folders that you want to move. The Bulk operations menu will appear.
- Click Bulk operations and then click Bulk Move
- In the Move window, select the Destination Project and the Destination Folder in the folders tree hierarchy.
NOTE: To be able to move a folder in another project, you must have View and Create permissions in that project.
- Click Move. A message with the results of this action will pop-up.
Copying (cloning) the structure of a folder
Follow these steps to copy (clone) the structure of a folder into 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 clone and click on its Copy Folder Structure option under the Actions menu.
- In the Copy Folder Structure window, select the Destination Project and the Destination Folder in the folders tree hierarchy. It represents the place where the copy (clone) will be made.
NOTE: The created structure includes the folder and its sub-folders; the documents (Files or URLs) from the selected folder are not cloned. To be able to copy (clone) a folder structure, you must have View and Create permissions in the destination project.
Bulk documents download
Follow these steps if you want to download multiple documents and folders at once:
- In Jira, go to Projects.
- Click the Documents tab.
- Make sure you are on the right project.
- Open the folder that contains the items that you want to download.
- Select the documents and folders that you want to move. The Bulk operations menu will appear.
- Click Bulk operations and then click Bulk Download
The selected documents are grouped in a ZIP archive, which is then downloaded locally on your computer.
NOTE: The downloded ZIP archive will preserver the folders structure. The file attachments of the select documents will be added to the archive; their names might be changed in order to preserve unicity. The selected URL documents are not downloaded, so they will not be included in the archive.
NOTE: You can also download a specific folder by clicking the Download option from its actions menu.
Locking/Unlocking Editing
While working on a new version of a document you might want to prevent the other users to edit that document until you finish working and publishing the new version. You can do this by using the Lock Editing menu-option, which is available in the actions menu of the document. When locking the document for editing you can leave a message that will be displayed to the other users each time they attempt to edit the document. After finishing the work on that document and publishing a new version you can unlock the document's editing by clicking the Unlock Editing menu-option or directly from the Edit Document screen. A document can be locked by any user that has Edit permissions. The unlocking of a document can either be done by the user that locked the document or by the Project Lead.
Lock editing for a document
Follow these steps to lock editing for 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 lock editing for and click on its Lock Editing option under the Actions menu.
The Lock Editing page will open.
NOTE The Lock Editing menu-option is available only if the user has Edit permissions. - Optionally, you can leave a message that will be displayed to the other users each time they attempt to edit the locked document.
- Click Save. A message with the result of this action will pop-up on top of the page.
The documents that are locked for editing have the "lock indicator" displayed near their icon:
Unlock editing for a document
Editing can be unlocked only by the user that locked the editing for that document or by the Project Lead.
Follow these steps to unlock editing for 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 unlock editing for and click on its Unlock Editing option under the Actions menu.
- A message with the result of this action will pop-up on top of the page.
You can also unlock editing for a document directly from the Edit screen, by checking the option Unlock editing for this document.
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.
The documents watched by you have the "watch indicator" displayed near their icon:
Start watching a document
Follow these 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 option 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 these 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 option 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.
Linking and referencing documents in Jira issues
Linking documents to Jira issues
You can link documents or folders to Jira issues by using the Link action of a Jira issue.
Follow these steps to link a document or folder to a Jira issue:
- Open the Jira issue that you want to link the document to.
- Select More > Link to display the Link dialog box.
- Click the Document option from the left of the dialog box.
- Search for the document that you want to link. If you want to link a document from a project other than the current Jira project, select that project in the dropdown list near the search box.
NOTE The dropdown list contains only the projects for which the current user has view permissions.
- In the search results table click the Select link from the row of the document that you want to link
- Optionally add a Comment to describe why you are linking the document.
- Click the Link button from the bottom of the dialog.
- The document you just linked is now listed under the Links section of the Jira issue.
Viewing the Jira issues linked to a document
To view the Jira issues that are linked to a specific 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 Linked Issues... option under the Actions menu. The Jira issues that are linked to the document will be displayed.
Referencing documents in Jira issues
You can add references to documents or folders in the Jira fields (such as Description) or in comments. The way to do this depends on what edit mode is currently used.
In Text mode this can be done via the {doc-key} macro.
For example, if the Key of your document is 180 (the Key of the document can be visualized in the Documents tab of the Jira project), you can add a reference to that document by entering the following text in the Jira field: {doc-key}180{doc-key}
A comment like this...
... will be displayed like this...
The text displayed by the macro depends of the type of the document represented by the specified key.
- If the key represents a document of type File, the macro displays the Title of the document as a link that allows downloading the newest file attached to the document.
- If the key represents a document of type URL, the macro displays the Title of the document as a link that opens the URL associated with the document.
- If the key represents a folder, the macro displays the Name of the folder as a link that displays the folder's content.
- If the key is invalid or an error occurs, the macro displays an error message in red text.
NOTE The macro works only for the Jira fields that are configured to use the Wiki Style Renderer.
If the Rich Text Editor is enabled in your Jira instance, you can add references to your documents while in Visual mode.
- Click the Document Link option from the insert menu
- Search for and then select the document that you want to link
- A link to the document will be inserted in the field
Version history
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 permissions, 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 these 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 option 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 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 these 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 option 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 permissions or if the document is locked for editing by another user.
Setting permissions over individual folders and documents
You can limit the access to your documents to a specific list users or groups. Also you can deny specific users or groups to perform certain actions like Edit or Delete on your documents.
NOTE A user must have "Set Permissions" privileges granted by the Jira admin in order to use this functionality. Also the permissions set by the users on specific documents and folders are within the limit of global permissions set by the Jira admin in Permissions page from the app's settings under Jira administration area. For example, if someone sets the View permission on Allow for a specific user account, that user will still not have the View permission if the account does not belong to a role for which the Jira Admin granted View access at the global level.
Follow these steps to set permissions over a folder or document:
- In Jira, go to Projects.
- Click the Documents tab.
- Make sure you are on the right project.
- Locate the folder or document that you want to set permissions for and click on its Set Permissions option under the Actions menu.
NOTE The Set Permissions action is available only if the user has Set Permissions privileges.
- Check the Include permissions from parent folder if you want this document to inherit the permissions from its parent folder.
NOTE The permissions inherited from the parent folder are displayed in italic text.
- In the Set Permissions window, check if the user or group that you want to set permissions for appears in the table. If not, add it to the table by selecting it and clicking Add.
- Once the object (user or group) is listed in the table, click its corresponding Change button. For the objects inherited from parent folder, click their Override button.
- Set the permissions for View, Edit and Delete as you want, then click Apply.
- To remove a user or group from the table, click its corresponding Remove button.
- Also, make sure to set permissions for Anyone Else as you want.
NOTE The Project Lead and possibly other users granted by the Jira Admin can access and modify the permissions set here.
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.
On some versions of Jira you can configure the Activity Stream gadget to show the activities related to Documents by selecting "JIRA - Documents" in the available streams list.
Using the Documents gadgets
New and Recently Updated Documents gadget
With this gadget you can display in your Jira dashboards the documents that were recently created or updated. How recently? It depends on the number of days that you specify in the gadget's configuration settings. The documents that were created in the period displayed by the gadget are marked as . Only the documents of type File or URL are displayed; folders are never displayed.
NOTE The current Jira user must have permissions for browsing the project and View permissions in Documents in order to visualize the documents displayed by the gadget.
Follow these steps to add the gadget to a Jira dashboard:
- Log in to Jira or navigate to your dashboard, if you are already logged in.
- Click the Add gadget button in the top-right corner of the dashboard. The "Add a gadget" dialog will be displayed.
- Find the New and Recently Updated Documents gadget in the list of gadgets and click Add gadget.
- Close the "Add a gadget" dialog.
- The New and Recently Updated Documents gadget will be displayed on your dashboard. Enter the following setup details for your gadget:
Item | Description |
---|---|
Gadget Title | Enter a title to be displayed in the title bar of the gadget or keep the default value. |
Project(s) | The Jira project(s) for which documents are to be displayed. You can select one or more projects. Only the projects on which the current user has Browse permission and View permission are listed. |
Days Previously | Days in the past (including today) for which documents are displayed. |
Records to Display | The maximum number of documents to be displayed. |
Refresh Interval | Indicates how often the data in the gadget will refresh. |
- Click the Save button. The gadget will be displayed on your dashboard.
The Documents Tree gadget
This gadget displays the folders structure of a project or of a specified folder in a tree view. You could use this gadget in your personal dashboards or in the team dashboards in order to facilitate the easier access to the project documentation. Clicking a folder in the tree view of the gadget will redirect you to the Documents tab of the project dashboard showing the content of that folder. Using this gadget you can display the folders tree structure in Confluence pages as well.
NOTE The current Jira user must have permissions for browsing the project and View permissions in Documents in order to visualize the folders displayed by the gadget.
Follow these steps to add the gadget to a Jira dashboard:
- Log in to Jira or navigate to your dashboard, if you are already logged in.
- Click the Add gadget button in the top-right corner of the dashboard. The "Add a gadget" dialog will be displayed.
- Find the Documents Tree gadget in the list of gadgets and click Add gadget.
- Close the "Add a gadget" dialog.
- The Documents Tree gadget will be displayed on your dashboard. Enter the following setup details for your gadget:
Item | Description |
---|---|
Gadget Title | Enter a title to be displayed in the title bar of the gadget or keep the default value. |
Folder | The folder for which tree folder structure is to be displayed. You can select one or more folders. Only the folder from projects on which the current user has Browse permission and View permission are listed. |
Refresh Interval | Indicates how often the data in the gadget will refresh. |
- Click the Save button. The gadget will be displayed on your dashboard.
Installation and configuration
Installing app
This app 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 these steps to install it:
- Log on to Jira as an administrator
- Go to Administration > Apps
- Click Manage apps
- Click Upload app
- Select the JAR file
- Click Upload to start the installation. When the installation is done, a confirmation message is displayed.
The app 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 app license.
Activating the app license
In order to run this app you need a trial or a commercial license. You can purchase the Documents app on the Atlassian Marketplace or through the Universal Plugin Manager (UPM). Once you obtained the license code, you must activate it.
Follow these steps to activate the app license:
- Log on to Jira as an administrator
- Go to Administration > Apps
- Click Manage apps
- Locate and expand the Documents app under User-installed apps
- 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.
Configuring the app settings
Follow these steps to configure the app settings:
- Log on to Jira as an administrator
- Go to Administration > Documents
- Click Settings under DOCUMENTS APP 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. |
Columns displayed in list view | Choose which columns to be displayed in the list view. These settings affect all users. The Type and Title columns are always displayed, that's why they cannot be unchecked. |
Configuring the app permissions
You can restrict the access to the "Documents" tab or restrict specific privileges (create, edit, delete, move) regarding documents or folders through the app permissions configuration. Follow these steps to configure the app permissions:
- Log on to Jira as an administrator
- Go to Administration > Documents
- Click Permissions under DOCUMENTS APP 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.
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. |
Unlock | Check this option if you want the project role members to be able to Unlock editing for specific documents and folders. The “Unlock” option will be hidden for the users that do not have this permission but it is always offered to the user who locked the document regardless this setting. |
Set Permissions | Check this option if you want the project role members to be able to restrict the access to specific documents and folders or to deny specific operations (View, Edit or Delete) for specific users or groups by setting permissions over individual documents and folders. See more about how users can set permissions over individual folders and documents in section Setting permissions over individual folders and documents. The permissions set by the users over individual documents and folders are within the limits of the system-wide permissions that you set here. |
- If you want the document creator to be able to set permissions over his/her individual documents and folders regardless of his project role, check The document creator can always set permissions over own documents and folders.
- If you want only the document creator to be able to set permissions over documents and folders, then check Only the document creator can set permissions over documents and folders.
IMPORTANT When checking Only the document creator can set permissions over documents and folders, the settings from the Set Permissions column become obsolete being all unchecked automatically.
- Click Save to apply the changes.
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.
NOTE The Project Lead has full priviledges and can perform all the actions on project's documents.
File & metadata storage
The files attached to the documents are stored in a newly created sub-folder named "documentsaddon" located in the Jira attachments folder. The metadata is stored in the Jira database.
NOTE Do not delete or rename this folder!
Bulk documents upload and migration from another Document Management System
Documents Bulk Uploader
Documents Bulk Uploader is a Java application that allows importing files as documents in a bulk manner. With Documents Bulk Uploader you can upload the files located in a folder from your local drive (the "source folder") into a specified folder of a Jira project (the "destination folder"). In the source folder you can have as many sub-folders as you want; the upload process will create a folder structure in Documents as the one from the specified source folder. The files are imported as documents of type File.
Documents Bulk Uploader can be used for day-by-day document import, but also when migrating from another document management system.
A list with the available versions of Documents Bulk Uploader along with the links to documentation can be found here.
Documents CLI Uploader
Documents CLI Uploader is a command line interface (CLI) Java application that allows uploading files into Documents app. You can use this CLI application to build your own tool for migrating documents from another document management system towards Documents.
A list with the available versions of Documents CLI Uploader along with the links to documentation can be found here.
Documents REST API
Documents API consists in a set of methods that you can use to programatically access and manage your documents.
IMPORTANT: You have to be authenticated to Jira in order for the methods of the Documents API to be successful. Follow the Jira API documentation to see how you can authenticate to Jira.
Obtaining the list of Jira projects
Use this method to obtain a list of Jira projects over which the current user has permissions to access its documents. The result is in JSON format and contains the list of the projects along with some attributes.
Request URL
The request URL takes the following form:
GET <ROOT>/rest/stonikbyte-documents-api/1.0/accessible-project
A successful response
An HTTP 200 status response indicates a successful request. Here is an example of data returned in JSON format:
[
{
"id":"10000",
"name":"DEMO Project"
},
{
"id":"10001",
"name":"Second Project"
}
]
Data | Description | Example |
---|---|---|
id | The ID the Jira project | 10000 |
name | The name of the Jira project | "DEMO Project" |
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or in case of invalid Documents app license |
Obtaining the list of documents for a Jira project
Use this API method to obtain the list of all documents from a Jira project. The result is in JSON format and contains the list of documents along with some attributes like ID.
Request URL
The request URL takes the following form:
GET <ROOT>/rest/stonikbyte-documents-api/1.0/document?projectId={projectId}
Parameters
Parameter | Description |
---|---|
{projectId} | The Id of the Jira project. For obtaining the project ID, see Getting the list of Jira projects above |
A successful response
An HTTP 200 status response indicates a successful request. Here is an example of data returned in JSON format:
[
{
"id": "2",
"title": "DEMO"
},
{
"id": "3",
"title": "Market Requirements Document"
}
]
Data | Description | Example |
---|---|---|
id | The ID the document | 3 |
title | The Title of the document | "Market Requirements Document" |
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or in case of invalid Documents app license |
403 Forbidden | If user does not have View permissions in Documents |
Obtaining the attributes of a document
Use this API method to obtain the attributes (metadata) of a specific document. The result is in JSON format and contains the list of attributes along with their values.
Request URL
The request URL takes the following form:
GET <ROOT>/rest/stonikbyte-documents-api/1.0/document/{documentID}
Parameters
Parameter | Description |
---|---|
{documentID} | The Id (key) of the document |
A successful response
An HTTP 200 status response indicates a successful request. Here is an example of data returned in JSON format:
{
"id": 4,
"type": "File",
"jiraProjectId": 10000,
"parentId": 1,
"parentType": "Folder",
"title": "Market Requirements Document",
"originalFileName": "mrd.docx",
"originalFileExtension": "docx",
"fileSize": 1541093,
"target": "5803722147480494253",
"description": "This document describes the market requirements.",
"dateCreated": 1483010434245,
"createdBy": "admin",
"currentRevision": "1.0",
"currentRevisionDescription": "First Draft",
"currentRevisionAuthors": "",
"dateUpdated": 1483010815614,
"updatedBy": "admin"
}
Depending on the document type, one of more atributes will be present in the result. Only the attributes with a value set will be returned.
Data | Description | Example |
---|---|---|
id | The ID the document | 4 |
type | The type of the document. Possible values are: Folder, File and URL | "File" |
jiraProjectId | The ID of the Jira project the document belongs to | 10000 |
parentId | The ID of the folder or Jira project where the document is located | 1 |
parentType | The type of the parent. Possible values are: Folder and JiraProject | "Folder" |
title | The Title of the document | "Market Requirements Document" |
originalFileName | The name of the attached file. Is applicable only for documents of type File. | "mrd.docx" |
originalFileExtension | The extension of the attached file. Is applicable only for documents of type File. | "docx" |
fileSize | The size of the attached file in Bytes. Is applicable only for documents of type File. | 1541093 |
target | The internal indentifier of the attached file for documents of type File. Or, the target URL for documents of type URL. | 5803722147480494253 |
description | The Description of the document. | "This document describes the market requirements." |
dateCreated | The Date when the document was created in number of milliseconds since January 1st, 1970, UTC. | "1483010434245" |
createdBy | The key of the Jira user who created the document. | "admin" |
currentRevision | The Current Revision field of the document as entered during last update or during creation. | "1.0" |
currentRevisionDescription | The Revision Notes field of the document as entered during last update or during creation. | "First draft" |
currentRevisionAuthor | The Revision Author(s) field of the document as entered during last update or during creation. | "John Smith" |
currentRevisionDate | The Revision Date field of the document. | "2016-12-25" |
dateUpdated | The Date when the most recent update was done in number of milliseconds since January 1st, 1970, UTC. | "1483010815614" |
updatedBy | The key of the Jira user who performed the most recent update on the document. | "admin" |
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or in case of invalid Documents app license |
403 Forbidden | If user does not have View permissions over the document |
Obtaining the list of previous versions of a document
You can obtain a list with the previous versions of a document by sending a specific HTTP GET request to the Jira instance running this version of Documents app. The result is returned in JSON format.
Request URL
The request URL takes the following form:
http:/ /MY_JIRA_BASE_URL/rest/stonikbyte-documents-api/1.0/document/{documentKey}/version
Replace "http:/ /MY_JIRA_BASE_URL" with the base URL of your Jira server.
Parameters
You have to specify the following parameters:
Parameter | Description |
---|---|
documentKey | Represents the key (unique identifier) of the document for which you want to obtain the previous versions. |
An example of the request URL with parameters is as follows:
http:/ /myjiraserver:2990/jira/rest/stonikbyte-documents-api/1.0/document/31/version
In this example all the previous versions of the document with key 31 is returned.
A successful response
An HTTP 200 status response indicates a successful request.
{
"versionNumber": 1,
"currentRevision": "1.0",
"revisionAuthor": "John Smith",
"revisionDate": "2019-01-20 00:00:00.0",
"revisionNotes": "First Draft",
"createdBy":"admin",
"dateCreated": "2019-01-22 06:30:36.0"
}
The following data is returned for each document version:
Data | Description | Example |
---|---|---|
versionNumber | The version number. The versions of each document are numbered starting from 1. | 1 |
currentRevision | The Current Revision as it was in that document version | "1.0" |
currentRevisionAuthor | The Revision Author(s) as it was in that document version | "John Smith" |
revisionDate | The Revision Date as it was in that document version | "2019-01-20 00:00:00.0" |
revisionNotes | The Revision Notes as it was in that document version | "First Draft" |
createdBy | The Jira user who actually created this version in the Jira system | "admin" |
dateCreated | The date when the version was created in the Jira system | "2019-01-22 06:30:36.0" |
NOTE The folders do not have versioning, so the returned list will be always empty in their case.
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or in case of invalid Documents app license |
403 Forbidden | If user does not have View permissions over the document |
You can form links to download the file of a specific document version by using the documentKey and versionNumber. The link is in form:
http:/ /MY_JIRA_BASE_URL/plugins/servlet/StonikByte/VersionOfDocument?documentId=519&versionNumber=2
In this example, the file attached to version 2 of the document 519 will be downloaded.
Obtaining the attributes of a previous document version
Use this API method to obtain the attributes (metadata) of a specific document version. The result is in JSON format and contains the list of attributes along with their values.
Request URL
The request URL takes the following form:
GET <ROOT>/rest/stonikbyte-documents-api/1.0/document/{documentID}/version/{versionNumber}
Parameters
Parameter | Description |
---|---|
{documentID} | The Id (key) of the document |
{versionNumber} | The version number |
A successful response
An HTTP 200 status response indicates a successful request. Here is an example of data returned in JSON format:
{
"versionNumber": 2,
"title": "Market Requirements Document",
"originalFileName": "mrd.docx",
"originalFileExtension": "docx",
"fileSize": 1541093,
"target": "5803722147480494253",
"description": "This document describes the market requirements.",
"currentRevision": "1.0",
"revisionAuthor": "John Smith",
"revisionDate": "2019-01-20 00:00:00.0",
"revisionNotes": "First Draft",
"createdBy":"admin",
"dateCreated": "2019-01-22 06:30:36.0"
}
Depending on the document type, one of more atributes will be present in the result. Only the attributes with a value set will be returned.
Data | Description | Example |
---|---|---|
versionNumber | The version number | 2 |
title | The Title of the document | "Market Requirements Document" |
originalFileName | The name of the attached file. Is applicable only for documents of type File. | "mrd.docx" |
originalFileExtension | The extension of the attached file. Is applicable only for documents of type File. | "docx" |
fileSize | The size of the attached file in Bytes. Is applicable only for documents of type File. | 1541093 |
target | The internal indentifier of the attached file for documents of type File. Or, the target URL for documents of type URL. | 5803722147480494253 |
description | The Description of the document. | "This document describes the market requirements." |
currentRevision | The Current Revision field of the document as entered during last update or during creation. | "1.0" |
revisionAuthor | The Revision Author(s) field of the document as entered during last update or during creation. | "John Smith" |
revisionNotes | The Revision Notes field of the document as entered during last update or during creation. | "First draft" |
revisionDate | The Revision Date field of the document. | "2019-01-20 00:00:00.0" |
createdBy | The Jira user who actually created this version in the Jira system | "admin" |
dateCreated | The date when the version was created in the Jira system | "2019-01-22 06:30:36.0" |
You can form links to download the file of a specific document version by using the documentKey and versionNumber. The link is in form:
http:/ /MY_JIRA_BASE_URL/plugins/servlet/StonikByte/VersionOfDocument?documentId=519&versionNumber=2
In this example, the file attached to version 2 of the document 519 will be downloaded.
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or in case of invalid Documents app license |
403 Forbidden | If user does not have View permissions over the document |
Creating a new document or folder
Use this API method to create a new document or folder. The result is in JSON format and contains the list of attributes of the newly created document.
Request URL
The request URL takes the following form:
POST <ROOT>/rest/stonikbyte-documents-api/1.0/document?projectId={projectID}
Parameters
Parameter | Description |
---|---|
{projectID} | The id of the Jira project where the document will be created |
Also, the body of the request must contain a JSON with the attributes of the file.
Some of the attributes are required, depending on the document type.
Data | Description | Example |
---|---|---|
type | Required. The type of the document. Possible values are: Folder, File and URL | "File" |
parentId | The ID of the folder where the document will be created. If not specified, the document will be created in the root folder of the specified Jira project. | 1 |
title | Required. The Title of the document. | "Market Requirements Document" |
originalFileName | Required for documents of type File. The name of the attached file. | "mrd.docx" |
uploadedFileID | Required for documents of type File. To obtain the ID you have to upload the file first - see Uploading a file attachment section below | "9126255659437090493" |
targetURL | Required for documents of type URL. The target URL for documents of type URL. | "http://www.stonikbyte.com" |
description | The Description of the document. | "This document describes the market requirements." |
currentRevision | The Current Revision field of the document. | "1.0" |
currentRevisionDescription | The Revision Notes field of the document. | "First draft" |
currentRevisionAuthor | The Revision Author(s) field of the document. | "John Smith" |
currentRevisionDate | The Revision Date field of the document. It must be in YYYY-MM-DD format. | "2016-12-25" |
Example of JSON body for creating a folder:
{
"title": "Templates",
"type" : "Folder"
}
Example of JSON body for creating a document of type File:
{
"title": "Architectural Guidelines",
"type" : "File",
"originalFileName": "Architectural_Guidelines.pdf",
"uploadedFileID" : "9126255659437090493"
}
Example of JSON body for creating a document of type URL:
{
"title": "Company Web Site",
"type" : "URL",
"targetURL" : "http://www.stonikbyte.com"
}
A successful response
An HTTP 200 status response indicates a successful request. The result in JSON format will contain the list with the attributes of the newly created document. See Obtaining the attributes of a document for a description of these atributes.
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or in case of invalid Documents app license |
403 Forbidden | If user does not have Create permissions |
400 Bad Request | In case of invalid parameters. |
Uploading a file attachment
Use this API method to upload a file in Jira for being used later to create a document of File type. The result is in JSON format and contains the ID of temporary file uploaded in Jira.
NOTE: This API method will not create a document of type File in Documents. It is just the first step for the process of creating such a document. See "Creating a new document or folder" section above.
Request URL
The request URL takes the following form:
POST <ROOT>/rest/stonikbyte-documents-api/1.0/temporary-attachment?filename={fileName}&projectId=(projectID}&atl_token={atlToken}
Parameters
Parameter | Description |
---|---|
{fileName} | The name of the file attached |
{projectID} | The id of the Jira project where the document will be created |
{atlToken} | The upload token. To obtain the token, see Obtaining the Upload Token section below |
Also, the body of the request must contain as binary data the file to be uploaded.
A successful response
An HTTP 201(Created) status response indicates a successful request. The result in JSON format will contain the ID of the temporary attached file that you can use to create a new document of type File. See the Creating a new document or folder section above.
{
"name": "myfile.txt",
"id": "7214177218780006431"
}
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or in case of invalid Documents app license |
403 Forbidden | If user does not have Create or Edit permissions in Documents app |
400 Bad Request | In case of invalid parameters. |
Obtaining the Upload Token
Use this API method to obtain the token. This token is required when calling the method for uploading a file attachment (see above). The result is in JSON format and contains the token.
Request URL
The request URL takes the following form:
GET <ROOT>/rest/stonikbyte-documents-api/1.0/upload-token
A successful response
An HTTP 200 status response indicates a successful request. The result in JSON format will contain the token that you can use to upload a file in Jira. See the Uploading a file attachment section above.
{"atl_token" : "B1BP-2GYK-B3BL-S477|ec647875c44a11f602a5d2d760c3d6ba983e32ce|lin"}
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or in case of invalid Documents app license |
Updating an existing document
Use this API method to update an existing document or folder. The result is in JSON format and contains the list of attributes of the updated document.
Request URL
The request URL takes the following form:
PUT <ROOT>/rest/stonikbyte-documents-api/1.0/document/{documentID}
Parameters
Parameter | Description |
---|---|
{documentID} | The id of the document to be updated |
Also, the body of the request must contain a JSON with the modified attributes of the document.
Data | Description | Example |
---|---|---|
title | Required. The Title of the document. | "Market Requirements Document" |
originalFileName | Applicable only for documents of type File. The name of the attached file. | "mrd.docx" |
uploadedFileID | Applicable only for documents of type File. To obtain the ID you have to upload the file first - see Uploading a file attachment section below | "9126255659437090493" |
targetURL | Applicable only for documents of type URL. The target URL for documents of type URL. | "http://www.stonikbyte.com" |
description | The Description of the document. | "This document describes the market requirements." |
currentRevision | The Current Revision field of the document. | "1.0" |
currentRevisionDescription | The Revision Notes field of the document. | "First draft" |
currentRevisionAuthor | The Revision Author(s) field of the document. | "John Smith" |
currentRevisionDate | The Revision Date field of the document. It must be in YYYY-MM-DD format. | "2016-12-25" |
A successful response
An HTTP 200 status response indicates a successful request. The result in JSON format will contain the list with the attributes of the updated document. See Obtaining the attributes of a document for a description of these atributes.
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or in case of invalid Documents app license |
403 Forbidden | If user does not have View permissions |
400 Bad Request | In case of invalid parameters. |
404 Not found | If the document no longer exists. |
Deleting an existing document
Use this API method to delete an existing document or folder.
Request URL
The request URL takes the following form:
DELETE <ROOT>/rest/stonikbyte-documents-api/1.0/document/{documentID}
Parameters
Parameter | Description |
---|---|
{documentID} | The id of the document to be deleted |
A successful response
An HTTP 200 status response indicates a successful request.
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or in case of invalid Documents app license |
403 Forbidden | If user does not have Delete permissions |
404 Not found | If the document no longer exists. |
Searching and retrieving documents by title
You can search and retrieve documents by their title by sending a GET HTTP request to the Jira instance running this version of Documents app. A set of attributes of the matching documents are returned in JSON format.
Request URL
The request URL takes the following form:
http:/ /MY_JIRA_BASE_URL/plugins/servlet/stonikbyte/projectdocs/search-doc-titles?query=QUERY&projectKey=PROJECT_KEY
Replace "http:/ /MY_JIRA_BASE_URL" with the base URL of your Jira server.
Parameters
You have to specify the following parameters:
Parameter | Description |
---|---|
query | Represents the search criteria. All documents containing this value will be retrieved. Search is not key sensitive. Leave it blank to retrieve all documents. The parameter has to be URL encoded. |
projectKey | The key of the project you want to search into. |
An example of the request URL with parameters is as follows:
http:/ /myjiraserver:2990/jira/plugins/servlet/stonikbyte/projectdocs/search-doc-titles?query=plan&projectKey=DEMO
In this example all the documents of project DEMO containing “plan” in their title are returned.
A successful response
An HTTP 200 status response indicates a successful request. The following data about the matching documents is returned:
Data | Description | Example |
---|---|---|
key | The Key (unique identifier) of the document | 11 |
title | The Title of the document | Project Plan |
type | The type of the document. Possible values are: 1 - Folder; 2 - File; 3 - URL | 1 |
icon | The filename representing the document's icon. You can retrieve the icon by appending the file name to the following URL http:/ /MY_JIRA_BASE_URL/download/resources/com.stonikbyte.jira.plugins.project-docs-plugin/images/mime-types/ Example: http:/ /myjiraserver:2990/jira/download/resources/com.stonikbyte.jira.plugins.project-docs-plugin/images/mime-types/pdf24.png | pdf24.png |
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or missing View permissions. |
412 Precondition failed | Returned if one or more of the mandatory parameters are missing or if the license of the Documents app is expired. |
Searching and retrieving documents by using advanced search options
You can search and retrieve documents by specifying the scope of the search and field(s) to be search by sending a GET HTTP request to the Jira instance running this version of Documents app. A set of attributes of the matching documents are returned in JSON format.
Request URL
The request URL takes the following form:
http:/ /MY_JIRA_BASE_URL/plugins/servlet/stonikbyte/projectdocs/search-docs?query=QUERY&projectKey=PROJECT_KEY&fields=FIELDS&folderID=FOLDER&scope=SCOPE
Replace "http:/ /MY_JIRA_BASE_URL" with the base URL of your Jira server.
Parameters
You have to specify the following parameters:
Parameter | Description |
---|---|
query | Represents the search criteria. All documents containing this value will be retrieved. Search is not key sensitive. Leave it blank to retrieve all documents. The parameter has to be URL encoded. |
projectKey | The key of the project that you want to search into. |
fields | The field(s) to be used for search. It can be either "all" which will include most of the data fields associated with a document or one or more of the following values: "key","title", "description", "revision". The items in the list can be separated with comma. |
folderID | The key of the folder to be searched. See "scope" parameter for more info. This parameter will be used only if the scope parameter has one of the following values: "folderAndSubFolders" or "folder" |
scope | The scope of the search. By default the scope is the entire project. This parameter can have one of the following values: - "folderAndSubFolders" - the search will be restricted to the folder with the key specified through the "folderID" parameter and all its sub-folders - "folder" - the search result will include only documents from the folder with key specified through the "folderID" parameter If the "folderID" parameter is not provided, then the scope parameter is ignored and the entire project is searched. |
An example of the request URL with parameters is as follows:
http:/ /myjiraserver:2990/jira/plugins/servlet/stonikbyte/projectdocs/search-docs?query=chart&projectKey=DEMO&fields=title,description&folderID=1&scope=folderAndSubFolders
In this example all the documents from the folder with key 1 (that belongs to project DEMO) and its sub-folders that cotains “chart” in their Title or Description are returned.
A successful response
An HTTP 200 status response indicates a successful request. The following data about the matching documents is returned:
Data | Description | Example |
---|---|---|
key | The Key (unique identifier) of the document | 11 |
title | The Title of the document | Project Plan |
type | The type of the document. Possible values are: 1 - Folder; 2 - File; 3 - URL | 1 |
icon | The filename representing the document's icon. You can retrieve the icon by appending the file name to the following URL http:/ /MY_JIRA_BASE_URL/download/resources/com.stonikbyte.jira.plugins.project-docs-plugin/images/mime-types/ Example: http:/ /myjiraserver:2990/jira/download/resources/com.stonikbyte.jira.plugins.project-docs-plugin/images/mime-types/pdf24.png | pdf24.png |
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or missing View permissions. |
412 Precondition failed | Returned if one or more of the mandatory parameters are missing or if the license of the Documents app is expired. |
Retrieving document metadata
You can obtain the metadata (title, description, type, etc) of a document by sending a specific HTTP GET request to the Jira instance running this version of Documents app. The result is returned in JSON format.
Request URL
The request URL takes the following form:
http:/ /MY_JIRA_BASE_URL/plugins/servlet/stonikbyte/projectdocs/get-document-metadata?documentKey=X
Replace "http:/ /MY_JIRA_BASE_URL" with the base URL of your Jira server.
Parameters
You have to specify the following parameters:
Parameter | Description |
---|---|
documentKey | Represents the key (unique identifier) of the document. All documents containing this value will be retrieved. Search is not key sensitive. Leave it blank to retrieve all documents. The parameter has to be URL encoded. |
An example of the request URL with parameters is as follows:
http:/ /myjiraserver:2990/jira/plugins/servlet/stonikbyte/projectdocs/get-document-metadata?documentKey=31
In this example the metadata of document with key 31 is returned.
A successful response
An HTTP 200 status response indicates a successful request. The following data about the matching documents is returned:
Data | Description | Example |
---|---|---|
id | The key (unique identifier) of the document | 31 |
type | The type of the document. Possible values are: 1 - Folder; 2 - File; 3 - URL | 1 |
parentType | The type of the document's parent. Possible values are: 0 - Jira Project; 1 - Folder | 1 |
title | The Title of the document | Project Plan |
jiraProjectID | The ID of the Jira project the documents belong to. | 1000 |
originalFileName | The name of the attached file. | ProjectPlan.pptx |
originalFileExtension | The extension of the attached file. | pptx |
target | The internal name of the attached file for a document of type File or the target URL in case of a document of type URL | 8506976070117992219 or www.stonikbyte.com |
jiraProjectID | The ID of the Jira project the documents belong to. | 1000 |
title | The description of the document | text |
addedbyUserKey | The key of the user who added the document | admin |
addedByUserDirectoryId | The directory ID of the user who added the document | 1 |
dateAdded | The date when the document was added (UTC Time) | 12/09/2014 21:27:12 |
currentRevisionDescription | The Current Revision Description of the document | text |
currentRevision | The Current Revision of the document | text |
currentRevisionAuthor | The Current Revision Author of the document | text |
internalVersion | The current version of the document | 2 |
fileSize | The size of the attached file in bytes | 34696 |
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
---|---|
401 Unauthorized | Returned for unauthenticated requests or missing View permissions. |
412 Precondition failed | Returned if the document key parameter was not specified or if the license of the Documents app is invalid. |
Updated