Creación de acciones
Una acción específica las tareas que desea que realice el flujo de trabajo. Se puede crear una nueva acción para el proyecto con la CLI de ThingWorx Flow.
Por ejemplo, las acciones de Gmail se muestran en la siguiente imagen:
Para añadir una nueva acción o una nueva versión de la acción al conector, realice lo siguiente:
1. En el símbolo del sistema, ejecute los siguientes comandos:
a. cd <project root directory>
b. flow add action <name>
 |
El nombre de la acción no puede contener caracteres especiales, excepto un guion (-). Por ejemplo, servicename-action es un nombre de acción.
|
La ejecución de los comandos anteriores crea una carpeta en la siguiente ubicación <dirProyecto>\action\action name.
◦ En la carpeta se incluye una subcarpeta denominada v1 (versión 1).
◦ En la carpeta v1 se incluyen los siguientes ficheros:
▪ Fichero action.json: contiene los metadatos, como la entrada y salida de la acción. La información que aparece en el formulario de la acción se define en este fichero.
▪ Fichero index.js: contiene la lógica y la implementación del código de acción.
Están disponibles las siguientes opciones para el comando add action.
|
Opciones
|
Descripción
|
Tipo de datos
|
|---|---|---|
|
--version
|
Permite mostrar el número de versión.
|
[Booleano]
|
|
--help
|
Permite mostrar la ayuda.
|
[Booleano]
|
|
--parentDir, -d
|
El directorio padre del proyecto.
|
[por defecto: "."]
|
|
--logLevel, -1
|
Permite definir el nivel de registro.
|
[por defecto: "info"]
|
|
-- artifactVersion, -v
|
Versión del elemento que se debe probar.
|
[por defecto: "v1"]
|
2. Defina las propiedades de entrada y salida en el fichero action.json y, a continuación, añada el código de JavaScript al fichero index.js.
A continuación, se proporcionan el fichero action.json completado y su descripción:
{
"_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"
}
Consulte la siguiente tabla para obtener las descripciones de las propiedades del fichero action.json.
|
Propiedad
|
Especifique las propiedades en el fichero JSON.
|
||
|---|---|---|---|
|
name
|
Nombre de la acción.
En la acción gmail-details-get, gmail es el nombre del conector y details-get es el nombre de la acción.
|
||
|
label
|
Rótulo mostrado de la acción.
|
||
|
input
|
Esquema JSON del formulario de entrada. Consulte el esquema de entrada de ejemplo que se encuentra después de la tabla.
Los tipos de campo de entrada soportados son any, string, boolean, array u object.
En el esquema de entrada también se definen los mecanismos de autenticación soportados por la acción.
|
||
|
output
|
La propiedad define el esquema de salida que esta acción puede devolver cuando se ejecuta.
Los tipos de clave de salida soportados son Cadena, Número, Booleano o Cualquiera.
|
||
|
version
|
Versión de los elementos. Cuando se crea mediante la CLI de ThingWorx Flow, no se debe cambiar este valor.
|
||
|
tags
|
Una matriz de cadenas con valores que determina en qué grupo se muestra el conector en la interfaz de usuario. Normalmente, es el nombre mostrado del conector.
|
ThingWorx Flow soporta varios esquemas de autenticación. Por ejemplo, en el siguiente código se muestran los distintos esquemas de autenticación, como None, Basic y OAuth en el conector de 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
}
}
}
]
}
El fichero index.js para la acción debe exportar un objeto con el método execute, tal como se muestra en el siguiente código:
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)
}
}
El objeto de conexión está disponible como propiedad en el objeto de entrada. Para acceder a estos campos, utilice expresiones como, por ejemplo, input.connection.user_name.
Si el conector utiliza OAuth en su lugar, se puede recuperar el token de acceso mediante la expresión input.access_token.
En el siguiente vídeo se muestra la creación de una nueva acción con la CLI de ThingWorx.
Por ejemplo, para definir una nueva acción denominada gmail-details-get para la cuenta de Gmail, se debe definir la propiedad de entrada en el fichero action.json.
En la siguiente figura se muestra la asignación del código de propiedad de entrada y el formulario de acción que aparece en el lienzo de ThingWorx Flow.
Consulte la siguiente tabla para ver las descripciones de las propiedades de entrada:
Propiedad | Especifique la propiedad de entrada, tal como se describe a continuación. | ||
|---|---|---|---|
title | Título del formulario que se utiliza para aceptar las entradas en el lienzo de ThingWorx Flow. | ||
type (obligatorio) | El tipo del objeto de nivel superior siempre debe ser object. | ||
properties | Recopilación de entradas que se necesitan para ejecutar la acción. Cada propiedad corresponde a algunos elementos de la interfaz de usuario en el formulario resultante: cuadros de texto, listas desplegables, botones de opción, etc. Cada entrada debe tener las siguientes propiedades: title, type, minLength (opcional) y description (opcional), format, minValue, maxValue, pattern, minItems, maxItems para el tipo de matriz, etc.
Las propiedades del formulario de acción se pueden ordenar mediante el elemento propertyorder del esquema de entrada. Para que un campo opcional esté visible en el formulario de acción, defina esta propiedad en true. Por ejemplo, visible=true | ||
lookup | Cada entrada puede tener una propiedad lookup que especifique que el campo se debe rellenar con los valores buscados mediante la búsqueda descrita anteriormente. Para cada lookup, es necesario especificar las siguientes propiedades: • ID: nombre de la función. • service: nombre de la función de búsqueda a la que se llama cuando se pulsa en la flecha de la búsqueda.
• auth: conexión u OAuth. • searchable: si el valor se define en true, se activan los mecanismos searbyById y searchByValue. • dependencies: una matriz de cadenas. Permite especificar los campos obligatorios para la búsqueda. • onSelect: nombre de la función de búsqueda a la que se llama en la selección de un elemento específico de la lista que la búsqueda muestra. Se utiliza normalmente para controlar el esquema de formulario. |
De manera similar, se deben definir las propiedades de salida en el fichero action.json y, a continuación, ejecutar el fichero index.js. Para obtener más información y ejemplos, consulte el tema
Apéndice B: Tutorial sobre conectores de ThingWorx Flow.
Recuerde lo siguiente al crear acciones:
• Tipos de campo de entrada soportados: Any, String, Boolean, Array, Object
• Tipos de clave de salida soportados: String, Number, Boolean, Any
• minLength marca el campo según sea necesario.
• minItems marca un campo de matriz según sea necesario.
• maxItems define el límite máximo para un campo de matriz.
• select2: {active:true} marca el campo como campo de selección 2.
• Formato: date/datetime/time para añadir el selector de fecha, fecha y hora u hora en el campo de entrada.
• ThingWorx Flow soporta oneOf.
• ThingWorx Flow soporta actualmente $ref que solo hace referencia a local.
Consulte la siguiente tabla para ver las descripciones de las propiedades de salida:
Propiedad | Especifique la propiedad de salida, tal como se describe a continuación. |
|---|---|
type (obligatorio) | El tipo del objeto de nivel superior siempre debe ser object. |
properties | Se utiliza para definir los campos de salida que devuelve la acción y que se pueden utilizar en las acciones posteriores. |
Un ejemplo de la propiedad de salida formateada para mayor claridad es el siguiente:
{
"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
}
Para obtener información sobre un SDK de las API que se pueden utilizar en acciones, consulte la sección
SDK de conectores de ThingWorx Flow.
Creación de ayuda dependiente del contexto
ThingWorx Flow dispone de un mecanismo para que los desarrolladores de conectores proporcionen ayuda dependiente del contexto para los URL.
Tal como se muestra en la imagen anterior, se puede iniciar la ayuda dependiente del contexto pulsando en 
en la página de acción.
en la página de acción.Para la ayuda dependiente del contexto, se proporciona un URL en el atributo href del elemento de uso.
"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 puede ser cualquier URL absoluto que proporcione ayuda sobre una acción. Además, si el sitio soporta páginas de ayuda específicas de idioma, hay una disposición para proporcionar un marcador para el ID de idioma. El servidor ThingWorx Flow reemplaza el marcador por el idioma que el usuario prefiera. Se puede colocar el token locale, según sea necesario para el sitio.
A continuación, se muestran algunos ejemplos:
Si el idioma preferido de los usuarios es francés, por ejemplo, ThingWorx Flow construye el URL reemplazando <%=locale%> por fr lo que resulta en el siguiente vínculo: