JS7® JobScheduler メール通知設定

# 概要

JS7 JobScheduler にて、WorkFlowの正常終了／エラー時に、メール通知を送る方法です。
通知の基本的な説明も含めて記載します。

# 前提条件

- JS7 jobscheduler の環境準備、初期設定を済ませ、リソース変数`/Defaults/eMailDefault`を取り込んでいること
まだの方はこちらから
[JS7® JobScheduler 初期設定、サンプルWorkFlowの登録](https://qiita.com/natsumadenikimero/items/2d3162b688329f5ecae2)
- メール通知をするためのSMTP関連の設定（サーバー、認証情報など）が用意できていること
- 動作確認環境 JOC 2.2.3, 2.3.x, 2.4.x  CentOS7/Amazon Linux2/ Docker sosberlin/js7:joc
- 本例はJOCがLinux環境を前提としています。
Windowsでもほぼ同じ内容かと思いますが、動作チェックはしておりません。

# Notification の設定概要

## 基本構造

まず通知に関する設定内容を大雑把に確認します。
CONFIGURATION より Notification の設定を開いてください。

デフォルトでは、このような状態となっています。
![notify_default.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/b09844a6-775b-6f66-771c-66e1ccfde36b.png)

## 各基本要素の説明

大きく下記４つの設定から成り立っています。

- MessageFragments
- MonitorFragments
- ObjectFragments
- Notifications

### MessageFragments

メール本文や、Slackで送信するjsonなどを定義します。
用途別や正常/エラー用など複数定義可能

### MonitorFragments

実際に通知を行う際の手段(メール、コマンド等)の定義と、その際に参照するメッセージ本文（MessageFragments）の指定ができます。
通知手段として下記の4タイプが提供されています。

- CommandFragment  &nbsp;&nbsp;&nbsp;&nbsp;コマンドラインでの処理の定義。Slack通知はこちら
- MailFragment  &nbsp;&nbsp;&nbsp;&nbsp;メール送信 の定義　宛先、件名など
- JMSFragment  &nbsp;&nbsp;&nbsp;&nbsp;JMS API の定義
- NSCAFragment  &nbsp;&nbsp;&nbsp;&nbsp;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](https://kb.sos-berlin.com/display/PKB/JS7+-+Notification+-+Configuration)

### モニター変数の利用方法

- モニター変数を利用するには、`${変数名}` という書式を使う必要があります。
※`$変数名` では参照できません。
※コマンドで使う場合は、値が展開されるタイミングが、通常のOS変数とは異なります。
- コマンド中では、上記`${変数名}` 以外にも、環境変数としてプレフィックス `JS7_` を付けた名前で参照できます。
`$JS7_変数名`　 `${JS7_変数名}`
※こちらは通常の環境変数と同じように扱えます。
- コマンド中では、`${MESSAGE}` という変数名でメッセージ本文を展開できます。

おおよそ下記のような展開イメージです。

1. メッセージ, コマンド中のモニター変数`${MON_N_XXX}`, `${MON_O_XXX}`, `${MON_OS_XXX}`, `${JOC_XXX}`, `${MESSAGE}` が展開される。
1. モニター変数が環境変数`$JS7_MON_N_XXX`, `$JS7_MON_O_XXX`, `$JS7_MON_OS_XXX`, `$JS7_JOC_XXX` として定義される。
1. コマンドで定義した内容がスクリプトとして実行される。

# Notification でのメール通知設定

WorkFlowの実行結果をメール通知する設定の例です。

## 事前準備

リソース変数にて、SMTP関連設定を行います。
`/Defaults/eMailDefault` を編集、Deployしてください。
※コピーして別名（/Defaults/eMailGmail など）で定義しても構いません。
![JobResources_eMailDefault.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/e1ca0968-ccb6-5d9a-1405-3bd9350fdd1d.png)

ちなみに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*** に通知先メールアドレスを登録してください。
※複数の場合はカンマ区切り
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/6de36c79-cd0e-c9b9-75d7-7f5016754ebd.png)

さらに、Notification の設定2か所(notify_on_success  notify_on_failure) の、NotificationObjects（通知の対象範囲を選択）にて、***any***を選択します。
（anyはすべてのWorkFlowを対象、noneはすべて対象外の設定となっています）
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/f372594f-8a7b-469b-eeab-f1c74f2ab1a3.png)

最後に画面右上の Validate で内容チェック後、 Release をしてください。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/6917570d-723f-ec80-219a-c85019cb3412.png)

とりあえず通知が飛べばいい　という場合は、これだけでOKです。
実際にWorkFlowを実行して、正常／エラー時にメール通知が飛ぶことを確認してみてください。

## メール通知設定（カスタマイズ編）

せっかくなので、通知設定を自在にカスタマイズできるように、実際に設定を入れ込んでいきます。

### MessageFragment（本文）

(Ver 2.4より機能追加) MessageFragments にて、メッセージ本文で使用されるTimeZoneを指定します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/88eb9fdc-eccf-4a9b-3d39-ec0d6970e1f9.png)

:::note warn
TimeZone指定は Ver 2.4.0 からの機能です。Ver 2.3以前ではUTC固定となります。
:::

MessageFragments より Add Child Node で新規にMessageを作成します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/c6165e3f-5647-3486-4f1f-56304985279a.png)

まずは正常通知用のメッセージを作成します。

名前は `text_on_success` とします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/d74dc96c-e73f-e059-6cb8-e202e2facf5e.png)

メール本文は例えばこんな感じです。
モニター変数の箇所は、実際のメール本文では値が入ります。
※お好みで加工してください

```: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` とします。
メール本文はこんな感じです

```: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 を作成します。
※使い方の説明も兼ねて新規作成をしますが、既存の設定を編集しても構いません。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/79e83821-db42-0c2f-c133-23ce4eb38437.png)

まず正常時のメール設定を作ります。
名前は `mail_text_on_success` とします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/94893757-1914-f91b-e62e-27bd0bccbdf9.png)

|項目|値|
|-|-|
|name|mail_text_on_success|
|jdb_resources|/Defaults/eMailDefault を選択<br>※定義されたSMTPサーバー、認証情報などが使われます|
|content_type|text/plain|
|charset|UTF-8|
|encoding|Base64|
|priority|Normal|

MessageRef にて、先ほど作成したメッセージ `text_on_success`を選びます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/8f992c7d-5b3b-e770-0065-eb3e49af1cf5.png)

Subject は`JS7 JobScheduler Notification: ${MON_N_TYPE} - Workflow: ${MON_O_WORKFLOW_NAME}` とします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/09a29ad7-2acd-3aba-9aac-a97abdc89c53.png)

今作成したMailFragment `mail_text_on_success` にて To を作成します。
宛先は、ご自身の通知先メールアドレスを入力してください。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/da3b841f-db2a-0c4a-82a5-dd1a4b6d3ad5.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/2dbdeb73-ed25-086a-ec01-57f180214096.png)

同様の手順で、エラー時のメール設定を作成してください。

|項目|値|
|-|-|
|name|mail_text_on_failure|
|jdb_resources|/Defaults/eMailDefault を選択<br>※定義された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を作成します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/df760a5e-a989-558a-1542-16736836d073.png)

名前は `example_only` とします。
controller_id　は　空のままで結構です。（特定コントローラー上のみ指定が可能。未指定ですべて対象）
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/b9ce6314-8c4a-c20f-096a-3a5ab63e833c.png)

Workflows のpathに、`/Examples.Unix/.*` と指定してください。
（正規表現で/Examples.Unixフォルダ以下の全ワークフローを指定）
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/7638749b-424c-0da1-4d6f-8b5bcf6d0149.png)

【参考】例えばこんな風に、Workflowを複数追加して、複数のフォルダを含める定義も可能です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/66fac3aa-abb9-7c07-3a91-fe221a56f951.png)

### Notifications（ステータスと設定の関連付け）

最後にNotificationの設定を行います。
こちらは、今ある設定を修正していきます。

まず、`notify_on_success`　の設定から確認していきます。
こちらは、typeに `SUCCESS`が選ばれているので、正常時のが対象の設定となります。
※Statusの種類は `SUCCESS`,`WARNING`,`ERROR`の3パターン
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/8a5ea0ed-aab6-32de-fa30-86c57a0fc75a.png)

次に、MailFragmentRef (メール通知手段を指定)にて、先ほど作った `mail_text_on_success`を選びます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/cc186919-65d4-a0ff-63f9-dc1ac92ec47b.png)

次に、WorkflowRef（対象範囲を指定）にて、`example_only`を選びます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/d116d769-ab5c-97b5-e1f1-e6980e49cf73.png)
これで、正常終了時のメール通知設定が完了しました。

同様に、エラー時の通知設定も修正します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/12c643d3-5b35-5d8d-fd7a-91ea6137a29c.png)

|項目|設定値|
|-|-|
|name|notify_on_failure|
|type|ERROR, WARNING の２つを選択|
|MailFragmentRef|mail_text_on_failure|
|WorkflowRef|example_only|

最後に画面右上の Validate で内容チェック後、 Release をしてください。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2529537/6917570d-723f-ec80-219a-c85019cb3412.png)

お疲れ様でした。以上でメール通知設定は完了となります。
実際にWorkFlowを実行して、正常／エラー時にメール通知が飛ぶことを確認してみてください。

# 最後に

通知設定は、一見ややこしそうに見えますが、内容が整理できると割と簡単です。
今回は触れませんでしたが、対象範囲の指定で、さらにJob単位でも細かく指定可能です。（重要なJobだけ対象にするなど）
エラーが出てたのに気づかない、、、なんてことの防止に、ぜひ設定を行ってください。