Garoon x Box 連携（ポータル・スケジュール）

はじめに

Box は、Box Inc. が提供するクラウドコンテンツ管理サービスです。

cybozu developer network では Box と連携した Box for kintone プラグインを公開していますが、今回は Garoon と連携する便利なカスタマイズを 2 件紹介します。

1. ポートレットのカスタマイズ
   Garoon のログインユーザーに紐づく Box アカウントのフォルダーを表示します。
   Box で管理しているファイルを Garoon から閲覧できるようになります。
2. スケジュールのカスタマイズ
   予定に紐づく Box Notes をボタンひとつで作成・表示します。
   Box Note を作っておけば、打ち合わせなどの議事録のメモ帳として使えるので、議事録管理もかんたんです。

必要なもの

• クラウド版 Garoon
• Box ビジネスアカウント

注意事項

• このカスタマイズには、クラウド版 Garoon の環境が必要です。
• カスタマイズプログラムは、その動作を保証するものではありません。
  カスタマイズプログラムの技術的なサポート等は行っていません。

ポートレットのカスタマイズ

完成イメージ

Box アカウントのフォルダー一覧を表示するポートレットです

カスタマイズの設定

Garoon ポートレットを追加、ポータルに表示します。

1. HTML ポートレットの追加

次の内容で、HTML ポートレットを追加します。
手順の詳細は、クラウド版 Garoon ヘルプ | HTMLポートレットの設定をご参照ください。

項目	値
ポートレット名	任意の値を入力してください。 この記事では「Box 連携」とします。
ポートレットの内容	「テキスト」を選択します。 「内容」には、下記のポートレット HTML を貼り付けます。

ポートレットHTML

2. ポータルへの配置

作成した HTML ポートレットをポータルに配置します。
手順の詳細は、クラウド版 Garoon ヘルプ | ポートレットを配置するをご参照ください。

動作確認

1. Garoon で、カスタマイズしたHTMLポートレットを配置したポータルを開きます。
2. Box ポートレット上のログインボタンをクリックし、Box のアカウント情報を入力してログインします。
   
   次の画面が表示される場合は、雲のアイコンを操作します。
   
3. Garoon のポータルに Box のファイル一覧が表示されます。
   

スケジュールのカスタマイズ

完成イメージ

予定メニュー連携を使って、特定の予定メニューのときに、予定の詳細画面で Box Note を作成、表示します。

Box Note の作成

予定の詳細画面の[Box Noteを追加する]ボタンをクリックすると、予定のタイトルと同じファイル名で Box Note を作成します。

• Box Note は、ひな形になる Box Note をコピーして作成されます。
• Box Note は、議事録を作成する人が作成してください。
  共同で編集したい場合は、作成した Box Note の共有リンク設定を、編集権限付き共有リンクに変更してください。
  参照：box Support | Box Notes の共有

予定に紐づく Box Note の表示

予定に紐づく Box Note が作成されていれば、予定の詳細画面に Box Note の内容を表示します。

• [Box で編集する]ボタンをクリックすると、別タブでその Box Note が表示され内容を編集できます。
• [Box noteの連携削除]ボタンをクリックすると、予定と Box Note の紐付けが解除されます。
  ※ 連携を解除しても、作成した Box Note は削除されません。
  ※ 繰り返し予定では、同じ Box Note が表示されます。

システム構成

Garoon と Box の関係は次のようになっています。

• Box API で API 実行に必要なアクセストークンを取得します。
• 取得したアクセストークンを利用して、Box のAPIを実行し、ノートの作成や共有 URL を生成します。

スケジュールのカスタマイズの設定

スケジュールのカスタマイズでは、Box と Garoon で設定します。

Box の設定

Box では、以下の設定を行います。

1. アプリの作成
2. テンプレートとする Box Note の準備
3. 管理対象ユーザーの追加

1. アプリの作成

OAuth による認可を行うための「クライアントID」と「クライアントシークレット」を発行します。

1. Box 開発者コンソール にログインします。
2. [アプリの新規作成]をクリックします。
   
3. [カスタムアプリ]を選択します。
   
4. [サーバー認証 (クライアント資格情報許可)]を選択し、アプリ名を入力します。
   ここでは、例として「Garoon-schedule」を入力しています。
   入力が終わったら、[アプリを作成]ボタンをクリックします。
   
5. [構成]タブで、次の内容を設定します。設定したら[保存]ボタンをクリックします。
   
   
   • アクセスレベル：「アプリ + Enterprise アクセス」を選択
   • 管理操作：「ユーザーを管理する」にチェック
   • 高度な機能：「as-user ヘッダーを使用して API 呼び出しを行う」
6. [承認]タブで、「Enterpriseへのアクセス権限に対する承認を得るためにアプリを送信」の[確認して送信]ボタンをクリックします。
   
   
   
7. 「アプリ承認の送信内容の確認」ダイアログで、「アプリの説明」に適当な内容を入力し、[送信]ボタンをクリックします。
   
8. 右上のユーザーアイコンをクリックし、「管理コンソール」を選択します。
9. 左メニューの「アプリ」を選択し、[カスタムアプリ]タブで作成したアプリを選択します。
10. [承認]ボタンをクリックします。
    
11. 「カスタムアプリの承認」ダイアログで、[承認]ボタンをクリックします。
12. [マイアプリ] > [作成したアプリ名] > [一般]タブを開きます。
13. 「マイアプリ」で、Enterprise ID を確認します。
    Enterprise ID は、後述のプロキシ API の設定で使用するので、メモしておいてください。
    
14. 「サービスアカウント情報」で、Service Account ID を確認します。
    Service Account ID は、後述の ひな形 Box Note 準備で Note の共有先として利用するので、メモしておいてください。
    
15. [構成]タブを開きます。
16. 「OAuth 2.0資格情報」で、クライアント ID とクライアントシークレットを確認します。
    クライアントシークレットは、[クライアントシークレットを取得]ボタンをクリックすると取得できます。
    クライアント ID とクライアントシークレットは、後述のプロキシ API の設定で使用するので、メモしておいてください。
    

以上で、アプリの設定は終わりです。

2. ひな形 Box Note の準備

予定に紐づく Box Note の元となる、ひな形 Box Note を用意します。

1. Box にログインします。
2. 任意のフォルダーを開き、[新規]ボタンをクリック、[テンプレート使用の Box Note]を選択します。
   
3. 新規ウィンドウが表示されます。任意のテンプレートを選択し、[作成]ボタンをクリックします。
   この記事では、Box が用意している「ミーティングアジェンダ」を利用します。
   
4. 作成された Note の URL より、Note ID（「notes/」以降の値）を確認します。
   例： URL が https://app.box.com/notes/xxxxxx のとき、Note ID は xxxxxx です。
   Note ID は、後述のカスタマイズファイルの適用で利用するので、メモしておいてください。
5. サンプルデータが入力されているので、不要な部分を削除しておきます。
6. ノートを追加したフォルダーに戻り、[共有]ボタンをクリックします。
7. 「ユーザーを招待」に、先ほどメモしておいた Service Account ID を入力し、[送信]ボタンをクリックします。
   

以上で、ひな形 Box Note の準備は終わりです。

3. 管理対象ユーザーの追加

管理対象ユーザーに、Box カスタマイズを適用するユーザーのメールアドレスを追加します。
このとき、.com 共通 のユーザーのメールアドレスと同じメールアドレスを指定してください。
手順の詳細は「box Support | 管理対象ユーザーの追加」を参照してください。

Garoon の設定

Garoon では、以下の設定を行います。

1. プロキシ API の設定の追加
2. 予定連携メニューの追加
3. スケジュールカスタマイズの適用

1. プロキシ API の設定の追加

Box API を実行するため、6つのプロキシ API 設定を追加します。
手順の詳細は、クラウド版 Garoon ヘルプ | プロキシAPIの設定をご参照ください。

• ファイルのコラボレーション（アクセス権）に操作ユーザーを追加する

  項目	値
  ステータス	「有効」を選択
  プロキシコード	addUserToCollaborations
  メソッド	「POST」を選択
  URL	https://api.box.com/2.0/collaborations
  ヘッダー	キー：Content-Type　値：application/json

• テンプレートとする Box Note をコピーする
  

  項目	値
  ステータス	「有効」を選択
  プロキシコード	copyNote
  メソッド	「POST」を選択
  URL	https://api.box.com/2.0/files
  ヘッダー	キー：Content-Type　値：application/json

• 共有リンクのURLを作成、取得する

  項目	値
  ステータス	「有効」を選択
  プロキシコード	createSharedLink
  メソッド	「PUT」を選択
  URL	https://api.box.com/2.0/files
  ヘッダー	キー：Content-Type　値：application/json

• アクセストークンを取得する
  

  項目	値
  ステータス	「有効」を選択
  プロキシコード	getApiToken
  メソッド	「POST」を選択
  URL	https://api.box.com/oauth2/token
  ヘッダー	キー：Content-Type　値：application/json
  ボディ	キー：client_id　値：Box の設定 - アプリの作成で確認したクライアント ID キー：client_secret　値：Box の設定 - アプリの作成で確認したクライアントシークレット キー：grant_type　値：client_credentials キー：box_subject_type　値：enterprise キー：box_subject_id　値：Box の設定 - アプリの作成で確認した Enterprise ID

• ファイルのコラボレーション（アクセス権）を取得する

  項目	値
  ステータス	「有効」を選択
  プロキシコード	getCollaborations
  メソッド	「GET」を選択
  URL	https://api.box.com/2.0/files
  ヘッダー	キー：Content-Type　値：application/json

• Box ユーザーのユーザー ID を取得する

  項目	値
  ステータス	「有効」を選択
  プロキシコード	getUserId
  メソッド	「GET」を選択
  URL	https://api.box.com/2.0/users
  ヘッダー	キー：Content-Type　値：application/json

手順2. 予定メニュー連携

予定メニュー連携を使うと、予定を登録するときに選択する「予定メニュー」に連携して、スケジュール詳細画面の「メモ」の下に行を追加できます。
手順の詳細は、クラウド版 Garoon ヘルプ | 予定メニュー連携を追加するをご参照ください。

追加する予定メニューは次のとおりです。

項目名	設定値
予定メニュー名	任意の値を選択します。 この記事では「打合」メニューが選択されたときに表示したいので、「打合」とします。
ポートレット	「ポートレット例」を選択し、下記のHTML を貼り付けます。

ポートレットHTML

3. カスタマイズファイルの適用

カスタマイズグループを作成し、スケジュールのカスタマイズファイルを適用します。
手順の詳細は、クラウド版 Garoon ヘルプ | スケジュールのカスタマイズをご参照ください。

追加するカスタマイズ設定は、次のとおりです。

項目名	設定値
カスタマイズ	「適用する」を選択します。
カスタマイズグループ名	任意の値を入力します。 今回は「Box 連携」とします。
適用対象	カスタマイズを適用するユーザー・グループを選択します。
JavaScript カスタマイズ	次の内容を指定します。 bundled_index.js 詳細は、「サンプルプログラム」をご参照ください。

サンプルプログラム

サンプルプログラムでは、webpack を使って、IE で動作させるために必要なライブラリの組み込みと構文を変換し、 jQuery や Garoon html/css/image-Kit for Customize を組み込みます。
webpack における IE 対応の詳細は、webpack入門 ~Babel,Polyfillを使って快適ES6ライフ~ をご参照ください。

※ webpack を実行するには、Node.js の実行環境が必要です。
Node.js 公式サイトからインストーラをダウンロードし、セットアップしてください。
このカスタマイズでは、Node.js 14 で動作を確認しています。

1. https://github.com/garoon/garoonBox にアクセスします。
2. [Clone or download] ボタンをクリックして、[Download ZIP]を選択します。
3. ダウンロードした zip ファイルを解凍します。
4. 解凍したファイルの「src」フォルダー下の「index.js」を開き、次の値を修正します。
   8行目 BOX_TARGET_FILE_ID：メモした Note ID
5. ターミナルで、解凍したフォルダーに移動します。

   $ cd garoonBox-master

6. 次のコマンドで、必要なライブラリをインストールします。

   $ npm install

7. webpack を実行します。

   $ npm run webpack_prod

8. 「dist」フォルダー以下の bundled_index.js を Garoon カスタマイズに利用します。

動作確認

1. Garoon スケジュールで、予定を登録します。
   このとき、「タイトル」項目の予定メニューで「打合」（「Garoon の設定 - 2. 予定メニュー連携」で設定したメニュー名と同じ値）を選択します。
   
2. 登録した予定をクリックし、予定の詳細画面を表示します。
3. 「打合」の[Box Noteを追加する]ボタンをクリックします。
   
4. Box へのログインを求めるウィンドウが表示されます。Box のアカウント情報を入力してログインします。
5. 予定の「タイトル」と同じ名前の Box Note が Box に作成されます。
   作成された Box Note が、Garoon の予定詳細画面に表示されれば OK です。
   ※ Box のログインを求められる場合は、Box のアカウント情報を入力してログインしてください。
   

おわりに

この記事では、Box  内のファイル一覧のポータル表示や、スケジュールに紐づく Box Note を作成・表示するポートレットカスタマイズを紹介しました。
他にも cybozu developer network では、様々な Garoon ポータルカスタマイズや Garoon スケジュールカスタマイズを紹介しています。ぜひご参照ください。

このカスタマイズでは、次の API を利用しています。

• Garoon API
  • 予定の詳細画面が表示されたときのイベント
  • 予定の値を取得する
  • カスタム項目（Schedule datastore）の値を取得する
  • 予定のカスタム項目（Schedule datastore）の登録
  • 予定のカスタム項目（Schedule datastore）の削除
  • 外部 API の実行
• Box API（外部サイト）
  • コラボレーションを作成
  • ファイルをコピー
  • 共有リンクを更新
  • アクセストークンをリクエスト
  • ファイルのコラボレーションリストの取得
  • 会社ユーザーのリストを取得

変更履歴

• 2021年8月16日　スケジュールカスタマイズのコード修正
  すでにこのカスタマイズを適用している場合、スケジュールのカスタマイズの設定を参考にもう一度適用し直してください。
  なお、適用し直す前に作成した Box Note は表示されなくなります。ご注意ください。
  変更内容の詳細は次のとおりです。
  
  • Box の共有リンクの保存先を、カスタム項目（additionalItems）からカスタム項目（Schedule datastore）に変更
  • jQuery と Garoon html/css/image-Kit for Customize を webpack でバンドルするように変更
  • Box への認証方法を、OAuth.io の利用から、Box のサーバー認証 (クライアント資格情報許可)に変更

 

このTipsは、2021年7月版 Garoonで確認したものになります。