はじめに

こんにちは。TIGの町田です。

Zuora Central Platform（Zuora社が提供するサブスクリプションプラットフォーム名の正式名称/以降 Zuora と記載いたします）の連載の第3回は、Notification(以後、通知機能)とイベントトリガー(EventTrigger)についてのお話です。

通知機能はZuora上の様々なイベントをトリガーに、メール通知やコールアウトによる通知・連携が行えます。業務フローを設計する際には、必ず理解しておく必要がある機能になるかと思います。通知機能についての概要やできること、設定方法について解説していきます。

過去のZuora記事はこちらを参照ください。

概要

通知機能は、イベント定義＋Notification(通知)の組み合わせで設定します。

イベント定義: カスタムイベントトリガーで後述するが、Zuora上でのオペレーションによって起こるオブジェクトなどの登録・更新・削除をトリガーとして後続の処理（通知）を行うための定義のこと
Notification(通知): イベント定義のトリガー発火を受けて、メール送信やコールアウトによるAPI呼び出しを行うための機能のこと

※上記シーケンス図補足

Process	Comment
1. Operation	UserによるZuoraへのなんらかの操作(UI, API, Batchなど)が発生
2. Polling	特定の操作やオブジェクトに対する変更を監視
3. Event fire	イベント発火による通知機能の実行
4. Call/Send	メール通知やCalloutの呼び出し

ロジックによる制御を挟みたい場合は、通知機能からWorkflowを呼び出すことで実現できます。

利用場面は以下のようなケースです。

コールアウトAPIに設定するリクエスト形式がネストしているなど、コールアウトAPIの設計に合わせたリクエストが、通知機能からのコールアウトだけではできない場合
イベント定義からのパラメータだけではできないデータの取得・加工を行いたい場合

※上記シーケンス図補足

Process	Comment
1. Operation	UserによるZuoraへのなんらかの操作(UI, API, Batchなど)が発生
2. Polling	特定の操作やオブジェクトに対する変更を監視
3. Event fire	イベント発火による通知機能の実行
4. Call Workflow	NotificationからWorkflow呼び出し～Workflowsにてロジックによる処理実行
5. Call/Send	Workflow内でのメール通知またはCalloutの呼び出し

設定方法

Zuoraログイン後の右上ユーザメニューを開き、請求を選択します
請求メニューでプロファイル、通知、およびメールテンプレートのセットアップを選択します
通知設定画面に遷移する。ここで通知の確認や追加・編集・削除を行う。新しい通知を作成する場合は、新しい通知の追加ボタンをクリックします
新しい通知の作成モーダルが開くので、まず初めに関連イベントを選択します
- 関連イベント: 通知を発火する条件のこと。デフォルトで用意されているイベントやカスタムイベントを選択する
- 有効: このチェックボックスにチェックしておかないと、通知機能が有効とならない
プルダウンで関連イベントを選択すると、イベントパラメータや配信オプションが設定できます

イベントパラメータ: 項目は選択した関連イベントによって異なる。イベントの細かい条件などを設定します
配信オプション: メールとコールアウトが選択可能。メールを選択した場合は、どのメールテンプレートを使用するか選択する。メールテンプレートは予め別画面にて作成しておく必要がある。そのメールテンプレートにて設定したアドレスに対して通知が送信される。詳細は後述。コールアウトでは、イベントを受けて配信したいURLに対して、イベントに関連したパラメータを付与してリクエストが可能。詳細は後述。

メールテンプレート

通知機能で使用可能なメールのテンプレートは、デフォルトで用意もされているが、新しく追加できます。メール本文には、関連イベントから受け取ったパラメータ等の差し込みが可能です。

通知設定画面にてメールテンプレートタブを選択します
メールテンプレートリスト画面に遷移択します。ここではテンプレートの追加・編集・削除ができる。テンプレートを新しく追加したい場合は新規メールテンプレートの追加をクリック択します
テンプレート編集画面

基本情報:: テンプレート名・関連イベントを設定択します。ここで選択した関連イベントに関係するパラメータを差し込みフィールドとしてメール本文に利用できる
メール情報: 差出人や宛先を設定可能

テンプレート本文

利用可能な差し込みフィールド: メール本文に差し込むフィールドのタグが確認可能です。関連イベントを選択すると、そのイベントに関連したパラメータが選択できるようになります
件名: メールの件名を設定。ここでも差し込みフィールドの利用は可能です
本文: フォーマットはHTMLかプレーンテキストを選択できます

コールアウト

コールアウトとは、外部WebサービスのAPIのコール、HTTP要求を送信して応答を受信することです。

コールアウトの設定画面:

呼び出すCalloutのURLを設定。Workflowを呼び出す場合は、Workflow設定画面で確認できるURLを設定します
パラメータ: ここで選択可能なパラメータは、選択したイベントに関連したパラメータのみが選択可能。ネストしたパラメータはできない
HTTPメソッド: POST,PUT,GET,DELETEが選択可能
再試行: チェックした場合、コールアウトの呼び出しエラー時に再試行を行う
ユーザ名/パスワード/ドメイン: Basic認証またはNTLM認証のみが選択可能。より安全な認証を利用したい場合は、WorkflowのCalloutで行うことができるため、Workflowを挟む必要がある
プレビュー: プレビューボタンをクリックすると、実際に送信するリクエストやヘッダ等の確認ができる

カスタムイベントトリガー

通知機能にて利用可能なイベントは、デフォルトで用意されているイベント以外に、カスタムで追加可能です
イベントトリガーはZuoraAPIを利用してのみ登録・更新・削除が可能です
- イベントはZuoraのオブジェクト単位で設定が可能です
- 設定が可能なオブジェクトやパラメータ等の詳細は、API Reference - Developer Center - Zuoraを参照してください
- 追加すると、通機設定画面の関連イベントのプルダウンメニューに追加されます

リクエスト例:

curl --location --request POST 'https://rest.apisandbox.zuora.com/events/event-triggers' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
    "baseObject": "Subscription",
    "condition": "changeType == '\''INSERT'\'' || changeType == '\''UPDATE'\''",
    "description": "説明",
    "eventType": {
        "name": "イベント名",
        "displayName": "表示名",
        "description": "説明"
    },
    "active": true
}'

パラメータ補足:

baseObject：監視するオブジェクトを設定
- 例：Subscription
condition： baseObjectに設定したオブジェクトのトリガー条件をJEXL式で設定
- 例：オブジェクト登録・更新時にイベントをトリガー:
  changeType == 'INSERT' || changeType == 'UPDATE'
- 例：請求が1000を超えた金額で更新された場合にイベントをトリガー:
  changeType == 'UPDATE' && Invoice.Status == 'Posted' && Invoice.Status_old != 'Posted' && Invoice.Amount > 1000

最後に

通知機能はZuora上の様々なイベントを業務と繋げるためには、必ず使いこなす必要がある機能です。特にWorkflowを実行するためのトリガーとして利用することも多いでしょう。

次回はそのWorkflowについて説明します。

Zuora連載 Vol.3 Notification及びEventTriggerの話

はじめに

目次

概要

設定方法

メールテンプレート

コールアウト

カスタムイベントトリガー

最後に

関連リンク