建立動作
動作可指定您想要工作流程執行的任務。您可使用 ThingWorx Flow CLI 為專案建立新動作。
例如，Gmail 中的動作如下圖所示：
欲將新動作或動作的新版本新增至連接器，請執行下列操作：
1. 從指令提示中，執行下列指令：
a. cd <project root directory>
b. flow add action <name>
 |
動作名稱不得包含除連字號 (-) 之外的特殊字元。例如，servicename-action 是動作名稱。
|
執行上述指令會在下列位置建立一個資料夾，即 <projectDir>\action\action name 資料夾。
◦ 此資料夾有一個名為 v1 (版本 1) 的子資料夾。
◦ V1 資料夾包含下列檔案：
▪ action.json 檔案 - 包含例如動作輸入與輸出的中繼資料。顯示在動作表單中的資訊即在此檔案中定義。
▪ index.js 檔案 - 包含動作程式碼的邏輯與實行。
add action 指令有下列選項可用。
|
選項
|
描述
|
資料類型
|
|---|---|---|
|
--version
|
顯示版本編號。
|
[布林值]
|
|
--help
|
顯示說明。
|
[布林值]
|
|
--parentDir, -d
|
專案的父目錄。
|
[預設："."]
|
|
--logLevel, -1
|
設定記錄層級。
|
[預設："info"]
|
|
-- artifactVersion, -v
|
要測試之加工品的版本。
|
[預設："v1"]
|
2. 在 action.json 檔案中設定輸入與 輸出內容，然後將 JavaScript 程式碼新增至 index.js 檔案。
已完成的 action.json 檔案及其描述如下：
{
"_id": "56b838816f724b0e259dae20",
"created_at": "2017-04-07T14:48:36.129Z",
"updated_at": "2017-04-07T14:48:36.129Z",
"uid": "actd47559da24fb85fae90b29099558e201cefa",
"name": "google-gmail-details-get",
"label": "Get Mail Details",
"input": {
"title": "Get Mail Details",
"type": "object",
"properties": {
"access_token": {
"title": "Authorize Gmail",
"type": "string",
"oauth": "gmail",
"minLength": 1
},
"id": {
"title": "Message ID",
"type": "string",
"minLength": 1,
"description": "Select/specify ID of the message of which details you wish to retrieve",
"lookup": {
"id": "g1",
"service": "gmail",
"auth": "oauth",
"enabled": true,
"searchable": true,
"dependencies": [
"access_token"
]
}
}
}
},
"output":
{
"title": "output",
"type": "object",
"properties": {
"id": {
"title": "id",
"type": "string",
"displayTitle": "ID"
},
"threadId": {
"title": "threadId",
"type": "string",
"displayTitle": "Thread ID"
},
"labelIds": {
"type": "array",
"title": "labelIds",
"displayTitle": "Label IDs",
"items": {
"type": "string"
}
},
"snippet": {
"title": "snippet",
"displayTitle": "Snippet",
"type": "string"
},
"historyId": {
"title": "historyId",
"displayTitle": "History ID",
"type": "string"
},
"internalDate": {
"title": "internalDate",
"displayTitle": "Internal Date",
"type": "string"
}
//schema truncated for clarity
},
"usage": {
"link": {
"href": "https://support.ptc.com/help/thingworx_hc/
thingworx_8_hc/activity/google-mail/get-mail-details",
"title": "Doc Link"
},
"html": "Fetch details of an email"
},
"version": "v1",
"icon": "gmail",
"act_type": "default",
"default_value": "",
"__v": 0,
"tags": [
"Gmail"
],
"category": "service"
}
"_id": "56b838816f724b0e259dae20",
"created_at": "2017-04-07T14:48:36.129Z",
"updated_at": "2017-04-07T14:48:36.129Z",
"uid": "actd47559da24fb85fae90b29099558e201cefa",
"name": "google-gmail-details-get",
"label": "Get Mail Details",
"input": {
"title": "Get Mail Details",
"type": "object",
"properties": {
"access_token": {
"title": "Authorize Gmail",
"type": "string",
"oauth": "gmail",
"minLength": 1
},
"id": {
"title": "Message ID",
"type": "string",
"minLength": 1,
"description": "Select/specify ID of the message of which details you wish to retrieve",
"lookup": {
"id": "g1",
"service": "gmail",
"auth": "oauth",
"enabled": true,
"searchable": true,
"dependencies": [
"access_token"
]
}
}
}
},
"output":
{
"title": "output",
"type": "object",
"properties": {
"id": {
"title": "id",
"type": "string",
"displayTitle": "ID"
},
"threadId": {
"title": "threadId",
"type": "string",
"displayTitle": "Thread ID"
},
"labelIds": {
"type": "array",
"title": "labelIds",
"displayTitle": "Label IDs",
"items": {
"type": "string"
}
},
"snippet": {
"title": "snippet",
"displayTitle": "Snippet",
"type": "string"
},
"historyId": {
"title": "historyId",
"displayTitle": "History ID",
"type": "string"
},
"internalDate": {
"title": "internalDate",
"displayTitle": "Internal Date",
"type": "string"
}
//schema truncated for clarity
},
"usage": {
"link": {
"href": "https://support.ptc.com/help/thingworx_hc/
thingworx_8_hc/activity/google-mail/get-mail-details",
"title": "Doc Link"
},
"html": "Fetch details of an email"
},
"version": "v1",
"icon": "gmail",
"act_type": "default",
"default_value": "",
"__v": 0,
"tags": [
"Gmail"
],
"category": "service"
}
有關 action.json 檔案中內容的描述，請參閱下表。
|
內容
|
在 JSON 檔案中輸入內容。
|
||
|---|---|---|---|
|
name
|
動作的名稱。
在 gmail-details-get 動作中，gmail 是連接器名稱，details-get 是動作名稱。
|
||
|
label
|
顯示動作標籤。
|
||
|
input
|
輸入表單的 JSON 結構描述。請參閱表後的範例輸入結構描述。
支援的輸入欄位類型有 any、string、boolean、array 或 object。
輸入結構描述也定義動作支援驗證機制。
|
||
|
output
|
此內容定義在執行此動作時其可傳回的輸出結構描述。
支援的輸出金鑰類型有 String、Number、Boolean 或 any。
|
||
|
version
|
加工品的版本。當使用 ThingWorx Flow CLI 建立時，不應變更此值。
如需詳細資訊，請參閱版本化連接器加工品主題。
|
||
|
tags
|
此內容是一個包含值的字串陣列，其可決定連接器在使用者介面中會顯示在哪個群組下。通常，它是連接器的顯示名稱。
|
ThingWorx Flow 支援多種驗證配置。例如，下列程式碼會在 OData 連接器中顯示各種驗證配置，如「無」、「基本」以及 OAuth：
{
"type": "object",
"title": "Select an Authentication Scheme",
"oneOf": [
{
"type": "object",
"title": "None",
"id": "act1",
"properties": {
"odataUrl": {
"type": "string",
"title": "Odata Metadata Url",
"displayTitle": "Odata Metadata Url",
"minLength": 1,
"description": "Please provide the odata metadata url"
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
},
{
"type": "object",
"title": "Basic",
"id": "act2",
"properties": {
"connection": {
"title": "Odata Connection",
"type": "string",
"connection": "odata",
"minLength": 1
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
},
{
"type": "object",
"title": "OAuth",
"id": "act3",
"properties": {
"oauth": {
"title": "Odata OAuth",
"type": "string",
"oauth": "odata",
"minLength": 1,
"needUrl": true
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
}
]
}
"type": "object",
"title": "Select an Authentication Scheme",
"oneOf": [
{
"type": "object",
"title": "None",
"id": "act1",
"properties": {
"odataUrl": {
"type": "string",
"title": "Odata Metadata Url",
"displayTitle": "Odata Metadata Url",
"minLength": 1,
"description": "Please provide the odata metadata url"
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
},
{
"type": "object",
"title": "Basic",
"id": "act2",
"properties": {
"connection": {
"title": "Odata Connection",
"type": "string",
"connection": "odata",
"minLength": 1
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
},
{
"type": "object",
"title": "OAuth",
"id": "act3",
"properties": {
"oauth": {
"title": "Odata OAuth",
"type": "string",
"oauth": "odata",
"minLength": 1,
"needUrl": true
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
}
]
}
動作的 index.js 檔案應使用 execute 方法匯出物件，如下列程式碼所示：
module.exports = function () {
/*
This function will receive an input that conforms to the schema specified in
activity.json. The output is a callback function that follows node's error first
convention. The first parameter is either null or an Error object. The second parameter
of the output callback should be a JSON object that conforms to the schema specified
in activity.json
*/
this.execute = function (input, output) {
let outputData = {}
return output(null, outputData)
}
}
/*
This function will receive an input that conforms to the schema specified in
activity.json. The output is a callback function that follows node's error first
convention. The first parameter is either null or an Error object. The second parameter
of the output callback should be a JSON object that conforms to the schema specified
in activity.json
*/
this.execute = function (input, output) {
let outputData = {}
return output(null, outputData)
}
}
連線物件將作為輸入物件的內容使用。欲存取此欄位，請使用運算式，如 input.connection.user_name。
然而，如果您的連接器使用 oauth，則可以使用運算式 input.access_token 擷取存取權杖
下面的視訊示範如何使用 ThingWorx CLI 建立新動作。
例如，若要為您的 Gmail 帳戶定義名為 gmail-details-get 的新動作，請在 action.json 檔案中設定輸入內容。
下圖顯示輸入內容程式碼與顯示在 ThingWorx Flow 畫布上的動作表單的對應。
有關輸入內容的描述，請參閱下表：
內容 | 如下所述輸入輸入內容 | ||
|---|---|---|---|
title | 用來接受 ThingWorx Flow 畫布上輸入之表單的標題。 | ||
type (必要) | 頂層物件的類型必須始終是 object。 | ||
properties | 執行動作所必需的輸入集合。每個內容都與所產生表單中的某使用者介面元素對應：文字方塊，下拉清單、單選按鈕等等。每個輸入都必須有下列內容：title、type、minLength (選用) 及陣列類型的 description (選用)、format、minValue、maxValue、pattern、minItems、maxItems 等。
您可使用輸入結構描述中的 propertyorder 元素，為動作表單中的內容排序。 若要使選用欄位在動作表單上可見，請將此內容設定為 true。例如，visible=true | ||
lookup | 每個輸入都可以有一個 lookup 內容，用來指定應為欄位填入由上述查詢所搜尋的值。 針對每個 lookup，您都必須指定下列內容： • id - 函數的名稱。 • service - 當您按一下查詢上的箭頭時所呼叫之查詢函數的名稱。
• auth - 連線或 OAuth。 • searchable - 如果將值設定為 true，會啟用 searbyById 與 searchByValue 機制。 • dependencies - 字串陣列。它可指定查詢所需的欄位。 • onSelect - 在從查詢所顯示清單中選取特定項目時將呼叫之查詢函數的名稱。此內容通常用來處理表單結構描述。 |
建立動作時，請記住下列事項：
• 支援的輸入欄位類型 - Any、String、Boolean、Array、Object
• 支援的輸出金鑰類型 - String、Number、Boolean、Any
• minLength 將欄位標記為必填。
• minItems 將陣列欄位標記為必填。
• maxItems 設定陣列欄位的上限。
• select2—{active:true} 將欄位標記為選取 2 欄位。
• 格式 - date/datetime/time 可在輸入欄位中新增日期/日期與時間/時間選擇器。
• ThingWorx Flow 支援 oneOf
• ThingWorx Flow 目前僅支援 $ref，這表示僅限本機。
有關輸出內容的描述，請參閱下表：
內容 | 如下所述輸入輸出內容 |
|---|---|
type (必要) | 頂層物件的類型必須始終是 object。 |
properties | 用來定義您動作傳回的輸出欄位，其可在後續動作中使用。 |
為了清楚明瞭的目的，我們為您提供下列經過格式化的輸出內容範例：
{
"title": "output",
"type": "object",
"properties": {
"id": {
"title": "id",
"type": "string",
"displayTitle": "ID"
},
"threadId": {
"title": "threadId",
"type": "string",
"displayTitle": "Thread ID"
},
"labelIds": {
"type": "array",
"title": "labelIds",
"displayTitle": "Label IDs",
"items": {
"type": "string"
}
},
"snippet": {
"title": "snippet",
"displayTitle": "Snippet",
"type": "string"
},
"historyId": {
"title": "historyId",
"displayTitle": "History ID",
"type": "string"
},
"internalDate": {
"title": "internalDate",
"displayTitle": "Internal Date",
"type": "string"
}
//schema truncated for clarity
}
"title": "output",
"type": "object",
"properties": {
"id": {
"title": "id",
"type": "string",
"displayTitle": "ID"
},
"threadId": {
"title": "threadId",
"type": "string",
"displayTitle": "Thread ID"
},
"labelIds": {
"type": "array",
"title": "labelIds",
"displayTitle": "Label IDs",
"items": {
"type": "string"
}
},
"snippet": {
"title": "snippet",
"displayTitle": "Snippet",
"type": "string"
},
"historyId": {
"title": "historyId",
"displayTitle": "History ID",
"type": "string"
},
"internalDate": {
"title": "internalDate",
"displayTitle": "Internal Date",
"type": "string"
}
//schema truncated for clarity
}
如需可在動作中使用之 SDK for API 的相關資訊，請參閱 ThingWorx Flow 連接器 SDK 部份。
建立前後關聯感應式說明
ThingWorx Flow 有一個機制，可讓連接器開發者為 URL 提供前後關聯感應式說明。
如上圖所示，可以按一下動作頁上的 
，啟動前後關聯感應式說明。
，啟動前後關聯感應式說明。對於前後關聯感應式說明，URL 在 usage 元素的 href 屬性中提供。
"usage": {
"link": {
"href": "http://organization.com/help/topic",
"title": "connector:i18nkey-for-title"
},
"html": " connector:i18nkey-for-html"
}
"link": {
"href": "http://organization.com/help/topic",
"title": "connector:i18nkey-for-title"
},
"html": " connector:i18nkey-for-html"
}
href 可以是提供動作相關說明的任何絕對 URL。此外，如果網站支援語言特定說明頁面，還可以為語言 id 提供預留位置。ThingWorx Flow 伺服器會將預留位置取代為使用者偏好的語言。可以根據網站需要放置 locale 權杖。
範例如下所示：
例如，如果使用者偏好語言為 French，則 ThingWorx Flow 在建構 URL 時會將 <%=locale%> 取代為 fr，因此會產生以下連結：