Garoon カスタマイズで外部システムの API を実行する〜打合せコスト算出カスタマイズ〜

はじめに

「Garoon スケジュール・ポータルのカスタマイズをはじめよう〜会議効率化カスタマイズ〜」では、Garoon JavaScript API と Garoon REST API の使い方を知り、Garoon カスタマイズの基本を学びました。
次にこの記事で、Garoon JavaScript カスタマイズで外部システムの API を実行する方法を学んでいきましょう。

Garoon と社内で利用している他のシステムを連携させると、Garoon のポータル上に他のシステムの情報を出力したり、Garoon のワークフローを承認したら自動で外部システムにそのデータを送信したりできるようになります。

この記事の内容は、「Cybozu Days 2019 の Garoon中級ハンズオン〜APIを使って作る、カスタマイズポータル作成ハンズオン〜」で紹介したものです。

この記事で学べること

• Garoon JavaScript API を使って、外部システムの API を実行する方法

環境準備

• Garoon クラウド版
• テキストエディタ

注意事項

• モバイル画面および KUNAI では利用できません。

ハンズオン

完成イメージ

参加者ごとに設定された単価から算出された予定※の打合せコストを、予定の詳細画面で見える化します。
※ 「予定メニュー」が「打合」の予定が対象です。

算出コストの内訳は、ブラウザの開発者コンソールに出力されます。

参加者の単価は、ユーザー情報のカスタマイズ項目に設定します。
設定していないユーザーの単価は、0円で算出されます。

Step 1: ユーザー項目の追加

この設定には、cybozu.com 共通管理者の権限が必要です。
手順の詳細は「ユーザー情報の項目を追加する（カスタマイズ項目）」をご参照ください。

1. Garoon メニュー右の歯車アイコンをクリックし、[cybozu.com 共通管理]を選択します。
2. 「ユーザー管理」の[組織/ユーザー]を選択します。
3. [プロフィール項目の設定]をクリックします。
4. 「カスタマイズ項目の設定」の[追加]ボタンをクリックします。
5. 以下の内容を入力します。入力が終わったら、[保存]ボタンをクリックします。
   

   項目	設定する値
   項目名	任意の値を入力します。 この記事では「単価」とします。
   項目コード	「UnitPrice」を入力します。
   タイプ	「文字列（1行）」を選択します。
   公開/非公開	「公開する」のチェックを外します。
   ユーザーによる変更	「ユーザーによる変更を許可する」のチェックを外します。

Step 2: プロキシ API の設定

1. Garoon メニュー右の歯車アイコンをクリックし、[Garoonシステム管理]を選択します。
2. [基本システムの管理]タブを選択し、[API]を選択します。
3. [プロキシAPIの設定]を選択します。
4. [追加する]をクリックします。
5. 以下の内容を入力します。入力が終わったら、[追加する]ボタンをクリックします。
   
   

   項目	設定する値
   ステータス	「有効」を選択します。
   プロキシコード	「CalculatingCosts」を入力します。
   メソッド	「GET」を選択します。
   URL	https://{subdomain}.cybozu.com ※ {subdomain} は利用している Garoon 環境のサブドメインに置き換えてください。
   ヘッダー	次のキーと値の組み合わせを設定します。 キー：X-Cybozu-Authorization 値：Garoon のログイン名とパスワードを「:」でつないだ値をBase64 エンコードしたもの ※ Base64エンコードの方法はこちらの記事を参照してください。

Step 3: カスタマイズファイルの作成

1. テキストエディタを開いて、次のコードの内容をコピー＆ペーストします。
2. ファイルの拡張子「.js」、文字コードは「UTF-8(BOMなし)」で、ファイルに名前を付けて保存します。
   この記事では、ファイル名を calculating-costs.js としています。

Step 4: カスタマイズの適用

カスタマイズグループを作成し、スケジュールのカスタマイズファイルを適用します。
手順の詳細は「スケジュールのカスタマイズ設定」をご参照ください。

1. Garoon メニュー右の歯車アイコンをクリックし、[Garoonシステム管理]を選択します。
2. [各アプリケーションの管理]タブを選択し、[スケジュール]を選択します。
3. [JavaScript/CSSによるカスタマイズ]を選択します。
4. [カスタマイズグループを追加する]をクリックします。
5. 次の内容を入力します。入力が終わったら、[追加する]ボタンをクリックします。
   

   項目	設定する値
   カスタマイズ	「適用する」を選択します。
   カスタマイズグループ名	任意の値を入力します。この記事では「会議効率化カスタマイズ」としています。
   適用対象	管理部など、打合せのコストを表示しても問題ないユーザーや部署を選択してください。
   JavaScript カスタマイズ	以下の順で、URL およびファイルを指定します。 https://js.cybozu.com/jquery/3.1.1/jquery.min.js calculating-costs.js（カスタマイズファイル）
   CSS カスタマイズ	grn_kit.css を指定します ※ grn_kit.css（Garoon html/css/image-Kit for Customize）の入手方法 https://github.com/garoon/css-for-customize にアクセスします。 [Clone or download] ボタンをクリックして、「Download ZIP」を選択します。 ダウンロードした zip ファイルを解凍します。 解凍したファイルの「css」フォルダー以下の「grn_kit.css」を利用します。

コードの解説

プロキシ API 設定

プロキシAPI 設定は、ブラウザから外部システムのAPIを実行するための Garoon の仕組みです。
garoon.base.proxy.send() を実行すると、あらかじめ設定しておいたプロキシ設定に基づいて、Garoon サーバーから外部システムの API へのリクエストを送信します。
参考：プロキシ API の設定

また、外部システムのAPI の実行に必要な認証情報※を、プロキシAPI設定で設定しカスタマイズファイル内にハードコーディングしないので、セキュアに API にアクセスできます。
参考：セキュアコーディングガイドライン - 認証情報をプログラムにハードコーディングしない
※ User API の場合は、「X-Cybozu-Authorization」というリクエストヘッダーが認証情報です。

garoon.base.proxy.send()

garoon.base.proxy.send() は、Garoon から外部システムの API を実行する Garoon JavaScript API です。
今回のコードでは、次の箇所で利用しています。

今回実行する User API の API ユーザーエクスポート API（JSON）に合わせて、garoon.base.proxy.send(プロキシコード, URL, メソッド, APIに渡すデータ)  という形で指定※します。
※ Promise を使う方法です。Promise については、こちらの記事をご参照ください。

• プロキシコード：「プロキシ API 設定」で設定したプロキシコード
• URL：API ユーザーエクスポート API（JSON） の URI を指定します。検索条件（今回は予定の参加者のユーザーコード）を URL パラメータで指定しています。
  今回のコードでは、変数 path と query を結合した値を指定していますが、path と query は次の部分で定義しています。
  たとえば、予定の参加者のユーザーコードが yamada と sato の場合、次のURLが指定されます。
  https://{subdomain}.cybozu.com/v1/users.json?codes[0]=yamada&codes[1]=sato
• メソッド：GET
• API に渡すデータ：なし

正常に実行できたら .then の引数で指定した関数の処理を実行し、エラーが発生したら .catch の引数で指定した関数の処理を実行します。
今回、正常に実行できたときは、取得した UnitPrice の値を使って打合せコストを算出し、画面上に表示しています。

動作確認

1. ユーザー情報を変更し、「UnitPrice」に、単価を設定します。
   参考：ユーザー情報の変更
2. 予定を登録します。
   予定メニュー：「打合」を選択します
   参加者：1. で単価を設定したユーザーを選択します。
3. 登録した予定の詳細画面を開きます。タイトルの下部に打合せコストが表示されていることを確認します。

おわりに

cybozu developer network では、さまざまな Garoon の連携カスタマイズ Tips を公開しています。
Tips に掲載しているコードで「どんなことをしているか？」を確認しながら、ぜひカスタマイズに挑戦してみてください。

利用している Garoon API

• Garoon JavaScript API
  • 予定の詳細画面が表示されたときのイベント
  • 外部 API の実行
• User API
  • API ユーザーエクスポート API（JSON）

利用しているライブラリ

• jQuery v3.1.1, ドキュメント（外部サイト）
  HTML要素の生成や操作を楽に扱うことができるライブラリです。
  打合せコストを表示する <>HTML 要素の作成や予定の詳細画面への挿入などに利用しています。
• Garoon html/css/image-Kit for Customize, ドキュメント
  ボタンなどの UI パーツをGaroon の見た目に調和させるスタイルシートのライブラリです。
  打合せコストを表示する HTML 要素の背景色に利用しています。

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