概要
JS7 JobScheduler にて、WorkFlowの正常終了／エラー時に、メール通知を送る方法です。
通知の基本的な説明も含めて記載します。
前提条件
- JS7 jobscheduler の環境準備、初期設定を済ませ、リソース変数
/Defaults/eMailDefaultを取り込んでいること
まだの方はこちらから
JS7® JobScheduler 初期設定、サンプルWorkFlowの登録 - メール通知をするためのSMTP関連の設定（サーバー、認証情報など）が用意できていること
- 動作確認環境 JOC 2.2.3, 2.3.x, 2.4.x CentOS7/Amazon Linux2/ Docker sosberlin/js7:joc
- 本例はJOCがLinux環境を前提としています。
Windowsでもほぼ同じ内容かと思いますが、動作チェックはしておりません。
Notification の設定概要
基本構造
まず通知に関する設定内容を大雑把に確認します。
CONFIGURATION より Notification の設定を開いてください。
デフォルトでは、このような状態となっています。
各基本要素の説明
大きく下記４つの設定から成り立っています。
- MessageFragments
- MonitorFragments
- ObjectFragments
- Notifications
MessageFragments
メール本文や、Slackで送信するjsonなどを定義します。
用途別や正常/エラー用など複数定義可能
MonitorFragments
実際に通知を行う際の手段(メール、コマンド等)の定義と、その際に参照するメッセージ本文（MessageFragments）の指定ができます。
通知手段として下記の4タイプが提供されています。
- CommandFragment コマンドラインでの処理の定義。Slack通知はこちら
- MailFragment メール送信 の定義 宛先、件名など
- JMSFragment JMS API の定義
- NSCAFragment Nagios NSCA の定義
ObjectFragments
通知対象とするWorkFlowの範囲を定義します。
特定フォルダ以下、特定WorkFlow、特定Jobなどの条件指定を複数定義可能です。
※正規表現も利用可
Notifications
Orderのステータス(Success,Warning,Error)、WorkFlowの対象範囲（ObjectFragments）に応じて、行う処理(MonitorFragments)、の指定ができます。
利用できる変数について
変数の例
通知メッセージ本文やコマンド中では、モニター変数を使用して、関連する項目値を参照することができます。
| モニター変数の種類 | 内容 |
|---|---|
| MON_N_XXX | Notification Variables 通知の基本情報 |
| MON_O_XXX | Order Variables Orderに関する情報 |
| MON_OS_XXX | Order Step 実行JOBに関する情報 |
| JOC_XXX | 実行内容に関する各種JOCのURL |
| モニター変数の例 | 内容 |
|---|---|
| MON_N_TYPE | 通知の種類 SUCCESS, WARNING, ERROR, RECOVERED |
| MON_O_ORDER_ID | Order ID |
| MON_OS_ERROR_TEXT | エラーメッセージ |
| JOC_HREF_ORDER | Order情報のURL |
Notification 設定内で使用できる変数は下記に掲載されています。
JS7 - Notification - Configuration
モニター変数の利用方法
- モニター変数を利用するには、
${変数名}という書式を使う必要があります。
※$変数名では参照できません。
※コマンドで使う場合は、値が展開されるタイミングが、通常のOS変数とは異なります。 - コマンド中では、上記
${変数名}以外にも、環境変数としてプレフィックスJS7_を付けた名前で参照できます。
$JS7_変数名${JS7_変数名}
※こちらは通常の環境変数と同じように扱えます。 - コマンド中では、
${MESSAGE}という変数名でメッセージ本文を展開できます。
おおよそ下記のような展開イメージです。
- メッセージ, コマンド中のモニター変数
${MON_N_XXX},${MON_O_XXX},${MON_OS_XXX},${JOC_XXX},${MESSAGE}が展開される。 - モニター変数が環境変数
$JS7_MON_N_XXX,$JS7_MON_O_XXX,$JS7_MON_OS_XXX,$JS7_JOC_XXXとして定義される。 - コマンドで定義した内容がスクリプトとして実行される。
Notification でのメール通知設定
WorkFlowの実行結果をメール通知する設定の例です。
事前準備
リソース変数にて、SMTP関連設定を行います。
/Defaults/eMailDefault を編集、Deployしてください。
※コピーして別名（/Defaults/eMailGmail など）で定義しても構いません。
ちなみにGmailで STARTTLS 利用時は、下記のような設定で送信できました。
※二段階認証を使っている方はアプリ パスワード発行してください
| Name | Value |
|---|---|
| from | xxxxx@gmail.com |
| from_name | JS7 JobScheduler |
| mail.smtp.host | smtp.gmail.com |
| mail.smtp.port | 587 |
| mail.smtp.timeout | 5000 |
| mail.smtp.connectiontimeout | 5000 |
| mail.smtp.user | xxxxx@gmail.com |
| mail.smtp.password | xxxxx |
| mail.smtp.starttls.enable ※追加 | true |
| mail.smtp.auth ※追加 | true |
| mail.smtp.ssl.protocols ※追加 | TLSv1.2 |
メール通知設定（最短編）
つぎにNotification 設定です。
ちなみに、メールフォーマットを気にしないならば、デフォルトの設定に一部修正を行うのみで、メール通知が飛ぶようになっています。
MailFragment の設定2か所（mail_on_success、mail_on_failure）の To に通知先メールアドレスを登録してください。
※複数の場合はカンマ区切り
さらに、Notification の設定2か所(notify_on_success notify_on_failure) の、NotificationObjects（通知の対象範囲を選択）にて、anyを選択します。
（anyはすべてのWorkFlowを対象、noneはすべて対象外の設定となっています）
最後に画面右上の Validate で内容チェック後、 Release をしてください。
とりあえず通知が飛べばいい という場合は、これだけでOKです。
実際にWorkFlowを実行して、正常／エラー時にメール通知が飛ぶことを確認してみてください。
メール通知設定（カスタマイズ編）
せっかくなので、通知設定を自在にカスタマイズできるように、実際に設定を入れ込んでいきます。
MessageFragment（本文）
(Ver 2.4より機能追加) MessageFragments にて、メッセージ本文で使用されるTimeZoneを指定します。
TimeZone指定は Ver 2.4.0 からの機能です。Ver 2.3以前ではUTC固定となります。
MessageFragments より Add Child Node で新規にMessageを作成します。
まずは正常通知用のメッセージを作成します。
名前は text_on_success とします。
メール本文は例えばこんな感じです。
モニター変数の箇所は、実際のメール本文では値が入ります。
※お好みで加工してください
${MON_O_WORKFLOW_PATH} は正常終了しました。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■Controller
Controller ID: ${MON_O_CONTROLLER_ID}
Agent URI: ${MON_OS_AGENT_URI}
■Order
Order ID: ${MON_O_ORDER_ID}
Order Log: ${JOC_HREF_ORDER_LOG}
Workflow Path: ${MON_O_WORKFLOW_PATH}
Workflow Title: ${MON_O_WORKFLOW_TITLE}
Job Name: ${MON_OS_JOB_NAME}
Job Title: ${MON_OS_JOB_TITLE}
Job Label: ${MON_OS_JOB_LABEL}
Job Criticality:${MON_OS_JOB_CRITICALITY}
Job Log: ${JOC_HREF_JOB_LOG}
■Order History
Status: ${MON_O_SEVERITY}
Time elapsed: ${MON_O_TIME_ELAPSED}
Start Time: ${MON_O_START_TIME}
End Time: ${MON_O_END_TIME}
■Order Step History
Status: ${MON_OS_SEVERITY}
Start Time: ${MON_OS_START_TIME}
End Time: ${MON_OS_END_TIME}
Time elapsed: ${MON_OS_TIME_ELAPSED}
同様に、エラー通知用のメッセージも作成します。
名前は text_on_failure とします。
メール本文はこんな感じです
${MON_O_WORKFLOW_PATH} の実行時に ${MON_N_TYPE}が発生しました。
下記内容を確認してください。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■Error/Warning
Return Code: ${MON_OS_RETURN_CODE}
Message: ${MON_OS_ERROR_TEXT}
Error Code: ${MON_OS_ERROR_CODE}
Warning: ${MON_N_WARN_TEXT}
■Controller
Controller ID: ${MON_O_CONTROLLER_ID}
Agent URI: ${MON_OS_AGENT_URI}
■Order
Order ID: ${MON_O_ORDER_ID}
Order Log: ${JOC_HREF_ORDER_LOG}
Workflow Path: ${MON_O_WORKFLOW_PATH}
Workflow Title: ${MON_O_WORKFLOW_TITLE}
Job Name: ${MON_OS_JOB_NAME}
Job Title: ${MON_OS_JOB_TITLE}
Job Label: ${MON_OS_JOB_LABEL}
Job Criticality:${MON_OS_JOB_CRITICALITY}
Job Log: ${JOC_HREF_JOB_LOG}
■Order History
Status: ${MON_O_SEVERITY}
Time elapsed: ${MON_O_TIME_ELAPSED}
Start Time: ${MON_O_START_TIME}
End Time: ${MON_O_END_TIME}
■Order Step History
Status: ${MON_OS_SEVERITY}
Start Time: ${MON_OS_START_TIME}
End Time: ${MON_OS_END_TIME}
Time elapsed: ${MON_OS_TIME_ELAPSED}
MonitorFragment (通知手段）
次にメールのサーバー、宛先、件名などの設定を行います。
MonitorFragment より、MailFragment を作成します。
※使い方の説明も兼ねて新規作成をしますが、既存の設定を編集しても構いません。
まず正常時のメール設定を作ります。
名前は mail_text_on_success とします。
| 項目 | 値 |
|---|---|
| name | mail_text_on_success |
| jdb_resources | /Defaults/eMailDefault を選択 ※定義されたSMTPサーバー、認証情報などが使われます |
| content_type | text/plain |
| charset | UTF-8 |
| encoding | Base64 |
| priority | Normal |
MessageRef にて、先ほど作成したメッセージ text_on_successを選びます。
Subject はJS7 JobScheduler Notification: ${MON_N_TYPE} - Workflow: ${MON_O_WORKFLOW_NAME} とします。
今作成したMailFragment mail_text_on_success にて To を作成します。
宛先は、ご自身の通知先メールアドレスを入力してください。
同様の手順で、エラー時のメール設定を作成してください。
| 項目 | 値 |
|---|---|
| name | mail_text_on_failure |
| jdb_resources | /Defaults/eMailDefault を選択 ※定義されたSMTPサーバー、認証情報などが使われます |
| content_type | text/plain |
| charset | UTF-8 |
| encoding | Base64 |
| priority | Normal |
| MessageRef | text_on_failure を選択 |
| Subject | JS7 JobScheduler Notification: ${MON_N_TYPE} - Workflow: ${MON_O_WORKFLOW_NAME} |
| To | 通知先メールアドレス |
ObjectFragments（対象範囲）
通知対象範囲も指定してみます。
ObjectFragments より、WorkFlowsを作成します。
名前は example_only とします。
controller_id は 空のままで結構です。（特定コントローラー上のみ指定が可能。未指定ですべて対象）
Workflows のpathに、/Examples.Unix/.* と指定してください。
（正規表現で/Examples.Unixフォルダ以下の全ワークフローを指定）
【参考】例えばこんな風に、Workflowを複数追加して、複数のフォルダを含める定義も可能です。
Notifications（ステータスと設定の関連付け）
最後にNotificationの設定を行います。
こちらは、今ある設定を修正していきます。
まず、notify_on_success の設定から確認していきます。
こちらは、typeに SUCCESSが選ばれているので、正常時のが対象の設定となります。
※Statusの種類は SUCCESS,WARNING,ERRORの3パターン
次に、MailFragmentRef (メール通知手段を指定)にて、先ほど作った mail_text_on_successを選びます。
次に、WorkflowRef（対象範囲を指定）にて、example_onlyを選びます。
これで、正常終了時のメール通知設定が完了しました。
同様に、エラー時の通知設定も修正します。
| 項目 | 設定値 |
|---|---|
| name | notify_on_failure |
| type | ERROR, WARNING の２つを選択 |
| MailFragmentRef | mail_text_on_failure |
| WorkflowRef | example_only |
最後に画面右上の Validate で内容チェック後、 Release をしてください。
お疲れ様でした。以上でメール通知設定は完了となります。
実際にWorkFlowを実行して、正常／エラー時にメール通知が飛ぶことを確認してみてください。
最後に
通知設定は、一見ややこしそうに見えますが、内容が整理できると割と簡単です。
今回は触れませんでしたが、対象範囲の指定で、さらにJob単位でも細かく指定可能です。（重要なJobだけ対象にするなど）
エラーが出てたのに気づかない、、、なんてことの防止に、ぜひ設定を行ってください。