Un tutorial de introducción al desarrollo de ProcessMaker.IO

Matt McClintock 28 de septiembre de 2017 Flujo de trabajo

Hola a todos. Soy Taylor Dondich y soy el CTO aquí en ProcessMaker. ProcessMaker.IO es nuestro motor de flujo de trabajo en la nube y estoy emocionado de mostrarles cómo empezar. La mejor manera de mostrarles cómo es con el código real.
 
Este primer post es el primero de una serie de tutoriales que te introducirán en ProcessMaker.IO. Cada nuevo post le presentará nuevos conceptos y cómo usarlos. Empezarás con un flujo de trabajo simple y luego trabajarás en el uso de escenarios más complejos. Estos escenarios mostrarán algunas de las emocionantes características que tiene ProcessMaker.IO.
 
ProcessMaker.IO es libre de registrarse y empezar. Una vez que tengas tu cuenta, puedes obtener el código para estos tutoriales en nuestro depósito GitHub.
Para nuestro ejemplo, supongamos que somos un desarrollador de Widget Co. Nuestro jefe quiere que construyamos un formulario que permita a nuestros clientes contactarnos por cualquier razón. Si rellenan el formulario, deberíamos recibir un correo electrónico con los datos que el cliente nos ha proporcionado.
 
Es un ejemplo simple y perfecto para mojarnos los pies.

Inscribirse 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 con un enlace para verificar tu cuenta. Una vez verificada, puedes crear tu primer motor de flujo de trabajo.

Verás el tablero de ProcessMaker.IO. Este tablero muestra la lista de sus motores de flujo de trabajo. Como no tiene ninguno, haga clic en el botón "Crear instancia" para crear su 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 API y datos. Este nivel de aislamiento 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 organices tus motores depende de ti. Cada motor tiene sus propios datos y no puede ver los datos de otro motor en tu cuenta.

Creando su primer flujo de trabajo

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 como lo siguiente:

Si está familiarizado con los procesos de negocios, 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 usted está familiarizado con BPMN, se sentirá cómodo usando el motor. Si no está familiarizado con BPMN, no se preocupe, no es un conocimiento necesario. Recorreremos los conceptos.

Cuando se crea un flujo de trabajo en ProcessMaker.IO, se 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 puede crear un proceso de forma programada, que es lo que haremos en este ejemplo. ProcessMaker.IO tiene SDKs disponibles en muchos idiomas. Para este ejemplo, usaremos el ProcessMaker.IO PHP SDK.

Primero, queremos inicializar nuestro cliente SDK. Para ello, necesitarás el punto final de la API de tu motor y el token de acceso a la API de tu primer usuario. Estos se pueden encontrar en tu panel de control.

Asegúrate de descargar el código de nuestro repositorio GitHub. Usaremos esto como punto de partida. Querrás ejecutar el comando de instalación del compositor de PHP para instalar el SDK. Una vez hecho, crea un archivo .env en la raíz de tu directorio de código. Este contendrá su punto final de la API, el token de acceso y otras opciones de configuración.

PMIO_ENDPOINT=https://fds23zz.api.processmaker.io/api/v1
PMIO_ACCESS_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjkwMTBmZGI5YWMxYTZiNGI2ZGMyZjNiODZmZDg5OTJhYWRlODI0MGU5MWI3NWRkNDhjNTA4MzRlYjQzZjUzNmFjMDkxNTg4MDY5MDZiM2MxIn0.eyJhdWQiOiIxIiwianRpIjoiOTAxMGZkYjlhYzFhNmI0YjZkYzJmM2I4NmZkODk5MmFhZGU4MjQwZTkxYjc1ZGQ0OGM1MDgzNGViNDNmNTM2YWMwOTE1ODgwNjkwNmIzYzEiLCJpYXQiOjE1MDY1NDM5MTMsIm5iZiI6MTUwNjU0MzkxMywiZXhwIjoxNTM4MDc5OTEzLCJzdWIiOiIxIiwic2NvcGVzIjpbXX0.PTFaPvddgKqB51trFAV2Ka_8W2npZ9jbc2uGAoYdFKfMNvvNl07DWTDXxK90B0OwLAA08husWmfkVomWlm6W44hXuJEa8zG3SfRGwpzPQiA4NZ706YkbWqjLfY5QH41MwpJlkgKeQv6Q6nvZluyXrzQlvZVkSfSb9GvNe4h6arLLn1KQp3xQnnK-Jk8Q109uEnhmkOs4mfUKj5rd0E_DKJUTc-CmXoJZ8zsvuDv-irv7PtQlpQRmVdlOJD2mTO2NwQpLjdl4d3D4a7zKpMcrkeLmqz_Cums4uk5069Ju2TRmAbyGfWUgL7aTg-o80xWPnwY9AY7xC__mZvW1ydlpLKX18-bIpj_5acCyqQmnA921KAoO99YV3rT19I_VKF9dglzMOPWrcLzb44qK4ONXjx8Za3zyFJZpBa_SrCkhYiOhY1GNNk5EpqqMCAT_D8nCnrR7fmLrXtFJsP9yPDYwMZxYuppCH6rcqLIeB0VlmEiNTJu_1RlYgcmG02boSNPXHmzrEd9eJKRksSWVfkE90quuDMNoEFYaL1A_yU0yn2iW0T--lh_kPOGEth2WrShoYEZ667FSrSmsRYoLe8BiqGbiSquYrtDhYhcidOeWyZLtUDMnVNi00v3i3hrIp7KIvIM9zAQxzk3OwAxFrKV6Ut3-cqyvpMhWo9NPyZI
# Ponlo en true si quieres registrar cada llamada HTTP api
[email protected]
PMIO_DEBUG=falso
PMIO_DEBUG_FILE=debug.log

Iniciando el SDK de PHP

Queremos inicializar primero 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.

// Create our API configuration object and pass in it's configuration
$config = new Configuration();
$config->setHost(getenv('PMIO_ENDPOINT'));
$config->setAccessToken(getenv('PMIO_ACCESS_TOKEN'));
$config->setDebug(getenv('PMIO_DEBUG'));
$config->setDebugFile(__DIR__ . '/' . getenv('PMIO_DEBUG_FILE'));

// Initialize our API client which will be referenced by client scripts
$pmio = new Client(new 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, a tareas y cómo cada elemento fluye al 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.

$response = $pmio->addProcess(nuevo ProcessCreateItem([
    'data' => new Process([
        'attributes' => nuevos ProcessAttributes([
            'nombre' => 'Proceso de introducción'
        ])
    ])
]));
// Obtener el objeto de datos subyacente que realmente representa nuestro proceso
$proceso = $respuesta->getData();

Creando los eventos de inicio y final

En el mundo del flujo de trabajo, los eventos describen lo que sucede en su flujo de trabajo en varios momentos. Para nuestro simple caso, estamos usando un Evento de Inicio y un Evento de Fin. 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 señala que nuestro flujo de trabajo está completo. El objetivo del flujo de trabajo es ir del Evento de Inicio al Evento Final. En el archivo, introduction/create.php, verás cómo los creamos.

$response = $pmio->addEvent($proceso->getId(), nuevo EventCreateItem([
    'data' => nuevo Evento([
        'attributes' => nuevos EventAttributes([
            'nombre' => 'Inicio',
            "tipo" => "INICIO",
            'definition' => EventAttributes::DEFINITION_MESSAGE
        ])
    ])
]));
$startEvent = $response->getData();

$response = $pmio->addEvent($proceso->getId(), nuevo EventCreateItem([
    'data' => nuevo Evento([
        'attributes' => nuevos EventAttributes([
            'nombre' => 'Fin',
            "tipo" => "FIN",
            'definition' => EventAttributes::DEFINITION_NONE
        ])
    ])
]));
$endEvent = $response->getData();

Creación de la tarea de enviar un correo electrónico

En nuestro flujo de trabajo, queremos enviar un correo electrónico cuando el cliente envíe el formulario de contacto. Para hacerlo, necesitamos usar 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 de la intervención humana. Esto es exactamente lo que queremos para que nuestro flujo de trabajo envíe un correo electrónico.

$response = $pmio->addTask($proceso->getId(), nuevo TaskCreateItem([
    'data' => nueva Tarea([
        'attributes' => nuevos TaskAttributes([
            'nombre' => 'Enviar correo electrónico de formulario de contacto',
            "tipo" => "TAREAS DE SERVICIO
        ])
    ])
]));
$serviceTask = $response->getData();

Tenemos que decirle a nuestra ServiceTask los detalles de su implementación. Usaremos uno de los conectores de ProcessMaker.IO para proporcionar la capacidad de enviar correo. ProcessMaker.IO tiene muchos conectores que permiten la interacción con servicios de terceros. Están disponibles los conectores para Slack, Mailchimp y Google Apps, entre otros.

Primero creemos nuestra plantilla de correo electrónico para poder decirle a nuestro conector que la use.

$template = <<

Name: {name}
Email: {email}
Subject: {subject}
Message: {message}

EOM;
Esta es una plantilla de correo electrónico HTML. Puedes ver algunos campos rodeados por 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.
 
Vamos a crear nuestro conector y decirle que se asocie con nuestra ServiceTask.
$pmio->addTaskConnector($process->getId(), $serviceTask->getId(), new TaskConnectorCreateItem([
    'data' => new TaskConnector([
        'attributes' => new TaskConnectorAttributes([
            'connector_class' => 'SendMailConnector',
            'input_parameters' => [
                'to' => getenv('TARGET_EMAIL_ADDRESS'),
                'name' => 'Introduction Form Submission',
                'subj' => 'Contact Form Submission from {name}',
                'body' => $template
            ]
        ])
    ])
]));

Asegúrate de que has modificado la TARGET_EMAIL_ADDRESS en tu archivo .env. Puedes verlo referenciado en el ejemplo de código.

Conectando todo junto con los flujos...

Ahora que tenemos nuestros eventos y tareas, necesitamos definir el camino desde el evento de inicio hasta el evento de fin. Los flujos definen estos caminos. Un Flujo debe tener un origen y un destino. Por ejemplo, nuestro primer flujo comienza con nuestro Evento de Inicio y termina con la Tarea de Servicio. Otro Flujo se mueve desde la Tarea de Servicio hasta nuestro Evento Final. Vamos a crearlos ahora.

$pmio->addFlow($proceso->getId(), nuevo FlowCreateItem([
    'data' => new Flow([
        'attributes' => nuevos FlowAttributes([
            "nombre" => "Comenzar a servir la tarea",
            'from_object_id' => $startEvent->getId(),
            'from_object_type' => $startEvent->getType(),
            'to_object_id' => $serviceTask->getId(),
            'to_object_type' => $serviceTask->getType()
        ])
    ])
]));

$pmio->addFlow($proceso->getId(), nuevo FlowCreateItem([
    'data' => new Flow([
        'attributes' => nuevos FlowAttributes([
            'nombre' => 'Tarea de servicio a fin',
            'from_object_id' => $serviceTask->getId(),
            'from_object_type' => $serviceTask->getType(),
            'to_object_id' => $endEvent->getId(),
            'to_object_type' => $endEvent->getType()
        ])
    ])
]));

Manteniendo nuestra identificación de proceso y la identificación de evento de inicio para uso futuro

Una vez que hemos definido nuestro Proceso, necesitamos saber el ID del Proceso y el Evento de Inicio. Usaremos estos valores cuando llamemos a nuestra API con los datos de nuestro formulario HTML.

print("Process ID: " . $proceso->getId() . "n");
print("Start Event ID: "n"); print("Start Event ID"). "n");

Ejecutando su guión de creación

Al ejecutar tu guión, obtendrás tu ID de proceso final y el ID de evento de inicio

$ php./introducción/crear.php
Identificación del proceso: b78fc897-91f8-4f38-b8e3-7d60267d9b67
Iniciar identificación de evento: 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, un formulario ya está preparado en el archivo introduction/form.html.
 
Queremos actualizar el archivo para definir una variable que represente un punto final de la API de nuestro motor. Este endpoint es el webhook de 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 POST HTTP con datos de formulario. Estos datos de formulario representan el modelo de datos cuando se ejecuta el flujo de trabajo.

Para nuestro ejemplo, estamos usando jQuery para enviar el formulario a nuestro webhook. Usamos una llamada AJAX. Si la llamada tiene éxito, mostramos un buen mensaje al usuario y nuestro flujo de trabajo se pone en marcha.

$('#contact-form').on('submit', function(e) {
     $.ajax({
         url: pmio_webook,
         type: 'POST',
         data: {
             name: $('#contactInputName').val(),
             email: $('#contactInputEmail').val(),
             subject: $('#contactInputSubject').val(),
             message: $('#contactInputMessage').val()
         }
     })
         // Our promise handler on success
         .done(function() {
             $('#contact-form button, #contact-form p.alert-danger').remove();
             $('#contact-form p.alert-success').removeClass('hide');
         })
         // And our promise handler on failure
         .fail(function(xhr, status, err) {
             $('#contact-form p.alert-danger').removeClass('hide');
         });
     return false;
 });

Envío del formulario

Si cargas el archivo HTML en tu navegador, podrás enviar el formulario y ver un mensaje de éxito. Detrás de las escenas, se llamó al webhook del evento de inicio de nuestro flujo de trabajo. ¡Está vivo!

El ciclo de vida de la instancia de flujo de trabajo

Los Eventos de Inicio crean 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 testigo que viaja a través del flujo de trabajo.
 
Comenzando en el Evento de Inicio, atraviesa el Flujo de Trabajo, ejecutando Tareas a lo largo del camino. Las Tareas del 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 la Ficha llega al Evento Final, el ciclo de vida de la instancia termina. La instancia tiene un estado de COMPLETADA.
 
En nuestro ejemplo, el ciclo de vida del flujo de trabajo tenía estos pasos:
  1. El Token comenzó en el Start Event Webhook, poblando el Modelo de Datos.
  2. El Token fluyó a la Tarea de Servicio, ejecutando el SendMailConnector
  3. El Token fluyó desde la Tarea de Servicio hasta el Evento Final, señalando 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 básicos. La mayoría de los flujos de trabajo no van a ser tan simples. Como nuestro ejemplo, todos los flujos de trabajo contendrán una mezcla de Eventos, Tareas y Flujos.
 
En nuestro próximo tutorial, empezaremos a introducir la lógica en nuestro flujo de trabajo. Usaremos la lógica para enviar a diferentes destinatarios de correo electrónico basándonos en la evaluación de los valores en nuestro modelo de datos.

Solicite una demostración

    Consentimiento a la Política de Privacidad Al marcar esta casilla usted consiente en Declaración de privacidad de ProcessMaker.



    Actualización de la privacidad
    Utilizamos cookies para que las interacciones con nuestro sitio web y servicios sean fáciles y significativas. Las cookies nos ayudan a entender mejor cómo se utiliza nuestro sitio web y adaptar la publicidad en consecuencia.

    Acepta