Создание действий
Действие указывает задания, которые требуется выполнять в рабочем процессе. Можно создать новое действие для проекта с помощью интерфейса командной строки (CLI) ThingWorx Flow.
Например, действия в 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 - содержит логику и реализацию кода действия.
Для команды добавления действия доступны следующие опции.
|
Опции
|
Описание
|
Тип данных
|
|---|---|---|
|
--version
|
Отображает номер версии.
|
[Boolean]
|
|
--help
|
Отображает справку.
|
[Boolean]
|
|
--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
|
Версия артефактов. При создании с помощью интерфейса командной строки (CLI) ThingWorx Flow это значение не должно изменяться.
Дополнительные сведения см. в разделе Создание версий артефактов соединителя.
|
||
|
tags
|
Строковый массив со значениями, которые определяют, в какой группе соединитель отображается в интерфейсе пользователя. Обычно это отображаемое наименование соединителя.
|
ThingWorx Flow поддерживает несколько схем аутентификации. Например, в следующем коде приведены различные схемы аутентификации, например "Нет", "Базовая" и OAuth, в соединителе OData:
{
"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.
Например, чтобы определить новое действие с именем gmail-details-get для учетной записи Gmail, необходимо задать входное свойство в файле 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 - имя функции подстановок, которая вызывается при выборе определенного элемента из отображаемого списка выбора. Обычно используется для обработки схемы формы. |
Точно так же необходимо задать выходные свойства в файле action.json, а затем выполнить файл index.js. Дополнительные сведения и примеры см. в разделе Учебник B. Учебник по SDK соединителей ThingWorx Flow.
Помните следующее при создании действий:
• Поддерживаемые типы полей ввода: Any, String, Boolean, Array, Object.
• Поддерживаемые типы ключей вывода: String, Number, Boolean, Any.
• minLength - отмечает поле как обязательное.
• minItems - отмечает поле массива как обязательное.
• maxItems - задает максимальный предел для поля массива.
• select2: {active:true} - отмечает поле как поле типа Select 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 для интерфейсов API см. в разделе SDK соединителя ThingWorx Flow.
Создание контекстной справки
ThingWorx Flow имеет механизм для разработчиков соединителей, предоставляющий контекстную справку для URL-адресов.
Как показано на рисунке выше, контекстную справку можно запустить, щелкнув значок 
на странице действия.
на странице действия.Для контекстной справки URL-адрес предоставляется в атрибуте элемента hrefusage.
"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-адрес, который предоставляет справку о действии. Кроме того, если сайт поддерживает страницы справки на определенном языке, существует условие, предоставляющее местозаполнитель для идентификатора языка. Сервер ThingWorx Flow заменяет местозаполнитель языком, предпочтительным для пользователя. Лексему locale можно помещать согласно требованиям сайта.
Примеры:
Если языковой настройкой пользователей является Французский, ThingWorx Flow строит URL-адрес, заменяя <%=locale%> на fr, и ссылка имеет вид: