ONLYOFFICE DocsとJiraの連携方法について

## ONLYOFFICEとJiraの連携について

ONLYOFFICEでは、ONLYOFFICE DocsとJira Softwareを連携させ、Jiraの課題に添付されたオフィス文書でコラボレーションを行うための公式コネクタを提供しています。[Atlassian Marketplace](https://marketplace.atlassian.com/) または [GitHub](https://github.com/ONLYOFFICE/onlyoffice-jira) からダウンロードすることができます。このアプリケーションは Apache ライセンスで配布されています。

:::note warn
動作の詳細については、[APIドキュメント](https://api.onlyoffice.com/editors/Jira#how-it-works)をご覧ください。
:::


### 主な機能

* テキスト文書、スプレッドシート、スライド、フォームを「**ONLYOFFICEで編集する**」オプションを使用して表示および編集

:::note warn
フォームの詳細については、フォームの[作成](https://test-helpcenter.onlyoffice.com/onlyoffice-editors/onlyoffice-document-editor/UsageInstructions/CreateFillableForms.aspx)と[記入](https://test-helpcenter.onlyoffice.com/onlyoffice-editors/onlyoffice-document-editor/UsageInstructions/FillingOutForm.aspx)のための対応する記事をお読みください。
:::

* リアルタイムでドキュメントを共同編集：2つの共同編集モード（高速と厳格）、変更履歴、コメント、内蔵チャット
* **JWTサポート**により、適切な権限を持つユーザーを除いて、誰もあなたのドキュメントにアクセスできないように、トラフィック保護

### 対応フォーマット

* 作成、編集、閲覧用：DOCX, PPTX, XLSX, DOCXF
* フォームへの入力用：OFORM
* 閲覧のみ：DOC、DOCM、DOC、DOTX、DOTM、ODT、FODT、OTT、RTF、TXT、HTML、HTM、MHT、PDF、DJVU、FB2、EPUB、XPS、XLS、XLSM、XLTZ 、XLTX、XLTM、ODES、FODS、ONTS、CSV、PPS、PPX、PPSM、PPT、PPTM、POT、POTX、POTM、ODP、FODP、OTP

## ONLYOFFICE DocsとJiraを連携させる

### 必要条件

* ONLYOFFICE Docs 6.4.0 またはそれ以上
Jiraと任意のエンドクライアントの両方から解決可能で接続可能なONLYOFFICE Docsのインスタンスが必要です。それはJiraに直接POSTできる必要があります。

:::note warn
ONLYOFFICE Docsのインストールについては、ONLYOFFICE Docsの公式[ドキュメントページ](https://helpcenter.onlyoffice.com/installation/docs-index.aspx)を参照してください。
:::

* Jira ソフトウェア (サーバーまたはデータセンター) v. 7.13.0 - 8.19.0
Jira Software のインストールについては、[Atlassianの公式ドキュメント](https://confluence.atlassian.com/adminjiraserver/installing-jira-applications-938846823.html)を参照してください。

## Jira 用 ONLYOFFICE コネクタのインストール

[Atlassian Marketplace](https://marketplace.atlassian.com/) からコネクタをダウンロードするか、[GitHub](https://github.com/ONLYOFFICE/onlyoffice-jira) で公開されているソースコードからコンパイルすることができます。

### Atlassian Marketplace からコネクタを追加する

１．Jira Software インスタンスに管理者としてログインしてください。
２．右上の**管理アイコン**をクリックし、メニューから「**アプリの管理**」オプションを選択します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2655664/20099b66-8bbb-adce-3c80-bc348c1fa7e7.png)

３．「**新しいアプリの検索**」セクションが表示されます。「**Marketplaceの検索**」フィールドをクリックし、**Jira ONLYOFFICE** 統合アプリを見つけます。
４．「**インストール**」ボタンをクリックして、アプリケーションをダウンロードおよびインストールします。

### ソースコードからコンパイルしたコネクタを追加する

まず、Jira 用 ONLYOFFICE コネクタをコンパイルできるようにするために、以下の前提条件をインストールする必要があります。

* [1.8.X of the Oracle Java SE Development Kit 8](https://www.oracle.com/java/technologies/downloads/#java8)
* [Atlassian Plugin SDK](https://developer.atlassian.com/server/framework/atlassian-sdk/install-the-atlassian-sdk-on-a-linux-or-mac-system/)

Jira 用 ONLYOFFICE コネクタをコンパイルするには、以下の手順に従ってください。

１．[onlyoffice-jira](https://github.com/ONLYOFFICE/onlyoffice-jira/tree/main) リポジトリをクローンします。

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

２．`onlyoffice-jira`ディレクトリに移動します。

```
cd onlyoffice-jira
```

３．以下のコマンドを実行します。

```
atlas-package
```

コネクタがコンパイルされるのを待ちます。完了後、コネクタはターゲット フォルダで見つけることができます。

コンパイルされたコネクタは、「Jira Software 管理」→「**アプリの管理**」ページでアップロードすることができます。

１．管理者として Jira Software インスタンスにログインします。
２．右上の「**管理アイコン**」をクリックし、メニューから「アプリの管理」オプションを選択します。
３．ページの左側にある「アプリの管理」セクションを選択します。
４．「**アプリのアップロード**」リンクをクリックします。
５．「**ファイルの選択**」ボタンをクリックし、コンパイルされた`target/onlyoffice-jira-app.jar`ファイルを参照し、「**アップロードする**」をクリックします。アプリケーションがインストールされるまで待ちます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2655664/d4fb67b8-b79f-3a4c-19d8-ebae72e3258a.png)

### Jira 用 ONLYOFFICE コネクタを設定する

「**アプリ管理**」ページでインストールされた**Jira用ONLYOFFICE統合アプリ**の下にある設定ボタンをクリックするか、「**アプリ管理**」ページの「**その他**」セクションでアプリを見つけます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2655664/99973f4f-d97b-b879-e750-28772e870b0b.png)

「**ドキュメント編集サービスのアドレス**」欄には、ONLYOFFICE DocsがインストールされているサーバーのIPアドレスまたはホスト名を指定します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2655664/087ce686-3f81-785f-1858-cb7b29ad08ef.png)

また、ONLYOFFICE Docsへのリクエスト時にJSONウェブトークンを検証するための**シークレットキー**を指定することができます。詳細については、この記事の「**ONLYOFFICEとJiraの統合のためのJWTを有効にする**」セクションをご覧ください。

「**サーバーの高度設定**」セクションは、ネットワーク構成上、インストールした Jira Software と ONLYOFFICE Docs の間でパブリックアドレスを使用したリクエストができない場合に使用できます。この場合、対応するフィールドで内部リクエストのためのアドレスを指定します。

* ONLYOFFICE Docs からの内部リクエストのための Jira Software サーバーアドレス
* Jira Software サーバーからの内部リクエストのための ONLYOFFICE Docs のアドレス

「**保存**」をクリックして、設定を保存します。

## ONLYOFFICEとJiraの連携でJWTを有効にする

不正アクセスからドキュメントを保護するために、ONLYOFFICE編集部ではJSON Web Token（JWT）を使用しています。このトークンは、ドキュメントエディタの初期化時、およびONLYOFFICE Docsの内部サービス間のコマンドの交換時に、設定に追加されます。シクレットキーは、ONLYOFFICE Docsへのリクエスト時に、JSONウェブトークンに署名し、トークンを検証するために使用されます。

ドキュメントを保護するために、トークン検証を有効にし、ONLYOFFICE Docs設定ファイルで独自のシクレットキーを指定し、コネクタ設定でも同じシクレットキーを指定する必要があります。

**ステップ１**：ONLYOFFICE Docsを設定する

　　１．任意の利用可能なテキストエディターで local.json ファイルを開いてください。
* Linuxの場合：`/etc/onlyoffice/documentserver/local.json`
* Windowsの場合：`%ProgramFiles%ONLYOFFICE⇄DocumentServer⇄local.json`
* Dockerの場合：`docker exec -it <containerID> bash`コマンドを使用してONLYOFFICE Docsコンテナに入り、`/etc/onlyoffice/documentserver/local.json`を開いてください。

　　２．3つのセクションで`false`の値を`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`

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

　　４．変更内容を保存します。
　　５．設定変更を有効にするために、サービスを再起動します。

```
supervisorctl restart all
```

**ステップ２**：コネクタの設定で同じシークレットキーを指定する

コネクタの設定で、**シークレットキー**の欄に同じシークレットを指定し、設定を保存します。

## Jira内でONLYOFFICE Docsを使い始める

### ファイルの表示と編集

課題のどの**添付ファイル**ブロックからでも、ONLYOFFICEエディタを開くことができます。このオプションは、課題リスト、バックログなど、課題を開くことができるどのモジュールからでも利用可能です。

:::note warn
添付ファイルは、[管理者が有効にする](https://support.atlassian.com/jira-cloud-administration/docs/configure-file-attachments/)必要があります。
新しい添付ファイルは、課題ページで「その他」→「ファイルを添付」オプションを使用して追加できます。詳しくは、[公式ドキュメント](https://confluence.atlassian.com/jiracoreserver/attaching-files-and-screenshots-to-issues-939937892.html)をご覧ください。
:::

テキスト文書、スプレッドシート、スライド、フォームを開くには、必要なファイルにマウスポインタを合わせ、「**ONLYOFFICEで編集する**」アイコンをクリックします。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2655664/38cbc40e-d968-29a8-4f89-d8df0f812eda.png)

ファイルは、新しいブラウザのタブで、対応するONLYOFFICEエディタに開かれます。

### アクセス権限

ファイルへのアクセス権限は、課題に対するユーザーのアクセス権限に依存します。

**ファイルの編集**。ファイルを編集するためには、ユーザーは添付ファイルを作成する権限`添付ファイルの作成`を持っている必要があります。

**ファイルの閲覧**。ONLYOFFICEビューアでのファイルプレビューは、課題を閲覧できるすべてのユーザーが利用できますが、課題の編集権限や添付ファイルの作成権限は持っていません。編集に対応していない[ファイル形式](https://helpcenter.onlyoffice.com/integration/gettingstarted-jira.aspx#Overview_block)の場合、閲覧用にファイルが開かれます。

### 変更内容の保存

ファイルに加えられた変更は、元のファイルと同じ名前の新しいファイルに保存されます。ファイル名の末尾には、`Sample-1.docx`のようなポストフィックスが追加されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2655664/c767e20b-8641-b024-d04e-01d12716cc81.png)

共同編集中にファイルに加えられた変更は、そのファイルの最初のバージョンにのみ保存されます。ドキュメントを複数のユーザーが同時に編集している場合、変更内容は最初のファイルにのみ表示されます。最後のユーザーがエディタを閉じるまで、ファイルの新しいバージョンは発行に追加されません。