Webhookで関連レコードの集計をするカスタマイズ

kintoneの機能である「関連レコード一覧」、便利ですよね! この機能を使うとあるレコードをもとに、そのレコードに関連するレコードの一覧を見ることが出来ます。

Customineのカスタマイズでは、この関連レコードを集計することが簡単に出来ます。例えば「関連レコード一覧を集計する」などを参考にしていただければと思います。

例えば以下のように「セミナー」アプリと「参加者」アプリがあり、セミナーアプリ側から、その参加者一覧として関連レコードを表示しているようなケースです。

「セミナー」アプリに対するカスタマイズで、セミナーの情報を更新した際に「申込数」などのフィールドを集計することが出来ます。

これらの集計は便利なのですが、関連レコード一覧で設定した「参照するアプリ」側のレコードが更新された場合(ここでは参加者アプリ)に、これらの集計が実行できないという問題があります。 そこでこのカスタマイズでは、Webhookを利用して関連レコードの集計を実現してみようと思います。

まずはじめにやること

Job RunnerでkintoneのWebhookや定期実行タスクのカスタマイズを作成する前に、まず「ジョブへのスロット割り当てについて」を実施する必要があります。

(既に一度割り当ててある方は不要です)

これは、利用中のアプリスロットをどの程度Job Runnerで利用できるようにするか、という設定になります。

詳しくは Job Runnerを利用するとき、初めにすること : ジョブへのスロット割り当てについて をご確認ください。

カスタマイズの種類について

gusuku Customine で作成できるカスタマイズには、以下の種類があります。

  • kintone アプリのカスタマイズ : ユーザーの画面操作に連動した処理

  • Webhook のカスタマイズ : kintone の Webhook に連動して実行する処理

  • 定期実行タスク : 毎日xx時、1時間おき など定期的に実行する処理

こちらの記事では、Webhook のカスタマイズを作成します。


Webhookカスタマイズの概要

今回作成するカスタマイズは、このような流れで作ってみようと思います。

  • 「参加者アプリ」にレコードが追加(更新)された時のWebhookにより、起動

  • 上記レコードをもとに、「参加者アプリ」から同じセミナーに参加する参加者すべてを取得

  • 各種集計を実行

  • 「セミナー」アプリの、申込みがあったセミナーのレコードを更新

それでは進めていきましょう。

利用するアプリの概要

利用するアプリは単純化のため、最小限のフィールドを用意しました。

「参加者アプリ」には、以下のように氏名や参加するセミナーなどの情報と、アンケート項目が2点「役職」と「kintoneの導入状況について」というフィールドがあります。このアンケート項目の2点を、セミナー申込数とともにあとで集計してみたいと思います。

「セミナーアプリ」はこのようになっています。

定員や残数といった必要な情報とともに、参加者の関連レコード一覧があります。 この関連レコード一覧を集計した内容として、「申込数」「役職分布(割合で表示しています)」「導入状況(平均導入UU数概算)」などの集計項目を設置しました。

APIトークンの設定

フォームの作成の後は、各アプリにAPIトークンを設定しておきます。


「参加者アプリ」からはレコードを読み込むだけなので「レコード閲覧権限」を、「セミナー」アプリには集計結果を書き込みますので「レコード閲覧」と「レコード編集」を、それぞれアクセス権として設定しておいてください。


APIトークンについては、以下の点にご注意ください。


  • APIトークンに付与する権限は、よく検討し必要最小限のものを付与するよう心がけてください。

  • 生成したAPIトークンは取扱に注意し、第三者に知られないようにしてください。


Webhookの作成

上記の2つのアプリを使って、カスタマイズを作成していきます。

新規のカスタマイズ作成から「kintoneアプリのWebhook」を選択します。

続いて、どのアプリ用のWebhookを作成するかを選択します。ここでは「参加者アプリ」のWebhookとして作成しますので、「参加者アプリ」を選択して作成を開始します。

まずは「kintone接続設定」

初期状態では、kintone 接続設定を行う と Webhook を開始した時という条件がセットされています。

これはWebhookカスタマイズでの定番のパターンです。レコードを取得したり更新したりと、kintoneアプリに接続するためには必ずAPIトークンの設定が必要です。

今回は、2個のアプリを操作しますので、接続設定を2つ設定しています。

次に「Webhook から渡されたレコードを取得する」

次に、「Webhook から渡されたレコードを取得する」を使用します。これで、Webhookが実行されたアプリのレコードを取得しています。

このレコードの中身を使って、各アプリからレコードを取得し、それをもとに集計を実行してみます。

Webhookで申込が合ったセミナーと、同じセミナーに申し込んでいる参加者の一覧を取得してみます。

集計・更新するためのレコードを取得

レコードを取得する方法はいくつかありますが、ここでは簡単に「キーを指定してレコードを取得する」を使っています。 注意すべき点は、取得元アプリと、APIトークンの対応を間違えずに設定することです。はじめに設定した「kintone接続設定」とkintoneアプリの対応を、間違えないようにしてください。

アクションの7番では、「参加者アプリ」から同じセミナーに参加した参加者のレコードを取得しています。

アクションの8番では、申し込まれたセミナーの集計結果を書き込むために、「セミナー」アプリレコードを取得しています。後者は1行だけ更新するので、「最大取得件数」のパラメーターを1に設定しています。

ここで注目していただきたいのは、8番の「レコード全行が準備できた時」という条件です。

Job Runnerのジョブでは、大量のレコードを順次処理することが多いので、レコードを取得したときに実行するための条件が以下の2種類用意されています。

「レコード1行が準備できた時」では、文字通り1つずつ順次レコードを処理する方法です。「レコード全行が準備できた時」では、対象となるレコードをすべて取得してから「やること」を実行する条件になります。 

使い分けとしては、基本的には「1行が準備できた時」のご利用をおすすめします。ただ、レコード数が少ない場合、もしくは今回のケースのようにレコード全体の数などの集計を行いたい場合には、「全行が準備できた時」をご利用ください。

「全行が準備できた時」は、数十〜数百行単位のレコードであれば特に問題はありませんが、これを例えば数万件あるレコードに対して実行してしまうと、時間(=コスト)が非常にかかるものの、結局メモリ不足などでエラーになり、ジョブが実行出来ませんので、気をつけてください。

今回は、参加者全体の数を知りたいので、「レコード全行が準備できた時」を利用しています。

レコードの集計

取得したレコードを集計するやることも、いろいろあります。 ここでは「レコード行数をカウントする」と「レコード中の条件に合う行数をカウントする」を使ってみました。

アンケートで各項目の選択内容をカウントするために、「レコード中の条件に合う行数をカウントする」を使用しています。

アクションの10番・11番以降は、各役職項目ごとに、集計の条件を変えたものをいくつも追加しています。集計している項目数が多いので、アクション数も多いのですが、条件を変えてカウントしているだけで、内容はほぼ同じです。

ここまでで、集計は完了しました。あとはこれをレコードにセットするだけです。

集計結果をフィールドにセット

このようにいろいろな値を集計したときには、「フィールド値をまとめてセットする」を利用するのが便利です。

まず「役職分布」のグループですが、ここでは各役職を%で集計するフォームになっていますので、「選択された件数 ÷ 申込数 × 100」で割合を計算しています。 具体的には以下のような式を書いています。

= $7 / $6 * 100

一方、「導入状況(平均導入UU数概算)」の集計では、「選択された項目 × 人数 ÷ 申込数」という計算をしています。大変大雑把な計算ですが、各参加者のおおよその導入ユーザー数が計算されていることになります。

設定は以上で完成です。kintoneに登録して、実際に実行してみましょう。

レコードの保存は?

フィールドに値をセットしただけで、保存されないのではないか?と思われるかもしれませんが、ご安心ください。保存は自動で実行されます。


kintoneから取得してなにか値がセットされたレコードは、ジョブの最後にまとめて保存されます。 基本的にはレコードの保存を自分で考慮する必要はありません。

Webhook を kintoneアプリに登録

作成したカスタマイズを実行するには、画面上部の黄色い「ジョブ生成・設定」ボタンをクリックしてください。ジョブが生成され、ダイアログが開きます。詳しい使い方についてはこちらのページをご確認ください。

ここで表示されているURLを、kintoneアプリの設定の中にある、Webhookに登録します。

今回は、参加者アプリにレコードが追加されたときにこのWebhookを実行したいので、「通知を送信する条件」としては「レコードの追加」を選択しておいてください。

この設定を保存して、「アプリを更新」した後、このアプリにレコードを追加してみてください。

ジョブ設定ダイアログの「実行履歴」ボタンをクリックして、左上のリロードボタンで履歴の更新をしてください。

こちらの実行履歴に上がってこない場合、エラーになっている可能性がありますので、kintone側のWebhookログをご確認ください。

まとめ

以上でkintoneのWebhookで、関連レコードを集計する簡単なカスタマイズのご紹介を終わります。Webhookを起点として、簡単にkintoneのレコードを集計できることを、ご確認いただければと思います。


Job Runnerでのレコードの更新は簡単に出来る分、思いもよらない大量のレコードを、意図しない内容で更新したりすることも可能です。 カスタマイズ作成の際には、テストアプリとテストデータでよくテストの上、実際のアプリに適用していくことをおすすめします。