Un tutorial de introducción para desarrolladores a ProcessMaker.IO
Hola a todos. Soy Taylor Dondich y soy el CTO aquí en ProcessMaker. Creador de procesos.IO es nuestro motor de flujo de trabajo de alto rendimiento en la nube y me complace mostrarle cómo comenzar. La mejor manera de mostrarte cómo es con código real. Esta primera publicación es la primera de una serie de tutoriales que le presentarán ProcessMaker.IO. Cada nueva publicación le presentará nuevos conceptos y cómo utilizarlos. Comenzarás con un flujo de trabajo simple y luego avanzarás hacia el uso de escenarios más complejos. Estos escenarios mostrarán algunas de las interesantes características que tiene ProcessMaker.IO. ProcessMaker.IO es gratuito al registrarse y empezar. Una vez que tengas tu cuenta, podrás obtener el código para estos tutoriales en nuestro repositorio de GitHub.Para nuestro ejemplo, supongamos que somos desarrolladores en Widget Co. Nuestro jefe quiere que construyamos un formulario que permita a nuestros clientes contactarnos por cualquier motivo. Si completan el formulario, deberíamos recibir un correo electrónico con los datos proporcionados por el cliente. Es un ejemplo sencillo y perfecto para mojarnos los pies.
Registrarse y poner en marcha su primer motor de flujo de trabajo
Primero, visite la página de registro de ProcessMaker.IO para crear su cuenta. Una vez que hayas completado tus datos, recibirás un correo electrónico que tiene un enlace para verificar tu cuenta. Una vez verificado, podrás crear tu primer motor de flujo de trabajo. Verás el panel de control de ProcessMaker.IO. Este panel muestra la lista de sus motores de flujo de trabajo. Como no tienes ninguno, haz clic en el botón “Crear instancia” para crear tu propio motor.
Acerca de los motores de flujo de trabajo
Cada motor de flujo de trabajo es un entorno aislado que tiene su propio punto final de API y datos. Este nivel de aislamiento le permite tener muchos motores para diferentes escenarios. Podrías tener un motor para un entorno de puesta en escena y otro para producción. Puede tener motores separados para diferentes unidades de negocio. La forma en que organizas tus motores depende de ti. Cada motor tiene sus propios datos y no puede ver los datos de otro motor en su cuenta.
Para nuestro ejemplo, crearemos un flujo de trabajo simple, también conocido como proceso, que enviará un correo electrónico. Si visualizáramos este flujo de trabajo, se vería así: Si está familiarizado con los procesos comerciales, el diagrama anterior le resultará familiar. Es un Diagrama BPMN que representa visualmente lo que queremos hacer. ProcessMaker.IO es un motor de flujo de trabajo compatible con BPMN. Si está familiarizado con BPMN, se sentirá cómodo utilizando el motor. Si no estás familiarizado con BPMN, no te preocupes, no es un conocimiento necesario. Repasaremos los conceptos. Al crear un flujo de trabajo en ProcessMaker.IO, puede elegir cómo hacerlo. Si está familiarizado con las herramientas de diagramación BPMN, puede crear un diagrama BPMN e importarlo al motor. Mostraremos un ejemplo de esto en un tutorial posterior. También puedes crear un proceso mediante programación, que es lo que haremos en este ejemplo. ProcessMaker.IO tiene SDK disponibles en muchos idiomas. Para este ejemplo, utilizaremos el SDK PHP de ProcessMaker.IO. Primero, queremos inicializar nuestro cliente SDK. Para hacer esto, necesitará el punto final de API de su motor y el token de acceso a API de su primer usuario. Estos se pueden encontrar en su panel de control. Asegúrese de descargar el código desde nuestro repositorio de GitHub. Usaremos esto como punto de partida. Querrá ejecutar el comando composer install de PHP para instalar el SDK. Una vez hecho esto, cree un archivo .env en la raíz de su directorio de código. Esto contendrá su punto final de API, token de acceso y otras opciones de configuración.
PMIO_PUNTO FINAL=https://fds23zz.api.processmaker.io/api/v1 PMIO_ACCESS_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjkwMTBmZGI5YWMxYTZiNGI2ZGMyZjNiODZmZDg5OTJhYWRlODI0MGU5MWI3NWRkNDhjNTA4MzRlYjQzZjUzNmFjMDkxNTg4MDY5MDZiM2MxIn0.eyJhdWQiOiIxIiwianRpIjoiOTAxMGZkYjlhYzFhNmI0YjZkYzJmM2I4NmZkODk5MmFhZGU4MjQwZTkxYjc1ZGQ0OGM1MDgzNGViNDNmNTM2YWMwOTE1ODgwNjkwNmIzYzEiLCJpYXQiOjE1MDY1NDM5MTMsIm5iZiI6MTUwNjU0MzkxMywiZXhwIjoxNTM4MDc5OTEzLCJzdWIiOiIxIiwic2NvcGVzIjpbXX0.PTFaPvddgKqB51trFAV2Ka_8W2npZ9jbc2uGAoYdFKfMNNvvNl07DWTDXxK90B0OwLAA08husWmfkVomWlm6W44hXuJEa8zG3SfRGwpzPQiA4NZ706YkbWqjLfY5QH41MwpJlkgKeQv6Q6nvZluyXrzQlvZVkSfSb9GvNe4h6arLLn1KQp3xQnnK-Jk8Q109uEnhmkOs4mfUKj5rd0E_DKJUTc-CmXoJZ8zsvuDv-irv7PtQlpQRmVdlOJD2mTO2NNwQpLjdl4d3D4a7zKpMcrkeLmqz_Cums4uk5069Ju2TRmAbyGfWUgL7aTg-o80xWPnwY9AY7xC__mZvW1ydlpLKX18-bIpj_5acCyqQmnA921KAoO99YV3rT19I_VKF9dglzMOPWrcLzb44qK4ONXjx8Za3zyFJZpBa_SrCkhYiOhY1GNNk5EpqqMCAT_D8nCnrR7fmLrXtFJsP9yPDYwMZxYuppCH6rcqLIeB0VlmEiNTJu_1RlYgcmG02boSNPXHmzrEd9eJKRksSWVfkE90quuDMNoEFYaL1A_yU0yn2iW0T--lh_kPOGEth2WrShoYEZ667FSrSmsRYoLe8BiqGbiSquYrtDhHYhcidOeWyZLtUDMnVNi00v3i3hrIp7KIvIM9zAQxzk3OwAxXFrKV6Ut3-cqyvpMhWo9NPyZI # Establezca en verdadero si desea registrar cada llamada a la API HTTP DIRECCIÓN_CORREO ELECTRÓNICO_OBJETIVO=myaddress@mydomain.com PMIO_DEBUG=falso PMIO_DEBUG_FILE=debug.log
Inicializando el SDK de PHP
Primero queremos inicializar nuestro Cliente API con nuestras credenciales. En nuestros ejemplos de código, el archivo es bootstrap.php. Este archivo está incluido en todos los ejemplos. Veamos cómo se inicializa el cliente.
/InicializarnuestroclienteAPIalqueharánreferencialosscriptsdelcliente $pmio = nuevo Cliente(nuevo ApiClient($config));
Creación del objeto de proceso
El objeto de proceso es lo que almacena la definición de nuestro flujo de trabajo. Contendrá el mapeo de eventos, tareas y cómo cada elemento fluye hacia el siguiente. No te preocupes por esos términos, los cubriremos pronto. En el archivo introduction/create.php, comenzamos creando el objeto de proceso a través de nuestra API.
$respuesta = $pmio->addProcess(nuevo ProcessCreateItem([ 'datos' => nuevo Proceso([ 'atributos' => nuevos atributos de proceso([ 'nombre' => 'Proceso de introducción' ]) ]) ])); /Obtenerelobjetodedatossubyacentequerealmenterepresentanuestroproceso $process = $response->getData();
Creación de los eventos de inicio y fin
En el mundo del flujo de trabajo, los eventos describen lo que sucede en su flujo de trabajo en distintos momentos. Para nuestro caso simple, utilizamos un evento de inicio y un evento final. Un Evento de Inicio es lo que inicia la ejecución de nuestro proceso. Nuestro evento de inicio se activa cuando un cliente envía el formulario de contacto. El evento final indica que nuestro flujo de trabajo está completo. El objetivo del flujo de trabajo es pasar del evento de inicio al evento final. En el archivo introduction/create.php verás cómo los creamos.
$respuesta = $pmio->addEvent($process->getId(), nuevo EventCreateItem([ 'datos' => nuevo Evento([ 'atributos' => nuevos atributos de evento([ 'nombre' => 'Inicio', 'tipo' => 'INICIAR', 'definición' => Atributos del evento::DEFINITION_MESSAGE ]) ]) ])); $startEvent = $response->getData();
$respuesta = $pmio->addEvent($process->getId(), nuevo EventCreateItem([ 'datos' => nuevo Evento([ 'atributos' => nuevos atributos de evento([ 'nombre' => 'Fin', 'tipo' => 'FIN', 'definición' => Atributos del evento::DEFINITION_NONE ]) ]) ])); $endEvent = $response->getData();
Creación de la tarea para enviar un correo electrónico
En nuestro flujo de trabajo, queremos enviar un correo electrónico cuando el cliente envía el formulario de contacto. Para ello, necesitamos utilizar una tarea de servicio. Una tarea representa algo procesable en un flujo de trabajo y a quién debe involucrar. Una tarea de servicio se ejecuta en segundo plano y no necesita intervención humana. Esto es exactamente lo que queremos para que nuestro flujo de trabajo envíe un correo electrónico.
$respuesta = $pmio->addTask($process->getId(), nuevo TaskCreateItem([ 'datos' => nueva tarea([ 'atributos' => nuevos TaskAttributes([ 'nombre' => 'Enviar formulario de contacto por correo electrónico', 'tipo' => 'TAREA-SERVICIO' ]) ]) ])); $serviceTask = $response->getData();
Tenemos que decirle a nuestro ServiceTask sus detalles de implementación. Utilizaremos uno de los conectores de ProcessMaker.IO para brindar la posibilidad de enviar correo. ProcessMaker.IO tiene muchos conectores que permiten interacciones con servicios de terceros. Hay conectores disponibles para Slack, Mailchimp, Google Apps y más. Primero creemos nuestra plantilla de correo electrónico para que podamos indicarle a nuestro conector que la use.
Esta es una plantilla de correo electrónico HTML. Puedes ver algunos campos rodeados de tirantes rizados. ProcessMaker.IO puede inyectar valores en estos marcadores de posición. El modelo de datos del proceso en ejecución contiene estos valores. En nuestro ejemplo, el envío del formulario HTML representa el modelo de datos. Creemos nuestro conector y le digamos que se asocie con nuestra ServiceTask.
$pmio->addTaskConnector($process->getId(), $serviceTask->getId(), nuevo TaskConnectorCreateItem([ 'datos' => nuevo TaskConnector([ 'atributos' => nuevos TaskConnectorAttributes([ 'connector_class' => 'SendMailConnector', 'parámetros_entrada' => [ 'to' => getenv('DIRECCIÓN_CORREO ELECTRÓNICO_OBJETIVO'), 'nombre' => 'Envío de formulario de introducción', 'subj' => 'Envío de formulario de contacto desde {nombre}', 'cuerpo' => $plantilla ] ]) ]) ]));
Asegúrese de haber modificado TARGET_EMAIL_ADDRESS en su archivo .env. Puedes verlo referenciado en el ejemplo de código.
Cableándolo todo junto con flujos
Ahora que tenemos nuestros eventos y tareas, necesitamos definir la ruta desde el Evento de Inicio hasta el Evento Final. Los flujos definen estos caminos. Un flujo debe tener una fuente y un objetivo. Por ejemplo, nuestro primer flujo comienza desde nuestro Evento de inicio y finaliza con la ServiceTask. Otro flujo pasa de ServiceTask a nuestro evento final. Vamos a crearlos ahora.
$pmio->addFlow($process->getId(), nuevo FlowCreateItem([ 'datos' => nuevo flujo([ 'atributos' => nuevos FlowAttributes([ 'nombre' => 'Tarea de servicio a finalizar', 'from_object_id' => $serviceTask->getId(), 'desde_tipo_objeto' => $serviceTask->getType(), 'to_object_id' => $endEvent->getId(), 'to_object_type' => $endEvent->getType() ]) ]) ]));
Mantenemos nuestro ID de proceso y el ID de evento de inicio para uso futuro
Una vez que hayamos definido nuestro Proceso, necesitamos conocer el ID del Proceso y el Evento de Inicio. Usaremos estos valores al llamar a nuestra API con los datos de nuestro formulario HTML.
print("ID del proceso: " . $process->getId() . "n"); print("ID del evento de inicio: " . $startEvent->getId() . "n");
Ejecutando su script de creación
Al ejecutar su script, obtendrá su ID de proceso final y su ID de evento de inicio
$ php ./introducción/crear.php ID del proceso: b78fc897-91f8-4f38-b8e3-7d60267d9b67 ID del evento de inicio: 271bf2f1-47bb-4616-9edb-3892b5696710
Preparación del formulario HTML
Ahora que tenemos un flujo de trabajo definido en nuestro motor, podemos preparar nuestro formulario HTML. En nuestros ejemplos de código, ya está preparado un formulario en el archivo introduction/form.html. Queremos actualizar el archivo para definir una variable que represente un punto final de API de nuestro motor. Este punto final es el webhook para nuestro evento de inicio.
Observe que la URL contiene tanto el ID del proceso como el ID del evento de inicio. El punto final del webhook nos permite enviar un HTTP POST con datos del formulario. Estos datos de formulario representan el modelo de datos cuando se ejecuta el flujo de trabajo. Para nuestro ejemplo, usamos jQuery para enviar el formulario a nuestro webhook. Utilizamos una llamada AJAX. Si la llamada es exitosa, mostramos un mensaje agradable al usuario y se inicia nuestro flujo de trabajo.
Si carga el archivo HTML en su navegador, podrá enviar el formulario y ver un mensaje de éxito. Detrás de escena, se llamó webhook del evento de inicio de nuestro flujo de trabajo. ¡Está vivo!
El ciclo de vida de la instancia de flujo de trabajo
Iniciar eventos crea nuevas instancias de un flujo de trabajo. Estas instancias tienen su propio ciclo de vida independiente, así como su propio modelo de datos. La instancia de flujo de trabajo crea un token que viaja a través del flujo de trabajo. Comenzando en el evento de inicio, recorre el flujo del flujo de trabajo y ejecuta tareas a lo largo del camino. Las Tareas en el flujo de trabajo pueden utilizar el Modelo de Datos en su ejecución, así como cambiarlo después de la ejecución. El modelo de datos es un documento JSON que puede contener tipos de datos complejos. En nuestro ejemplo, el modelo de datos es la colección de valores de campos de formulario incluidos en el envío de ajax. Una vez que el token llega al evento final, el ciclo de vida de la instancia finaliza. La instancia tiene un estado de COMPLETADO. En nuestro ejemplo, el ciclo de vida del flujo de trabajo tenía estos pasos:
El token se inició en el webhook de inicio del evento, llenando el modelo de datos.
El token fluyó a ServiceTask, ejecutando SendMailConnector
El token fluyó desde la tarea de servicio hasta el evento final, lo que indica la finalización del flujo de trabajo.
Este ciclo de vida ocurre en el motor y es asincrónico a la llamada ajax. Si lo seguiste, deberías haber recibido un correo electrónico en tu bandeja de entrada.
Próximos pasos
Nuestro flujo de trabajo es muy simple pero nos dio la oportunidad de cubrir algunos conceptos centrales. La mayoría de los flujos de trabajo no serán tan simples. Al igual que nuestro ejemplo, todos los flujos de trabajo contendrán una combinación de eventos, tareas y flujos. En nuestro próximo tutorial, comenzaremos a introducir lógica en nuestro flujo de trabajo. Usaremos lógica para enviar a diferentes destinatarios de correo electrónico en función de la evaluación de valores en nuestro modelo de datos.
15 de octubre de 2026
Herramientas puntuales versus plataforma: qué sucede cuando la orquestación no es nativa
