ThingWorx Flow > ThingWorx Flow SDK > ThingWorx Flow CLI > 建立觸發器
建立觸發器
當在連線系統中發生訂閱事件時，觸發器會啟動工作流程。如此一來，您便可以自動化複雜的業務流程，而不必每次都手動執行工作流程。
例如，下圖顯示了可從您專案中建立的觸發器清單。
有兩種類型的觸發器：
• 輪詢觸發器
• 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，以及一個包含程式碼邏輯的 JavaScript 檔案 index.js。這些檔案會建立在 <projectDir>\trigger\poll\<triggername>\v1 目錄下
* 
預設會建立 Webhook 觸發器。可使用 -p 選項建立輪詢觸發器。
如需格式化輸入與輸出結構描述的相關資訊，請參閱 建立動作主題下的註記。以下是經過截斷的簡化結構描述。
下表說明 trigger.json 檔案中的選項：
trigger.json 檔案
選項
描述
type (必要)
最外側物件的類型必須是 object。
title (必要)
允許選取觸發器的清單標籤。
description
觸發器的簡短描述。
properties
用來定義觸發器組態的輸入表單欄位。它包含下列定義：
• 要顯示在觸發器組態視窗中的輸入欄位
• 要顯示在觸發器服務清單中的事件名稱。
觸發器定義的開頭是一組例如 authentication 與 customFilters 的常用內容，及所有觸發器事件常用的其他任何內容。所有內容都具有 type、title 與 description 內容。外部系統通常會顯示一些事件，這些事件必須以 oneOf 表示。oneOf 內的每個物件都與一個事件對應。如果系統顯示一個事件，則不需要 oneOf 區塊。
oneOf 陣列包含一或多個事件。每個事件是一個 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"
}
}
}
]


其中每一個事件的輸出內容中應包含對應的輸出結構描述。例如，如果具有如上方所示的 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"
}
}
}
}
輪詢觸發器 index.js 檔案的結構如下：
module.exports = Trigger
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 伺服器擷取資料。它可以使用選項物件的 API 來快取已擷取物件的相關資訊，以確定新資訊是否可用。
options 物件有一個 meta 內容，用來保留在呼叫 execute 方法時可用的資訊。
如需有關常用 API 的詳細資訊，請參閱 ThingWorx Flow 連接器 SDK 部份。
選項物件的 setMeta 方法可以用來將有關目前或先前執行的資訊儲存到資料庫。例如，它可以用來儲存上次執行此方法的時間。此方法也可用來儲存有關計算之前結果與目前結果之間差異的資訊。輸出參數是遵循節點錯誤優先慣例的回撥。如果發生錯誤，應將此參數作為第一個參數傳回，或者第一個參數應為 null，並會傳回符合輸出的結果作為第二個參數。
• validate 方法 - 在將觸發器儲存至資料庫之前由 ThingWorx Flow 伺服器呼叫。如果驗證失敗，將不會儲存觸發器。此方法可用來驗證輸入，例如與服務之間的連線。
• activate 方法 - 會在現有觸發器與另一個工作流程關聯時呼叫。在大多數情況下，從中執行驗證即已足夠。activate 方法的範例實行方式如下：
function activate(input, options, output){
return output(null,true)
}
欲存取所選的觸發器事件，請使用輸入物件 (input.event) 的 "event" 內容。文件物件包含源自表單的輸入欄位。輸入欄位包含 connection 與 access_token 等一般內容以及源自輸入表單的任何其他欄位。例如，欲存取屬於連線物件一部份的 user_name 內容，請使用運算式，如 document.input.connection.user_name
Webhook 觸發器
這些觸發器是以訂閱為基礎的觸發器。訂閱是在連線系統中針對事件所建立，當在連線系統中發生事件時，就會使用事件裝載呼叫 webhook URL。連線系統必須支援 Webhook，才能使用這類觸發器。它會將資料即時傳送至 ThingWorx Flow 引擎，這樣一來，只要在外部應用程式或服務中發生指定事件，您的流程便會執行。
您可以使用下列指令建立 Webhook 觸發器：
flow add trigger
執行此指令會建立
• 中繼資料檔案 trigger.json - 包含輸入與輸出
• index.js JavaScript 檔案 - 包含程式碼邏輯
這些檔案會建立在 <projectDir>\trigger\webhook\<triggername>\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) {
}
以下是在 Webhook 觸發器中使用的方法：
• activate 方法 - 能夠以簡單的無人職守方式實行，如下所示：
function activate(input, options, output) {
return output(null, true);
}
• register 方法 - 可用來向外部服務註冊 ThingWorx Flow 伺服器提供的 Webhook URL：register 方法會接收其內容包含 Webhook URL 的文件物件。文件物件的內容如下所示：
◦ webhook_name - Webhook 物件的名稱。
◦ webhook - Webhook url。
◦ input- 包含其他內容 (如 connection、access_token) 的輸入物件，以及源自觸發器輸入表單的任何其他欄位。
方法的輸出將作為 "hook_response" 內容儲存在文件物件中。在許多情況下，此 hook_reponse 包含目標系統所提供的觸發器 ID。通常，嘗試從目標系統中取消註冊 webhook 時，此 id 會傳送回目標系統。
• unregister 方法 - 可傳送取消註冊請求，此請求會移除在向連線系統執行註冊呼叫時建立的 Webhook 訂閱。使用 document.hook_response 及其內容以取得可用來取消註冊的資訊。
您為觸發器編寫完整程式碼之後，可以繼續為觸發器建立驗證。
• execute 方法 - 使用方式如下：
◦ 可將服務資料的格式轉換為適合在流程中使用的格式，或符合已定義輸出結構描述的格式。
◦ 在某些情況下，服務不會提供足夠的資訊。如果遇到此類情況，此方法可在服務中查詢其他資訊。
如需有關觸發器的詳細資訊與範例，請參閱 ThingWorx Flow 連接器 SDK 教學專區。