cybozu developer network

Enhanced by Google

カテゴリー内の他の記事

Garoon スケジュール・ポータルのカスタマイズをはじめよう〜会議効率化カスタマイズ〜

作成日
更新日

Index

はじめに

この記事は、「API ドキュメントを読んだけど、使い方がわからない」「Garoon カスタマイズに興味はあるけど、何から始めて良いかわからない」といった人に向けた内容です。
Garoon スケジュールやポータルのカスタマイズを通じて、Garoon JavaScript API と Garoon REST API の使い方を知り、Garoon カスタマイズの基本を学んでみましょう。

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

この記事で学べること

  • Garoon JavaScript API（イベント）の使い方
  • Garoon REST API の使い方
    • 予定の更新
    • 条件に一致する予定の取得
  • 予定のカスタム項目（schedule datastore）
  • Garoon スケジュールおよびポータルのカスタマイズを適用する方法

環境準備

  • Garoon クラウド版、またはパッケージ版 ver. 5.9 以降
  • テキストエディタ

注意事項

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

Garoon JavaScript API と Garoon REST API

ここでは Garoon の代表的なアプリケーションであるワークフロー、スケジュール、ポータルを例に、Garoon JavaScript API と Garoon REST API を説明します。

Garoon JavaScript API と Garoon REST API

JavaScript とは

JavaScript はブラウザで利用できるプログラミング言語です。
Web ページはコンテンツの内容を作る HTML と 見た目を整える CSS を使って作られていますが、一度読み込むとページの内容は基本的に変化しません。
しかし、JavaScript を利用すると、リアルタイムにページの内容を書き換えできるので、Web ページに動きをつけることができます。

Garoon JavaScript API とは

Garoon JavaScript API は、画面をカスタマイズするためのインターフェースで、開いている Garoon の画面に表示されている内容や HTMLの要素を取得、操作できます。
Garoon JavaScript API を使うと、Garoon の画面の見た目を変えたり、入力された値が正しいかをチェックするなどの動きを変えたりできます。

JavaScript には、「●●が実行されたときに◯◯を行う」といった処理ができる「イベント」という仕組みがあります。
Garoon の場合、「予定の詳細画面が表示されたとき」「ワークフローが承認されたとき」といったイベントが存在します。
このイベントを利用すると、「グループ週画面が表示されたときに、週画面に付加情報を表示する」といったカスタマイズができます。

Garoon REST API とは

Garoon REST API は、データ連携のためのインターフェースで、Garoon で管理しているデータを外部システムに渡したり、外部システムから Garoon にデータを登録、更新、削除できます。

また、Garoon REST API は、スケジュールとワークフローといった、Garoon の異なるアプリケーション間でデータをやり取りしたい場合や、開いている Garoonの画面上に無い内容を取得、操作したい場合にも利用します。

ハンズオン

それでは、スケジュールとポータルをそれぞれカスタマイズしていきましょう。

完成イメージ

会議の効率化（会議が短縮された時間）を数値として把握し、ポータルで全社の成果をグラフで見える化するカスタマイズです。

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

スケジュールの完成イメージ

  • 予定の詳細画面の「会議を終了する」ボタンをクリックすると、予定の終了日時が更新されます。
    ※ 「予定メニュー」が「打合」の予定が対象です。
  • 「会議を終了するボタン」で会議を終了した予定の場合、改善成果（短縮された会議時間）を表示します。

ポータルのカスタマイズ

ポータルの完成イメージ

  • ポータルに、直近1週間の改善成果をグラフ表示します。
    • 短縮された会議時間の予定ランキング
    • 1週間でどの程度会議を効率できたかの比較

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

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

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

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

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

  1. Garoon メニュー右の歯車アイコンをクリックし、[Garoonシステム管理]を選択します。
  2. [各アプリケーションの管理]タブを選択し、[スケジュール]を選択します。
  3. [JavaScript/CSSによるカスタマイズ]を選択します。
  4. [カスタマイズグループを追加する]をクリックします。
  5. 次の内容を入力します。入力が終わったら、[追加する]ボタンをクリックします。
    項目 設定する値
    カスタマイズ 「適用する」を選択します。 
    カスタマイズグループ名 任意の値を入力します。この記事では「会議効率化カスタマイズ」としています。
    適用対象 カスタマイズを適用するユーザーやグループを選択します。
    JavaScript カスタマイズ 以下の順で、URL およびファイルを指定します。
    • https://js.cybozu.com/jquery/3.1.1/jquery.min.js
    • schedule-customize.js（カスタマイズファイル）
    CSS カスタマイズ  grn_kit.css を指定します

    ※ grn_kit.css（Garoon html/css/image-Kit for Customize）の入手方法
    1. https://github.com/garoon/css-for-customize にアクセスします。
    2. [Clone or download] ボタンをクリックして、「Download ZIP」を選択します。
    3. ダウンロードした zip ファイルを解凍します。
    4. 解凍したファイルの「css」フォルダー以下の「grn_kit.css」を利用します。

コードの解説

イベントを使って、予定の詳細画面を開いたときに実行する処理を定義する

16行目〜110行目では、イベントを使って、予定の詳細画面を開いたときに実行する処理を記述しています。
...略...  Garoon のイベントは、garoon.events.on(処理を行うタイミングのイベントタイプ, 実行する処理の関数);という形で指定します。
今回、処理を行うタイミングは「予定の詳細画面を開いたとき」なので「schedule.event.detail.show」というイベントタイプを指定します。
2番目の引数には、実行する処理を関数の形で指定します（ function(event) { ... } の部分）

「会議を終了する」ボタンをクリックしたときに、Garoon REST API を実行する

30行目〜58行目の finishMeeting 関数は、「会議を終了する」ボタンをクリックしたときに呼び出されます。このとき、
finishMeeting 関数では、2つの Garoon REST API を実行しています。

  • 予定のカスタム項目（Schedule datastore）の更新 API
    予定のカスタム項目（Schedule datastore）は、スケジュールのカスタマイズにおいて複数のデータを保持できる機能です。
    このカスタマイズでは、「ボタンをクリックしたか」「ボタンをクリックしたときの時刻」「削減できた時間」「効率(%)」を、カスタム項目（Schedule datastore）として保存しています。
  • 予定の更新 API

Garoon 上で Garoon REST API を実行するときは、Garoon REST APIリクエストを送信する API  を利用できます（50行目、51行目）。
この API  は、garoon.api(REST API の URL パス, メソッド, APIに渡すデータ) という形で指定します。
※ Promise を使う方法です。Promise については、こちらの記事をご参照ください。
例えば、予定の更新 API を実行するときに指定する内容は、次のようになります。

  • REST API の URL パス： /api/v1/schedule/events/更新する予定のID
  • メソッド：PATCH
  • APIに渡すデータ：更新したい内容

REST API が正常に実行できた後の処理は、.then の引数で指定した関数に記述します（52行目〜52行目）の .then(function(resp) { ... }) の部分）。
今回は、画面を再読み込みしています。

動作確認

  1. 予定を登録します。
    • 予定メニュー：「打合」を選択します
    • 日時：現在時刻が開始日時と終了日時の間になるように設定します
      例：現在時刻が 10:30 なら、日時を 10:00 〜 11:00 に設定する。
  2. 登録した予定の「会議を終了する」ボタンをクリックして、会議を終了します。
  3. 予定の終了日時が更新され、短縮時間や効率の情報が表示されたことを確認します。

ポータルのカスタマイズ

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

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

Step 2: ポートレットの追加

手順の詳細は「HTMLポートレットを追加する」をご参照ください。

  1. Garoon メニュー右の歯車アイコンをクリックし、[Garoonシステム管理]を選択します。
  2. [各アプリケーションの管理]タブを選択し、[ポータル]を選択します。
  3. [HTMLポートレット]をクリックし、[HTMLポートレットを追加する]をクリックします。
  4. 次の内容を入力します。入力が終わったら、[追加する]ボタンをクリックします。
    項目 設定する値
    ポートレット名 任意の値を入力します。この記事では「会議効率化ポートレット」とします。
    グループ 任意のポートレットグループを選択します。
    Myポータル Myポータルで利用する場合はチェックを入れます。
    ポートレットの内容 次の内容を貼り付けます。

Step3: カスタマイズの適用

引き続き、追加したポートレットにカスタマイズファイルを適用します。手順の詳細は「ポータルのカスタマイズ」をご参照ください。

  1. 前手順で追加したポートレットを開きます。
  2. [JavaScript/CSSによるカスタマイズ]を選択します。
  3. [カスタマイズグループを追加する]をクリックします。
  4. 次の内容を入力します。入力が終わったら、[追加する]ボタンをクリックします。
    項目 設定する値
    カスタマイズ 「適用する」を選択します。 
    適用対象 カスタマイズを適用するユーザーやグループを選択します。
    JavaScript カスタマイズ 以下の順で、URL およびファイルを指定します。
    • https://js.cybozu.com/jquery/3.1.1/jquery.min.js
    • https://js.cybozu.com/momentjs/2.15.1/moment-with-locales.min.js
    • https://js.cybozu.com/chartjs/v2.2.2/Chart.min.js
    • portlet-customize.js（カスタマイズファイル）
    CSS カスタマイズ  以下の順で、URL およびファイルを指定します。
    • https://js.cybozu.com/font-awesome/v5.5.0/css/fontawesome-all.min.css
    • portlet-customize.css
      次の内容をテキストエディタにコピー＆ペーストし、ファイルの拡張子「.css」、文字コードは「UTF-8(BOMなし)」で保存したものです。

Step4: ポータルに配置

  1. ポートレットを作成したら、ポータルに配置します（参考：ポートレットを配置する）。
  2. ポータルに配置したら公開設定を行います（参考：ポータルを公開する）。

コードの解説

コードは長いですが、ほんどがグラフに必要なデータを生成している処理です。
このコードでポイントとなる2点を説明します

Garoon REST API を使って、条件に一致する予定を取得する

45行目〜58行目の getSchedules 関数 は、ポータル画面の読み込みが完了した時に呼び出されます。
ポータルからスケジュールの予定を取得するには、Garoon REST API の予定の一覧取得 APIを実行します。
またスケジュールのカスタマイズと同じく、Garoon 上で実行するので、Garoon REST APIリクエストを送信する API を使っています。

  • REST API の URL パス： /api/v1/schedule/events
  • メソッド：GET
  • APIに渡すデータ：絞り込み条件
    orderBy は並び順、rangeStart / rangeEnd は取得する予定の日時の範囲です。
予定の取得に成功したら、取得した予定を元にグラフを生成する

さきほどの getSchedules 関数は、ポータル画面の読み込みが完了した時に呼び出されます（374行目〜376行目）。
getSchedules 関数では Promise が返却されます。
正常に実行できたら .then の引数で指定した関数の処理を実行し、エラーが発生したら .catch の引数で指定した関数の処理を実行します。 

動作確認

  1. スケジュールのカスタマイズ - 動作確認の手順にしたがって、会議の終了を行った予定を作成します。
  2. ポートレットを配置したポータルを開きます。
  3. ポータルにグラフが表示されていることを確認します。

おわりに

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

利用している Garoon API

利用しているライブラリ

  • jQuery v3.1.1, ドキュメント（外部サイト）
    HTML要素の生成や操作を楽に扱うことができるライブラリです。
    スケジュールのカスタマイズでは、改善成果を表示する HTML 要素の作成や予定の詳細画面への挿入などに利用しています。
  • Moment.js v2.15.1, ドキュメント（外部サイト）
    日付の加算などの日付操作やフォーマットを楽に扱うことができるライブラリです。
    ポータルのカスタマイズで、直近7日の予定を取得する処理で現在時刻から1週間前の日付の計算などに利用しています。
  • Chart.js v2.2.2, ドキュメント（外部サイト）
    グラフを生成や表示するライブラリです。
    ポータルのカスタマイズで、ポートレットに表示する、直近1週間の改善成果を棒グラフや複合グラフの生成や表示に利用しています。
  • Font Awesome v5.5.0, ドキュメント（外部サイト）
    Web アイコンフォントを表示するスタイルシートのライブラリです。
    ポータルのカスタマイズで、ポートレットのタイトル部分のチェックボックスマークに利用しています。
  • Garoon html/css/image-Kit for Customize, ドキュメント
    ボタンなどの UI パーツをGaroon の見た目に調和させるスタイルシートのライブラリです。
    スケジュールのカスタマイズで、予定の詳細画面に追加した「会議を終了する」ボタンに利用しています。

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

 

記事に関するフィードバック

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

サインインしてコメントを残してください。