El objetivo de este documento es aclarar las diferencias y el uso de los web services y del proyecto de API de HEFLO. Esto le ayudará a automatizar mejor su proceso BPMN, aprovechándose al máximo sin complicar las cosas en exceso ni asignar recursos de manera incorrecta.
Antes de presentar las características específicas de HEFLO, es importante comprender la diferencia entre las integraciones tradicionales de web services y las personalizaciones de API.
Un web service es un mecanismo de comunicación, generalmente basado en los protocolos REST o SOAP, utilizado para intercambiar datos entre sistemas. En la práctica, permite que una aplicación envíe o reciba información de otra aplicación a través de endpoints predefinidos y solicitudes y respuestas estructuradas. Estas integraciones pueden conectar a HEFLO con sistemas de terceros desarrollados de forma interna o externa. En HEFLO, una configuración de web service normalmente requiere una URL del servicio, parámetros opcionales de ruta o consulta, configuraciones de autenticación y el mapeo de datos de solicitud o respuesta utilizado durante la automatización del proceso.
Las personalizaciones de API, por otro lado, están diseñadas para implementar lógica de negocio personalizada y escenarios de automatización avanzados. En lugar de simplemente intercambiar datos, una personalización de API permite a los desarrolladores crear proyectos que manipulan la información del proceso de forma programática, aplican validaciones y cálculos, integran múltiples servicios, transforman datos o ejecutan lógicas de decisión complejas. Estos proyectos pueden ser desarrollados por el equipo del cliente o por el equipo de HEFLO, y utilizan funciones preconstruidas y APIs proporcionadas por la plataforma para comunicarse directamente con los procesos automatizados a través de objetos de contexto, parámetros de solicitud y payloads de respuesta. Además, las personalizaciones de API se pueden ejecutar y depurar localmente durante el desarrollo y, posteriormente, implementar en servidores externos o entornos serverless para su uso en producción.
En resumen, los web services se enfocan principalmente en la comunicación de sistema a sistema y el intercambio de datos, mientras que las personalizaciones de API proporcionan una capa programable que permite un comportamiento de automatización avanzado, lógica de procesamiento personalizada y capacidades de integración más profundas.
¿Qué son los Web Services en HEFLO?
En HEFLO, los web services funcionan con base en el protocolo REST y la transferencia de datos a través de JSON. Su objetivo principal es permitir el intercambio de datos entre aplicaciones desarrolladas por terceros y/o por el usuario. Los elementos BPMN como Tareas y Eventos, Campos de Datos Externos o Botones de Acción también pueden ser utilizados por los web services para Buscar, Enviar y Recibir datos con configuraciones ligeramente diferentes.
El uso típico para esta configuración incluye APIs de terceros para obtener registros públicos, como códigos postales, información de empresas o tasas de cambio; automatizaciones de terceros, como Zapier, que pueden usar webhooks; y APIs personalizadas de la empresa o integración con ERPs, entre otros.
¿Qué son las personalizaciones de API?
Por otra parte, HEFLO ofrece un proyecto de API basado en Node.js que cuenta con funciones integradas que permiten al usuario ejecutar reglas de negocio o lógicas complejas para manipular datos. Además de los elementos BPMN, los Campos de Datos Externos y los botones de Acción, también podemos usar el proyecto para trabajar en Campos de Formulario a través de las operaciones de Inicialización, Adición, Cambio y Eliminación; llamar a la API durante el flujo de ejecución, definir participantes y trabajar con registros personalizados: creación, actualización y eliminación. Puede encontrar una lista completa de funciones integradas y disparadores en nuestra documentación de la API: Link
Ventajas y limitaciones
A partir del resumen anterior, ya podemos ver las ventajas y desventajas de cada enfoque. Los web services se utilizan normalmente cuando no se necesita una lógica de negocio compleja y el enfoque es únicamente la transferencia de datos. Los parámetros de entrada y salida se definen en la documentación y generalmente son fijos; estos deben recuperarse del JSON utilizando el acceso a propiedades de objetos (o navegación por JSON Path), como data[0].parameters.name, y mapearse a un campo de destino. Otros escenarios incluyen APIs genéricas de la empresa que implementan la lógica de negocio, pero son consumidas por diferentes servicios y, por lo tanto, funcionan con datos JSON y aplicaciones intermedias para permitir la comunicación entre HEFLO y otros sistemas. Todo esto es «estático» en el sentido de que el usuario final es solo un consumidor, pero no requiere habilidades de programación, mantenimiento ni capacidad de alojamiento.
La personalización de API de HEFLO permite el acceso a todas las características de un web service, pero con acceso a funciones integradas que permiten operaciones de datos específicas, manipulación de datos a través de alias y mucho más, aunque tiene la desventaja de requerir programación en Node.js, mantenimiento y alojamiento. Vale la pena señalar que HEFLO ofrece un servicio de consultoría o servicio de implementación para tales situaciones; hable con nuestro equipo de Ventas para obtener más información.
Casos de uso típicos de integración y automatización
Independientemente de la elección del método de integración, primero debemos establecer la configuración del servicio. Para ello:
- Inicie sesión en su entorno de HEFLO y acceda al editor de procesos.
- En el menú superior, haga clic en las herramientas de visualización del editor (icono del ojo).
- Seleccione la opción de web services.
- En la pestaña de web services, haga clic en crear un nuevo registro (icono de más).
- En la página de configuración de Web service, complete los campos obligatorios según su configuración.
- Nombre – Se utiliza para identificar fácilmente el servicio utilizado.
- URL de producción – La URL utilizada para llamar al servicio; no inserte la ruta de la función aquí, esto se utilizará más adelante.
Ej.: La API de código postal, como Zippopotam, requiere la siguiente URL para ejecutar una búsqueda:
https://api.zippopotam.us/us/90210
En este paso, solo insertamos la parte inicial de la URL, sin los parámetros:
https://api.zippopotam.us/us/ - URL de prueba (Opcional) – Normalmente es la misma que la URL de producción.
- Método – Define si la llamada es de «lectura» o de «escritura».
- Tipo de autenticación – Tipo de autenticación utilizado por el servicio.
Para servicios o aplicaciones que realizan operaciones específicas, como consultas a bases de datos en entornos de HEFLO, o donde se requiera una capa adicional de protección, podemos definir una clave de API (API key) y utilizarla para exigir una validación antes de cada llamada. Para generar una nueva Clave de API, vaya a la pestaña de claves de API en la página del Web service y:
- En la región de Claves de API, haga clic en Agregar nueva clave (icono de más).
- Si el MFA está configurado, se le solicitará que ingrese su Código de Autenticador.
- En la pantalla de configuración, puede definir un nombre descriptivo para ella.
- Cierre la ventana para iniciar automáticamente la descarga del archivo de la clave.
Una vez que se genera la clave, se guarda en nuestro servidor con un cifrado irreversible. Esto significa que no es posible recordar la contraseña y, si la pierde, deberá volver a generar la clave y realizar el mantenimiento en todos los programas de llamada que usted administre.
Tenga en cuenta que este no es el único método para crear la configuración o la clave; ambos se pueden configurar directamente en el elemento BPMN, el campo de formulario o acción, y en la definición del participante.
Configuraciones de web services
En esta sección demostraremos cómo configurar una llamada de web service para dos escenarios diferentes: el uso de un servicio de terceros y un proyecto de API personalizado. Tenga en cuenta, sin embargo, que se puede encontrar documentación adicional para otros escenarios en nuestra Base de Conocimientos: Link.
Caso 1: Servicio de terceros – Código postal de EE. UU. usando Zippopotam
El objetivo de esta configuración es extraer cierta información del código postal (país, estado, ciudad) en función de un código postal determinado. Este es un uso típico de la configuración de un web service, donde el usuario conoce las entradas (solicitudes) y salidas (respuestas) esperadas.
Podemos modelar esta llamada utilizando una tarea de servicio que lea el código postal de la tarea “Recolectar datos”, realice la solicitud para recopilar la información del código postal y muestre la información en la tarea “Mostrar datos”. Un enfoque alternativo es utilizar un botón de acción dentro del formulario para realizar la solicitud; esto elimina la tarea de web service y puede ser útil en escenarios donde el usuario deba visualizar la información de forma inmediata.
Para configurar este caso de uso, primero:
- 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, las tareas “Recolectar datos” y “Mostrar datos”, la tarea de servicio y el elemento de fin, como se muestra en la imagen a continuación.
- En la tarea “Recolectar datos”, vincule una entrada de datos (formulario).
- Haga doble clic en el formulario para acceder a la ventana de creación de formularios.
- Dentro de ella, cree un campo de texto llamado “Código postal” y márquelo como obligatorio.
- Haga lo mismo para la tarea “Mostrar datos”, creando también los siguientes campos de texto:
a. País;
b. Estado;
c. Ciudad.
- En la tarea de servicio, haga clic en el menú de propiedades (lado derecho) y localice la sección Ejecución.
- Establezca el tipo de conector como Web service.
- Haga clic en el botón Configurar web service para abrir la ventana de configuración.
- Aquí necesitamos configurar la llamada al web service y definir los parámetros de envío y recepción.
Para este ejemplo, los parámetros de entrada se envían directamente dentro de la URL, por lo que no utilizamos la pestaña “Parámetros de envío”, solo copie la configuración a continuación.
Para obtener más detalles sobre cómo definir correctamente la “URL de producción” y el “Recurso”, consulte la documentación del web service. - En la pestaña de respuesta, mapee cada parámetro recibido con el campo de destino.
Tenga en cuenta que este paso requiere conocimientos de acceso a propiedades de objetos; alternativamente, puede utilizar soluciones en línea, como JSON path finder, para identificar fácilmente la ruta de datos correcta. - 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.
Nota: A veces, el JSON de respuesta tiene un formato diferente al esperado, por lo que pueden ser necesarios algunos ajustes. Asegúrese de probar siempre antes de publicar el proceso.
Caso 2: Proyecto de API personalizado
El objetivo de esta configuración es simular una API interna de la empresa que se pueda utilizar para ejecutar reglas de negocio sin usar las funciones integradas de HEFLO o para la transferencia de datos entre aplicaciones; en este caso, calcular el costo total en función del departamento, el número de cuotas y el costo por mes. Dado que la idea aquí es presentar la configuración del proceso BPMN, cubriremos brevemente cómo crear e implementar un proyecto basado en:
- Node.js + Express API;
- Exponerlo públicamente usando ngrok.
Se requiere un conocimiento mínimo de ambos para realizar ajustes y depurar; sin embargo, siguiendo los pasos, esta guía le dará acceso a una API simple para probar la configuración del web service.
Nota: Todos estos pasos se realizan utilizando una terminal, como la terminal de VS Code.
- Cree el directorio del proyecto.
a. Abra la terminal y ejecute:
mkdir custom-api
cd custom-api - Inicialice el proyecto Node.js.
a. Ejecute:
npm init -y
Esto crea un archivo package.json. - Instale las dependencias:
npm install express
- Cree el archivo de la API.
a. Cree un archivo llamado server.js dentro del directorio.
b. Pegue este contenido:
const express = require(«express»);
const app = express();
app.use(express.json());
app.post(«/computeTotal», (req, res) => {
const { code, param } = req.body;
const [numberStr, decimalStr] = (param || «»).split(«;»);
const number = parseFloat(numberStr);
const decimal = parseFloat(decimalStr);
let constant = 1;
switch (code) {
case «HR»:
constant = 1.25;
break;
case «ACC»:
constant = 1.30;
break;
case «IT»:
constant = 1.15;
break;
default:
constant = 1;
}
const total = constant * (number * decimal);
res.json({
total
});
});
app.listen(4000, () => {
console.log(«Server running on port 4000»);
}); - Ejecute la API localmente.
a. Inicie el servidor.
node server.js
b. Resultado esperado: Server running on port 4000
- Después de instalar y configurar su ngrok, exponga su API local.
a. Ejecute esto en una nueva terminal:
ngrok http 4000
b. Verá algo como:
Forwarding https://abcd-1234.ngrok-free.app -> http://localhost:4000
c. Su endpoint se convierte en:
https://abcd-1234.ngrok-free.app/computeTotal
- Mantenga ambos servicios en ejecución.
El siguiente paso es crear el proceso BPMN y configurar la llamada al web service; para ello se reutilizará el diagrama presentado en el Caso 1.
- 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, las tareas “Recolectar datos” y “Mostrar datos”, la tarea de servicio y el elemento de fin, como se muestra en la imagen a continuación.
- En la tarea “Recolectar datos”, vincule una entrada de datos (formulario).
- Haga doble clic en el formulario para acceder a la ventana de creación de formularios. A partir de aquí, el proceso cambia un poco:
- En la tarea “Recolectar datos”, cree tres campos y márquelos como obligatorios:
a. Departamento: Campo de texto con las opciones “HR”, “ACC”, “IT” y “Otro”.
b. Cuotas: Campo de número (entero);
c. Costo por mes (US$): Campo de número decimal; - En la tarea “Mostrar datos”, cree un campo de número decimal llamado “Total (US$)”.
- En la tarea de servicio, haga clic en el menú de propiedades (lado derecho) y localice la sección Ejecución.
- Establezca el tipo de conector como Web service.
- Haga clic en el botón Configurar web service para abrir la ventana de configuración.
- Aquí necesitamos configurar la llamada al web service y definir los parámetros de envío y recepción. Para ello, cree un nuevo web service y configure:
a. URL de producción: https://abcd-1234.ngrok-free.app/
b. Recurso: computeTotal
c. Método: Post
d. Autenticación: Ninguna
donde la URL de producción debe ser la que se muestra en la terminal de ngrok.
- En los parámetros de envío, mapeamos el campo del formulario con las entradas esperadas de la API, en este caso, code y param. La idea aquí es presentar los dos enfoques posibles: un solo campo o múltiples campos por entrada.
a. Nombre del parámetro: code Valor: Department
b. Nombre del parámetro: param Valor: :Installments;:Cost per Month (US$)
- Finalmente, la pestaña de respuesta mapeará el total con el campo de formulario “Total (US$)”.
a. Nombre del parámetro: total Valor: Total (US$)
- 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.
Es importante enfatizar que este enfoque utiliza un proyecto local para simular una API de la empresa que ya está implementada y disponible en línea; por lo tanto, esta implementación solo funcionará mientras el proyecto esté en ejecución.
Configuraciones de la API de HEFLO
Esta sección final demostrará cómo implementar un proyecto local de API de HEFLO y usarlo en un proceso BPMN simple. Para este escenario, implementaremos un proyecto de API que, ante un cambio de valor en el campo “Monto”, calculará un nuevo total después de aplicar los impuestos.
Se puede encontrar documentación adicional para otros escenarios en nuestra Base de Conocimientos: Link.
El enfoque aquí es similar al Caso 2, donde la idea es presentar la configuración del proceso BPMN. En este ejemplo, cubriremos brevemente cómo crear e implementar una API de integración ligera basada en:
- Node.js + Express;
- HEFLO’s SDK;
- Exposición pública mediante ngrok para la integración del webhook de HEFLO
Nuevamente, se requiere un conocimiento mínimo de esto para realizar ajustes y depurar; sin embargo, siguiendo los pasos, esta guía le dará acceso a una API simple para probar la configuración del web service.
Nota: Todos estos pasos se realizan utilizando una terminal, como la terminal de VS Code.
- Cree un directorio para el proyecto.
a. Abra la terminal:
mkdir heflo-api-project
cd heflo-api-project - Inicialice el proyecto Node.js.
a. Ejecute:
npm init -y
Esto crea un archivo package.json.
- Instale las dependencias
a. Necesitamos instalar Express.js y el SDK de la API de HEFLO; para ello, ejecute:
npm install express heflo-api
npm install -D typescript ts-node @types/node @types/express
El paquete de HEFLO proporciona la gestión del contexto de eventos para las personalizaciones del flujo de trabajo - Cree el tsconfig.json
{
«compilerOptions»: {
«target»: «es2020»,
«module»: «commonjs»,
«strict»: false,
«esModuleInterop»: true
}
} - Cree el servidor de la API.
a. Cree el archivo server.ts dentro del directorio.
b. Pegue el siguiente código:
import express from «express»;
import * as HEFLOApi from «heflo-api»;
const app = express();
app.use(express.json());
app.get(«/», (_, res) => { res.json({ status: «HEFLO API running» }); });
app.post(«/onChanged», async (req, res) => {
try {
const context = new HEFLOApi.Events.WorkItem.OnChanged({ body: req.body });
const department = context.WorkItem.Get(«department»);
const amount = parseFloat(context.WorkItem.Get(«amount_uss») || «0»);
let tax = 1;
switch (department) {
case «HR»:
tax = 1.25;
break;
case «ACC»:
tax = 1.30;
break;
case «IT»:
tax = 1.15;
break;
default:
tax = 1;
}
const total = amount * tax;
context.WorkItem.Set(«total_uss», total);
res.json(context.GetModifiedData());
} catch (err: any) {
console.error(err);
res.status(500).json({
error: err.message
});
}
});
const PORT = 4000;
app.listen(PORT, () => { console.log(`Server running on port ${PORT}`); }); - Ejecute el proyecto.
a. Inicie el servidor:
npx ts-node server.ts
Resultado esperado: Server running on port 4000
- Después de instalar y configurar su ngrok, exponga su API local.
a. Ejecute esto en la terminal:
ngrok http 4000
b. Verá algo como:
Forwarding https://abcd-1234.ngrok-free.app -> http://localhost:4000
Su endpoint se convierte en:
https://abcd-1234.ngrok-free.app/onChanged - Mantenga ambos servicios en ejecución.
El siguiente paso es crear el proceso BPMN y configurar la llamada al web service; para ello se utilizará un diagrama de tarea única para mostrar únicamente el evento de cambio 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, las tareas “Recolectar datos” y “Mostrar datos”, y el elemento de fin, como se muestra en la imagen a continuación.
- En la tarea “Recolectar datos”, vincule una entrada de datos (formulario).
- Haga doble clic en el formulario para acceder a la ventana de creación de formularios.
- En la tarea “Recolectar datos”, cree tres campos y configúrelos de la siguiente manera:
a. Departamento: Campo de texto con las opciones “HR”, “ACC”, “IT” y Otro.
b. Monto (US$): Campo de número decimal;
c. Total (US$): Campo de número decimal;
- 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.Get(«field_id»);
context.WorkItem.Set(«field_id»,);
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.Get(«field_id»);
context.WorkItem.Set(«field_id»,);
Para mapear el campo dentro de la aplicación.
c. Cree el siguiente alias para cada campo; estos deben ser los mismos que se usan en el código.
Campo: Departamento Alias: department;
Campo: Monto (US$) Alias: amount_uss;
Campo: Total (US$) Alias: total_uss. - Ahora es el momento de configurar la llamada a la API; seleccione el campo de formulario “Monto (US$)” y haga clic en el icono del lápiz.
- Haga clic en la opción Cambio, esto configurará el evento de llamada cada vez que cambie el campo.
- 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: onChanged
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, a diferencia de antes, 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.
Es importante señalar que este enfoque utiliza un proyecto local para simular una API de la empresa que normalmente estaría implementada y disponible en línea. Como resultado, esta implementación solo funcionará mientras el proyecto local esté en ejecución.
Una vez validada la solución, coordine con su equipo de TI para implementar el proyecto en un entorno de producción adecuado. Como alternativa, HEFLO ofrece servicios de consultoría e implementación para ayudar a las organizaciones a implementar y gestionar sus reglas de negocio. Para obtener más información, comuníquese con el equipo de ventas en: Link
Conclusión
En resumen, este artículo explica los enfoques de integración disponibles en HEFLO y ayuda a los usuarios a identificar la mejor opción para cada escenario de automatización.
Los web services se utilizan normalmente cuando no se necesita una lógica de negocio compleja y el enfoque es únicamente la transferencia de datos; mientras tanto, la personalización de API de HEFLO permite el acceso a todas las características de un web service, pero con acceso a funciones integradas que permiten operaciones de datos específicas, manipulación de datos y mucho más.
Para ambos casos se presentaron ejemplos sencillos de uso y configuración, pero tenga en cuenta que también contamos con documentación adicional relacionada con información o casos de uso en nuestra base de conocimientos y documentación de la API.