6 トリガーの使用
この章のトピックは、次のとおりです:
トリガー機能の概要
Enterprise Data Qualityのトリガーは、EDQシステムの様々なトリガー・ポイントでコールできるスクリプト(JavaScriptまたはGroovy)です。トリガーには、定義済トリガーとカスタム・トリガーの2つのタイプがあります。
定義済トリガーについて
定義済トリガーはEDQインストールに付属しています。ディレクタ・ユーザー・インタフェースに表示され、ジョブ構成で使用されて、ジョブの開始、Webサービスの停止、電子メール通知の送信、およびジョブ内から別のジョブの実行を行うことができます。ディレクタ・ユーザーはトリガー・ポイント(ジョブの開始、ジョブの終了、またはその両方)で実行するようにこれらのトリガーを設定できます。ディレクタのオンライン・ヘルプ・システムで定義済トリガーの詳細を参照できます。
カスタム・トリガーについて
カスタム・トリガーはJavascriptまたはGroovyのスキルのある人により作成され、特定のワークフローの目的を達成するようにEDQの機能を拡張することができます。カスタム・トリガーを使用して次のようなタスクを実行できます。
-
電子メール・メッセージの送信
-
JMSメッセージの送信
-
Webサービスのコール
-
ファイルの記述
-
テキスト・メッセージの送信
次の定義済トリガー・ポイントでカスタム・トリガーを実行することができます。
-
ジョブ・フェーズの実行前
-
ジョブ・フェーズの実行後
-
一致決定の作成時
-
ケース管理での遷移の作成時
-
ジョブの完了時
これらの各トリガー・ポイントには、特別なAPIによりトリガーに渡される、一意のパスと定義済の引数のセットがあります。詳細は、「EDQトリガー・ポイントについて」を参照してください。
カスタム・トリガーについては、このドキュメントの後半で説明します。
トリガーの格納
カスタム・トリガーはEDQのconfig
(構成)ディレクトリのtriggers
サブディレクトリに格納される必要があります。新しいまたは更新されたトリガーは自動的にロードされ、システムを再起動する必要はありません。
スクリプト・トリガーAPIを使用したトリガーの構成
スクリプトAPIの機能を使用してトリガーを作成できます。これらの機能はトリガー・コードで定義されます。このドキュメントでの例はJavaScriptですが、同じAPIがGroovyでも使用可能です。
次にこのAPIでの各機能について説明します。
- getPath()
-
トリガーが処理するパスを定義する文字列を返します。各トリガー・ポイントには一意のパスがあります。トリガー・ポイントに到達すると、指定したパスに一致するトリガーが実行されます。トリガー・ポイントの詳細は、「EDQトリガー・ポイントについて」を参照してください。
この機能は正規表現です。たとえば、パス
/log/com\.datanomic\..*
はログ出力名に文字列datanomic
が含まれるログ出力パスと一致します(つまり、"datanomic"という語がEDQ用の別名になっている、EDQに定義されたログ出力)。 - run(path, id, env, arg1, arg2 ...)
-
トリガーを実行します。これらの変数のそれぞれに対してトリガーAPIが返す値の詳細は、「EDQトリガー・ポイントについて」を参照してください。
- path
-
トリガーのパスで、
/runtime/engine/interval/end
などです。 - id
-
トリガーID。IDはトリガーがディレクタ・ユーザー・インタフェースで構成されるときに設定されます。このIDは単純なトリガーに対してはnullです。
- env
-
1つ以上のキー/値のペアの形式でのトリガー環境で、
env.project = project name
などです。env
の入力は、トリガー・ポイントごとに固有です。これらの値はスクリプト内でenv
オブジェクトのプロパティとして公開されます。ほとんどのトリガー・ポイントは関連するEDQプロジェクトIDおよびプロジェクト名で渡されます。 - arg
-
追加の引数はトリガー・ポイントに特有です。たとえば、
Interval end
トリガー・ポイントは、次を返します: タスク・コンテキスト・オブジェクト、プロセス・オプション、間隔数(>= 1)、実行統計。
- filter(path, env)
-
(オプション機能)トリガーをフィルタ処理で除外してから実行できます。このフィルタを使用して、不要なトリガーの実行によるオーバーヘッドを回避します。トリガーを有効にするには
true
を返し、無効にするにはfalse
を返します。 - getLevel()
-
(オプション機能)トリガーが受け入れる最大レベルを返します。たとえば、次の文では、トリガーはトリガー・システムでの他の設定にかかわらず、すべてのレベルを受け入れることができます。レベルの設定の詳細は、「トリガー・レベルの設定」を参照してください。
function getLevel() { return Level.SEVERE; }
- getTriggerNames(path, env)
-
(オプション機能)ディレクタ・ユーザー・インタフェースでの表示用の
TriggerName
オブジェクトの配列を返します。詳細は、「ジョブ構成のトリガーの公開」を参照してください。ディレクタ・インタフェースでのトリガー名の取得と公開は、ジョブ構成画面でのみ可能です。
プロパティ・ファイルを使用したトリガーの構成の拡張
プロパティ・ファイルでスクリプト・トリガー用の追加の構成を指定できます。すべてのトリガーで使用可能なconfig
という名前の定義済オブジェクトにより、これらのプロパティへのアクセスが行われます。これらのプロパティ・ファイルのEDQのベース・ディレクトリは、triggers
ディレクトリ内のサブディレクトリconfig
です。次にconfig
オブジェクトの便利なメソッドを示します。
EDQトリガー・ポイントについて
この項では、カスタム・トリガーをコールできるEDQ内でのトリガー・ポイントについて説明します。
- ログ・メッセージ
-
ログ・メッセージがシステムで生成されるたびにコールされます。
コンポーネント 説明 Path
/log/
loggername
Env
null
Arguments
java.util.logging.LogRecord
- Syslogメッセージ
-
高レベル
syslog
ログ・メッセージが生成されるたびにコールされます。source
引数は、イベント・ソースの詳細を含むJavaオブジェクトです。これは表示用の文字列に変換できます。コンポーネント 説明 Path
/syslog
Env
env.event
=event_name
env.source
=event_source_as_string
Arguments
event_name
,source
,message
- プロセス開始
-
プロセスの開始時にコールされます。この引数はプロセス構成の情報を含むJavaオブジェクトです。
コンポーネント 説明 Path
/
runtime/engine/task/start
Env
env.project
=project_name
env.projectID
=project_ID
env.missionname
=job_name
env.processname
=process_name
Arguments
Task_context_object
,process_options
注:
タスクを開始するためのパスを指定する場合、トリガー・スクリプトがエラーをスローしないように、トリガー・スクリプトに
addLibrary('runtime')
を含める必要があります。 - プロセス終了
-
プロセスの終了時にコールされます。この引数はプロセス構成の情報を含むJavaオブジェクトです。
コンポーネント 説明 Path
/runtime/engine/task/end
Env
env.project
=project_name
env.projectID
=project_ID
env.missionname
=job_name
env.processname
=process_name
Arguments
Task_context_object
,process_options
注:
タスクを終了するためのパスを指定する場合、トリガー・スクリプトがエラーをスローしないように、トリガー・スクリプトに
addLibrary('runtime')
を含める必要があります。 - 間隔終了
-
通常のプロセスの終了時または間隔モードで実行するプロセスの各間隔の終了時にコールされます。実行済レコードの数などの統計を返します。
コンポーネント 説明 Path
/runtime/engine/interval/end
Env
env.project
=project_name
env.projectID
=project_ID
env.missionname
=job_name
env.processname
=process_name
Arguments
Task_context_object
,process_options
,interval_number (>= 1)
,execution_statistics
- ジョブ・フェーズ前
-
'フェーズ前'に対するジョブ構成の実行でコールされます。
コンポーネント 説明 Path
/missions/phase/pre
Env
env.project
=project_name
env.projectID
=project_ID
env.missionname
=job_name
env.processname
=process_name
Arguments
なし
- ジョブ・フェーズ後
-
'フェーズ後'に対するジョブ構成の実行でコールされます。
コンポーネント 説明 Path
/missions/phase/post
Env
env.project
=project_name
env.projectID
=project_ID
env.missionname
=job_name
env.processname
=process_name
Arguments
なし
- 一致判定
-
EDQが可能性のある一致について決定する必要のあるときにコールされます。これは関係決定トリガーと呼ばれています。関係決定トリガーは、一致を実行するために必要な、関係および決定データを返すメソッドを含むことができます。このトリガー・ポイントは一致レビューに特有です。
コンポーネント 説明 Path
/matchreview/relationship/decision/
Env
env.project
=project_name
Arguments
TriggerInfo
メソッドのリスト。それぞれに1つの関係のデータが含まれます。これらのメソッドの説明は、「TriggerInfoメソッドの理解」を参照してください。 - ケース作成時
-
個々のケース・ソースに属するケースが作成されるときにコールされます。
コンポーネント 説明 Path
/casemanagement/create/<ケース・ソース名>
Env
env.sourceName
= ケース・ソース名
env.caseType = ケースまたはアラートのタイプ
env.currentState = 作成したケースの現在の状態
Arguments
com.datanomic.director.casemanagement.beans.CaseBean
- ケースまたはアラート遷移後
-
ケースまたはアラートが個々のワークフローに対応する次の論理状態に遷移した後にコールされます。
コンポーネント 説明 Path
/casemanagement/transition/<ワークフロー名>/<遷移>
Env
env.sourceName = ケース・ソース名
env.caseType = ケースのタイプ('case'または'alert')
env.currentState = 作成したケースの現在の状態
Arguments
com.datanomic.director.casemanagement.beans.CaseBean,java.util.List<com.datanomic.director.casemanagement.beans.CaseHistoryBean>,comment,restrictingPermission
ここで、
comment
はユーザーが入力するもので、restrictingPermission
はコメントにアクセスするために必要な権限です。 - ケースまたはアラート更新時
-
ケースまたはアラートがユーザーに更新されるときにコールされます。これには、割当て、状態変更、優先度変更または他の編集の実行が含まれます。
コンポーネント 説明 Path
/casemanagement/update/<ケース・ソース名>
Env
env.sourceName = ケース・ソース名
env.caseType = ケースのタイプ('case'または'alert')
env.currentState = 作成したケースの現在の状態
Arguments
com.datanomic.director.casemanagement.beans.CaseBean,java.util.List<com.datanomic.director.casemanagement.beans.CaseHistoryBean>,comment,restrictingPermission
ここで、
comment
はユーザーが入力するもので、restrictingPermission
はコメントにアクセスするために必要な権限です - ケースまたはアラートへのコメント追加時
-
ケースまたはアラートにコメントが追加されるときにコールされます。
コンポーネント 説明 Path
/casemanagement/commented/<ケース・ソース名>
env.sourceName = ケース・ソース名
Env
env.caseType = ケースのタイプ('case'または'alert')
env.currentState = 作成したケースの現在の状態
Arguments
com.datanomic.director.casemanagement.beans.CaseBean,java.util.List<com.datanomic.director.casemanagement.beans.CaseHistoryBean>,comment,restrictingPermission
ここで、
comment
はユーザーが入力するコメントで、restrictingPermission
はコメントにアクセスするために必要な権限です。 - システム更新発生後
-
エスカレーションまたは一括更新の一環としてケースまたはアラートが更新された後にコールされます。
コンポーネント 説明 Path
/casemanagement/systemupdate/<ケース・ソース名>
Env
env.sourceName = ケース・ソース名
env.caseType = ケースのタイプ('case'または'alert')
env.currentState = 作成したケースの現在の状態
Arguments
com.datanomic.director.casemanagement.beans.CaseBean,java.util.List<com.datanomic.director.casemanagement.beans.CaseHistoryBean>,comment,restrictingPermission
ここで、
comment
はユーザーが入力するコメントで、restrictingPermission
はコメントにアクセスするために必要な権限です。
TriggerInfoメソッドの理解
この項では、TriggerInfo
トリガー・ポイントに関連する各メソッドについて説明します。これらのメソッドは、一致レビューで使用されるTriggerInfo
トリガー・ポイントに特有です。
表6-1 TriggerInfoトリガー・ポイントに関連するメソッド
メソッド | 返されるデータ | 説明 |
---|---|---|
|
文字列 |
決定の前に照合ステータスを返します。 |
|
文字列 |
決定の前に関係レビュー・ステータスを返します。 |
|
整数 |
関係IDを返します。 |
|
整数 |
最初のレコードのIDを返します。 |
|
整数 |
最初の入力のIDを返します。 |
|
整数 |
2番目のレコードのIDを返します。 |
|
整数 |
2番目の入力のIDを返します。 |
|
文字列 |
新しい関係のレビュー・ステータスを返します。 |
|
文字列 |
新しい照合ステータスを返します。 |
|
文字列 |
関係を生成したルールの名前を返します。 |
|
文字列 |
コメントを作成したユーザーのユーザー名を返します。 |
|
文字列 |
作成されたコメントを返します。 |
|
日付 |
コメントが作成された日時を返します(コメントが存在する場合)。 |
|
文字列 |
レビューを実行したユーザーの名前を返します。 |
|
日付 |
レビューが実行された日時を返します。 |
|
リスト |
最初のレコードを構成するすべてのソース属性(列)を返します。 |
|
リスト |
2番目のレコードを構成するすべてのソース属性(列)を返します。 |
|
値 |
最初のレコードの指定されたソース属性(列)の値を返します。 |
|
値 |
2番目のレコードの指定されたソース属性(列)の値を返します。 |
トリガー・レベルの設定
すべてのトリガー・ポイントには関連するレベル(java.util.logging.Level
値)があります。デフォルトでは、INFO
よりも低いレベルのトリガー・コールは無視されます。
このレベルを変更する1つの方法は、levels.properties
という名前のファイルをconfig
ディレクトリのtriggers
サブディレクトリに作成することです。このファイルには、デフォルトのレベルと、個別のパス用の1つ以上のオーバーライド・レベルの両方を含めることができます。例6-1では、デフォルトのレベルをFINE
に設定し、パス/runtime/engine/.*
用のレベルをFINER
に設定しています。パターンとレベル・プロパティに対し独自の接頭辞を定義できます。
レベルを変更するもう1つの方法は、トリガーにgetLevel
関数を定義することです。説明は、「スクリプト・トリガーAPIを使用したトリガーの構成」を参照してください。
例6-1 トリガー・レベルの設定
default = fine runtime.pattern = /runtime/engine/.* runtime.level = finer
ジョブ構成のトリガーの公開
トリガーはディレクタのジョブ・フェーズの構成中に、ジョブでの使用のために選択されます。これはジョブ・フェーズの前または後に実行するように設定することができます。構成画面でトリガーを選択できるようにするには、各トリガーが名前のリストを返すことができる必要があります。これにより必要に応じて1つのトリガーが複数のタスクを実行できるようになります。
トリガー名には次のコンポーネントがあります。
-
トリガーのrun機能に渡される、内部ID。この機能の説明は、「スクリプト・トリガーAPIを使用したトリガーの構成」を参照してください。
-
表示可能なラベル
-
グループ名
同じグループのトリガー名は、ジョブ構成画面で1つのノードとして表示されます。
新しいトリガー名を作成するには、次のようにします。
var n1 = new TriggerName(id, label) n1.group = "My group";
トリガーからトリガー名を返すには、次のようにします。
トリガー名を返すには、次の例に示すように、getTriggerNames
関数を使用します。
function getTriggerNames(path, env) { var n1 = new TriggerName(id1, label1); var n2 = new TriggerName(id2, label2); ... n1.group = "My group"; n2.group = "My group"; ... return [n1, n2 ...] }
getTriggerNames
の詳細は、「スクリプト・トリガーAPIを使用したトリガーの構成」を参照してください。
トリガーの例
次に、カスタム・トリガーを使用する方法の例を示します。
注:
このドキュメントでの例はJavaScriptですが、同じAPIがGroovyでも使用可能です。
- 例1 トリガーを使用したJMS経由でのログ・メッセージの送信
-
この例では、ロギング・ライブラリが、メッセージのフォーマット指定および出力に使用できるロギング・オブジェクトをインポートします。JMSプロパティ・ファイルはEDQ構成ディレクトリの
triggers/config/jms/jms.properties
からロードされます。// Test trigger for task running with JMS addLibrary("logging"); addLibrary("jms"); function getPath() { return "/log/com\.datanomic\..*"; } function run(path, id, env, logrecord) { var pfiles = config.getTriggerConfigFiles("jms", "jms\\.properties"); if (pfiles.length > 0) { var props = config.loadProps(pfiles[0]); var jms = JMS.open(props); var msg = logging.format(logrecord); var len = msg.length; // Remove trailing newlines while (len > 0) { var c = msg.charAt(len - 1); if (c != '\n' && c != '\r') { break; } len--; } jms.send(msg.substring(0, len)); jms.close(); } }
- 例2 トリガーを使用したJMS経由でのSyslogメッセージの送信
-
この例では、最初の行(
#! id : syslog
)の特別なid
ディレクティブがトリガーの内部IDを定義します。同じIDで複数のトリガー定義がある場合、後のものが前のものを置き換えます。標準のEDQインストールでは、標準のロギングAPI経由でメッセージをログに記録する定義済syslog
トリガーがあります。この例でのid
ディレクティブの追加により、JMSsyslog
トリガーが定義済トリガーを置き換えます。#! id : syslog // Test trigger for task running with JMS addLibrary("logging"); addLibrary("jms"); function getPath() { return "/syslog"; } function getLevel() { return Level.SEVERE; } function run(path, id, env, level, event, source, message) { var pfiles = config.getTriggerConfigFiles("jms", "jms\\.properties"); var props = null; if (pfiles.length == 0) { logger.log(Level.WARNING, "syslogger called but no properties"); } else { props = config.loadProps(pfiles[0]); var jms = JMS.open(props); var xml = <syslog level={level}><source>{source}</source><message>{message}</message></syslog> logger.log(Level.INFO, "xml = {0}", xml.toXMLString()); jms.send(xml.toXMLString()); jms.close(); } }
- 例3 ミッション・フェーズ通知用のトリガーの使用
-
この例では、1組のトリガー名が定義され、ジョブ構成画面に表示されます。この例ではトリガーがログ・メッセージを書き込みますが、JMS通知を送信するように構成することもできます。
// Test trigger for misssion phase notification addLibrary("logging"); function getPath() { return "/missions/phase/.*"; } function run(path, id, env) { logger.log(Level.INFO, "phase called with path {0} and id {1}", path, id); } function getTriggerNames(path, env) { var n1 = new TriggerName("logme", "logme2"); n1.group = "logmegroup"; var n2 = new TriggerName("n2", "n2"); n2.group = "logmegroup"; return [n1, n2]; }