Atlassian Jira/Confluence のクロール

今回は、Atlassian Jira および Confluence を対象に、Fess を使ってクロールし、検索可能にする方法を紹介します。

Jira や Confluence は、課題管理やドキュメント管理として多くの現場で利用されていますが、情報が分散しがちで「探しにくい」と感じる場面も少なくありません。 本記事では、Fess を利用してJira/Confluenceの情報を横断的に検索できる環境を構築する手順を、実際の設定例を交えながら解説します。

Atlassianでの認証設定

まずは、Atlassian側でアプリを作成して、アクセストークンとリフレッシュトークンを生成します。

アプリの作成

ブラウザでDeveloperコンソールにアクセスします。

「Create」をクリックして、「OAuth2.0 integration」を選択してください。

「アプリ名」を入力し、「I agree to be bound by Atlassian's developer terms.」にチェックを入れて「Create」ボタンをクリックします。

このアプリの「Client ID」と「Secret」の値はクロール設定の時に必要になるので、以下の手順で値を確認しておいてください。

左メニューの「Settings」をクリックし、「Authentication details」欄の「Client ID」と「Secret」の値をコピーしておきます。

スコープの追加

左メニューの「permissions」をクリックして、それぞれ必要なスコープを追加します。

Jira API のスコープ

「Jira API」横の「Add」ボタンをクリックします。ボタンの表示が「Configure」に変わるのでもう一度クリックします。

Jira APIの画面で「Edit Scope」をクリックします。

以下のスコープにチェックを入れて「Save」ボタンをクリックします。

• read:jira-user
• read:jira-work

チェックを入れたスコープが選択されていることを確認してください。

Confluence API のスコープ

Jira API と同じ手順で追加します。 Confluence API では以下のスコープにチェックを入れてください。

• read:confluence-content.all
• read:confluence-user
• search:confluence
• read:confluence-space.summary

OAuth 2.0 の有効化

コールバックURLを登録します。

左メニューの「Authorization」をクリックして、「OAuth 2.0 (3LO)」横の「Add」または「Configure」をクリックします。

コールバックURLを入力します。アプリからアクセスできる任意のURLを設定してください。今回は http://localhost:8080/ を入力しました。 入力後は「Save changes」をクリックして保存してください。

認可コードの取得

コールバックURLを登録すると、「Authorization URL generator」が表示されるので、これを使って認可コードを取得します。 authorization URL は Jira と Confluence それぞれ表示されていますが、同じ手順で取得できます。

まず、対象の authorization URL をコピーしてローカルのテキストエディタにコピーします。 URLに以下の変更を加えてください。

• refresh_token を取得するため、URL中の scope パラメータの先頭に offline_access%20 を追加
• ${YOUR_USER_BOUND_VALUE} は任意のトークンを設定

ブラウザを起動し、修正したURLにアクセスします。 同意画面が表示されるので、「Accept」をクリックしてください。

コールバックされたURL(ブラウザのアドレスバーに表示されたURL)の code の値が認可コードになります。

access_token と refresh_token を取得

以下のcurlコマンドを実行して access_token と refresh_token を取得します。

curl --request POST \
  --url 'https://auth.atlassian.com/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{"grant_type": "authorization_code","client_id": "YOUR_CLIENT_ID","client_secret": "YOUR_CLIENT_SECRET","code": "YOUR_AUTHORIZATION_CODE","redirect_uri": "YOUR_APP_CALLBACK_URL"}'

以下の値は利用している環境の値に置き換えてください。

• YOUR_CLIENT_ID ：アプリ作成時に確認した Client ID
• YOUR_CLIENT_SECRET ：アプリ作成時に確認した Secret
• YOUR_AUTHORIZATION_CODE ：取得した認可コード
• YOUR_APP_CALLBACK_URL ：登録済みのコールバックURL

コマンド実行後のレスポンスに access_token と refresh_token が含まれているので、この値を控えておいてください。

Fessのクロール設定

今回は、Fess 15.6.1を利用して説明します。

プラグインのインストール

クロール設定を作成する前に、クロール時に使用するプラグインをインストールします。 Fessの管理画面にログインして「システム」＞「プラグイン」＞「インストール」をクリックします。 「リモートタブ」で「fess-ds-atlassian-15.6.0」を選択して「インストール」をクリックしてください。

インストール後、プラグイン一覧画面を表示して、fess-ds-atlassian が登録されていることを確認してください。

クロールの設定

管理画面の「クローラー」＞「データストア」＞「新規作成」をクリックして以下を入力します。

• 名前
• ハンドラ名
• パラメータ
• スクリプト

名前には任意のクロール設定の名前を入力し、ハンドラ名は「JiraDataStore」または「ConfluenceDataStore」を選択します。

パラメータは次のように記述します。

home=AtlassianのURL（https://xxxxx.atlassian.net）
is_cloud=true
auth_type=oauth2
oauth2.client_id=アプリ作成時に確認した`Client ID`
oauth2.client_secret=アプリ作成時に確認した`Secret`
oauth2.access_token=取得した`access_token`
oauth2.refresh_token=取得した`refresh_token`

スクリプトは以下で設定します。

Jiraをクロールする場合は以下を設定してください。

url=issue.view_url
title=issue.summary
content=issue.description + issue.comments
last_modified=issue.last_modified

Confluenceをクロールする場合は以下を設定してください。

url=content.view_url
title=content.title
content=content.body + content.comments
last_modified=content.last_modified

クロールの実行

クロール設定の登録後、「システム」>「スケジューラ」>「Default Crawler」から「今すぐ開始」をクリックします。 クロールが完了したら、検索画面にアクセスして検索してみましょう。JiraまたはConfluenceに登録した内容が検索できていれば成功です。

まとめ

今回は、Fess を利用して、Atlassian JiraおよびConfluenceの情報をクロールし、検索可能にする方法を紹介しました。 Fess を利用することで、Jiraの課題情報やConfluenceのドキュメントを含めて、横断的に検索できるようになり、情報が分散して「探しにくい」という課題を解消できます。

Jira や Confluence を日常的に利用している環境では、ぜひFessによる横断検索の導入をご検討ください。