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/loggernameEnvnullArgumentsjava.util.logging.LogRecord - Syslogメッセージ
-
高レベル
syslogログ・メッセージが生成されるたびにコールされます。source引数は、イベント・ソースの詳細を含むJavaオブジェクトです。これは表示用の文字列に変換できます。コンポーネント 説明 Path/syslogEnvenv.event=event_nameenv.source=event_source_as_stringArgumentsevent_name,source,message - プロセス開始
-
プロセスの開始時にコールされます。この引数はプロセス構成の情報を含むJavaオブジェクトです。
コンポーネント 説明 Path/
runtime/engine/task/startEnvenv.project=project_nameenv.projectID=project_IDenv.missionname=job_nameenv.processname=process_nameArgumentsTask_context_object,process_options注:
タスクを開始するためのパスを指定する場合、トリガー・スクリプトがエラーをスローしないように、トリガー・スクリプトに
addLibrary('runtime')を含める必要があります。 - プロセス終了
-
プロセスの終了時にコールされます。この引数はプロセス構成の情報を含むJavaオブジェクトです。
コンポーネント 説明 Path/runtime/engine/task/endEnvenv.project=project_nameenv.projectID=project_IDenv.missionname=job_nameenv.processname=process_nameArgumentsTask_context_object,process_options注:
タスクを終了するためのパスを指定する場合、トリガー・スクリプトがエラーをスローしないように、トリガー・スクリプトに
addLibrary('runtime')を含める必要があります。 - 間隔終了
-
通常のプロセスの終了時または間隔モードで実行するプロセスの各間隔の終了時にコールされます。実行済レコードの数などの統計を返します。
コンポーネント 説明 Path/runtime/engine/interval/endEnvenv.project=project_nameenv.projectID=project_IDenv.missionname=job_nameenv.processname=process_nameArgumentsTask_context_object,process_options,interval_number (>= 1),execution_statistics - ジョブ・フェーズ前
-
'フェーズ前'に対するジョブ構成の実行でコールされます。
コンポーネント 説明 Path/missions/phase/preEnvenv.project=project_nameenv.projectID=project_IDenv.missionname=job_nameenv.processname=process_nameArgumentsなし
- ジョブ・フェーズ後
-
'フェーズ後'に対するジョブ構成の実行でコールされます。
コンポーネント 説明 Path/missions/phase/postEnvenv.project=project_nameenv.projectID=project_IDenv.missionname=job_nameenv.processname=process_nameArgumentsなし
- 一致判定
-
EDQが可能性のある一致について決定する必要のあるときにコールされます。これは関係決定トリガーと呼ばれています。関係決定トリガーは、一致を実行するために必要な、関係および決定データを返すメソッドを含むことができます。このトリガー・ポイントは一致レビューに特有です。
コンポーネント 説明 Path/matchreview/relationship/decision/Envenv.project=project_nameArgumentsTriggerInfoメソッドのリスト。それぞれに1つの関係のデータが含まれます。これらのメソッドの説明は、「TriggerInfoメソッドの理解」を参照してください。 - ケース作成時
-
個々のケース・ソースに属するケースが作成されるときにコールされます。
コンポーネント 説明 Path/casemanagement/create/<ケース・ソース名>Envenv.sourceName= ケース・ソース名env.caseType = ケースまたはアラートのタイプenv.currentState = 作成したケースの現在の状態Argumentscom.datanomic.director.casemanagement.beans.CaseBean - ケースまたはアラート遷移後
-
ケースまたはアラートが個々のワークフローに対応する次の論理状態に遷移した後にコールされます。
コンポーネント 説明 Path/casemanagement/transition/<ワークフロー名>/<遷移>Envenv.sourceName = ケース・ソース名env.caseType = ケースのタイプ('case'または'alert')env.currentState = 作成したケースの現在の状態Argumentscom.datanomic.director.casemanagement.beans.CaseBean,java.util.List<com.datanomic.director.casemanagement.beans.CaseHistoryBean>,comment,restrictingPermissionここで、
commentはユーザーが入力するもので、restrictingPermissionはコメントにアクセスするために必要な権限です。 - ケースまたはアラート更新時
-
ケースまたはアラートがユーザーに更新されるときにコールされます。これには、割当て、状態変更、優先度変更または他の編集の実行が含まれます。
コンポーネント 説明 Path/casemanagement/update/<ケース・ソース名>Envenv.sourceName = ケース・ソース名env.caseType = ケースのタイプ('case'または'alert')env.currentState = 作成したケースの現在の状態Argumentscom.datanomic.director.casemanagement.beans.CaseBean,java.util.List<com.datanomic.director.casemanagement.beans.CaseHistoryBean>,comment,restrictingPermissionここで、
commentはユーザーが入力するもので、restrictingPermissionはコメントにアクセスするために必要な権限です - ケースまたはアラートへのコメント追加時
-
ケースまたはアラートにコメントが追加されるときにコールされます。
コンポーネント 説明 Path/casemanagement/commented/<ケース・ソース名>env.sourceName = ケース・ソース名Envenv.caseType = ケースのタイプ('case'または'alert')env.currentState = 作成したケースの現在の状態Argumentscom.datanomic.director.casemanagement.beans.CaseBean,java.util.List<com.datanomic.director.casemanagement.beans.CaseHistoryBean>,comment,restrictingPermissionここで、
commentはユーザーが入力するコメントで、restrictingPermissionはコメントにアクセスするために必要な権限です。 - システム更新発生後
-
エスカレーションまたは一括更新の一環としてケースまたはアラートが更新された後にコールされます。
コンポーネント 説明 Path/casemanagement/systemupdate/<ケース・ソース名>Envenv.sourceName = ケース・ソース名env.caseType = ケースのタイプ('case'または'alert')env.currentState = 作成したケースの現在の状態Argumentscom.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]; }