Jira

Об интеграции ONLYOFFICE и Jira

ONLYOFFICE предлагает официальные коннекторы для интеграции ONLYOFFICE Docs с Jira, которые позволяют совместно работать над офисными документами, прикрепленными к задачам Jira. Доступны два коннектора в зависимости от способа развертывания Jira:

• Jira Data Center / Server — доступен в Atlassian Marketplace и на GitHub. Распространяется под лицензией Apache.
• Jira Cloud — доступен в Atlassian Marketplace и на GitHub. Распространяется под лицензией Apache.

Обратите внимание

Чтобы узнать больше о том, как работает коннектор для Jira, посетите нашу документацию по API.

Основные возможности

• Создание новых документов, таблиц, презентаций и форм.

• Просмотр и редактирование текстовых документов, таблиц, презентаций и форм с помощью параметра Edit in ONLYOFFICE.

  Обратите внимание

  Подробнее о формах см. в соответствующих статьях о создании и заполнении форм.

• Совместное редактирование документов в реальном времени: два режима совместного редактирования (Быстрый и Строгий), Отслеживание изменений, комментарии и встроенный чат.

• Поддержка JWT для защиты передаваемых данных: доступ к документам есть только у пользователей с соответствующими правами.

• Поддержка ИИ-ассистента (только в Jira Cloud) — подключите предпочитаемого поставщика ИИ через плагин ИИ. Совместим с OpenAI, Mistral, Anthropic, Google Gemini, DeepSeek и другими. Подробнее см. в руководстве по ИИ.

Поддерживаемые форматы

Для просмотра:

• WORD: DOC, DOCM, DOCX, DOT, DOTM, DOTX, EPUB, FB2, FODT, HTM, HTML, HWP, HWPX, MD, MHT, MHTML, ODT, OTT, PAGES, RTF, STW, SXW, TXT, WPS, WPT, XML
• CELL: CSV, ET, ETT, FODS, NUMBERS, ODS, OTS, SXC, XLS, XLSM, XLSX, XLT, XLTM, XLTX
• SLIDE: DPS, DPT, FODP, KEY, ODG, ODP, OTP, POT, POTM, POTX, PPS, PPSM, PPSX, PPT, PPTM, PPTX, SXI
• PDF: DJVU, DOCXF, OFORM, OXPS, PDF, XPS
• DIAGRAM: VSDM, VSDX, VSSM, VSSX, VSTM, VSTX

Для редактирования:

• WORD: DOCM, DOCX, DOTM, DOTX
• CELL: XLSB, XLSM, XLSX, XLTM, XLTX
• SLIDE: POTM, POTX, PPSM, PPSX, PPTM, PPTX
• PDF: PDF

Следующие форматы также доступны для редактирования в Jira Data Center / Server. Обратите внимание, что при редактировании этих форматов возможна потеря информации:

• WORD: EPUB, FB2, HTML, ODT, OTT, RTF, TXT
• CELL: CSV, ODS, OTS
• SLIDE: ODP, OTP

Что нового в 4.1.1

Jira Data Center

Изменено

• Исправлена проблема с HTTP-запросами плагина, когда Jira развернута с контекстным путем.

Полный список изменений доступен здесь.

Jira Cloud

Добавлено

• Первый выпуск коннектора ONLYOFFICE для Jira Cloud.

Полный список изменений доступен здесь.

Подключение ONLYOFFICE Docs к Jira Data Center / Server

Требования

• ONLYOFFICE Document Server v6.4.0 (серверная или облачная версия) или выше.

  Вам понадобится экземпляр ONLYOFFICE Docs, доступный и разрешаемый по имени как из Jira, так и со всех клиентских устройств. Он должен иметь возможность напрямую отправлять POST-запросы в Jira.

  Обратите внимание

  Подробнее об установке ONLYOFFICE Docs см. на официальной странице документации.

• Jira Software. Существует два коннектора для разных версий Jira Data Center:

  • Коннектор ONLYOFFICE v3.1.1 для Jira Software (Server или Data Center) v. 9.0.0 — 9.17.5
  • Коннектор ONLYOFFICE v4.1.1 для Jira Software (Server или Data Center) v. 10.0.0 — 10.7.2
  Обратите внимание

  Подробнее об установке Jira Software см. в официальной документации Atlassian.

• Коннектор ONLYOFFICE для Jira.

  Чтобы скачать нужную версию коннектора, воспользуйтесь этим списком.

Установка коннектора ONLYOFFICE для Jira

Вы можете скачать коннектор из официального Atlassian Marketplace или скомпилировать его из исходного кода, доступного на GitHub.

Добавление коннектора из Atlassian Marketplace

1. Войдите в свой экземпляр Jira Software как администратор.

2. Нажмите значок Administration в правом верхнем углу и выберите в меню пункт Manage apps.

   

3. Откроется раздел Find new apps. Нажмите поле Search the Marketplace и найдите Jira ONLYOFFICE integration app.

4. Нажмите кнопку Install, чтобы скачать и установить приложение.

Добавление коннектора, скомпилированного из исходного кода

Сначала нужно установить следующие компоненты, необходимые для компиляции коннектора ONLYOFFICE для Jira:

• 1.8.X Oracle Java SE Development Kit 8
• Atlassian Plugin SDK

Чтобы скомпилировать коннектор ONLYOFFICE для Jira, выполните следующие действия:

1. Клонируйте репозиторий onlyoffice-jira.

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

2. Перейдите в каталог onlyoffice-jira.

   cd onlyoffice-jira

3. Выполните следующую команду:

   atlas-package

   Дождитесь завершения компиляции коннектора. После этого коннектор можно найти в папке target.

Скомпилированный коннектор можно загрузить на странице Jira Software Administration > Manage Apps.

1. Войдите в свой экземпляр Jira Software как администратор.

2. Нажмите значок Administration в правом верхнем углу и выберите в меню пункт Manage apps.

3. Выберите раздел Manage apps в левой части страницы.

4. Нажмите ссылку Upload app.

5. Нажмите кнопку Choose File, найдите скомпилированный файл target/onlyoffice-jira-app.jar и нажмите Upload. Дождитесь завершения установки приложения.

   

Настройка коннектора ONLYOFFICE для Jira

Нажмите кнопку Configure под установленным Jira ONLYOFFICE integration app на странице Manage apps или найдите приложение в разделе OTHER на странице Manage apps.

Document Server

1. В поле Document Editing Service address укажите IP-адрес или имя хоста сервера, на котором установлен ONLYOFFICE Docs.

   Обратите внимание

   Адрес ONLYOFFICE Docs должен быть доступен из Jira, а адрес Jira должен быть доступен из ONLYOFFICE Docs.

2. Disable certificate verification (insecure) — установите этот флажок, чтобы отключить проверку сертификата и позволить Jira установить соединение с ONLYOFFICE Docs, если вы используете самоподписанный сертификат. Это небезопасное решение; настоятельно рекомендуем заменить сертификат на выпущенный центром сертификации.

3. Укажите Secret key (оставьте пустым, чтобы отключить) — секретный ключ для проверки JSON Web Token при запросе к ONLYOFFICE Docs.

   Обратите внимание

   Начиная с ONLYOFFICE Docs v7.2, JWT включен по умолчанию, а секретный ключ генерируется автоматически. Его нужно включить и на стороне Jira: найдите секретный ключ в файле конфигурации ONLYOFFICE Docs, а затем укажите тот же ключ в настройках коннектора. Подробнее см. в разделе Включение JWT этой статьи.

4. Authorization header (оставьте пустым, чтобы использовать заголовок по умолчанию) — заголовок авторизации JWT, используемый в ONLYOFFICE, — Authorization. Если он конфликтует с вашей конфигурацией, можно заменить его на пользовательский.

5. Connect to demo ONLYOFFICE Document Server — запустить тестовый сервер.

   Важно

   Это общедоступный тестовый сервер, который будет доступен в течение 30 дней. Не размещайте на нем конфиденциальные данные.

Расширенные настройки сервера

Раздел Advanced server settings можно использовать, если конфигурация вашей сети не позволяет выполнять запросы между Jira Software и ONLYOFFICE Docs по публичным адресам. Укажите адреса для внутренних запросов в соответствующих полях:

1. Server address for internal requests from the Document Editing Service — адрес сервера Jira Software для внутренних запросов из ONLYOFFICE Docs.
2. Document Editing Service address for internal requests from the server — адрес ONLYOFFICE Docs для внутренних запросов с сервера Jira Software.

Общие настройки

1. Editable formats — установите флажки рядом с форматами, которые поддерживаются вашей средой Jira.

   При сохранении в указанных форматах возможна потеря данных из-за ограничений форматов.

2. Editor interface — настройте интерфейс редакторов:

   • Display Chat menu button — скрыть или показать значок встроенного онлайн-чата (Chat) на левой панели.
   • Display the header more compact — скрыть или показать текст значков на верхней панели инструментов.
   • Display Feedback & Support menu button — скрыть или показать кнопку Feedback & Support на левой панели.
   • Display Help menu button — скрыть или показать кнопку Help на левой панели.
   • Display monochrome toolbar header — переключить верхнюю панель инструментов на монохромную цветовую палитру.

Безопасность

1. Enable plugins — включить или отключить поддержку плагинов в редакторах.
2. Run document macros — включить или отключить запуск макросов в редакторах.
3. Enable document protection for — выберите, разрешить ли защиту документов паролем всем пользователям (all users) или только владельцу документа (owner).

Нажмите Save, чтобы сохранить настройки.

Как это работает

Интеграция ONLYOFFICE следует API, описанному здесь.

1. Пользователь переходит к вложениям Jira и выбирает действие Edit in ONLYOFFICE.
2. Jira отправляет запрос в OnlyOfficeEditorServlet (URL вида: /plugins/servlet/onlyoffice/doceditor?attachmentId=$attachment.id).
3. Jira отправляет документ в службу хранения документов ONLYOFFICE и получает временную ссылку.
4. Jira подготавливает объект JSON со следующими свойствами:
   • url: временная ссылка, по которой ONLYOFFICE Docs скачивает документ;
   • callbackUrl: URL, по которому ONLYOFFICE Docs сообщает о статусе редактирования документа;
   • docserviceApiUrl: URL, по которому клиенту нужно отвечать ONLYOFFICE Docs (задается свойством files.docservice.url.api);
   • key: UUID, по которому ONLYOFFICE Docs определяет, нужно ли скачивать документ заново;
   • title: название (имя) документа.
5. Jira берет этот объект и создает страницу из шаблона freemarker, подставляя все эти значения, чтобы браузер клиента мог загрузить редактор.
6. Браузер клиента обращается к библиотеке JavaScript ONLYOFFICE Docs и отправляет ONLYOFFICE Docs конфигурацию DocEditor с указанными выше свойствами.
7. Затем ONLYOFFICE Docs скачивает документ из хранилища документов, и пользователь начинает редактирование.
8. Когда все пользователи и браузеры клиентов заканчивают редактирование, они закрывают окно редактирования.
9. После 10 секунд бездействия ONLYOFFICE Docs отправляет POST-запрос на callbackUrl, сообщая Jira, что клиенты завершили редактирование документа и закрыли его.
10. Документ со всеми изменениями сохраняется как новое вложение с постфиксом, добавленным к имени файла.

Включение JWT

Чтобы защитить документы от несанкционированного доступа, редакторы ONLYOFFICE используют JSON Web Token (JWT). Токен добавляется в конфигурацию при инициализации редактора документов и при обмене командами между внутренними службами ONLYOFFICE Docs. Секретный ключ используется для подписи JSON Web Token и проверки токена при запросе к ONLYOFFICE Docs.

Начиная с ONLYOFFICE Docs v7.2, JWT включен по умолчанию, а секретный ключ генерируется автоматически. Вам нужно найти секретный ключ в файле конфигурации ONLYOFFICE Docs, а затем указать тот же ключ в настройках коннектора.

Шаг 1: найдите секретный ключ в файле конфигурации ONLYOFFICE Docs

1. Откройте файл local.json в любом текстовом редакторе:

   • Для Linux — /etc/onlyoffice/documentserver/local.json

   • Для Windows — %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json

   • Для Docker — войдите в контейнер ONLYOFFICE Docs с помощью команды docker exec -it <containerID> bash и откройте /etc/onlyoffice/documentserver/local.json.

     Также можно найти секретный ключ по умолчанию, не открывая local.json, с помощью следующей команды:

     sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

   Файл local.json должен выглядеть так:

   {
     "services": {
       "CoAuthoring": {
         "token": {
           "enable": {
             "request": {
               "inbox": true,
               "outbox": true
             },
             "browser": true
           }
         },
         "secret": {
           "inbox": {
             "string": "yoursecret"
           },
           "outbox": {
             "string": "yoursecret"
           },
           "session": {
             "string": "yoursecret"
           }
         }
       }
     }
   }

2. Значение true указано в трех разделах, что означает, что проверка токена включена:

   • services.CoAuthoring.token.enable.browser
   • services.CoAuthoring.token.enable.request.inbox
   • services.CoAuthoring.token.enable.request.outbox

3. Автоматически сгенерированный секретный ключ указан в трех разделах. Вы можете заменить значение по умолчанию на собственный ключ — он должен быть одинаковым во всех трех разделах:

   • services.CoAuthoring.secret.inbox.string
   • services.CoAuthoring.secret.outbox.string
   • services.CoAuthoring.secret.session.string

4. Если вы вносите изменения, сохраните их и перезапустите службы:

   supervisorctl restart all

Шаг 2: укажите тот же секретный ключ в настройках коннектора

В настройках коннектора укажите тот же секретный ключ в поле Secret key и сохраните настройки.

Подключение к демонстрационному ONLYOFFICE Docs

Начиная с версии коннектора ONLYOFFICE 2.0.0, вы можете опробовать онлайн-редакторы ONLYOFFICE в Jira без установки ONLYOFFICE Docs.

Чтобы включить подключение, установите флажок Connect to demo ONLYOFFICE Docs server и нажмите кнопку Save.

Важно

Это общедоступный тестовый сервер, который будет доступен в течение 30 дней. Не размещайте на нем конфиденциальные данные.

Подключение ONLYOFFICE Docs к Jira Cloud

Требования

• Экземпляр ONLYOFFICE Docs — либо собственный, либо облачный.
• Jira Cloud.
• Коннектор ONLYOFFICE для Jira Cloud из Atlassian Marketplace.

Установка коннектора ONLYOFFICE для Jira Cloud

1. Перейдите на marketplace.atlassian.com.
2. Найдите ONLYOFFICE Connector for Jira и нажмите кнопку Get it now.
3. Во всплывающем окне выберите сайт, на который вы хотите установить приложение, и выберите редакцию, если доступно несколько вариантов.

Настройка коннектора ONLYOFFICE для Jira Cloud

Администраторы могут настроить приложение ONLYOFFICE через Apps → Manage apps → ONLYOFFICE Connector for Jira → Configure. На странице конфигурации задайте:

• ONLYOFFICE Docs address — URL установленного ONLYOFFICE Docs.
• ONLYOFFICE Docs secret key — включает JWT для защиты ваших документов от несанкционированного доступа. Подробнее см. в руководстве по настройке JWT.
• Authorization header.

Вы также можете подключиться к общедоступному тестовому серверу ONLYOFFICE Docs на один месяц, установив соответствующий флажок.

Важно

Это общедоступный тестовый сервер, который будет доступен в течение 30 дней. Не размещайте на нем конфиденциальные данные.

Начало работы с ONLYOFFICE Docs в Jira Data Center / Server

Создание, просмотр и редактирование файлов

Редакторы ONLYOFFICE можно открыть из любого блока Attachments задачи. Эта возможность доступна для задач из любого модуля, где можно открыть задачу, например из списка задач, бэклога и т. д.

Обратите внимание

Вложения должны быть включены администратором.

Новое вложение можно добавить на странице задачи с помощью параметра More → Attach files. Подробнее см. в официальной документации.

Чтобы открыть существующий текстовый документ, таблицу, презентацию или форму, наведите указатель мыши на нужный файл и нажмите значок Edit in ONLYOFFICE. Если формат файла не поддерживается для редактирования, доступен параметр View in ONLYOFFICE. Для файлов .oform доступен параметр Fill in form in ONLYOFFICE. Полученный документ будет сохранен в формате PDF.

Файл откроется в новой вкладке браузера в соответствующем редакторе ONLYOFFICE.

Чтобы создать новый файл с помощью редакторов ONLYOFFICE:

1. В блоке Attachments задачи нажмите параметр Create file with ONLYOFFICE.

2. Выберите нужный тип файла: Document, Spreadsheet, Presentation или Form template.

3. Введите имя файла и нажмите Create.

   

4. Файл откроется в новой вкладке браузера в соответствующем редакторе ONLYOFFICE.

После завершения сеанса редактирования документ со всеми изменениями будет сохранен как новое вложение. Его можно узнать по тому же имени с постфиксом. Если вы совместно редактируете вложение, изменения сохраняются только после того, как последний пользователь закроет редактор.

Права доступа

Права доступа к файлам зависят от прав пользователя на соответствующую задачу.

Редактирование файлов. Чтобы редактировать файлы, пользователь должен иметь разрешение на создание вложений (Create attachments).

Просмотр файлов. Предварительный просмотр файлов в средствах просмотра ONLYOFFICE доступен всем пользователям, которые могут просматривать задачу, но не имеют прав на редактирование задачи или прав на создание вложений. Если формат файла не поддерживается для редактирования, файл будет открыт для просмотра.

Конвертация документов

Чтобы конвертировать документ в формат Office Open XML:

1. Наведите указатель мыши на нужный файл и нажмите значок ONLYOFFICE conversion service.

   

2. При необходимости можно изменить имя файла.

3. Нажмите кнопку Convert.

4. Конвертированный файл будет сохранен в блоке Attachments.

   

Сохранение изменений

Изменения, внесенные в файл, сохраняются в новый файл с тем же именем, что и у исходного файла, с постфиксом в конце имени, например Sample-1.docx.

Изменения, внесенные в файл в процессе совместного редактирования, сохраняются только в первую версию файла. Если документ одновременно редактируют несколько пользователей, изменения будут отображаться только в первом файле. Пока последний пользователь не закроет редактор, новая версия файла в задачу не добавляется.

Скачивание файлов

Чтобы скачать документ в другом формате:

1. Наведите указатель мыши на нужный файл и нажмите значок ONLYOFFICE conversion service.

   

2. При необходимости можно изменить имя файла.

3. Выберите нужный формат в списке Target type.

4. Нажмите кнопку Download.

5. Скачанный файл будет сохранен на вашем компьютере.

Обратите внимание

Чтобы узнать больше о наиболее распространенных проблемах и способах их решения, посетите наше руководство по устранению неполадок.

Начало работы с ONLYOFFICE Docs в Jira Cloud

На странице задачи Jira есть раздел ONLYOFFICE Docs. Если вы его не видите, нажмите значок шестеренки под заголовком задачи и выберите ONLYOFFICE Docs, чтобы включить его.

Создание файлов

Чтобы создать новый файл, нажмите кнопку Create with ONLYOFFICE. Во всплывающем окне введите имя файла и выберите формат файла. В настоящее время можно создавать файлы в форматах DOCX, XLSX, PPTX и PDF-форм.

После нажатия Create файл будет создан и сразу откроется во всплывающем окне с правами на редактирование. Вновь созданный файл также будет добавлен в раздел Attachments.

Редактирование и просмотр файлов

Чтобы открыть существующий файл для редактирования, нажмите значок карандаша рядом с ним. Чтобы открыть его только для просмотра, нажмите значок глаза. Редактор запустится в соответствующем режиме.

Важно

Из-за ограничений коннектора редактор не может оставаться открытым в течение длительного времени. Его необходимо перезапускать каждые четыре часа, чтобы обеспечить бесперебойную работу.

Права доступа

• Скачивание и просмотр: доступны всем пользователям с доступом к задаче Jira.
• Редактирование: пользователи могут редактировать созданные ими файлы. Чтобы редактировать файлы, созданные другими, пользователям необходимо разрешение Delete All Attachments.

Чтобы предоставить права на редактирование определенной роли Jira:

1. Откройте контекстное меню нужного проекта и выберите Project settings.
2. Перейдите в раздел Permissions, нажмите кнопку Action и обновите список ролей для Delete All Attachments.