Creación de activadores
Un activador inicia un flujo de trabajo cuando se produce un evento suscrito en el sistema conectado. De este modo, se pueden automatizar procesos empresariales complejos sin ejecutar manualmente el flujo de trabajo cada vez.
Por ejemplo, en la siguiente figura se muestra una lista de activadores que se pueden crear desde el proyecto.
Hay dos tipos de activadores:
• Activadores de sondeo
• Activadores de webhook
Activadores de sondeo
Buscan actualizaciones periódicamente, a intervalos regulares. Todos los activadores de sondeo se marcan con un icono de reloj en la lista de activadores. Para crear activadores de sondeo, realice lo siguiente:
1. En el símbolo del sistema, ejecute los siguientes comandos:
a. cd <user project root directory>
b. flow add trigger -p
Están disponibles las siguientes opciones para el comando add trigger.
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: "."] |
--polling,-p | Permite indicar que se trata de un activador de sondeo. | [por defecto: falso] |
-- artifactVersion,-v | Versión del elemento que se va a crear. | [por defecto: "v1"] |
2. La ejecución del comando add trigger crea un fichero de metadatos trigger.json que contiene la entrada y salida, y un fichero JavaScript index.js que contiene la lógica de código. Estos ficheros se crean en el directorio <dirProyecto>\trigger\poll\<nombreactivador>\v1
 | Por defecto, se crea el activador de webhook. Utilice la opción -p para crear un activador de sondeo. |
Para obtener información sobre el formato del esquema de entrada y salida, consulte la nota en el tema
Creación de acciones. A continuación, se muestra un esquema truncado y simplificado.
Las opciones del fichero trigger.json se describen en la siguiente tabla:
Opciones | Descripción |
|---|---|
type (obligatorio) | El tipo del objeto más externo debe ser un objeto. |
title (obligatorio) | Rótulo de la lista para permitir la selección del activador. |
description | Descripción breve del activador. |
properties | Se utiliza para definir los campos del formulario de entrada para la configuración de activador. Contiene las siguientes definiciones: • Campos de entrada que se deben mostrar en la ventana de configuración de activador • Nombre del evento para que aparezca en la lista de servicios de activador. |
Una definición de activador comienza por un conjunto de propiedades comunes, como la autenticación y customFilters, así como otras propiedades comunes a todos los eventos de activador. Todas las propiedades tienen un tipo, un título y una descripción. Los sistemas externos exponen normalmente algunos eventos y estos deben estar representados en un bloque oneOf. Cada objeto dentro de oneOf corresponde a un evento único. Si un sistema expone un único evento, no se requiere el bloque oneOf.
La matriz oneOf contiene uno o varios eventos. Cada evento es un objeto JSON. El siguiente ejemplo se aplica a un servicio con 2 eventos, Evento 1 y Evento 2. Se debe tener en cuenta que cada evento puede requerir un número y tipo de entradas diferentes.
[{
"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"
}
}
}
]
"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"
}
}
}
]
Cada uno de estos eventos debe tener un esquema de salida correspondiente en la propiedad de salida. Por ejemplo, si hay 2 eventos, tal como se muestra más arriba, la salida debe tener un esquema para Evento 1 y Evento 2 de la siguiente manera:
"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"
}
}
}
}
"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"
}
}
}
}
El fichero index.js para activadores de sondeo tiene la siguiente estructura:
module.exports = Trigger
Trigger.execute = function (input, options, output) {
}
Trigger.validate = function (input, options, output) {
}
Trigger.activate = (input, options, output) {
}
Trigger.execute = function (input, options, output) {
}
Trigger.validate = function (input, options, output) {
}
Trigger.activate = (input, options, output) {
}
El código para el método validate es similar al método execute. Consulte el ejemplo para ver el código.
A continuación, se muestran los métodos que se utilizan en los activadores de sondeo:
• Método execute: se llama periódicamente. El intervalo es una configuración del servidor ThingWorx Flow. El método execute utiliza la información de conexión de la entrada, luego se conecta al sistema externo y extrae datos del servidor ThingWorx Flow. Puede utilizar las API del objeto de opción para almacenar en caché la información sobre los objetos extraídos y determinar si hay nueva información disponible.
El objeto options tiene una propiedad meta que se utiliza para conservar la información que está disponible a través de las llamadas al método execute.
Para obtener más información sobre las API que suelen estar disponibles, consulte la sección
SDK de conectores de ThingWorx Flow.
El método setMeta del objeto de opciones se puede utilizar para conservar la información sobre las ejecuciones actuales o anteriores en la base de datos. Por ejemplo, se puede utilizar para almacenar la hora en que se ejecutó el método por última vez. También se puede utilizar para almacenar información para calcular un delta entre los resultados anteriores y los actuales. El parámetro output es una llamada que sigue la convención de error primero del nodo. Si se produce un error, se debe devolver como el primer parámetro o el primer parámetro debe ser nulo y se devuelve un resultado que se ajusta al esquema de salida como segundo parámetro.
• Método validate: el servidor ThingWorx Flow lo invoca antes de guardar un activador en la base de datos. Si la validación falla el activador no se guardará. Este método se puede utilizar para validar las entradas, como la conectividad con el servicio.
• Método activate: se llama cuando un activador existente se asocia con otro flujo de trabajo. En la mayoría de los casos, es suficiente ejecutar validate desde él. A continuación se proporciona un ejemplo de implementación del método activate:
function activate(input, options, output){
return output(null,true)
}
return output(null,true)
}
Para acceder al evento seleccionado del activador, utilice la propiedad "event" del objeto de entrada (input.event). En el objeto de documento se incluyen los campos de entrada del formulario. En el campo de entrada se incluyen las propiedades habituales, tales como connection y access_token, así como cualquier otro campo del formulario de entrada. Por ejemplo, para acceder a la propiedad user_name que forma parte del objeto de conexión, utilice una expresión, como document.input.connection.user_name
Activadores de webhook
Son activadores basados en suscripción. Las suscripciones se crean en eventos del sistema conectado y se llama a un URL de webhook con la carga del evento cuando se produce el evento en el sistema conectado. El sistema conectado debe soportar webhooks para que este tipo de activador funcione. Envía datos al motor de ThingWorx Flow en tiempo real, lo que permite que el flujo se ejecute en cuanto se produce el evento especificado en una aplicación o servicio externo.
Es posible crear activadores de webhook con el siguiente comando:
flow add trigger
La ejecución del comando crea lo siguiente:
• Un fichero de metadatos trigger.json: contiene las entradas y la salida.
• Un fichero JavaScript index.js: contiene la lógica de código.
Estos ficheros se crean en el directorio <dirProyecto>\trigger\webhook\<nombreactivador>\v1. El proceso para completar el fichero trigger.json para un activador de webhook es similar al de un activador de sondeo. Sin embargo, el código difiere significativamente.
El fichero index.js para activadores de webhook tiene la siguiente estructura:
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) {
}
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) {
}
A continuación, se muestran los métodos que se utilizan en los activadores de webhook:
• Método activate: puede tener una implementación simple sin ninguna operación, como se indica a continuación:
function activate(input, options, output) {
return output(null, true);
}
return output(null, true);
}
• Método register: se utiliza para registrar el URL de webhook que el servidor ThingWorx Flow proporciona con el servicio externo. El método register recibe un objeto de documento que tiene una propiedad que contiene el URL de webhook. Las propiedades del objeto de documento son las siguientes:
◦ webhook_name: el nombre del objeto de webhook.
◦ webhook: el URL de webhook.
◦ input: el objeto de entrada que contiene otras propiedades como, por ejemplo, connection, access_token y cualquier otro campo del formulario de entrada del activador.
La salida del método se almacena en el objeto de documento como propiedad "hook_response". Esta propiedad hook_response contiene, en muchos casos, el ID del activador proporcionado por el sistema de destino. Normalmente, este ID se devuelve al sistema de destino cuando se intenta anular el registro del webhook.
• Método unregister: se envía una solicitud de anular el registro que quita la suscripción de webhook que se ha creado al realizar la llamada de registro a los sistemas conectados. Utilice document.hook_response y sus propiedades para obtener la información que se puede utilizar para anular el registro.
Después de escribir el código completo para el activador, se puede empezar a crear una autenticación para el activador.
• Método execute: se utiliza de la manera que se indica a continuación.
◦ Para convertir los datos de servicio del formulario en un formulario que sea adecuado para su uso en flujos o en un formulario que coincida con el esquema de salida definido.
◦ En algunos casos, el servicio no proporciona suficiente información. En estos casos, puede consultar el servicio para obtener más información.