トリガーの作成
接続されたシステムで購読しているイベントが発生すると、トリガーはワークフローを起動します。これによってユーザーは複雑なビジネスプロセスを自動化でき、ワークフローを毎回手動で実行する必要がなくなります。
たとえば、次の図には、プロジェクトから作成可能なトリガーのリストが表示されています。
トリガーには次の 2 つのタイプがあります。
• ポーリングトリガー
• Webhook トリガー
ポーリングトリガー
一定間隔で、定期的に更新の有無をチェックします。トリガーリストで、すべてのポーリングトリガーに時計のアイコンが表示されています。ポーリングトリガーを作成するには、次の手順に従います。
1. コマンドプロンプトから、次のコマンドを実行します。
a. cd <user project root directory>
b. flow add trigger -p
add trigger コマンドでは次のオプションを使用できます。
オプション | 説明 | データ型 |
|---|---|---|
--version | バージョン番号を表示します。 | [ブール] |
--help | ヘルプを表示します。 | [ブール] |
--parentDir,-d | プロジェクトの親ディレクトリ。 | [デフォルト: "."] |
--polling,-p | これがポーリングトリガーであることを示します。 | [デフォルト: false] |
-- artifactVersion,-v | 作成する成果物のバージョン。 | [デフォルト: "v1"] |
2. add trigger コマンドを実行すると、入力と出力が格納されるメタデータファイル trigger.json と、コードのロジックが格納される index.js JavaScript ファイルが作成されます。これらのファイルはディレクトリ <プロジェクトディレクトリ>\trigger\poll\<トリガー名>\v1 の下に作成されます。
 | デフォルトでは、Webhook トリガーが作成されます。ポーリングトリガーを作成するには、-p オプションを使用します。 |
trigger.json ファイルの各オプションについて以下の表で説明します。
オプション | 説明 |
|---|---|
type (必須) | オブジェクトのタイプは必ず JSON でなければなりません。 |
title (必須) | トリガーを選択できるようにするリストのラベル。 |
description | トリガーの短い説明。 |
properties | トリガーコンフィギュレーションの入力フォームフィールドの定義に使用します。これには以下の定義が含まれています。 • トリガーコンフィギュレーションウィンドウに表示される入力フィールド • トリガーサービスリストに表示されるイベント名。 |
トリガー定義では、最初に、すべてのトリガーイベントに共通する authentication や customFilters などの共通プロパティのセットを指定します。すべてのプロパティが type、title、description プロパティを持ちます。外部システムは通常は複数のイベントを公開しているので、イベントを oneOf で表す必要があります。oneOf 内の各オブジェクトは単一のイベントに対応します。システムがイベントを 1 つだけ公開している場合、oneOf ブロックは必要ありません。
oneOf 配列には、1 つ以上のイベントが含まれます。各イベントは JSON オブジェクトです。次の例は、2 つのイベント (Event1 と Event2) があるサービスに適用されます。各イベントでは、入力に対して異なる数とタイプが必要になる場合があることに注意してください。
[{
"type": "object",
"title": "Event1",
"description": "Event 1 description",
"properties": {
"event": {
"type": "string",
"title": "Trigger",
"enum": [
"Event1"
],
"propertyOrder": 2,
"options": {
"hidden": true
}
},
"input_for_event1": {
"title": "input for event 1 ",
"minLength": 1,
"type": "string",
"propertyOrder": 3,
"description": "input required by event 1"
}
}
},
{
"type": "object",
"title": "Event2",
"description": "Event 2 description",
"properties": {
"event": {
"type": "string",
"title": "Trigger",
"enum": [
"Event1"
],
"propertyOrder": 4,
"options": {
"hidden": true
}
},
"input_for_event2": {
"title": "input for event 2 ",
"minLength": 1,
"type": "string",
"propertyOrder": 5,
"description": "input required by event 2"
}
}
}
]
"type": "object",
"title": "Event1",
"description": "Event 1 description",
"properties": {
"event": {
"type": "string",
"title": "Trigger",
"enum": [
"Event1"
],
"propertyOrder": 2,
"options": {
"hidden": true
}
},
"input_for_event1": {
"title": "input for event 1 ",
"minLength": 1,
"type": "string",
"propertyOrder": 3,
"description": "input required by event 1"
}
}
},
{
"type": "object",
"title": "Event2",
"description": "Event 2 description",
"properties": {
"event": {
"type": "string",
"title": "Trigger",
"enum": [
"Event1"
],
"propertyOrder": 4,
"options": {
"hidden": true
}
},
"input_for_event2": {
"title": "input for event 2 ",
"minLength": 1,
"type": "string",
"propertyOrder": 5,
"description": "input required by event 2"
}
}
}
]
これらの各イベントには、出力プロパティに対応する出力スキーマが必要です。たとえば、上記のように 2 つのイベントがある場合、出力には、Event1 と Event2 のそれぞれに対して次のようなスキーマが必要です。
"output": {
"Event1": {
"type": "object",
"properties": {
"opfield1": {
"type": "string",
"title": "Output field 1"
},
"opfield2": {
"type": "string",
"title": "Output field 2"
}
}
},
"Event2": {
"type": "object",
"properties": {
"opfield3": {
"type": "string",
"title": "Output field 3"
},
"opfield4": {
"type": "string",
"title": "Output field 4"
}
}
}
}
"Event1": {
"type": "object",
"properties": {
"opfield1": {
"type": "string",
"title": "Output field 1"
},
"opfield2": {
"type": "string",
"title": "Output field 2"
}
}
},
"Event2": {
"type": "object",
"properties": {
"opfield3": {
"type": "string",
"title": "Output field 3"
},
"opfield4": {
"type": "string",
"title": "Output field 4"
}
}
}
}
ポーリングトリガーの index.js ファイルの構造は次のとおりです。
module.exports = Trigger
Trigger.execute = function (input, options, output) {
}
Trigger.validate = function (input, options, output) {
}
Trigger.activate = (input, options, output) {
}
Trigger.execute = function (input, options, output) {
}
Trigger.validate = function (input, options, output) {
}
Trigger.activate = (input, options, output) {
}
validate メソッドのコードは execute メソッドとよく似ています。コードについてはサンプルを参照してください。
ポーリングトリガーで使用されるメソッドは以下のとおりです。
• execute メソッド - 定期的に呼び出されます。この間隔は ThingWorx Flow サーバーで設定します。execute メソッドは、入力からの接続情報を使用して ThingWorx Flow サーバーから外部システムに接続し、データをフェッチします。これは option オブジェクトの API を使用して、フェッチしたオブジェクトに関する情報をキャッシュし、新しい情報があるかどうかを判別します。
options オブジェクトは meta プロパティを使用して、execute メソッドの各呼び出しの間に使用可能な情報を維持します。
一般的に使用可能な API の詳細については、
ThingWorx Flow コネクタ SDKのセクションを参照してください。
options オブジェクトの setMeta メソッドを使用して、現在または以前の実行に関する情報をデータベースに保持できます。たとえば、メソッドが最後に実行された時刻を格納するために使用できます。これを使用して、前の結果と現在の結果の差分計算用の情報を保存することもできます。output パラメータはノードのエラーファースト規則に従うコールバックです。エラーが発生した場合、1 つ目のパラメータとしてエラーが返されます。エラーが発生しなかった場合、1 つ目のパラメータは null となり、出力に準拠している結果が 2 つ目のパラメータとして返されます。
• validate メソッド - トリガーをデータベースに保存する前に ThingWorx Flow サーバーによって呼び出されます。検証に失敗した場合、トリガーは保存されません。このメソッドは、入力や、サービスへの接続性などの検証に使用できます。
• activate メソッド - 既存のトリガーが別のワークフローに関連付けられている場合に呼び出されます。ほとんどの場合、そこから検証を実行するだけで十分です。activate メソッドの実装例を次に示します。
function activate(input, options, output){
return output(null,true)
}
return output(null,true)
}
トリガーの選択されたイベントにアクセスするには、入力オブジェクト (input.event) の "event" プロパティを使用します。ドキュメントオブジェクトには、フォームからの入力フィールドが含まれています。入力フィールドには、接続や access_token などの通常のプロパティと、入力フォームのその他のフィールドが含まれます。たとえば、接続オブジェクトの一部である user_name プロパティにアクセスするには、document.input.connection.user_name などの定義式を使用します。
Webhook トリガー
これらは購読に基づくトリガーです。接続されたシステムでのイベントに購読が作成され、接続されたシステムでそのイベントが発生した場合に Webhook URL が呼び出され、イベントペイロードが送信されます。このタイプのトリガーが機能するためには、接続されたシステムで Webhook がサポートされていなければなりません。このトリガーは ThingWorx Flow エンジンにデータをリアルタイムで送信するので、外部のアプリケーションまたはサービスで指定したイベントが発生するとただちにフローが実行されます。
Webhook トリガーは次のコマンドを使用して作成できます。
flow add trigger
このコマンドを実行すると以下が作成されます。
• メタデータファイル trigger.json - 入力と出力が格納されます
• index.js JavaScript ファイル - コードのロジックが格納されます
これらのファイルはディレクトリ <プロジェクトディレクトリ>\trigger\webhook\<トリガー名>\v1 の下に作成されます。Webhook トリガーの trigger.json ファイルを完成させるプロセスはポーリングトリガーとほぼ同じです。ただし、コードは大きく異なります。
Webhook トリガーの index.js ファイルの構造は次のとおりです。
module.exports = Trigger;
Trigger.execute = function execute(input, data, output) {
}
Trigger.activate = function execute(input, data, output) {
}
Trigger.register = function register(document, callback) {
}
Trigger.unregister = function unregister(document, callback) {
}
Trigger.execute = function execute(input, data, output) {
}
Trigger.activate = function execute(input, data, output) {
}
Trigger.register = function register(document, callback) {
}
Trigger.unregister = function unregister(document, callback) {
}
Webhook トリガーで使用されるメソッドは以下のとおりです。
• activate メソッド - 次のような単純な no-op (動作なし) 実装が可能です。
function activate(input, options, output) {
return output(null, true);
}
return output(null, true);
}
• register メソッド - ThingWorx Flow サーバーによって提供される Webhook URL を外部サービスに登録するときに使用します。register メソッドは、Webhook URL を含むプロパティを持つドキュメントオブジェクトを入力としてとります。ドキュメントオブジェクトのプロパティは次のとおりです。
◦ webhook_name - webhook オブジェクトの名前。
◦ webhook - webhook URL。
◦ input - 接続および access_token などその他のプロパティと、トリガー入力フォームからのその他のフィールドを含む、入力オブジェクト。
メソッドの出力は、"hook_response" プロパティとしてドキュメントオブジェクトに格納されます。この hook_reponse には、多くの場合、ターゲットシステムによって提供されるトリガーの ID が含まれています。通常、この ID は、webhook の登録を解除しようとしたときに、ターゲットシステムに返送されます。
• unregister メソッド - 接続されたシステムに対して登録呼び出しが行われたときに作成された Webhook 購読を除去する登録解除リクエストを送信します。document.hook_response とそのプロパティを使用して、登録解除に使用できる情報を取得します。
トリガーの完全なコードを記述した後、トリガーの認証の作成に進むことができます。
• execute メソッド - 以下の目的に使用されます。
◦ フローでの使用に適した形式や、定義されている出力スキーマに対応する形式に、フォームからのサービスデータを変換します。
◦ 場合によっては、サービスから十分な情報が提供されないことがあります。そのような場合、サービスに対して追加情報をクエリーできます。