この章では、Oracle Enterprise Data Qualityでトリガー機能を使用する方法について説明します。このドキュメントでは、トリガーのインストール場所、呼び出し方法、および使用方法について説明します。
この章の内容は以下のとおりです。
Oracle Enterprise Data Qualityのトリガーは、EDQシステムの様々なトリガー・ポイントでコールできるスクリプト(JavaScriptまたはGroovy)です。トリガーには、定義済トリガーとカスタム・トリガーの2つのタイプがあります。
定義済トリガーはEDQインストールに付属しています。ディレクタ・ユーザー・インタフェースに表示され、ジョブ構成で使用されて、ジョブの開始、Webサービスの停止、電子メール通知の送信、およびジョブ内から別のジョブの実行を行うことができます。ディレクタ・ユーザーはトリガー・ポイント(ジョブの開始、ジョブの終了、またはその両方)で実行するようにこれらのトリガーを設定できます。ディレクタのオンライン・ヘルプ・システムで定義済トリガーの詳細を参照できます。
カスタム・トリガーはJavascriptまたはGroovyのスキルのある人により作成され、特定のワークフローの目的を達成するようにEDQの機能を拡張することができます。カスタム・トリガーを使用して次のようなタスクを実行できます。
電子メール・メッセージの送信
JMSメッセージの送信
Webサービスのコール
ファイルの作成
テキスト・メッセージの送信
次の定義済トリガー・ポイントでカスタム・トリガーを実行することができます。
ジョブ・フェーズの実行前
ジョブ・フェーズの実行後
一致決定の作成時
ケース管理での遷移の作成時
ジョブの完了時
これらの各トリガー・ポイントには、特別なAPIによりトリガーに渡される、一意のパスと定義済の引数のセットがあります。詳細は、第6.6項「EDQトリガー・ポイントについて」を参照してください
カスタム・トリガーについては、このドキュメントの後半で説明します。
EDQでカスタム・トリガーを作成してデプロイするには、JavascriptまたはGroovyの知識が必要です。
カスタム・トリガーはEDQのconfig
(構成)ディレクトリのtriggers
サブディレクトリに格納される必要があります。新しいまたは更新されたトリガーは自動的にロードされ、システムを再起動する必要はありません。
スクリプトAPIの機能を使用してトリガーを作成できます。これらの機能はトリガー・コードで定義されます。このドキュメントでの例はJavaScriptですが、同じAPIがGroovyでも使用可能です。
次にこのAPIでの各機能について説明します。
トリガーが処理するパスを定義する文字列を返します。各トリガー・ポイントには一意のパスがあります。トリガー・ポイントに到達すると、指定したパスに一致するトリガーが実行されます。トリガー・ポイントの詳細は、第6.6項「EDQトリガー・ポイントについて」を参照してください
この機能は正規表現です。たとえば、パス/log/com\.datanomic\..*
はログ出力名に文字列datanomic
が含まれるログ出力パスと一致します(つまり、"datanomic"という語がEDQ用の別名になっている、EDQに定義されたログ出力)。
トリガーを実行します。これらの各変数に対するトリガーAPIによる戻り値の詳細は、第6.6項「EDQトリガー・ポイントについて」を参照してください
トリガーのパスで、/runtime/engine/interval/end
などです。
トリガーのIDIDはトリガーがディレクタ・ユーザー・インタフェースで構成されるときに設定されます。このIDは単純なトリガーに対してはnullです。
1つ以上のキー/値のペアの形式でのトリガー環境で、env.project = project name
などです。env
入力はトリガー・ポイントに特有です。これらの値はスクリプト内でenv
オブジェクトのプロパティとして公開されます。ほとんどのトリガー・ポイントは関連するEDQプロジェクトIDおよびプロジェクト名で渡されます。
追加の引数はトリガー・ポイントに特有です。たとえば、Interval end
トリガー・ポイントは、タスク・コンテキスト・オブジェクト、プロセス・オプション、間隔の数(>= 1)、実行統計を返します。
(オプション機能)トリガーをフィルタ処理で除外してから実行できます。このフィルタを使用して、不要なトリガーの実行によるオーバーヘッドを回避します。トリガーを有効にするにはtrue
を返し、無効にするにはfalse
を返します。
トリガーのパス。
1つ以上のキー/値のペアの形式でのトリガー環境です。env
入力はトリガー・ポイントに特有です。これらの値はスクリプト内でenv
オブジェクトのプロパティとして公開されます。ほとんどのトリガー・ポイントは関連するEDQプロジェクトIDおよびプロジェクト名で渡されます。次の例では、トリガーは関連プロジェクトの名前が"My project"であるときのみ有効になります。
function filter(path, env) { return env.project == 'My project'; }
(オプション機能)トリガーが受け入れる最大レベルを返します。たとえば、次の文では、トリガーはトリガー・システムでの他の設定にかかわらず、すべてのレベルを受け入れることができます。レベルの設定の詳細は、第6.8項「トリガー・レベルの設定」を参照してください
function getLevel() { return Level.SEVERE; }
(オプション機能)ディレクタ・ユーザー・インタフェースでの表示用のTriggerName
オブジェクトの配列を返します。詳細は、第6.10項「ジョブ構成のトリガーの公開」を参照してください。トリガー名の取得とディレクタ・インタフェースでの公開は、ジョブ構成画面でのみ可能です。
プロパティ・ファイルでスクリプト・トリガー用の追加の構成を指定できます。すべてのトリガーで使用可能なconfig
という名前の定義済オブジェクトにより、これらのプロパティへのアクセスが行われます。これらのプロパティ・ファイルのEDQのベース・ディレクトリは、triggers
ディレクトリ内のサブディレクトリconfig
です。次にconfig
オブジェクトの便利なメソッドを示します。
名前がtriggers/config
ディレクトリ内の指定したディレクトリで検索パターンに一致するファイル・オブジェクトの配列を返します。
triggers/config
ディレクトリ内のディレクトリの名前。
一致させる検索パターンを定義する正規表現(regex)。
指定したJavaプロパティ・ファイルをロードし、JavaScriptオブジェクトとして返します。
Javaプロパティ・ファイルの名前。
この項では、カスタム・トリガーをコールできるEDQ内でのトリガー・ポイントについて説明します。
ログ・メッセージがシステムで生成されるたびにコールされます。
コンポーネント | 説明 |
---|---|
Path |
/log/ loggername |
Env |
null |
Arguments |
java.util.logging.LogRecord |
高レベルsyslog
ログ・メッセージが生成されるたびにコールされます。source
引数はイベント・ソースの詳細を含むJavaオブジェクトです。これは表示用の文字列に変換できます。
コンポーネント | 説明 |
---|---|
Path |
/syslog |
Env |
env.event = event_name
|
Arguments |
event_name , source , message |
プロセスの開始時にコールされます。この引数はプロセス構成の情報を含むJavaオブジェクトです。
コンポーネント | 説明 |
---|---|
Path |
/runtime/engine/task/start |
Env |
env.project = project_name
|
Arguments |
Task_context_object , process_options |
注意: タスクを開始するためのパスを指定する場合、トリガー・スクリプトがエラーをスローしないように、トリガー・スクリプトにaddLibrary('runtime') を含める必要があります。 |
プロセスの終了時にコールされます。この引数はプロセス構成の情報を含むJavaオブジェクトです。
コンポーネント | 説明 |
---|---|
Path |
/runtime/engine/task/end |
Env |
env.project = project_name
|
Arguments |
Task_context_object , process_options |
注意: タスクを終了するためのパスを指定する場合、トリガー・スクリプトがエラーをスローしないように、トリガー・スクリプトにaddLibrary('runtime') を含める必要があります。 |
通常のプロセスの終了時または間隔モードで実行するプロセスの各間隔の終了時にコールされます。実行済レコードの数などの統計を返します。
コンポーネント | 説明 |
---|---|
Path |
/runtime/engine/interval/end |
Env |
env.project = project_name
|
Arguments |
Task_context_object , process_options , interval_number (>= 1) , execution_statistics |
'フェーズ前'に対するジョブ構成の実行でコールされます。
コンポーネント | 説明 |
---|---|
Path |
/missions/phase/pre |
Env |
env.project = project_name
|
Arguments |
なし |
'フェーズ後'に対するジョブ構成の実行でコールされます。
コンポーネント | 説明 |
---|---|
Path |
/missions/phase/post |
Env |
env.project = project_name
|
Arguments |
なし |
EDQが可能性のある一致について決定する必要のあるときにコールされます。これは関係決定トリガーと呼ばれています。関係決定トリガーは、一致を実行するために必要な、関係および決定データを返すメソッドを含むことができます。このトリガー・ポイントは一致レビューに特有です。
コンポーネント | 説明 |
---|---|
Path |
/matchreview/relationship/decision/ |
Env |
env.project = project_name |
Arguments |
TriggerInfo メソッドのリスト。それぞれに1つの関係のデータが含まれます。これらのメソッドの詳細は、第6.7項を参照してください。 |
個々のケース・ソースに属するケースが作成されるときにコールされます。
コンポーネント | 説明 |
---|---|
Path |
/casemanagement/create/<ケース・ソース名> |
Env |
env.sourceName = ケース・ソース名
|
Arguments |
com.datanomic.director.casemanagement.beans.CaseBean |
ケースまたはアラートが個々のワークフローに対応する次の論理状態に遷移した後にコールされます。
コンポーネント | 説明 |
---|---|
Path |
/casemanagement/transition/<ワークフロー名>/<遷移> |
Env |
env.sourceName = ケース・ソース名
|
Arguments |
com.datanomic.director.casemanagement.beans.CaseBean,java.util.List<com.datanomic.director.casemanagement.beans.CaseHistoryBean>,comment,restrictingPermission
ここで、 |
ケースまたはアラートがユーザーに更新されるときにコールされます。これには、割当て、状態変更、優先度変更または他の編集の実行が含まれます。
コンポーネント | 説明 |
---|---|
Path |
/casemanagement/update/<ケース・ソース名> |
Env |
env.sourceName = ケース・ソース名
|
Arguments |
com.datanomic.director.casemanagement.beans.CaseBean,java.util.List<com.datanomic.director.casemanagement.beans.CaseHistoryBean>,comment,restrictingPermission
ここで、 |
ケースまたはアラートにコメントが追加されるときにコールされます。
コンポーネント | 説明 |
---|---|
Path |
/casemanagement/commented/<ケース・ソース名> |
env.sourceName = ケース・ソース名
|
env.caseType = ケースのタイプ('case'または'alert')
|
Arguments |
com.datanomic.director.casemanagement.beans.CaseBean,java.util.List<com.datanomic.director.casemanagement.beans.CaseHistoryBean>,comment,restrictingPermission
ここで、 |
エスカレーションまたは一括更新の一環としてケースまたはアラートが更新された後にコールされます。
コンポーネント | 説明 |
---|---|
Path |
/casemanagement/systemupdate/<ケース・ソース名> |
Env |
env.sourceName = ケース・ソース名
|
Arguments |
com.datanomic.director.casemanagement.beans.CaseBean,java.util.List<com.datanomic.director.casemanagement.beans.CaseHistoryBean>,comment,restrictingPermission
ここで、 |
この項では、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
関数を定義することです。詳細は、第6.4項を参照してください。
トリガー・ファイル内でJava Message Service (JMS)を有効にするには、次の手順に従います。
内部JavaScript JMSライブラリをロードします。
addLibrary("jms");
JMS構成を定義するプロパティをロードします。これらのプロパティは、EDQ構成ディレクトリに含まれている標準realtime.properties
ファイルからのJMS設定で拡張されます。このファイルのデフォルト・バージョンは、EDQにバンドルされているオープンソースのActiveMQ Message Brokerのプロパティを定義します。最小限、トリガーは、使用するJMSトピックまたはキューに名前を付ける、destination
プロパティの値を提供する必要があります。
JMSオブジェクトを作成します。
var jms = JMS.open(props);
テキスト・メッセージを送信します。
jms.send(str)
スクリプト・オブジェクトから作成されたJMSマップ・メッセージを送信します。
jms.sendMap(jsobj)
テキスト・メッセージを作成します。送信前にプロパティおよびヘッダー値をメッセージに設定することができます。
var msg = jms.createTextMessage(str)
マップ・メッセージを作成します。送信前にプロパティおよびヘッダー値をメッセージに設定することができます。
var msg = jms.createMapMessage(jsobj)
先行する2つのメソッドのいずれかにより作成されたメッセージを送信します。
jms.sendMessage(msg)
トリガーはディレクタのジョブ・フェーズの構成中に、ジョブでの使用のために選択されます。これはジョブ・フェーズの前または後に実行するように設定することができます。構成画面でトリガーを選択できるようにするには、各トリガーが名前のリストを返すことができる必要があります。これにより必要に応じて1つのトリガーが複数のタスクを実行できるようになります。
トリガー名には次のコンポーネントがあります。
トリガーのrun機能に渡される、内部ID。この機能の詳細は、第6.4項を参照してください。
表示可能なラベル
グループ名
同じグループのトリガー名は、ジョブ構成画面で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
の詳細は、第6.4項を参照してください。
次に、カスタム・トリガーを使用する方法の例を示します。
注意: このドキュメントでの例はJavaScriptですが、同じAPIがGroovyでも使用可能です。 |
この例では、ロギング・ライブラリが、メッセージのフォーマット指定および出力に使用できるロギング・オブジェクトをインポートします。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(); } }
この例では、最初の行(#! id : syslog
)の特別なid
ディレクティブがトリガーの内部IDを定義します。同じIDで複数のトリガー定義がある場合、後のものが前のものを置き換えます。標準のEDQインストールでは、標準のロギングAPI経由でメッセージをログに記録する定義済syslog
トリガーがあります。この例でのid
ディレクティブの追加により、JMS syslog
トリガーが定義済トリガーを置き換えます。
#! 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(); } }
この例では、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]; }