3.2
通知

通知機能を利用することにより、eメール、SMS、push通知、Webhookなどの手段でユーザーにメッセージを送信することが可能です。

1. メール送信

CommandやListenerなどからメールを送信する機能です。 MailManagerクラスを介してメールを送信します。 送信する文面はMailTemplateとして登録・管理することが可能です。

1.1. MailTemplateの作成

MailTemplateアイコンを右クリックして「メールテンプレートを作成する」を選択してください。

1.2. 設定

テンプレートの編集

件名、文字コード(テキストメッセージ文字コード、HTMLメッセージ文字コード)、テキストメッセージ(Plainメッセージ)、HTMLメッセージを設定します。

項目 設定内容

表示名

表示名を設定します。

説明

説明を設定します。

文字コード

テキストメッセージの文字コードを設定します。 未指定の場合、メールの基本設定のデフォルトキャラクタセット(mail.charset)が設定されます。

HTML文字コード

HTMLメッセージの文字コードを設定します。 未指定の場合、文字コードと同じ値が設定されます。

Fromアドレス

標準の送信元アドレスを設定します。 詳細は送信元を参照してください。

Fromアドレス個人名

標準の送信元アドレス個人名を設定します。 詳細は送信元を参照してください。

ReplyToアドレス

標準の返信先アドレスを設定します。 詳細は送信元を参照してください。

ReplyToアドレス個人名

標準の返信先アドレス個人名を設定します。 詳細は送信元を参照してください。

ReturnPathアドレス

標準のエラーメール返信先アドレスを設定します。 詳細は送信元を参照してください。

S/MIME電子署名

S/MIMEによる署名を行う場合、チェックをいれてください。 事前に、S/MIME用の証明書(および秘密鍵)ストアに送信者のメールアドレスに対する証明書、秘密鍵が格納されている必要があります。 詳細はservice-configのMailServiceのSmimeCertStoreを参照してください。

S/MIME暗号化

S/MIMEによる暗号化を行う場合、チェックをいれてください。 事前に、S/MIME用の証明書ストアに受信者のメールアドレスに対する証明書が格納されている必要があります。 詳細はservice-configのMailServiceのSmimeCertStoreを参照してください。

件名

件名を設定します。 GroovyTemplate形式で記述します。

テキストメッセージ

テキスト形式のメッセージを設定します。 テキストメッセージとHTMLメッセージが両方設定された場合は、「multipart/alternative」形式でメールを送信します。 GroovyTemplate形式で記述します。

HTMLメッセージ

HTML形式のメッセージを設定します。 テキストメッセージとHTMLメッセージが両方設定された場合は、「multipart/alternative」形式でメールを送信します。 GroovyTemplate形式で記述します。

バインド変数の利用

件名、メッセージ内部でバインド変数を利用する場合は、メール生成処理に引数としてバインド変数を渡す必要があります。

MailManager#createMail(String tmplDefName, Map<String, Object> bindings)

また、次の変数がデフォルトでバインドされており、テンプレート内で利用可能です。

変数名 説明

mail

org.iplass.mtp.mail.Mail のインスタンス。

多言語の利用

複数の言語に対応したメールテンプレートを作成し、利用することができます。 Multilingual MailTemplateの「Add」ボタンをクリックする事で多言語用メールテンプレート作成ダイアログが表示されます。

設定項目は以下のとおりです。 その他の項目はメールテンプレートの編集と同様です。 送信時に選択される言語については送信時の言語を参照してください。

項目 設定内容

言語設定情報バインド名

この項目の設定値をバインド変数のキー、値に言語名かユーザーEntity(内部で言語プロパティを参照)をセットすることで、Mail作成時にユーザーに合わせた言語でメールを作成することができます。

例として、英語のメールテンプレートを送信する場合、言語設定情報バインド名に「sampleLangKey」と設定。 メール生成処理にて下記をバインド変数として渡します。

Map<String, Object> bindings = new HashMap<String, Object>();
bindings.put("sampleLangKey", "en");

Language

言語を設定します。

送信時の言語

送信時の言語は以下の順で決まります。

  1. 本テンプレートで指定されている言語設定情報バインド名で取得できる値
    取得した値がStringであれば、その値を言語として利用
    取得した値がユーザーEntityであれば、言語プロパティを利用

  2. テナントの言語

  3. システムのデフォルト言語

テナント

テナント情報に設定するメール送信関連の設定についてはテナント管理を参照してください。

MailService

メール送信時の基本設定はservice-configのMailServiceを参照してください。

1.3. 利用方法

メール送信処理

EntityのEventListenerを利用して、宛先を設定すればメッセージが出せます。MailManagerを利用するコード実装も可能です。 MailManagerを利用したメール送信は以下のように実装します。

import org.iplass.mtp.mail.Mail;
import org.iplass.mtp.mail.MailManager;

//メールの送信はMailManagerを利用
private MailManager mailManager = ManagerLocator.manager(MailManager.class);


private void sendMail() {

    try {
        //MailTemplateに渡すバインド変数設定(例ではtenantとuserを設定)
        Map<String, Object> bindings = new HashMap<String, Object>();
        bindings.put("tenant", tenant);
        bindings.put("user", user);

        //MailManager#createMail(メールテンプレート名, バインド変数) を呼び出し、Mailを生成
        Mail mail = mailManager.createMail("sampleMailTemplateName", bindings);(1)

        //送信先の設定(例ではTOの設定)
        mail.addRecipientTo((String)user.getValue(User.MAIL), (String)user.getValue(User.LAST_NAME) + "");(2)

        //MailManager#sendMail(Mail)を呼び出し、メールを送信
        mailManager.sendMail(mail);(3)

    } catch (RuntimeException e) {
    }
}
1 MailTemplateを利用して送信用メッセージを作成。 バインド変数とGroovyTemplate書式を利用して動的にメッセージを生成。
2 宛先を設定。 送信元の設定も可能(省略時はテナント情報から設定)
3 メールを送信。 メールサーバ情報や認証情報はserver-config.xmlで設定。

宛先

作成したMail(org.iplass.mtp.mail.Mail)に対して宛先を設定します。 宛先(TO、CC、BCC)に対してアドレスと個人名(省略可)を指定します。

項目 メソッド

TO送信アドレス

addRecipientTo(String address)

addRecipientTo(String address, String personal)

CC送信アドレス

addRecipientCc(String address)

addRecipientCc(String address, String personal)

BCC送信アドレス

addRecipientBcc(String address)

addRecipientBcc(String address, String personal)

送信元

送信時の送信者情報を設定します。 設定内容は以下の優先度で決まります。

  1. Mail

  2. MailTemplate

  3. Tenant

Mailに設定

作成したMail(org.iplass.mtp.mail.Mail)に対して、以下の項目で設定することができます。

項目 メソッド

送信元アドレス

setFrom(String address)

setFrom(String address, String personal)

setFromAddress(javax.mail.internet.InternetAddress address)

返信先アドレス

setReplyTo(String address)

setReplyTo(String address, String personal)

setReplyToAddress(javax.mail.internet.InternetAddress address)

ReturnPathアドレス

setReturnPath(String returnPath)

MailTemplateに設定

Mailに設定されていない場合は、MailTemplateに設定されている情報が設定されます。

Tenantに設定

MailにもMailTemplateにも設定されていない場合は、テナントに設定されている情報が設定されます。

ただし、ReturnPathアドレスについては、Tenantでは設定できません。 MailServiceの「mail.smtp.from」が設定されている場合はその値が利用されます。

添付ファイル

作成したMail(org.iplass.mtp.mail.Mail)に対して、以下のメソッドを利用することで添付ファイル付のメール送信が可能です。

項目 メソッド

DataHandler形式

addAttachment(javax.activation.DataHandler dataHandler)

BinaryReference形式

addAttachment(org.iplass.mtp.entity.BinaryReference bin)

2. SMS送信

SMS(ショートメッセージサービス)を利用して、携帯電話・スマートフォン宛にテキストメッセージを送信します。 送信する文面はSMSTemplateとして登録・管理することが可能です。

iPLAssではSMS送信を Twilio を利用した実装を 提供 しています。

2.1. SMSTemplateの作成

SMSTemplateアイコンを右クリックして「SMSテンプレートを作成する」を選択してください。

2.2. 設定

テンプレートの編集

テキストメッセージを設定します。

項目 設定内容

表示名

表示名を設定します。

説明

説明を設定します。

言語設定情報バインド名

この項目の設定値をバインド変数のキー、値に言語名かユーザーEntity(内部で言語プロパティを参照)をセットすることで、メッセージ作成時にユーザーに合わせた言語でメッセージを作成することができます。

例として、英語のSMSテンプレートを送信する場合、言語設定情報バインド名に「sampleLangKey」と設定。 メッセージ生成処理にて下記をバインド変数として渡します。

Map<String, Object> bindings = new HashMap<String, Object>();
bindings.put("sampleLangKey", "en");

テキストメッセージ

テキスト形式のメッセージを設定します。 GroovyTemplate形式で記述します。

多言語の利用

複数の言語に対応したSMSテンプレートを作成し、利用することができます。 Multilingual SmsTemplateの「Add」ボタンをクリックする事で多言語用SMSテンプレート作成ダイアログが表示されます。

設定項目は以下のとおりです。

項目 設定内容

Language

言語を設定します。

テキストメッセージ

テキスト形式のメッセージを設定します。 GroovyTemplate形式で記述します。

SmsService

SMS送信時の基本設定はservice-configのSmsServiceを参照してください。

2.3. 利用方法

メッセージ送信処理

EntityのEventListenerを利用して、宛先を設定すればメッセージが出せます。SmsMailManagerを利用するコード実装も可能です。 SmsMailManagerを利用したメッセージ送信は以下のように実装します。

import org.iplass.mtp.sms.SmsMail;
import org.iplass.mtp.sms.SmsMailManager;

//メッセージの送信はSmsMailManagerを利用
private SmsMailManager manager = ManagerLocator.manager(SmsMailManager.class);

private void sendMessage() {

    try {
        //SmsMailTemplateに渡すバインド変数設定(例ではtenantとuserを設定)
        Map<String, Object> bindings = new HashMap<String, Object>();
        bindings.put("tenant", tenant);
        bindings.put("user", user);

        //SmsMailManager#createMail(SMSテンプレート名, バインド変数) を呼び出し、SmsMailを生成
        SmsMail message = manager.createMail("sampleSmsMailTemplateName", bindings);(1)

        //送信元の設定
        mail.setFrom("+12345678901");

        //送信先の設定
        mail.setTo("+819012345678");(2)

        //SmsMailManager#sendMail(SmsMail)を呼び出し、メッセージを送信
        manager.sendMail(message);(3)

    } catch (RuntimeException e) {
    }
}
1 SmsMailTemplateを利用して送信用メッセージを作成。 バインド変数とGroovyTemplate書式を利用して動的にメッセージを生成。
2 送信先の電話番号を設定。国番号を付与した電話番号を指定します。
3 メッセージを送信。認証情報等はserver-config.xmlで設定。

3. プッシュ通知

モバイル端末へのプッシュ通知を行うための機能です。 繰り返し利用する通知メッセージ、タイトルなどをPushNotificationTemplateとして登録・管理することも可能です。 EntityのEventListenerを利用して、宛先を設定すれば通知が出せますが、PushNotificationManagerを利用するコード実装も可能です。

iPLAssではプッシュ通知サービスとしてFirebase Cloud Messaging(FCM) を利用したモジュールを標準提供します。サービスインタフェース(PushNotificationService)を独自実装することにより、Firebase Cloud Messaging以外のプッシュ通知サービスを利用することも可能です。

iPLAssの実装は、FCM HTTP v1 API に対応しています。

3.1. プッシュ通知の方法

プッシュ通知する場合はPushNotificationManagerのapiを利用します。
また、標準提供されている FCM を利用したモジュールを利用してプッシュ通知を行う場合は、以下の設定を行う必要があります。

  1. 当該プロジェクトに、ライブラリ iplass-googlecloud (Enterprise版は iplass-ee-googlecloud) の依存関係を追加する。

  2. mtp-service-config.xmlにて 外部プッシュ通知サービスの設定 を行う。

以下に FCM HTTP v1 API を利用するサンプルコードを示します。

import org.iplass.mtp.ManagerLocator;
import org.iplass.mtp.pushnotification.*;
import org.iplass.mtp.pushnotification.fcmv1.PushNotificationTargetType;

:
:

//プッシュ通知の際には、PushNotificationManagerを利用
PushNotificationManager pnm = ManagerLocator.manager(PushNotificationManager.class);

PushNotification pn = new PushNotification();
//通知先(RegistrationToken)を指定
pn.addTo(PushNotificationTargetType.TOKEN.getPrefixedValue("EgRo3fVLeKw6qPlo-X_Z1R:APA91bGkZ5..._gp0w")); (1) (2)
//メッセージをNotificationPayloadにて指定
pn.setNotification(
        new NotificationPayload(
                "Caution!",
                "Check your login history!",
                "ic_stat_notification"));

//送信オプションを指定
pn.getOptions().put("analytics_label", "label");

PushNotificationResult res = pnm.push(pn);

//PushNotificationResult#isSuccess()で通知成功したかどうか判断可能
System.out.println(res.isSuccess());
//PushNotificationResult#getDetails()で通知結果の詳細取得可能
System.out.println(res.getDetails());
1 通知先の指定は RegistrationToken、もしくはtopic、もしくはtopicの条件式(condition)を指定可能です。複数の通知先を設定する場合は、 addTo() を複数回実行してください。
2 FCM HTTP v1 API に対応したサービスを利用する場合、 addTo() で指定する通知先に種別を表す接頭辞が必要となります。接頭辞は下表の通りです。
FCM HTTP v1 API 利用時の通知先種別を識別する接頭辞
宛先種類 接頭辞 PushNotificationTargetType 列挙値 * 設定例

登録トークン

token:

TOKEN

token:EgRo3fVLeKw6qPlo-X_Z1R:APA91bGkZ5…​_gp0w

トピック

topic:

TOPIC

topic:weather

条件

condition:

CONDITION

condition:'foo' in topics && 'bar' in topics

* PushNotificationTargetType.TOKEN.getPrefixedValue("…​") では通知先に接頭辞を付与します。通知先の種類によって TOKEN, TOPIC, CONDITION を使い分けてください。

apiの詳細はPushNotificationManagerのjavadocを参照ください。

3.2. PushNotificationTemplateの利用

繰り返し利用する通知メッセージ、タイトルなどをPushNotificationTemplateとして登録・管理し、そのテンプレートを利用して通知メッセージを作成することが可能です。 PushNotificationTemplateはAdminConsoleにて登録・管理します。

PushNotificationTemplateの作成

AdminConsoleからNotificationカテゴリにあるPushNotificationTemplateの定義を作成します(PushNotificationTemplate → 右クリック → 作成)。

設定項目の説明

次の項目を設定可能です。

Default PushNotificationTemplateタブ

Default PushNotificationTemplateタブでは、言語設定によらない共通のメッセージを設定します。

設定項目 設定内容

タイトル

プッシュ通知のタイトルを指定します。この値は iOS のスマートフォンやタブレットには表示されません。

アイコン

通知アイコンを設定します。Androidのみ有効です。

本文

プッシュ通知のメッセージ本文を指定します。本文はGroovyTemplate形式で設定可能です。テンプレート呼び出し時にバインドされたオブジェクトを利用し、値の埋め込みが可能です。 次項に本文の記述例を示します。

ConfigScript

プッシュ通知のオプション、DataPayloadなどをGroovyScript形式で設定可能です。pnという変数名でPushNotificationのインスタンスがバインドされています。 次項にConfigScriptの記述例を示します。

本文の記述例

本文はGroovyTemplate形式で記述可能です。 次の例は、userでUserエンティティ、pointでIntegerのインスタンスがバインドされている場合を想定したものです。

${user.name}さん、
あなたのポイントは${point}ポイントです。
ConfigScriptの記述例

ConfigScriptはGroovyScript形式で記述可能です。 pnという変数名でPushNotificationのインスタンスがバインドされています。

(1)
pn.message = [
    'android': [
        'priority': 'high', (2)
        'notification': [
            'color': '#FF9900' (3)
        ]
    ],
    'apns': [
        'headers': [
            'apns-priority': '5' (2)
        ]
    ],
    'webpush': [
        'headers': [
            'Urgency': 'high' (2)
        ]
    ]
]

(4)
pn.data.score = '3x1'
1 pn.message (PushNotification#getMessage() で取得できる値) は FCM リクエストの本文の message にマッピングされます。設定値の詳細は ドキュメント を参照してください。
2 メッセージのデバイスタイプ別の優先度の設定。FCM メッセージの優先度については、ドキュメント を参照してください。
3 メッセージに追加のパラメータを設定。記載例は、Android の通知アイコンの色を指定。
4 DataPayloadの設定。DataPayload はFCM リクエストの本文の message.data にマッピングされます。
Multilingual PushNotificationTemplateタブ

Multilingual PushNotificationTemplateタブでは、言語毎のメッセージを定義可能です。

設定項目 設定内容

言語設定情報バインド名

ここに設定した値をキーとして、PushNotificationManagerに渡すバインド変数として言語キー(enやjaなど)、もしくはUserエンティティをセットすることで、受信側の設定言語にあわせた言語でのプッシュ通知が可能です。

Language

addボタンにより、言語毎にタイトル、本文を定義します。

PushNotificationTemplateを利用したプッシュ通知の方法

PushNotificationTemplateを利用してプッシュ通知する場合もPushNotificationManagerのapiを利用して行います。 また、実際にプッシュ通知を行う場合は、mtp-service-config.xmlにて外部プッシュ通知サービスの設定を正しく行う必要があります。

以下にapi利用のサンプルコードを示します。

import org.iplass.mtp.ManagerLocator;
import org.iplass.mtp.auth.AuthContext;
import org.iplass.mtp.pushnotification.*;
import org.iplass.mtp.pushnotification.fcmv1.PushNotificationTargetType;

:
:

PushNotificationManager pnm = ManagerLocator.manager(PushNotificationManager.class);

//PushNotificationTemplateに渡すバインド変数設定(例ではuserとpointを設定)
Map<String, Object> bindings = new HashMap<>();
bindings.put("user", AuthContext.getCurrentContext().getUser());(1)
bindings.put("point", 10);

//テンプレートを指定してPushNotificationを作成
PushNotification pn = pnm.createNotification("pointNotification", bindings);(2)
//通知先(RegistrationToken)を指定
pn.addTo(PushNotificationTargetType.TOKEN.getPrefixedValue("EgRo3fVLeKw6qPlo-X_Z1R:APA91bGkZ5..._gp0w"));

PushNotificationResult res = pnm.push(pn);
1 言語設定情報バインド名にuserと定義している場合、ユーザーのlanguageプロパティに設定されている値により、適切な言語のテンプレートが利用されます
2 バインド変数に与えたオブジェクトがPushNotificationTemplate定義にて参照可能となります。

apiの詳細はPushNotificationManagerのjavadocを参照ください。

3.3. mtp-service-config.xmlの設定

プッシュ通知する際には、Push通知を実際に行う外部サービスの設定を行う必要があります。

Firebase Cloud Messaging を利用する場合

Firebase Cloud Messaging(FCM)を利用する場合、mtp-service-config.xml の PushNotificationService の実装クラスとして、FCM HTTP v1 API 用の PushNotificationService を指定し設定を行います。
FCM の API リクエストに利用する認証情報を取得するため、GoogleCloudSettings の設定も必要となります。

設定例を以下に示します。

<!-- FCM HTTP v1 API を利用するための設定-->

(1)
<!-- GoogleCloudSettings -->
<service>
    <interface>org.iplass.mtp.impl.googlecloud.GoogleCloudSettings</interface>
    <class>org.iplass.mtp.impl.googlecloud.GoogleCloudSettings</class>

    <property name="credentialsFactory" class="org.iplass.mtp.impl.googlecloud.ServiceAccountSecretKeyGoogleCredentialsFactory">
        <!-- Firebase プロジェクトの設定で、サービスアカウント用の秘密鍵を生成し設定する。 -->
        <property name="serviceAccountSecretKeyFilePath" value="/path/to/firebase-adminsdk.json" />
        <property name="scope" value="https://www.googleapis.com/auth/firebase.messaging" />
        <!-- proxy利用する場合設定 -->
        <property name="proxyHost" value="xxxxxx.dentsusoken.com" />
        <property name="proxyPort" value="8080" />
    </property>
</service>

(2)
<!-- FCM HTTP v1 API 用の PushNotificationService  -->
<service>
    <interface>org.iplass.mtp.impl.pushnotification.PushNotificationService</interface>

    <class>org.iplass.mtp.impl.pushnotification.fcmv1.PushNotificationService</class>
    <!-- Google(Firebase) Project Id を設定する -->
    <property name="projectId" value="[set Firebase(Google) Project Id]" />
    <property name="compressRequest" value="true" />
    <property name="apiRequestValidateOnly" value="false" />
    <!-- リトライ処理を行う場合、enableRetry、exponentialBackoffにて設定 -->
    <property name="enableRetry" value="true" />
    <property name="exponentialBackoff" class="org.iplass.mtp.impl.http.ExponentialBackoff">
        <property name="retryIntervalMillis" value="500" />
        <property name="randomizationFactor" value="0.5" />
        <property name="multiplier" value="1.5" />
        <property name="maxIntervalMillis" value="60000" />
        <property name="maxElapsedTimeMillis" value="300000" />
    </property>
    <property name="defaultRetryAfterSeconds" value="60" />
    <property name="httpClientConfig" class="org.iplass.mtp.impl.http.HttpClientConfig">
        <!-- proxy利用する場合設定 -->
        <property name="proxyHost" value="xxxxxx.dentsusoken.com" />
        <property name="proxyPort" value="8080" />
    </property>
    <!--
    RegistrationTokenHandler 実装クラス。
    実行した結果、デバイス登録トークンが未登録の場合の処理を実施する場合、
    org.iplass.mtp.pushnotification.fcmv1.RegistrationTokenHandler の実装クラスを指定可能。
    -->
    <!--
    <property name="registrationTokenHandler" class="[set class of implements org.iplass.mtp.pushnotification.fcmv1.RegistrationTokenHandler]" />
    -->
    <!-- PushNotificationListener 実装クラス。複数設定可能 -->
    <!--
    <property name="listener" class="[set class of implements org.iplass.mtp.pushnotification.PushNotificationListener]" />
    -->
</service>
1 GoogleCloudSettings の設定内容の詳細は、service-config GoogleCloudSettings を参照してください。
2 FCM HTTP v1 API 用の PushNotificationService の設定内容の詳細は、service-config PushNotificationService を参照してください。

その他のプッシュ通知サービスを利用する場合

Firebase Cloud Messaging以外の外部プッシュ通知サービスを利用する場合、PushNotificationServiceの実装クラスを実装し、その実装クラスをmtp-service-config.xmlに設定します。

4. Webhook

特定のEvent発生時に外部サービスと連携し、ユーザーに更新情報を通知するための機能です。iPLAssでは、エンドポイントや認証情報、送信するHTTPリクエスト内容を「WebhookEndpoint」と「WebhookTemplate」に分けて登録・管理します。

4.1. WebhookEndpoint

エンドポイントや認証情報をWebhookEndpointとして登録・管理することが可能です。
WebhookEndpointはAdminConsoleにて登録・管理します。

WebhookEndpointの作成

AdminConsoleからNotificationカテゴリのWebhookフォルダ内にあるWebhookEndpointの定義を作成します(WebhookEndpoint → 右クリック → 作成)。

設定項目の説明

次の項目を設定可能です。

Endpoint Address

Webhookのエンドポイントを指定します。

項目 設定内容

Endpoint URL

エンドポイントURLを指定します。GroovyTemplate形式で動的に値をセットすることも可能です。

Header Authentication

Authorizationヘッダに含む認証情報を設定します。

項目 設定内容

Token Type

認証方式を指定します。認証方式は、Basic Authentication, Bearer Authentication, Custom Authentication, Disabled(無効)から選択してください。

Customize Token Type Name

(Token TypeがCustom Authentication の場合)
カスタムのスキーム名を設定してください。

「Header認証を編集」ボタン

選択したToken Typeに応じた認証情報を設定してください。設定した認証情報はToken Type毎に保持されます。

「Header認証を削除」ボタン

設定済の認証情報を削除します。

HMAC Authentication

必要に応じて、 HMAC認証を設定します。

項目 設定内容

Enable HMAC

HMAC認証を利用する場合は、チェックを入れてください。

Header Name

HMACの値をセットするヘッダ名を設定します。未入力の場合は、service-configで設定されたデフォルトのヘッダ名が適用されます。

「HMACの秘密鍵を生成」ボタン

service-configで設定したハッシュアルゴリズムを用いて、ランダムのHMACの秘密鍵が生成されます。

「HMACの秘密鍵を編集」ボタン

設定済みのHMACの秘密鍵を編集することが可能です。

「HMACの秘密鍵を削除」ボタン

設定済みのHMACの秘密鍵を削除します。

Authentication情報は編成ダイアログの「Save」ボタンを押した時点でデータベースに保存されます。

4.2. WebhookTemplate

外部システムに送信するHTTPリクエストの内容をWebhookTemplateとして登録・管理することが可能です。
WebhookTemplateはAdminConsoleにて登録・管理します。

WebhookTemplateの作成

AdminConsoleからNotificationカテゴリのWebhookフォルダ内にあるWebhookTemplateの定義を作成します(WebhookTemplate → 右クリック → 作成)。

設定項目の説明

次の項目を設定可能です。

項目 設定内容

Content-Type

Content-Typeを指定します。

  • 外部サービスのAPI仕様に合わせて、 application/x-www-form-urlencoded, application/json, text/plainなどを指定してください。

  • 後述のCustom HeaderにもContent-Typeを指定した場合、こちらの設定が優先されます。

Http Request Method

HTTPメソッド(通常はPOST)を指定します。

Custom Header

HTTPリクエストヘッダにカスタムヘッダを指定することが可能です。
ヘッダー名、値のペアで設定してください。

Sub Path/Query String

サブパス、クエリストリングを設定します。GroovyTemplate形式で記述可能です。

entityがバインドされている場合の記述例

www.url.com/something?var=1のURLで、varの値にバインドしたEntityのProperty値を利用したい場合、
?var=${entity.oid}の様に記述してください。

Webhook Payload Contents

(POST, PUT, PATCHの場合)
HTTPリクエストボディのコンテンツを記述します。
Content-Typeに応じた内容を、外部サービスのAPI仕様に合わせて記述してください。

4.3. 利用方法

Webhookの送信処理

EntityのEventListenerをトリガーとしてWebhookを実行することが可能です。WebhookManagerを利用するコード実装も可能です。実際にWebhookを実行する場合は、mtp-service-config.xmlにて、WebhookServiceを正しく設定する必要があります。

WebhookManagerを利用したWebhook送信は以下のように実装します。

import org.iplass.mtp.webhook.Webhook;
import org.iplass.mtp.webhook.WebhookManager;

//Webhookの送信はWebhookManagerを利用
private WebhookManager webhookManager = ManagerLocator.manager(WebhookManager.class);


private void sendWebhook() {

    try {
        //WebhookTemplateに渡すバインド変数設定(例ではentityを設定)
        Map<String, Object> bindings = new HashMap<String, Object>();
        bindings.put("entity", entity);

        //WebhookManager#createWebhook(WebhookTemplate名, バインド変数, WebhookEndpoint名) を呼び出し、Webhookインスタンスを生成
        Webhook webhook = webhookManager.createWebhook("sampleWebhookTemplateName", bindings,"sampleWebhookEndpointName");(1)

        //WebhookManager#sendWebhookAsync(Webhook)を呼び出し、Webhookを非同期処理として送信
        webhookManager.sendWebhookAsync(webhook);(2)

        //WebhookManager#sendWebhookSync(Webhook)を呼び出し、Webhookを同期処理として送信
        webhookManager.sendWebhookSync(webhook);(3)

    } catch (RuntimeException e) {
    }
}
1 既存のWebhookTemplate定義とWebhookEndpoint定義を利用して、Webhookのエンドポイントや送信メッセージを指定。 バインド変数とGroovyTemplate書式を利用して動的に送信メッセージを生成。
2 Webhookを非同期処理として送信。
3 Webhookを同期処理として送信。

4.4. 利用例

以下では、利用例としてMicrosoft Teams、Slack、LINEと連携してユーザーにメッセージを通知するサンプルを紹介します。

Microsoft Teamsと連携

Microsoft Teamsの「Incoming Webhook」を用いて、メッセージを通知する簡単なサンプルをここでは紹介します。

「Incoming Webhook」の作成
  1. サイドバー左下の[アプリ]を選択して、アプリ一覧から[Incoming Webhook]を選択する

  2. [チームに追加]をクリックして、Webhookで通知を行いたいチャネルを選択し、[コネクタを設定]をクリックする。

  3. 任意の名前を入力し、必要に応じてWebhookの画像アバターをアップロードした後、[作成]をクリックする。

  4. 作成されたWebhook URLをメモし、[完了]をクリックする。

WebhookEndpointの作成

AdminConsoleからWebhookEndpoint定義を新規で作成します。 以下の内容を入力してWebhookEndpointを作成してください。

項目 内容

Endpoint URL

先程メモしたWebhook URLを入力する。

WebhookTemplateの作成

AdminConsoleからWebhookTemplate定義を新規で作成します。 以下の内容を入力してWebhookTemplateを作成してください。

項目 内容

Content-Type

application/json

Http Request Method

POST

webHook Payload Content

本サンプルでは、以下の簡単なテキストメッセージを通知します 。

{
    "text": "new Entity: ${entity.name} が作成されました"
}
EntityのEventListenerを設定する

任意のEntityにEventListenerを設定します。

項目 内容

Type

SendNotification

Notification type

Webhook

Template

先程作成したWebhookTemplateを選択してください。

Destination

先程作成したWebhookEndpointのnameを入力してください。

Events

afterInsertをチェックしてください。

結果確認

対象のEntityにデータを挿入してみてください。
正しく設定されている場合、Microsoft Teamsの選択したチャネルにWebhookボットから通知メッセージが送信されます。

Slackと連携

Slackの「Incoming Webhook」を用いて、メッセージを通知する簡単なサンプルをここでは紹介します。

「Incoming Webhook」の作成
  1. Slackの Incoming Webhookの設定ページに遷移する

  2. [Slackに追加]をクリックして、Webhookで通知を行いたいチャンネルを選択し、[Incoming Webhook インテグレーションの追加]をクリックする。

  3. 作成されたWebhook URLをメモする。

WebhookEndpointの作成

AdminConsoleからWebhookEndpoint定義を新規で作成します。 以下の内容を入力してWebhookEndpointを作成してください。

項目 内容

Endpoint URL

先程メモしたWebhook URLを入力する。

WebhookTemplateの作成

AdminConsoleからWebhookTemplate定義を新規で作成します。 以下の内容を入力してWebhookTemplateを作成してください。

項目 内容

Content-Type

application/json

Http Request Method

POST

webHook Payload Content

本サンプルでは、以下の簡単なテキストメッセージを通知します 。

{
    "text": "new Entity: ${entity.name} が作成されました"
}
EntityのEventListenerを設定する

任意のEntityにEventListenerを設定します。

項目 内容

Type

SendNotification

Notification type

Webhook

Template

先程作成したWebhookTemplateを選択してください。

Destination

先程作成したWebhookEndpointのnameを入力してください。

Events

afterInsertをチェックしてください。

結果確認

対象のEntityにデータを挿入してみてください。
正しく設定されている場合、Slackの選択したチャネルにWebhookボットから通知メッセージが送信されます。

LINEと連携

LINEの「Messaging API」を用いて、メッセージを通知する簡単なサンプルをここでは紹介します。簡単の為、本サンプルでは、 ブロードキャストメッセージを送信するAPIを利用します。

「Messaging API」の設定
  1. LINEのチャネル作成ガイドを参照して、Messaging APIチャネルを作成する。

  2. 「チャネルアクセストークン」を取得する。チャネルアクセストークンは、コンソールの[チャネル設定]から対象のチャネルを選択して、[チャネル基本設定]タブで発行可能です。

WebhookEndpointの作成

AdminConsoleからWebhookEndpoint定義を新規で作成します。 以下の内容を入力してWebhookEndpointを作成してください。

項目 内容

Endpoint URL

Header Authentication

TokenTypeで「Bearer Authentication」を選択し、「Header認証を編集」をクリックする。入力フォームに先程取得したチャネルアクセストークンを入力する。

WebhookTemplateの作成

AdminConsoleからWebhookTemplate定義を新規で作成します。 以下の内容を入力してWebhookTemplateを作成してください。

項目 内容

Content-Type

application/json

Http Request Method

POST

webHook Payload Content

本サンプルでは、以下の簡単なテキストメッセージを通知します。

{
    "messages":[
        {
            "type":"text",
            "text":"Hello"
        },
        {
            "type":"text",
            "text": "new Entity: ${entity.name} が作成されました"
        },
        {
            "type":"text",
            "text":"説明:${entity.description} "
        },
    ]
}
EntityのEventListenerを設定する

任意のEntityにEventListenerを設定します。

項目 内容

Type

SendNotification

Notification type

Webhook

Template

先程作成したWebhookTemplateを選択してください。

Destination

先程作成したWebhookEndpointのnameを入力してください。

Events

afterInsertをチェックしてください。

結果確認

対象のEntityにデータを挿入してみてください。
正しく設定されている場合、LINE公式アカウントと友だちになっているすべてのユーザーにプッシュメッセージが送信されます。