2019/05/12 メンテナンスで追加される Garoon API の紹介

Moment.js はメンテナンスモードになり、日付処理できる代替ライブラリへの移行が推奨されています。
代替ライブラリのひとつ Luxon については、kintone カスタマイズでの導入方法の紹介記事があります。

はじめに

2019/05/12の定期メンテナンスのお知らせ で告知した Garoon の5月アップデートで、 Garoon API が複数追加されます。

この記事では、追加される Garoon API のうち、次の API を使ったカスタマイズ例を紹介します。

• ファイルキーから画像 URL を取得する（画像アセット）
• 「予定の登録」「予定の変更」画面の登録/変更実行前イベント（スケジュール）

ファイルキーから画像 URL を取得する（画像アセット）

画像アセット

「画像アセット」は、画像ファイルを Garoon の共有リソースとして保存する機能です。

画像アセットでは、画像ファイルをファイルキーと一緒に登録します。
そのあと、利用したい画像のファイルキーを指定しファイルキーから画像URLを取得する API を使うと、画像の URL を取得できます。

「画像アセット」を使うメリット

これまで、Garoon のカスタマイズで画像を使う場合、「ファイル管理」アプリケーションに画像ファイルを保存していました。
そして、保存した画像ファイルのアドレス情報（URL）を右クリックで確認し、カスタマイズファイルの画像 URL を書き換える必要がありました。

しかし、今回のアップデートで追加された「ファイルキーから画像URLを取得する API」を使うと、
画像アセットに登録した画像ファイルのURLを自動で取得できるので、カスタマイズファイルの画像ファイルURLを書き換える必要がありません！

これにより、カスタマイズの手順は下図のようにぐっと簡略化されます。

「画像アセット」を使ったポータルカスタマイズ

完成例

スケジュールに登録された、自分の予定と施設を表示するポートレットを作ります。
このポートレットでは、いまの予定や30分以内の次の予定について、予定名や時間、施設の画像を表示します。

カスタマイズ手順

手順 1.「画像アセット」に画像ファイルを登録する

ポートレットに表示する施設の画像ファイルを準備し、「画像アセット」アプリケーションに追加します。

1. [Garoon システム管理] から、[各アプリケーションの管理]タブを選択し、[画像アセット]を選択します。
2. [画像アセット一覧]を選択し、[画像アセットを追加する]をクリックします。
   
3. 「画像アセットの追加」画面で、[ファイルを添付]をクリックし、施設の画像ファイルを指定します。
   次のように入力します。
   
   
   

   項目名	値
   ファイルキー	ファイルキーから画像URLを取得する API で画像を指定するためのキーです。 今回のカスタマイズでは、施設情報の施設コードをキーに画像を指定するので、ファイルキーには「施設コード」を入力します。 ※「施設コード」の確認は、[Garoon システム管理] > [各アプリケーションの管理] > [スケジュール] > [施設/施設グループ] で確認できます（参考：施設を管理する）

4. [追加する]ボタンをクリックします。
5. 同様の手順で、ポートレットに表示する施設の画像ファイルすべてを、画像アセットに登録します。

手順2. カスタマイズファイルの準備

今回のカスタマイズでは、次の2つのカスタマイズファイルを利用します。
また、カスタマイズファイル内では、Cybozu CDN に公開されている Moment.js と jQuery を利用しています。

• カスタマイズファイル
  • ポートレットを表示する JavaScript ファイル（next_room_main.js）
  • ポートレットに適用する css ファイル（next_room.css）
• 外部ライブラリ
  • Moment.js 2.10.3
    https://js.cybozu.com/momentjs/2.10.3/moment-with-locales.min.js
  • jQuery 3.3.1
    https://js.cybozu.com/jquery/3.3.1/jquery.min.js

 カスタマイズファイル

• ポートレットを表示する JavaScript ファイル（next_room_main.js）
  Garoon の予定を取得し、予定から HTML を生成するスクリプトファイルです。
  • 今回のポイントは、95行目の「garoon.assets.images.getUrl(facility.code) 」です。
    garoon.assets.images.getUrl は、画像アセットに登録された画像について、ファイルキーから画像URLを取得する API です。
    さきほど画像アセットに登録するとき、ファイルキーに「施設コード」を設定しました。
    そのため、API に「施設コード」を指定し、施設の画像URLを取得しています。
• ポートレットに適用する css ファイル（next_room.css）
  ポートレットに適用するスタイルシートファイルです。
  

手順3. カスタマイズの適用

1. [Garoon システム管理] から、[各アプリケーションの管理]タブを選択し、[ポータル]を選択します。
2. [HTMLポートレット]を選択し、[HTMLポートレットを追加する]をクリックします。
3. 次のように入力します。HTMLポートレット設定の詳細は、「HTMLポートレットの設定」をご参照ください。
   

   項目名	値
   ポートレット名	ポートレット名を入力します。 今回は「次の予定ポートレット」としました。
   グループ	適宜設定してください。
   Myポータル	適宜設定してください。
   ポートレットの内容	「テキスト」を選択し、次の内容を入力してください。 <div class="next_room"> </div>

4. 入力が完了したら、[追加する]ボタンをクリックし、ポートレットを追加します。　
5. HTMLポートレットの一覧から、先ほど追加したポートレットを選択します。
6. [JavaScript/CSSによるカスタマイズ]をクリックします。
7. 次のように入力します。入力後、[設定する]ボタンをクリックします。
   
   
   

   項目名	値
   カスタマイズ	適用する
   JavaScript カスタマイズ	次の順でリンクおよびファイルを追加します。 https://js.cybozu.com/momentjs/2.10.3/moment-with-locales.min.js https://js.cybozu.com/jquery/3.3.1/jquery.min.js ポートレットを表示する JavaScript ファイル（next_room_main.js）
   CSS カスタマイズ	次のファイルを追加します。 ポートレットに適用する css ファイル（nextRoom.css）

8. 追加したポートレットをポータルに追加します。
   ポータルへの追加方法は「ポートレットを配置する」をご参照ください。

手順は以上です。

「予定の登録」「予定の変更」画面の登録/変更実行前イベント（スケジュール）

「「予定の登録」画面や「予約の変更」画面で、「登録する」または「変更する」ボタンをクリックした後に発生するイベントです。
（参考：「予定の登録画面の保存前イベント」「予定の変更画面の保存前イベント」）
このイベントによって、「入力内容のエラーチェック」や「定例ミーティングの場合はメモ欄にアジェンダのテンプレートを追加する」といった処理ができるようになりました。

※2019年5月現在、このイベントは Promise 対応していません。そのため、非同期処理の実行を待ってから登録または変更処理の実行はできません。

「予定の登録画面/予約の変更画面の登録前実行イベント」を使ったカスタマイズ例

完成例

予定を登録するときうっかり施設を設定し忘れて、当日打ち合わせする場所がない！となってしまったことはありませんか？
そんなうっかりミスを防ぐため、予定の登録または変更時に、施設の指定がなければエラーにするカスタマイズをご紹介します。

カスタマイズ手順

手順1. カスタマイズファイルの準備

今回のカスタマイズでは、次のカスタマイズファイルを利用します。

• カスタマイズファイル
  • 施設の設定有無をチェックする JavaScript ファイル（check_set_facility.js）

カスタマイズファイル

• 施設の設定有無をチェックする JavaScript ファイル（check_set_facility.js）
  Garoon 予定の登録または変更時に、施設が設定されていなければエラーにして予定を登録させないスクリプトファイルです。
  • 今回のポイントは、9行目と11行目です。
    • エラーダイアログを表示し予定を登録（変更）させないようにするには、event オブジェクトのエラープロパティに、表示したいエラーメッセージを設定します。
      今回は、施設の設定がされていない場合、つまり施設に関するプロパティの長さが0なら、エラープロパティに値を設定します。
    • 最後に event オブジェクトを返却して event の内容を Garoon に反映させます。

手順2. カスタマイズの適用

1. [Garoon システム管理] から、[各アプリケーションの管理]タブを選択し、[スケジュール]を選択します。
2. [JavaScript/CSSによるカスタマイズ]を選択し、[カスタマイズグループを追加する]をクリックします。
3. 次のように入力します。入力後、[追加する]ボタンをクリックします。
   
   
   

   項目名	値
   カスタマイズ	適用する
   カスタマイズグループ名	カスタマイズグループ名を入力します。
   適用対象	カスタマイズを適用したい対象（ユーザー、組織またはロール）を選択します。
   JavaScript カスタマイズ	カスタマイズファイルを追加します。 施設の設定有無をチェックする JavaScript ファイル（check_set_facility.js）
   CSS カスタマイズ	なし

手順は以上です。

おわりに

2019年5月の定期メンテナンスで、Garoon API が複数登録され、Garoon カスタマイズの幅が広がりました。

この記事で紹介しているAPI 以外にも、ワークフローのフィールドを編集可/不可に設定できたり、在籍情報を取得・更新できる API なども追加されています。

これからも Garoon API は追加される予定なので、Garoon カスタマイズに挑戦して、運用に合わせてより使いやすくしていただければと思います。

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