HEFLO proporciona un proyecto de personalización de API basado en Node.js que permite la implementación de reglas de negocio avanzadas, integraciones y manipulación de datos durante la ejecución del proceso. Al utilizar el proyecto de API de HEFLO, los desarrolladores pueden extender el comportamiento de la automatización de procesos más allá de las configuraciones estándar de BPMN. Las personalizaciones se pueden utilizar con:
- Elementos BPMN;
- Campos de Datos Externos;
- Botones de Acción;
- Eventos de Campos de Formulario, como Inicialización, Adición, Cambio y Eliminación;
- Disparadores del flujo de ejecución del proceso;
- Definición dinámica de participantes;
- Operaciones de registros personalizados, como creación, actualización y eliminación.
La biblioteca de la API de HEFLO también proporciona funciones auxiliares integradas que simplifican el acceso a los datos del proceso, campos de elementos de trabajo, registros, tokens y contexto de ejecución. Puede encontrar una lista completa de los disparadores, eventos y funciones auxiliares disponibles en la documentación de la API de HEFLO: Link.
Aunque los proyectos de personalización de HEFLO ofrecen la flexibilidad de un entorno de web service completo, también requieren conocimientos de Node.js, mantenimiento del proyecto, alojamiento e infraestructura de despliegue. Para las organizaciones que prefieren asistencia en la implementación, HEFLO también ofrece servicios de consultoría e implementación.
Nota: En el artículo se puede encontrar un enfoque alternativo para un proyecto de API de HEFLO: Información General de Integraciones en HEFLO: Web Services vs. Personalizaciones de API.
Estructura del proyecto y elementos mínimos
Un proyecto de personalización de HEFLO se implementa normalmente como una aplicación de Serverless Framework desplegada en AWS Lambda. La estructura mínima del proyecto es:
├── package.json
├── process
├ └── functions.ts
├── serverless.yml
└── tsconfig.json
donde cada archivo tiene una responsabilidad específica en el proyecto.
package.json
El archivo package.json define las dependencias y la configuración del proyecto. Contiene:
- Dependencias de paquetes de Node.js;
- Dependencias de Serverless Framework;
- Paquetes de configuración de TypeScript;
- Dependencia del SDK de la API de HEFLO;
- Bibliotecas de utilidades como Axios, Moment, análisis de CSV y paquetes de AWS SDK.
Ejemplo de dependencia: «heflo-api»: «^1.0.32»
El paquete heflo-api proporciona acceso al contexto de ejecución de HEFLO y a los métodos auxiliares utilizados durante la automatización del proceso.
serverless.yml
El archivo serverless.yml define cómo se despliega la aplicación en AWS Lambda.
Example:
service: projectName
provider:
name: aws
runtime: nodejs16.x
region: sa-east-1
functions:
function01:
handler: process/functions.function01
events:
– http:
path: /function01
method: post
Esta configuración:
- Crea una función de AWS Lambda;
- Expone un endpoint HTTP;
- Conecta el endpoint a una función de TypeScript;
- Permite el despliegue utilizando el Serverless Framework.
tsconfig.json
Este archivo define la configuración del compilador de TypeScript. Los ajustes de ejemplo incluyen:
{
«target»: «ES2020»,
«module»: «commonjs»,
«strict»: true
}
El proyecto utiliza TypeScript para mejorar la mantenibilidad, la seguridad de tipado y las capacidades de depuración.
processFunction.ts
El archivo functions.ts contiene la lógica de personalización. Cada función exportada se puede utilizar como:
- Manejadores de eventos de formulario;
- Acciones de disparo;
- Endpoints de API;
- Manejadores de ejecución de flujos de secuencia;
- Rutinas de automatización personalizadas.
Ejemplo:
exports.function01 = async (event: any) => {
const body = JSON.parse(event.body);
const context = new HEFLOApi.Events.WorkItem.OnChanged({ body });
const textField = context.WorkItem.Get(«textField»);
// custom business logic here
};
El elemento principal de cada personalización es el objeto de contexto proporcionado por la biblioteca de la API de HEFLO. Este objeto da acceso a:
- Campos de elementos de trabajo;
- Datos del proceso;
- Registros;
- Participantes;
- Información del token actual;
- Métodos de ejecución del flujo de trabajo.
Instalación de dependencias y prerrequisitos
Antes de ejecutar el proyecto, asegúrese de tener instaladas las siguientes herramientas:
- Node.js;
- npm;
- Serverless Framework;
- Ngrok.
Para esta guía, se utilizará Visual Studio Code como el IDE para editar, probar y depurar el proyecto.
Los siguientes pasos describen un proceso de configuración simplificado para preparar el entorno de desarrollo y crear la estructura del proyecto desde cero.
- Descargue e instale Visual Studio Code.
- Descargue e instale Node.js desde el sitio web oficial.
- Después de la instalación, valide la instalación utilizando un prompt del sistema o terminal::
node -v - Valide también npm:
npm -v - Instale TypeScript.
npm install typescript -g - Valide la instalación:
tsc -v - Instale Serverless Framework.
npm install serverless@3.39.0 -g
Nota: Consulte la documentación oficial de Serverless Framework para obtener la versión estable más reciente. - Valide la instalación:
serverless -v
- Instale ngrok.
ngrok se utiliza durante el desarrollo local para exponer públicamente la API local de modo que HEFLO pueda acceder a los endpoints de personalización durante las pruebas.
a. Cree una cuenta en el sitio web de ngrok;
b. Descargue el archivo ejecutable;
c. Extraiga y abra ngrok;
d. Autentique la instalación utilizando el comando proporcionado en el panel de ngrok.
Ejemplo: ngrok config add-authtoken YOUR_TOKEN
Después de la autenticación, ngrok estará listo para usarse.
Creación de una función de personalización sencilla
Después de instalar todos los prerrequisitos, podemos crear el proyecto de personalización. Primero, cree la carpeta del proyecto, esto se puede hacer directamente a través de VS Code o mediante una terminal; para ello:
- Abra una terminal y cree el directorio del proyecto:
mkdir heflo-customization
cd heflo-customization - Inicialice el proyecto Node.js; para ello, ejecute:
npm init -y - Instale las dependencias del proyecto.
Para este ejemplo, instalaremos únicamente las dependencias mínimas necesarias.
npm install \
heflo-api \
serverless@3.39.0 \
serverless-offline@8.8.0 \
serverless-plugin-typescript@2.1.2 \
typescript
Nota: El paquete serverless-plugin-typescript actualmente es compatible solo con las versiones v2 y v3 de Serverless Framework. Por esta razón, el proyecto utiliza serverless@3.39.0. Instalar la versión más reciente de Serverless Framework puede causar conflictos de dependencias durante la instalación. Para evitar problemas de compatibilidad, instale siempre las versiones especificadas en esta guía.
Adicionalmente, instale las dependencias de desarrollo:
npm install –save-dev \
@types/aws-lambda \
serverless-plugin-common-excludes \
serverless-plugin-include-dependencies - Cree la estructura del proyecto.
A continuación se muestra una estructura de proyecto sugerida.
heflo-customization
├── package.json
├── process
├ └── functions.ts
├── serverless.yml
└── tsconfig.json
- Cree el archivo tsconfig.json con el siguiente contenido:
{
«compilerOptions»: {
«target»: «ES2020»,
«module»: «commonjs»,
«sourceMap»: true,
«outDir»: «.build»,
«strict»: true,
«rootDir»: «./»,
«esModuleInterop»: true
}
}
Esta configuración habilita la compilación de TypeScript compatible con Serverless Framework y AWS Lambda. - Cree el archivo serverless.yml:
service: heflo-customization
frameworkVersion: ‘3’
provider:
name: aws
runtime: nodejs16.x
region: sa-east-1
timeout: 30
versionFunctions: false
functions:
function01:
handler: process/functions.function01
events:
– http:
path: /function01
method: post
plugins:
– serverless-offline
– serverless-plugin-typescript
– serverless-plugin-common-excludes
– serverless-plugin-include-dependencies
– serverless-dotenv-plugin - Cree su primera función de personalización.
Cree el archivo process/functions.ts:
import * as HEFLOApi from «heflo-api»;
exports.function01 = async (event: any) => {
try {
const body = JSON.parse(event.body);
const context = new HEFLOApi.Events.WorkItem.OnExecuteSequenceFlow({
body,
});
context.WorkItem.Set(
«textField»,
«Customization executed successfully»
);
return {
statusCode: 200,
body: JSON.stringify(
context.GetModifiedData()
),
};
} catch (error) {
return {
statusCode: 500,
body: JSON.stringify({
message: `Something went wrong: ${error}`,
}),
};
}
};
Este ejemplo sencillo recibe el payload del evento de HEFLO, crea el contexto de ejecución de HEFLO según el tipo de evento y actualiza el campo de proceso textField con el siguiente mensaje: «Customization executed successfully», para luego devolver los datos modificados de vuelta a HEFLO.
Ejecución del proyecto localmente
- Inicie el servidor local:
serverless offline
La API se ejecutará localmente en el puerto 3000.
- Abra otra terminal y ejecute:
ngrok http 3000
ngrok generará una URL HTTPS pública que se puede configurar dentro de HEFLO para fines de prueba.
Despliegue de la personalización
Después de realizar las pruebas locales, despliegue el proyecto en AWS Lambda utilizando:
serverless deploy
El proceso de despliegue:
- Empaqueta la aplicación;
- Sube el código a AWS;
- Crea las funciones Lambda;
- Crea los endpoints de API Gateway;
- Devuelve las URL públicas de la API.
Ejemplo de resultado:
endpoints:
POST – https://xxxx.execute-api.sa-east-1.amazonaws.com/dev/sampleFunction
Estos endpoints se pueden utilizar directamente dentro de las configuraciones de automatización de HEFLO.
Uso de la personalización en la automatización de HEFLO
Después del despliegue, el endpoint se puede conectar a los eventos de automatización de procesos dentro de HEFLO.
El siguiente paso es crear el proceso BPMN y configurar la llamada al web service; para ello se utilizará un diagrama simple de dos tareas para enviar, recibir y mostrar el evento en el campo del formulario.
- Desde la página principal del entorno de HEFLO, acceda al editor de procesos.
- Abra un proceso BPMN existente o cree uno desde cero.
- Verifique que el proceso tenga habilitada la opción Proceso automatizado.
- Agregue el elemento de inicio, la “Primera tarea”, la “Segunda tarea” y el elemento de fin, como se muestra en la imagen a continuación.
- En ambas tareas, vincule una entrada de datos (formulario).
- Haga doble clic en el formulario para acceder a la ventana de creación de formularios.
- En la “Primera tarea”, cree un campo de texto llamado “Campo de Texto”.
- Aquí debemos dar un paso adicional y, para ello, tenemos dos enfoques posibles:
a. El primero es usar el identificador del campo para mapear el campo del formulario dentro de la aplicación; para esto:
i. Haga clic en el icono del lápiz en el lado derecho del campo y seleccione la opción Editar
ii. En la parte inferior de la ventana, haga clic en el icono “</>” para acceder al identificador del campo y reemplace field_id en las líneas como:
context.WorkItem.Set(«textField»,);
Para mapear el campo dentro de la aplicación.
b. El segundo es crear un alias personalizado; esto mantiene el código de la API más simple y fácil de mantener; para ello:
i. Haga clic en el icono del lápiz en el lado derecho del campo y seleccione la opción Editar.
ii. En la parte inferior de la ventana, haga clic en el icono “</>” para acceder al identificador del campo.
iii. Seleccione la opción para crear un alias y confirme.
iv. Use estos en lugar de field_id en las líneas como:
context.WorkItem.Set(«textField»,);
Para mapear el campo dentro de la aplicación.
Utilizando el segundo enfoque, cree el siguiente alias para el campo de texto; este debe ser el mismo que se usa en el código.
Campo: Campo de Texto Alias: textField; - Ahora es el momento de configurar la llamada a la API; seleccione el flujo de ejecución entre las dos tareas y, en la pestaña de ejecución (menú de propiedades), haga clic en el botón de ejecución.
- En tipo de personalización, seleccione API usando NodeJS.
- Aquí necesitamos configurar la llamada al web service. Para este ejemplo, cree un nuevo web service y configure:
a. URL de producción: https://abcd-1234.ngrok-free.app/
b. Recurso: function01
c. Método: Post
d. Autenticación: Ninguna
Donde la URL de producción debe ser la misma que se muestra en la terminal de ngrok.
Tenga en cuenta que no necesitamos configurar ningún parámetro de envío ni de respuesta; toda la información se manipulará dentro de la aplicación y se enviará al entorno de HEFLO dentro de un contexto. - Confirme la configuración.
- Guarde la configuración.
- En el editor, haga clic derecho en el elemento de inicio y seleccione Probar, luego Iniciar nuevo elemento de trabajo.
- Valide la configuración.
Un punto interesante es que este pequeño proyecto se puede adaptar aún más para modelar reglas de negocio complejas y servir como punto de partida para futuros proyectos. Otros escenarios de uso comunes incluyen:
- Eventos de cambio de campo;
- Inicialización de formularios;
- Ejecución de botones de acción;
- Ejecución de flujos de secuencia;
- Validaciones de aprobación;
- Asignación dinámica de participantes;
- Integraciones externas.
El endpoint de personalización recibe el contexto de ejecución del proceso desde HEFLO y devuelve los datos modificados a la plataforma. Este enfoque permite la implementación de reglas de negocio avanzadas mientras mantiene el modelo BPMN limpio y fácil de mantener.
Consideraciones Finales
Las personalizaciones de API de HEFLO proporcionan una poderosa capa de extensión para los proyectos de automatización de procesos. Al combinar el modelado de procesos BPMN, la personalización en Node.js y el despliegue Serverless, las organizaciones pueden implementar soluciones de automatización altamente flexibles y fáciles de mantener.
La biblioteca de la API de HEFLO simplifica la interacción con el proceso y permite a los desarrolladores enfocarse en la lógica de negocio en lugar de los detalles de la infraestructura.