Jira

About the ONLYOFFICE and Jira integration

ONLYOFFICE offers an official connector to integrate ONLYOFFICE Docs with Jira Software to collaborate on office documents attached to your Jira issues. You can download it from the official Atlassian Marketplace or GitHub. The application is distributed under the Apache license.

To learn more about how it works, please visit our API documentation.

Main features

Creating new documents, spreadsheets, presentations, and forms.
Viewing and editing text documents, spreadsheets, presentations, and forms using the Edit in ONLYOFFICE option.
To learn more about forms, please read the corresponding articles for creating and filling out forms.
Co-editing documents in real-time: two co-editing modes (Fast and Strict), Track Changes, comments, and a built-in chat.
JWT support to secure your traffic so that no one can have access to your documents with the exception of the users with proper rights.

Supported formats

For creating, editing and viewing: DOCX, XLSX, PPTX, DOCXF.
For working with forms: DOCXF/PDF.
For viewing only: DOC, DOCM, DOC, DOTX, DOTM, ODT, FODT, OTT, RTF, TXT, HTML, HTM, MHT, PDF, DJVU, FB2, EPUB, XPS, XLS, XLSM, XLTZ, XLTX, XLTM, ODS, FODS, OTS, CSV, PPS, PPSX, PPSM, PPT, PPTM, POT, POTX, POTM, ODP, FODP, OTP.

Connecting ONLYOFFICE Docs to Jira

Requirements

ONLYOFFICE Document Server v6.4.0 (server or cloud version) or later
You need an instance of ONLYOFFICE Docs that is resolvable and connectable both from Jira and any end clients. It must be able to POST to Jira directly.
Please refer to the official documentation page to learn more about installing ONLYOFFICE Docs.
Jira Software (Server or Data Center) v. 9.0.0 - 9.9.*
Please refer to the official Atlassian documentation to learn more about installing Jira Software.
ONLYOFFICE Connector v2.1.0 and later for Jira

Installing the ONLYOFFICE connector for Jira

You can download the connector from the official Atlassian Marketplace or compile it from source codes available on GitHub.

Adding the connector from the Atlassian marketplace

Log into your Jira Software instance as an administrator.
Click the Administration icon in the upper right corner and choose the Manage apps option from the menu.
The Find new apps section will open. Click the Search the Marketplace field and find the Jira ONLYOFFICE integration app.
Click the Install button to download and install the application.

Adding the connector compiled from the source code

First of all, you need to install the following prerequisites to be able to compile the ONLYOFFICE connector for Jira:

To compile the ONLYOFFICE connector for Jira, follow these steps:

Clone the onlyoffice-jira repository.

git clone https://github.com/ONLYOFFICE/onlyoffice-jira.git

Go to the onlyoffice-jira directory.
```
cd onlyoffice-jira
```
Run the following command:
```
atlas-package
```
Wait while the connector is being compiled. After it's done, the connector can be found in the target folder

You can upload the compiled connector on your Jira Software Administration > Manage Apps page.

Log into your Jira Software instance as an administrator.
Click the Administration icon in the upper right corner and choose the Manage apps option from the menu.
Select the Manage apps section on the left-hand side of the page.
Click the Upload app link.
Click the Choose File button, browse for the compiled target/onlyoffice-jira-app.jar file and click Upload. Wait while the application is being installed.

Configuring the ONLYOFFICE connector for Jira

Click the Configure button below the installed Jira ONLYOFFICE integration app on the Manage apps page or find the app in the OTHER section of the Manage apps page.

In the Document Editing Service address field, specify the IP address or hostname of the server with ONLYOFFICE Docs installed.

The address of ONLYOFFICE Docs must be accessible from Jira, as well as the address of Jira must be accessible from ONLYOFFICE Docs.

Disable certificate verification (insecure) - check this box to disable the certificate verification and allow Jira to establish connection with ONLYOFFICE Docs if you are using a self-signed certificate for your ONLYOFFICE Docs (otherwise, Jira will not validate a self-signed certificate and will not allow connection to/from ONLYOFFICE Docs). This is an insecure solution, and we strongly recommend that you replace the certificate with the one issued by some CA.

Specify a Secret key - the secret to validate the JSON web token upon the request to ONLYOFFICE Docs.

Starting from ONLYOFFICE Docs v7.2, JWT is enabled by default and the secret key is generated automatically. You need to enable it on the Jira side as well: find your secret key in the ONLYOFFICE Docs configuration file, then specify the same secret key in the connector settings. For more details, see the Enabling JWT for the ONLYOFFICE and Jira integration section of this article.

The Advanced server settings section can be used if your network configuration does not allow requests between the installed Jira Software and ONLYOFFICE Docs using the public addresses. In this case, specify addresses for internal requests in the corresponding fields:

Jira Software server address for internal requests from ONLYOFFICE Docs.
ONLYOFFICE Docs address for internal requests from the Jira Software server.

Click Save to save the settings.

How it works

The ONLYOFFICE integration follows the API documented here.

User navigates to the Jira attachments and selects the Edit in ONLYOFFICE action.
Jira makes a request to OnlyOfficeEditorServlet (URL of the form: /plugins/servlet/onlyoffice/doceditor?attachmentId=$attachment.id).
Jira sends the document to ONLYOFFICE Document storage service and receives a temporary link.
Jira prepares a JSON object with the following properties:
- url: the temporary link that ONLYOFFICE Docs uses to download the document;
- callbackUrl: the URL that ONLYOFFICE Docs uses to inform about status of the document editing;
- docserviceApiUrl: the URL that the client needs to reply to ONLYOFFICE Docs (provided by the files.docservice.url.api property);
- key: the UUID to instruct ONLYOFFICE Docs whether to download the document again or not;
- title: the document title (name).
Jira takes this object and constructs a page from a freemarker template, filling in all of those values so that the client browser can load up the editor.
The client browser makes a request to the JavaScript library from ONLYOFFICE Docs and sends ONLYOFFICE Docs the DocEditor configuration with the above properties.
Then ONLYOFFICE Docs downloads the document from document storage and the user begins editing.
When all users and client browsers are done with editing, they close the editing window.
After 10 seconds of inactivity, ONLYOFFICE Docs sends a POST to callbackUrl letting Jira know that the clients have finished editing the document and closed it.
The document with all the changes is saved as a new attachment with the postfix added to the file name.

Enabling JWT for the ONLYOFFICE and Jira integration

To protect documents from unauthorized access, ONLYOFFICE editors use the JSON Web Token (JWT). The token is added in the configuration when the Document Editor is initialized and during the exchange of commands between inner ONLYOFFICE Docs services. The secret key is used to sign the JSON web token and validate the token upon the request to ONLYOFFICE Docs.

Starting from ONLYOFFICE Docs v7.2, JWT is enabled by default and the secret key is generated automatically. You need to find your secret key in the ONLYOFFICE Docs configuration file, then specify the same secret key in the connector settings.

Step 1: Find your secret key in the ONLYOFFICE Docs configuration file

Open the local.json file with any available text editor.
- For Linux - /etc/onlyoffice/documentserver/local.json
- For Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json
- For Docker – enter the ONLYOFFICE Docs container using the docker exec -it <containerID> bash command and open /etc/onlyoffice/documentserver/local.json
  Alternatively, you can use the following command to find the default secret key without opening local.json:
```
sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'
```
The local.json file should look like this:
```
{"services": {"CoAuthoring": {"token": {"enable": {"request": {"inbox": true,"outbox": true},"browser": true}},"secret": {"inbox": {"string": "yoursecret"},"outbox": {"string": "yoursecret"},"session": {"string": "yoursecret"}}}}}
```
The true value is specified in three sections. It means that token validation is enabled.
- services.CoAuthoring.token.enable.browser
- services.CoAuthoring.token.enable.request.inbox
- services.CoAuthoring.token.enable.request.outbox
The automatically generated secret key is specified in three sections. You can replace the default secret value with your own secret key. The secret key must be the same in three sections.
- services.CoAuthoring.secret.inbox.string
- services.CoAuthoring.secret.outbox.string
- services.CoAuthoring.secret.session.string
If you make changes, save them and restart the services for the config changes to take effect.
```
supervisorctl restart all
```

Step 2: Specify the same secret key in the connector settings

In the connector settings, specify the same secret in the Secret key field and save the settings.

Connecting to the demo ONLYOFFICE Docs

Starting from ONLYOFFICE connector version 2.0.0, you can try the ONLYOFFICE online editors within Jira without installing ONLYOFFICE Docs.

To turn the connection on, click the Connect to demo ONLYOFFICE Docs server checkbox and click the Save button.

ImportantThis is a public test server that will be available during a 30-day period. Don’t share your sensitive data there.

Start using ONLYOFFICE Docs within Jira

Creating, viewing and editing files

You can open the ONLYOFFICE editors from any Attachments block of an issue. This option is available for issues from any module where an issue can be opened, e.g., issue list, backlog, issues, etc.

Attachments must be enabled by the administrator.

A new attachment can be added on the issue page using the More -> Attach files option. To learn more, see the official documentation.

To open an existing text document, spreadsheet, presentation, or form, move the mouse pointer over the necessary file and click the ONLYOFFICE_connector Edit in ONLYOFFICE icon. If the file format is not supported for editing, the View in ONLYOFFICE option is available. For the .oform files, the Fill in form in ONLYOFFICE option is available. The resulting document will be saved in a PDF format.

The file will be opened in a new browser tab in the corresponding ONLYOFFICE editor.

To create a new file using the ONLYOFFICE editors:

In the Attachments block of an issue, click the Create file with ONLYOFFICE option.
Choose the needed file type: Document, Spreadsheet, Presentation, or Form template.
Type in the file name and click Create.
The file will be opened in a new browser tab in the corresponding ONLYOFFICE editor.

After the editing session is over, a document with all the changes will be saved as a new attachment. You will recognize it by the same name with a postfix. If you're editing an attachment collaboratively, the changes are saved only after the last user quits the editor.

Access permissions

Access permissions for files depend on a user's access rights to the corresponding issue.

Editing files. To be able to edit files, a user must have permissions for creating attachments (Create attachments).

Viewing files. File preview in the ONLYOFFICE viewers is available for all users who can view an issue, but do not have permissions for editing the issue or permissions for creating attachments. If the file format is not supported for editing, the file will be opened for viewing.

Converting documents

To convert a document to the Office Open XML format:

Move the mouse pointer over the necessary file and click the ONLYOFFICE conversion service icon.
Optionally, you can change the file name.
Click the Convert button.
The converted file will be stored in the Attachments block.

Saving changes

The changes made to a file are saved to a new file with the same name as the original file, with a postfix added at the end of the file name, e.g., Sample-1.docx.

The changes made to a file during the co-editing process are only saved to the first version of the file. If the document is being edited by several users simultaneously, the changes will be displayed only in the first file. Until the last user closes the editor, a new version of the file is not added to the issue.

Downloading files

To download a document in a different format:

Move the mouse pointer over the necessary file and click the ONLYOFFICE conversion service icon.
Optionally, you can change the file name.
Select the necessary format from the Target type list.
Click the Download button.
The downloaded file will be stored on your computer.

Watch video

How to integrate ONLYOFFICE with Jira

Host ONLYOFFICE Docs on your own server or use it in the cloud

Get it now Use in the cloud