【Garoon REST API】スケジュールで受付管理業務を実現する

はじめに

今回は、スケジュールのカスタマイズにより、「受付管理業務」を実現します。

想定するシナリオは次のとおりです。

1.「応対ユーザー」がお客様の来訪予定を登録する。
2. お客様が定刻に来社する。
3.「受付ユーザー」は、来訪予定からお客様のアポイントを確認する。
4.「受付ユーザー」は、お客様の来社を「応対ユーザー」へ通知する。
5.「応対ユーザー」は、通知を確認し、お客様と面会

受付管理業務を実現する上での要件は次のようなものでしょう。

• 受付ユーザーがその日に来訪予定を一覧等で簡単に確認できる
• 応対ユーザーへの来訪通知が簡単に行える

これらの Garoon で実現するために、次のような機能を作りこんでいきます。

• 受付ユーザーが来訪者を確認できるよう、打ち合わせ参加者として受付ユーザーを強制的に自動設定する機能
• 受付ユーザーを参加者として含む、当日の来訪予定を一覧表示する機能（ポータル）
• 簡単なクリック操作で来訪を通知する機能（コメント登録による通知）
• その他便利機能（関連情報の照会、来訪登録の取消等）

前提事項と注意事項

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

完成イメージ

スケジュールとポートレットのカスタマイズで受付管理業務を実現します。

予定登録／編集時

受付ユーザーのポータル

スケジュールの詳細

リソースの準備

受付ユーザーの定義

受付ユーザー情報は、ファイル管理に配置することにより、ポータル、スケジュールの双方から共有できるようにします。

1. 受付ユーザーとして使用するユーザーの情報を確認します。
   まず、Garoon システム管理画面の [各アプリケーションの管理] > [メール] > [ユーザーアカウント] をクリックします。
   
   • ログイン名：cybozu.com 共通管理の「ユーザーの管理」の[組織/ユーザー]をクリックし、ログイン名を確認します。
     
   • ユーザーID：該当するユーザーをクリックし、「ユーザーアカウント一覧」画面の URL を確認します。
     URL の uid=数字 の数字部分がユーザー ID です。
     
     
     
2. 次のサンプルコードをテキストエディターに貼り付けます。3行目と5行目を、1. で確認した内容に置き換えます。
   ファイル名を「attendee.js」、文字コードを「UTF-8」で保存します。 上記画面を例とすると、記載内容は次のようになります。
   ※ サンプルのため、受付ユーザーの定義はグローバル変数を使用しています。実運用の際は、CSV ファイルでの管理に変更するなどを推奨します。

ライブラリー

• jQuery
  1. https://github.com/jquery/jquery/releases/tag/3.6.0 にアクセスします。
  2. 「Assets」の「Source code(zip)」をクリックし、zip ファイルをダウンロードします。
  3. zip ファイルを解凍します。
  4. 「dist」フォルダー内の jquery.min.js を利用します。
• SweetAlert2
  1. https://github.com/sweetalert2/sweetalert2/releases/tag/v11.0.16 にアクセスします。
  2. 「Assets」の sweetalert2.min.js と sweetalert2.min.css をクリックし、ファイルをダウンロードします。
  3. ダウンロードした sweetalert2.min.js と sweetalert2.min.css を利用します。
• Moment.js
  1. https://github.com/moment/moment/releases/tag/2.29.1 にアクセスします。
  2. 「Assets」の「Source code(zip)」をクリックし、zip ファイルをダウンロードします。
  3. zip ファイルを解凍します。
  4. 「min」フォルダー内の moment.min.js と moment-with-locales.min.js を利用します。
• Garoon html/css/image-Kit for Customize
  1. https://github.com/garoon/css-for-customize にアクセスします。
  2. [Code]ボタン >「Download ZIP」を選択し、zip ファイルをダウンロードします。
  3. zip ファイルを解凍します。
  4. 「css」フォルダー内の grn_kit.css を利用します
• css for SweetAlert on Garoon
  1. https://github.com/garoon/css-for-SweetAlert にアクセスします。
  2. [Code]ボタン >「Download ZIP」を選択し、zip ファイルをダウンロードします。
  3. zip ファイルを解凍します。
  4. 「css」フォルダー内の sweetalert_button_grn.css を利用します

カスタマイズの適用

スケジュール参加者自動設定機能

1. 次のサンプルコードをエディタにコピーして、ファイル名を「add-attendee.js」、文字コードを「UTF-８」で保存します。
   ※ ファイル名は任意ですが、ファイルの拡張子は「js」にしてください。
2. スケジュールにカスタマイズグループを追加し、JavaScript / CSSによるカスタマイズを適用します。
   カスタマイズグループを追加する手順は、スケジュールのカスタマイズ を参照してください。
   
   適用するファイルおよびリンクは次のとおりです。
   
   • JavaScript カスタマイズ
     
     • jQuery：ダウンロードした jquery.min.js
     • 受付ユーザー定義：作成した attendee.js
     • スケジュール参加者自動設定機能：作成した add-attendee.js
   • CSS カスタマイズ: 
     • Garoon html/css/image-Kit for Customize：ダウンロードした grn_kit.css
       
   
   カスタマイズグループを追加した後の画面は、次のようになります。
   

来訪予定ポートレット

1. 次のサンプルコードをコピーして、HTML ポートレットを作成します。
   ポートレットを作成する手順は、HTML ポートレットの設定 - ポートレットの作成 を参照してください。
2. 次のサンプルコードをエディタにコピーして、ファイル名を「attendee-portlet.js」、文字コードを「UTF-８」で保存します。
   ※ ファイル名は任意ですが、ファイルの拡張子は「js」にしてください。
3. 作成したポートレットに、JavaScript / CSSによるカスタマイズを適用します。
   カスタマイズを適用する手順は、ポータルのカスタマイズ を参照してください。
   
   適用するファイルおよびリンクは次のとおりです。
   
   • JavaScript カスタマイズ
     
     • jQuery：ダウンロードした jquery.min.js
     • SweetAlert2： sweetalert2.min.js
     • Moment.js：ダウンロードした moment.min.js と moment-with-locales.min.js
     • 受付ユーザー定義：作成した attendee.js
     • 来訪予定ポートレット：作成した attendee-portlet.js
   • CSS カスタマイズ: 
     • SweetAlert2：ダウンロードした sweetalert2.min.css
     • Garoon html/css/image-Kit for Customize：ダウンロードした grn_kit.css
       
     • css for SweetAlert on Garoon：ダウンロードした sweetalert_button_grn.css
   
   カスタマイズを適用した後の画面は、次のようになります。
   
    
4. 作成したポートレットをポータルへ配置します。
   
   ※ ポートレットへのアクセスは、適宜アクセス権を設定してください。
   例：My ポートレットでの利用を許可しない、ポートレットを配置したポータルへのアクセスを受付ユーザーのみに限定する、ポートレットへのアクセスを受付ユーザーのみに限定する、など。

解説

利用しているライブラリー

• jQuery v3.6.0, ドキュメント
  • ボタンやクリックイベントの登録などに利用しています。
• SweetAlert2 v11.0.16, ドキュメント
  • 来訪予定リストポートレットで、対応連絡を行う際のコメント入力ダイアログで使用しています。
• Moment.js v2.29.1, ドキュメント
  • 来訪予定リストポートレットで、日時のフォーマット等、日付操作をカンタンにするために使用しています。
• Garoon html/css/image-Kit for Customize
  • Garoon ライクな UI で表示するためのライブラリーです。スケジュール参加者自動設定機能の「対応完了」ボタンや、来訪予定リストポートレットの表示で利用してます。
• css for SweetAlert on Garoon
  
  • Garoon で SweetAlert2 を利用するとき、レイアウト崩れを防ぐ css です。

スケジュール参加者自動設定機能

サンプルコード 13 行目では、「受付ユーザー」を追加する予定メニューを定義しています。
「来訪」以外の予定メニューで「受付ユーザー」を追加したい場合、変更してください。

15 行目では、受付を完了したときタイトルに付ける文言を定義しています。適宜変更してください。

27 行目では、予定の登録画面の保存実行前イベント、予定の変更画面の保存実行前イベント を使用しています。

30~33 行目では、選択された予定メニューが「来訪」のとき、「受付ユーザー」を予定の参加者に追加します。

このカスタマイズでは、受付処理済みのスケジュールかどうか、カスタム項目（Schedule datastore）を利用して管理しています。
35〜45 行目では、カスタム項目（Schedule datastore）の値を取得する API を使って、このスケジュールのカスタム項目（Schedule datastore）の値を取得します。
カスタム項目の値が取得できなければ、カスタム項目（Schedule datastore）の値をセットする API を使って初期値を設定します。

54 行目では、予定の登録画面が表示されたときのイベント を使用しています。
既存のスケジュールを再利用した場合、タイトルへの付加された【受付対応済み】の文言やカスタム項目での受付処理済みかのフラグが設定されたままなので、それらをクリアする必要があります。

58～74 行目がクリアを行っている箇所です。
受付処理済みのスケジュールを再利用して新規スケジュールを作成した場合、カスタム項目（Schedule datastore）の内容も引き継がれ、受付処理済の状態で登録されてしまうため、それを防止しています。

来訪予定リストポートレット

13 行目では、リスト表示する予定メニューを定義しています。
「来訪」以外の予定を一覧に表示したい場合は変更してください。

15 行目と 17 行目は、対応連絡を行った際に更新する内容の定義です。スケジュールのタイトルに 15 行目の文言を付加し、17 行目の文言をコメントとして登録します。

90～104 行目で、予定の一覧取得（クエリで条件を指定）API を使って表示する予定を取得する処理です。
開始・終了日時が本日かつ、受付ユーザーを参加者として含むスケジュールを取得します。

106～114 行目が表示対象の スケジュールのカスタム項目（Schedudule datastore）を取得する処理です。
一覧に表示するスケジュールが受付処理済みかを取得しています。

127〜140 行目は、スケジュールにコメントを投稿する処理です。
コメント登録 は SOAP API を利用するため、jQuery の ajax 関数を利用して HTTP リクエストを送信します。

142 行目から、対応連絡登録するためのダイアログを作成しています。

167～190 行目が受付処理済み登録を行う処理です。
受付対応済みの処理では、スケジュールを更新する API を使ってスケジュールのタイトルを更新し、カスタム項目（Schedule datastore）の更新 API を使って、受付処理済みを設定します。
これらの API は REST API なので、Garoon REST API リクエストを送信する API を使って、HTTP リクエストを送信します。

205 行目から、画面の読み込みが完了した際に発火するイベントを定義しています。来訪予定リストを表示します。

206～217 行目で、予定を取得とカスタム項目（Schedule datastore）を取得しています。
予定の取得 API は予定メニューで絞り込めないため、予定を取得したあとに絞り込みます。

218～247 行目で、スケジュールをリストに出力します。

258～267 行目は、「対応連絡」ボタンをクリックした際のイベント処理です。クリックされたスケジュールの ID、タイトルを元に、コメント登録ダイアログを表示します。

269～280 行目が表示対象のスケジュールを切り替えるためのイベント処理です。押されたボタンによって、その日のすべての来訪予定あるいは未処理の予定を表示します。

おわりに

ぜひ、自社の受付業務への適用が可能か検討の上、活用してみてください。

API を利用したカスタマイズにより、Garoon の利便性はさらに向上できます。今後も Tips を定期的に公開していきますので、ご期待ください。

変更履歴

• 2021年6月9日
  • スケジュールの付加情報の保存先を、カスタム項目（additionalItems）からカスタム項目（datastore）に変更するなど、サンプルコードの修正を行いました。
    この修正で、利用しているライブラリーやリソースの適用先の変更を行っています。
    カスタム項目（additionalItems）を利用するカスタマイズを Garoon に適用している場合は、リソースの準備を参考に、カスタマイズを再適用してください。

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