Wiki

Clone wiki

Documents Add-On / Cloud

Documents for Jira Cloud

The content of this page applies to Documents Cloud app.

On this page:

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 displayed according to the current layout and visualization mode.

The Document tab in Three Column Layout and List View Mode

The current layout and visualization mode can be changed by using the menus from the top-right corner of the page.

The menu for changing the layout

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.

ItemDescription
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 a URL specific icon.
Icon indicatorsThe 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:
400_lock12.png (black) – indicates that the document is locked for editing by you. A tooltip showing the locker, lock date and the lock message is displayed when hovering the mouse pointer over it.
400_lock12_other.png (gray) – indicates that the document is locked for editing by another user. A tooltip showing the locker, lock date and the lock message is displayed when hovering the mouse pointer over it.
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.
RevisionShows the value of the Current Revision attribute of the document. It is always empty for folders.
File sizeThe 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 byShows the Jira user that posted the document or created the folder.
Posted onShows 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 byShows 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 onShows 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 menuAn icon (700_Actions_Menu_Icon.png) that offers a menu with the actions that can be performed on each document or folder. The icon becomes visible when hovering the mouse over that document or folder. See below a description of all available actions.

The actions menu is available in both list view and icon view. It is displayed when hovering the mouse over a document or folder.

The actions menu in icons and list view

Possible actions are:
Download – use this action to download the file attached to the document. It is only available for File type documents and for 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 all 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 all document types if the current user has Edit permission.
Delete – use this action to delete a document or folder. It is available for all document types and for 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 all 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 if the current user has Create permission.
Previous Versions – use this action to access the previous versions of a document. It is available for all document types if the current user has View permission.
Show in Folder – opens the parent folder of the document or folder. It is available for all 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 for 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.

The search box

Optionally, you can use the advanced search options to make the search operation more precise.

The advanced search options

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.

The search results

Follow the next steps to search documents:

  • In Jira, go to Projects.
  • Make sure that 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 that 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 documents

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.

Adding File documents

A File document consists in a consists in a file that is uploaded and stored in Jira, plus data about that file like Title or Description.

Follow these steps to add (post) a new document of type File:

  • In Jira, go to Projects.
  • Make sure that you are on the right project.
  • Click the Documents tab of the Jira project and navigate to the folder where you want to add the new document.
  • Click Add > Add File
    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.

Adding a document of type File

  • Optionally, enter a short Description for the document.
  • 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.
  • 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.
  • 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.

Adding URL documents

A URL document 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 of type URL:

  • In Jira, go to Projects.
  • Make sure that you are on the right project.
  • Click the Documents tab of the Jira project and navigate to the folder where you want to add the new document.
  • Click Add > Add URL
    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.

Adding a document of type URL

  • Optionally, enter a short Description for the document.
  • 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.
  • 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 that 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.
  • For documents of type File 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 attach the new file to the document.

Deleting a document or folder

Follow these steps to delete a document or folder:

  • In Jira, go to Projects.
  • Make sure that 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.

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 that 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.

Moving a document to another folder

The Split Pane Layout mode allows moving items (documents and folders) from a pane to another by using drag & drop.

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 in a different project, you must have View and Create permissions in that project.

Selecting the destination folder for copying a folder structure

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 that 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.

Leaving a message when locking editing a 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:

The icon indicating that a document is locked for editing

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 that 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.

Unlocking a document from the Edit Document dialog box

Linking documents to Jira issues

The users can link documents and folders to Jira issues in order to make them visible and accessible on the Jira issues screen.

Linked documents of a Jira issue

There are two ways to link documents to Jira issues, as described below. Both methods produce the same type of "both-ways" link between the document and Jira issue.

Linking documents to Jira issues from the issue screen

Follow these steps to link a document or folder to a Jira issue:

  • Navigate to the Jira issue.
  • Click Linked documents in the right panel. The panel will be open, showing the currently linked documents.

NOTE The Linked documents table does not display the linked documents over which the current user does not have View permissions.

  • Click the dropdown list under Add new link, search for the document that you want to link and select it.

Linking a document to a Jira issue

  • Click the Link button. The document will be added in the linked documents table.
  • Repeat the previous two steps, if you want to link other documents.
  • Click Save changes. The links are created and from now on they will appear in the Linked documents table.
  • If you want to unlink a document, click its X icon.

Linking Jira issues to documents

Follow these steps to link a Jira issue to a document or folder:

  • In Jira, go to Projects.
  • Make sure that you are on the right project.
  • Click the Documents tab.
  • Locate the document or folder and click on its Linked issues option under the Actions menu. The Linked issues dialog will open showing the issues currently linked to the document.

NOTE The linked issues table does not display the linked issues over which the current user does not have View permissions.

  • At Add link to issue, click the dropdown list, search for the Jira issue that you want to link and select it.

Linking a Jira issue to a document

  • Click Add Link.
  • Repeat the previous two steps, if you want to link other issues.
  • Click Save. The links are created and from now on they will appear in the linked issues table.
  • Click X icon of a linked issue, if you want to unlink it.

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 on the left side and data of the selected version on the right side.

Viewing the previous versions of a document

  • In the list with the versions from the left side, click View to select a version and visualize its data on 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 on the left side and data of the selected version on the right side.
  • In the list with the versions from the left side, click View to select a version and visualize its data on 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.

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 340NewDocumentIcon.png. Only the documents of type File or URL are displayed; folders are never displayed.

The "New and Recently Updated Documents" gadget

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 and navigate to your dashboard.
  • Click the Edit button in the top-right corner of the dashboard. The "Add a Gadget" panel will be displayed.
  • Find the New and Recently Updated Documents gadget in the list of gadgets and click Add.
  • The New and Recently Updated Documents gadget will be displayed on your dashboard. Enter the following setup details for your gadget:

    Configuring the "New and Recently Updated Documents" gadget
ItemDescription
Gadget TitleEnter 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 in Documents are listed.
Days to includeDays in the past (including today) for which documents are displayed.
Records to includeThe maximum number of documents to be displayed.
  • 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.

The "Documents Tree" gadget

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 and navigate to your dashboard.
  • Click the Edit button in the top-right corner of the dashboard. The "Add a Gadget" panel will be displayed.
  • Find the Documents Tree gadget in the list of gadgets and click Add.
  • The Documents Tree gadget will be displayed on your dashboard. Enter the following setup details for your gadget:

    Configuring the "Documents Tree" gadget
ItemDescription
Gadget titleEnter a title to be displayed in the title bar of the gadget or keep the default value.
FolderThe 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 in Documents are listed.
Refresh IntervalIndicates 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

  • Log into your Jira instance as an admin.
  • Click the admin dropdown and choose Apps.
  • Open Find new apps tab.
  • Search for "Documents Cloud".
  • Once you locate the "Documents Cloud" app, click on it.
  • Click Try it free to download and install it.
  • Click Close in the "Installed and ready to go" dialog.

At this stage the app is installed, but the users cannot use it yet. Some post-installation steps are required. Please continue with Configuring the app repository section below.

Configuring the app repository

The app requires a dedicated Jira team-managed (aka next-gen) private project to serve as data repository. The repository is the place where all the documents added via the app, including files and metadata, will be stored. Right after the app installation you have to create and configure a Jira team-managed (next-gen) private project that will serve as the app repository. For more details about the app repository, see the File & metadata storage section below.

Follow these steps to create and configure the app repository project:

  • Log into your Jira instance as an admin.
  • Create a new private team-managed (next-gen) project that will be used as the app repository:
    • Go to Projects>Create project.
    • At Project templates select Software development and choose the Kanban template

      NOTE If you are on Jira Service Management, you might not have the option to create team-managed projects. Go to https://<YOUR_SITE_NAME>.atlassian.net/jsd-next-gen and switch Enable team-managed projects to ON. Then click the Create a team-managed project button to begin the project creation.

    • At Choose a project type step, click Select a team-managed project
    • In "Create project" screen enter a suggestive project name, select Private access and keep the default Kanban template.

      NOTE If you are on Jira Service Management, you might not have the Kanban template. If so, select the Quick Start template from the Work Management templates category.

      Create App Repository Project
    • Click Create. The project is created.
  • Disable the notifications on the new next-gen project:
    • Go to Project settings > Notifications.
    • Delete all the notification events from the table.
      Removing the notification events
  • Navigate to Apps > DOCUMENTS > Repository. The current displayed status indicates that the repository is not yet configured. Repository not yet configured
  • The repository project must have a specific configuration in terms of issue types and custom fields in order to be used as the app repository. The selected project can be automatically or manually configured. It is recommended to attempt the automatic configuration method first because it is much faster and, if this (by any reason) cannot be performed, to use the manual configuration method instead. But you can choose any of them.
  • To configure the repository project automatically:
    • At Repository project select the Jira next-gen project that you created before.
    • Click Configure project to start configuring the selected project automatically.
    • You will be prompted to provide your email address and an API token. This is required by the app to automatically configure the project. Click the "here" link and generate an API token.
      Entering the API token
    • Copy the generated token and paste it in the API token field.
    • After entering the email and API token, click Configure.
    • The automatic process of configuring the selected project will start. You can revoke the API token once this step is completed; it is no longer required.
    • If it is successful, click Set as repository. The repository project configuration is now fully completed!
    • If the configuration fails, try configuring the project manually by performing the steps below.
  • To configure the repository project manually:
    • Open the next-gen project that will be used as the app repository.
    • Go to Project settings > Issue types.
    • Click Add issue type and then Create issue type.
    • At Name enter Document and type a suggestive description.
      Adding issue type Document
    • Click Create to add the new issue type.
    • You can delete the other issue types from this project.
    • Select the Document issue type.
    • Create all the fields from the table below and add them to the Documents issue type. Make sure that you set their name and type as in the table.
Field NameField Type
Added ByShort text
Current RevisionShort text
Current Revision Author(s)Short text
Current Revision DateTimestamp
Current Revision DescriptionParagraph
File SizeNumber
Include Parent PermissionsNumber
Internal VersionNumber
Jira Project IdNumber
Updated ByShort text
Lock ReasonShort text
Locked ByShort text
Lock TimeTimestamp
File ExtensionShort text
File NameShort text
Parent IdNumber
Parent TypeNumber
TargetParagraph
Document TypeNumber
Watchers ListParagraph
Linked ItemsParagraph
    • Keep the default issue fields Summary, Description, Status and Reporter.
    • In the end, the project configuration should look like this:
      The app repository project fully configured
    • When you finished configuring the project, go back to Apps > DOCUMENTS > Repository
    • At Repository project select the Jira next-gen project that you created and just configured.
    • Click Validate. The app will verify if the selected project was properly created and configured. If not, you can correct the issues listed in red-color text and try again.
    • If the validation is successful, click Set as repository. The repository project configuration is now fully completed!

At this stage the repository is configured and the users can start using the app. To test, open a Jira project, click on its Documents tab and create a new folder or File. App Repository Project successfully configured

VERY IMPORTANT!

  • Do not modify the issue-types or the fields configuration of this project because this impacts the app's functionality.
  • Do not manually create, delete or modify the issues of this project because this can cause invalid app repository data.
  • Ensure that the regular users do not have access to the repository project.
  • Do not delete this project. Deleting the project will cause the lost of the entire Documents data from your Jira Cloud instance.

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 into your Jira instance as an admin.
  • Navigate to Apps > DOCUMENTS > Permissions.
  • On the Permissions tab, check the actions that you want to allow for each project role. The list includes the project roles from both classic and the next-gen projects. See the table below for a complete description of the available permissions.

Configuring the app permissions

The table below shows details about the available permissions.

PermissionDescription
ViewCheck this option if you want the project role members to view and download the documents posted on the “Document” tab. The users who do not have this permission will get a permission error message when trying to access the Documents tab.
CreateCheck 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 who do not have this permission.
EditCheck this option if you want the project role members to be able to edit documents and folders or to restore previous versions of the documents. The “Edit” option will be hidden for the users who do not have this permission.
DeleteCheck 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 who do not have this permission.
MoveCheck 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 who do not have this permission.
UnlockCheck 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 who do not have this permission, but it is always offered to the user who locked the document regardless of this setting.
  • Click Save to apply the changes.

NOTE If a Jira user is member of a project role that has a specific permission but 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 permissions and can perform all the actions on project's documents.

File & metadata storage

All the documents and folders created in Documents app are stored as Jira issues in a dedicated Jira next-gen project (aka "app repository"), which must be configured in a certain way by the Jira administrator during the app's post-installation steps (see Configuring the app repository). The files uploaded are stored as attachments to these issues while the metadata is stored in the specific Jira custom fields of the repository next-gen project.

Backing-up the repository project assures the backup of all the documents from the entire Jira Cloud instance, which includes attachments and metadata.

VERY IMPORTANT!

  • Do not modify the issue-types or the fields configuration of this project because this might affect the app's functionality.
  • Do not manually create, delete or modify the issues of this project because this can cause invalid app repository data.
  • Ensure that the regular users do not have access to the repository project.
  • Do not delete this project. Deleting the project will cause the lost of the entire Documents data from the entire Jira Cloud instance.

Bulk documents import and migration

You can import multiple documents and folders in a bulk manner by using Documents Cloud Uploader, a Java multi-platform desktop application.

This app supports two import methods:

  • Import folder content. Using this method you can quickly import the contents (files and folders) of a local folder from your computer. The imported documents will have the Title set to their file/folder name. The folders structure will be preserved. Only documents of type Folder and File can be imported by using this method. Also, it does not support importing metadata attributes like Description or Current Revision. This method is recommended to be used when you just installed the Documents app and you want to move your existing project files to Jira Cloud or to migrate the files from your previous document management system other than Documents for Jira Server / Data Center.
  • Import documents with metadata. This method is based on an input CSV file, which must contain the metadata attributes (like Title, Description, Revision Notes, etc) of the items to be imported along with the local path to their corresponding file from the local disk that has to be imported. It supports importing documents of type Folder, File and URL. This method is recommended to be used when migrating Documents data from Jira Server (or Data Center) to Jira Cloud - in this case the CSV file along with the files and folders to be imported being easily generated by bulk downloading in Documents for Jira Server the documents to be migrated.

IMPORTANT!

  • The user running the import via Documents Cloud Uploader must have administrative permissions over the Jira project that serves as the app repository (see Configuring the app repository).
  • The migration of documents of type "Wiki" is currently not supported.

The most common scenarios of using these import methods are described below.

If you just installed Documents in your Jira Cloud instance, you might want to upload the existing project-related files to the Jira projects.

Follow these steps to bulk import existing files and folders into a Jira project:

  • Centralize all the files to be imported in a folder on your local computer. You can organize these files in sub-folders as necessary.
  • Make sure that Documents app has been installed and configured and you can access the Documents tab of the Jira project where the data will be imported into.
  • Download Bulk Documents Uploader on your local computer.
PlatformDownload
Windows 64-bitdocuments-cloud-uploader-win64.zip
Linux 64-bitdocuments-cloud-uploader-tar.gz
  • Extract the downloaded archive and open it. Execute run_gui.bat if you are on Windows or run_gui.sh if you are on Linux. The Documents Cloud Uploader will open.
  • At Import type choose Import folder content

    Uploading folder content

  • At Source folder click ... and select the folder that contains the data to be uploaded. The folder content will be loaded in the DATA TO IMPORT table. Check for eventual errors in the MESSAGES field.
  • At Destination folder's key you have to enter the key (id) of the existing folder from Documents where the data will be imported. To determine the key:
    • Log on to your Jira Cloud instance
    • Open the Jira project where you want to import the data into
    • Click its Documents tab
    • Navigate and locate the folder where the files will be uploaded
    • Note down its key.

      Identifying the destination folder id

    • If you want to import the files in the project's root folder, hover the mouse over the [Project Root] in the navigation bar. Its key will be displayed in a tooltip.

      Identifying the key of the root folder

  • At What to import make sure that Import folders and Import files are both checked. If you want just to import the folders structure, uncheck Import files.
  • Click Start.... The "Jira Connection Settings" dialog will appear. Enter the info required by the app to connect to your Jira Cloud instance:
    • At Jira Base URL enter the base URL of your Jira Cloud instance in form of "https://myjira.atlassian.net".
    • At Your Email enter the email address of your Jira Cloud account.
    • At API Token you must enter a valid API token. Use the link offered in the dialog box to generate an API token. You can revoke the generated token after you finish importing the data.

      Entering Jira connection info

    • Click Test Connection to validate the provided connection info. If the test fails, please double-check the info provided and try again.
  • Click OK in "Jira Connection Settings" dialog to continue the import process.
  • The app is trying to connect to your Jira Cloud instance to check if the destination folder exists. If it exists, a confirmation dialog will be popped-up.

    Start import confirmation

  • Click OK in the confirmation dialog to start the import. The app will proceed with the import of the documents, starting with the folders.
  • Check for any errors in the MESSAGES field. When it is done check the content of the destination folder from Jira Cloud; it should display the imported documents.

Migrating data from Documents for Jira Server or Data Center to Documents Cloud

You can migrate the Documents data from Jira Server to Jira Cloud. The migration process consists in two main steps: first, export the documents from Jira Server along with their metadata and then, import the exported data into Jira Cloud by using the Documents Cloud Uploader utility.

IMPORTANT!

  • You will have to migrate the data project-by-project.
  • The migration process will NOT migrate the documents of type Wiki, the permissions on the individual documents and folders, and the historical data (previous versions).
  • The current version of Documents for Jira Cloud does not support all the functionalities of Documents for Jira Server. Check the Features comparison between Documents for Jira Server and Documents for Jira Cloud section below before proceeding with the data migration.

Follow these steps to migrate the documents of a Jira project from Jira Server into Jira Cloud:

  • Bulk download (export) the project's documents from Jira Server along with their metadata:
    • Log on to your Jira Server instance
    • Open the Jira project that you want to migrate
    • Click its Documents tab
    • Select all the folders and documents that you want to migrate
    • Click the Bulk Operations > Download.

      Export document from Jira Server

      The selected documents are downloaded in a ZIP archive that contains a metadata.csv file with the documents metadata (Title, Description, Current Revision, etc). The downloaded ZIP archive preserves the folders structure. The file names might be changed in order to preserve the unicity. The documents of type URL are included in the metadata.csv. The documents of type Wiki are not included.
      You can also download a single folder, by clicking the Download option from its actions menu.
  • Extract the ZIP archive on your local computer.

At this point the export of the data from Jira Server is done. Proceed further with the data import into Jira Cloud:

  • Make sure that Documents app has been installed and configured and you can access the Documents tab of the Jira project where the data will be migrated.
  • Download Bulk Documents Uploader on your local computer.
PlatformDownload
Windows 64-bitdocuments-cloud-uploader-win64.zip
Linux 64-bitdocuments-cloud-uploader-tar.gz
  • Extract the downloaded archive and open it. Execute run_gui.bat if you are on Windows or run_gui.sh if you are on Linux. The Documents Cloud Uploader will open.
  • At Import type choose Import documents with metadata

    Uploading documents with metadata

  • At Source CSV file click ... and select the medata.csv file from the folder where you extracted the ZIP archive with the exported documents. Its content will be loaded in the DATA TO IMPORT table. Check for eventual errors in the MESSAGES field.
  • At Destination folder's key you have to enter the key (id) of the existing folder from Documents where the data will be migrated. To determine the key:
    • Log on to your Jira Cloud instance
    • Open the Jira project where you want to import the data into
    • Click its Documents tab
    • Navigate and locate the folder where the files will be uploaded
    • Note down its key.

      Identifying the destination folder id

    • If you want to import the files in the project's root folder, hover the mouse over the [Project Root] in the navigation bar. Its key will be displayed in a tooltip.

      Identifying the key of the root folder

  • At What to import make sure that Import folders, Import files and Import URLs are all checked.
  • Click Start.... The "Jira Connection Settings" dialog will appear. Enter the info required by the app to connect to your Jira Cloud instance:
    • At Jira Base URL enter the base URL of your Jira Cloud instance in form of "https://myjira.atlassian.net".
    • At Your Email enter the email address of your Jira Cloud account.
    • At API Token you must enter a valid API token. Use the link offered in the dialog box to generate an API token. You can revoke the generated token after you finish importing the data.

      Entering Jira connection info

    • Click Test Connection to validate the provided connection info. If the test fails, please double-check the info provided and try again.
  • Click OK in "Jira Connection Settings" dialog to continue the import process.
  • The app is trying to connect to your Jira Cloud instance to check if the destination folder exists. If it exists, a confirmation dialog will be popped-up.

    Start import confirmation

  • Click OK in the confirmation dialog to start the import. The app will proceed with the import of the documents, starting with the folders.
  • Check for any errors in the MESSAGES field. When it is done check the content of the destination folder from Jira Cloud; it should display the migrated documents.

Repeat these steps for the others Jira projects that you want to migrate.

Features comparison between Documents for Jira Server and Documents for Jira Cloud

The table below displays side-by-side the supported functionalities of Documents for Jira Server and Documents for Jira Cloud.

NOTE StonikByte is working actively on adding the functionalities from Documents for Jira Server into Documents for Jira Cloud, so this list is subject of change.

Functionality / FeatureAvailability on ServerAvailability on Cloud
Documents tab for each Jira projectYesYes
List View and Icon View visualization modesYesYes
Tree Navigation pane, content pane and details paneYesYes
Configurable columns display for List View modeYesNo
File preview for images, text files and PDFs in details paneYesYes, except for PDFs
Folders hierarchyYesYes
Documents of type FileYesYes
Documents of type URLYesYes
Documents of type WikiYesNo
Documents metadata (Title, Description, Current Revision, etc)YesYes
Document search in metadataYesYes
Lock / Unlock documentYesYes
Bulk operations (Download, Move, Delete)YesNo
Add, Edit, Delete, Move, Move to other projectYesYes
Upload files with drag & dropYesYes
Folder downloadYesNo
Copy (clone) folders structureYesYes
Watch / unwatch document (email notifications)YesNo
Link documents to Jira issuesYesYes
Reference documents in Jira issue description and comments (via doc-key macro)YesNo
Global permissionsYesYes
Permissions on individual documentsYesNo
Previous versions (versions history)YesYes
Activity Stream postingYesNo
New & Recently Updated Documents dashboard gadgetYesYes
Documents Tree dashboard gadgetYesYes
Bulk Documents Upload utilityYesYes
Documents REST APIYesNo

For how to migrate the Documents data from Jira Server to Jira Cloud, see Migrating data from Documents for Jira Server or Data Center to Documents Cloud.

Updated