6 トリガーの使用

この章では、Enterprise Data Qualityでトリガー機能を使用する方法について説明します。このドキュメントでは、トリガーのインストール場所、呼び出し方法、および使用方法について説明します。

この章のトピックは、次のとおりです:

トリガー機能の概要

Enterprise Data Qualityのトリガーは、EDQシステムの様々なトリガー・ポイントでコールできるスクリプト(JavaScriptまたはGroovy)です。トリガーには、定義済トリガーとカスタム・トリガーの2つのタイプがあります。

定義済トリガーについて

定義済トリガーはEDQインストールに付属しています。ディレクタ・ユーザー・インタフェースに表示され、ジョブ構成で使用されて、ジョブの開始、Webサービスの停止、電子メール通知の送信、およびジョブ内から別のジョブの実行を行うことができます。ディレクタ・ユーザーはトリガー・ポイント(ジョブの開始、ジョブの終了、またはその両方)で実行するようにこれらのトリガーを設定できます。ディレクタのオンライン・ヘルプ・システムで定義済トリガーの詳細を参照できます。

カスタム・トリガーについて

カスタム・トリガーはJavascriptまたはGroovyのスキルのある人により作成され、特定のワークフローの目的を達成するようにEDQの機能を拡張することができます。カスタム・トリガーを使用して次のようなタスクを実行できます。

  • 電子メール・メッセージの送信

  • JMSメッセージの送信

  • Webサービスのコール

  • ファイルの記述

  • テキスト・メッセージの送信

次の定義済トリガー・ポイントでカスタム・トリガーを実行することができます。

  • ジョブ・フェーズの実行前

  • ジョブ・フェーズの実行後

  • 一致決定の作成時

  • ケース管理での遷移の作成時

  • ジョブの完了時

これらの各トリガー・ポイントには、特別なAPIによりトリガーに渡される、一意のパスと定義済の引数のセットがあります。詳細は、「EDQトリガー・ポイントについて」を参照してください。

カスタム・トリガーについては、このドキュメントの後半で説明します。

トリガーの使用に必要なスキル

EDQでカスタム・トリガーを作成してデプロイするには、JavascriptまたはGroovyの知識が必要です。

トリガーの格納

カスタム・トリガーは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を返します。

path

トリガーのパス。

env

1つ以上のキー/値のペアの形式でのトリガー環境です。envの入力は、トリガー・ポイントごとに固有です。これらの値はスクリプト内でenvオブジェクトのプロパティとして公開されます。ほとんどのトリガー・ポイントは関連するEDQプロジェクトIDおよびプロジェクト名で渡されます。次の例では、トリガーは関連プロジェクトの名前が"My project"であるときのみ有効になります。

function filter(path, env) {
  return env.project == 'My project';
}
getLevel()

(オプション機能)トリガーが受け入れる最大レベルを返します。たとえば、次の文では、トリガーはトリガー・システムでの他の設定にかかわらず、すべてのレベルを受け入れることができます。レベルの設定の詳細は、「トリガー・レベルの設定」を参照してください。

function getLevel() {
  return Level.SEVERE;
}
getTriggerNames(path, env)

(オプション機能)ディレクタ・ユーザー・インタフェースでの表示用のTriggerNameオブジェクトの配列を返します。詳細は、「ジョブ構成のトリガーの公開」を参照してください。ディレクタ・インタフェースでのトリガー名の取得と公開は、ジョブ構成画面でのみ可能です。

プロパティ・ファイルを使用したトリガーの構成の拡張

プロパティ・ファイルでスクリプト・トリガー用の追加の構成を指定できます。すべてのトリガーで使用可能なconfigという名前の定義済オブジェクトにより、これらのプロパティへのアクセスが行われます。これらのプロパティ・ファイルのEDQのベース・ディレクトリは、triggersディレクトリ内のサブディレクトリconfigです。次にconfigオブジェクトの便利なメソッドを示します。

config.getTriggerConfigFiles(base, pattern)

名前がtriggers/configディレクトリ内の指定したディレクトリで検索パターンに一致するファイル・オブジェクトの配列を返します。

base

triggers/configディレクトリ内のディレクトリの名前。

pattern

一致させる検索パターンを定義する正規表現(regex)。

config.loadProps(file)

指定したJavaプロパティ・ファイルをロードし、JavaScriptオブジェクトとして返します。

file

Javaプロパティ・ファイルの名前。

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トリガー・ポイントに関連するメソッド

メソッド 返されるデータ 説明

getPreviousMatchStatus()

文字列

決定の前に照合ステータスを返します。

getPreviousRealtionshipReviewStatus()

文字列

決定の前に関係レビュー・ステータスを返します。

getRelationshipId()

整数

関係IDを返します。

getRecordId()

整数

最初のレコードのIDを返します。

getInputId()

整数

最初の入力のIDを返します。

getRelatedRecordId()

整数

2番目のレコードのIDを返します。

getRelatedInputId()

整数

2番目の入力のIDを返します。

getReviewStatus()

文字列

新しい関係のレビュー・ステータスを返します。

getMatchStatus()

文字列

新しい照合ステータスを返します。

getRuleName()

文字列

関係を生成したルールの名前を返します。

getCommentUser()

文字列

コメントを作成したユーザーのユーザー名を返します。

getReviewComment()

文字列

作成されたコメントを返します。

getCommentDate()

日付

コメントが作成された日時を返します(コメントが存在する場合)。

getReviewedUser()

文字列

レビューを実行したユーザーの名前を返します。

getReviewDate()

日付

レビューが実行された日時を返します。

SourceAttribute getRecordSourceAttributes()

リスト

最初のレコードを構成するすべてのソース属性(列)を返します。

SourceAttribute getRelatedRecordSourceAttributes()

リスト

2番目のレコードを構成するすべてのソース属性(列)を返します。

getRecordAttributeValue(SourceAttribute sa)

最初のレコードの指定されたソース属性(列)の値を返します。

getRelatedRecordAttributeValue(SourceAttribute sa)

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

トリガーでのJMSの使用

トリガー・ファイル内でJava Message Service (JMS)を有効にするには、次の手順に従います。

  1. 内部JavaScript JMSライブラリをロードします。
    addLibrary("jms");
    
  2. JMS構成を定義するプロパティをロードします。これらのプロパティは、EDQ構成ディレクトリに含まれている標準realtime.propertiesファイルからのJMS設定で拡張されます。このファイルのデフォルト・バージョンは、EDQにバンドルされているオープンソースのActiveMQ Message Brokerのプロパティを定義します。最小限、トリガーは、使用するJMSトピックまたはキューに名前を付ける、destinationプロパティの値を提供する必要があります。
  3. JMSオブジェクトを作成します。
    var jms = JMS.open(props);
    
  4. テキスト・メッセージを送信します。
    jms.send(str)
    
  5. スクリプト・オブジェクトから作成されたJMSマップ・メッセージを送信します。
    jms.sendMap(jsobj)
    
  6. テキスト・メッセージを作成します。送信前にプロパティおよびヘッダー値をメッセージに設定することができます。
    var msg = jms.createTextMessage(str)
    
  7. マップ・メッセージを作成します。送信前にプロパティおよびヘッダー値をメッセージに設定することができます。
    var msg = jms.createMapMessage(jsobj)
    
  8. 先行する2つのメソッドのいずれかにより作成されたメッセージを送信します。
    jms.sendMessage(msg)

ジョブ構成のトリガーの公開

トリガーはディレクタのジョブ・フェーズの構成中に、ジョブでの使用のために選択されます。これはジョブ・フェーズの前または後に実行するように設定することができます。構成画面でトリガーを選択できるようにするには、各トリガーが名前のリストを返すことができる必要があります。これにより必要に応じて1つのトリガーが複数のタスクを実行できるようになります。

トリガー名には次のコンポーネントがあります。

同じグループのトリガー名は、ジョブ構成画面で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ディレクティブの追加により、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();
  }
}
例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];
}