创建操作
操作可指定您希望工作流执行的任务。您可以使用 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 连接器中的各种身份验证架构（例如：None、Basic 和 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)
}
}
connection 对象可用作 input 对象的属性。要访问此字段，请使用如下表达式 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 - 从查找所显示的列表中选择特定项时所调用的查找函数的名称。它通常用于处理表单架构。 |
创建操作时，请切记下列事项：
• 支持的输入字段类型 - 任意、字符串、布尔型、数组、对象
• 支持的输出键类型 - String、Number、Boolean、Any
• minLength 用于将字段标记为必填字段。
• minItems 用于将数组字段标记为必填数组字段。
• maxItems 用于设置数组字段的最大限制。
• select2—{active:true} 用于将字段标记为 select2 字段。
• 格式 - 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
}
有关可在“操作”中使用的 API 的 SDK 信息，请参阅
ThingWorx Flow 连接器 SDK 部分。
创建上下文相关帮助
ThingWorx Flow 为连接器开发人员提供了一种机制，可以为 URL 提供上下文相关帮助。
如上图所示，可在操作页面上单击 
来启动上下文相关帮助。
来启动上下文相关帮助。对于上下文相关帮助，在使用关系元素的 href 属性中提供了 URL。
"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 令牌。
示例如下：
例如，如果用户的首选语言是 法语，则 ThingWorx Flow 可将 <%=locale%> 替换为 fr 来构造 URL，由此生成下列链接：