Un tutoriel d'introduction à ProcessMaker.IO pour les développeurs
S'inscrire et démarrer votre premier moteur de workflow
Une fois que vous aurez rempli vos coordonnées, vous recevrez un courriel contenant un lien pour vérifier votre compte. Une fois vérifié, vous pouvez créer votre premier moteur de workflow.
À propos des moteurs de workflow
Créer votre premier flux de travail
Pour notre exemple, nous allons créer un flux de travail simple, également connu sous le nom de processus, qui enverra un courrier électronique. Si nous devions visualiser ce flux de travail, il ressemblerait à ce qui suit :
Si vous êtes familier avec les processus d'entreprise, le diagramme ci-dessus vous semblera familier. Il s'agit d'un Diagramme BPMN qui représente visuellement ce que nous voulons faire. ProcessMaker.IO est un moteur de workflow conforme à BPMN. Si vous êtes familier avec BPMN, vous serez à l'aise avec le moteur. Si vous n'êtes pas familier avec BPMN, ne vous inquiétez pas, ce n'est pas une connaissance nécessaire. Nous allons passer en revue les concepts.
Lorsque vous créez un flux de travail dans ProcessMaker.IO, vous avez le choix de la manière de le faire. Si vous êtes familier avec les outils de diagrammes BPMN, vous pouvez créer un diagramme BPMN et l'importer dans le moteur. Nous en montrerons un exemple dans un tutoriel ultérieur. Vous pouvez également créer un processus par programmation, ce que nous allons faire dans cet exemple. ProcessMaker.IO propose des SDK dans de nombreuses langues. Pour cet exemple, nous utiliserons le SDK PHP de ProcessMaker.IO.
Tout d'abord, nous voulons initialiser notre client SDK. Pour ce faire, vous aurez besoin de l'API de votre moteur et du jeton d'accès à l'API de votre premier utilisateur. Ceux-ci se trouvent dans votre tableau de bord.
N'oubliez pas de télécharger le code à partir de notre dépôt GitHub. Nous l'utiliserons comme point de départ. Vous devrez lancer la commande d'installation du compositeur PHP pour installer le SDK. Une fois l'installation terminée, créez un fichier .env à la racine de votre répertoire de code. Il contiendra votre API, votre jeton d'accès et d'autres options de configuration.
PMIO_ENDPOINT=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 # Mettre à true si vous voulez enregistrer chaque appel HTTP api [email protected] PMIO_DEBUG=faux PMIO_DEBUG_FILE=debug.log
Initialisation du SDK PHP
Nous voulons d'abord initialiser notre client API avec nos identifiants. Dans nos exemples de code, le fichier est le fichier bootstrap.php. Ce fichier est inclus dans tous les exemples. Voyons comment le client est initialisé.
// 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));
Création de l'objet du processus
L'objet de processus est ce qui stocke la définition de notre flux de travail. Il contient la cartographie des événements, des tâches et de la manière dont chaque élément passe au suivant. Ne vous inquiétez pas pour ces termes, nous les couvrirons bientôt. Dans le fichier introduction/create.php, nous commençons par créer l'objet processus via notre API.
$response = $pmio->addProcess(new ProcessCreateItem([ données" => nouveau processus ([ attributs" => nouveaux ProcessAttributes([ nom" => "Processus d'introduction". ]) ]) ])) ; // Obtenir l'objet de données sous-jacent qui représente réellement notre processus $process = $response->getData() ;
Créer les événements de début et de fin
Dans le monde du travail, les événements décrivent ce qui se passe dans votre flux de travail à différents moments. Pour notre cas simple, nous utilisons un événement de début et un événement de fin. Un événement de début est ce qui commence l'exécution de notre processus. Notre événement de début se déclenche lorsqu'un client soumet le formulaire de contact. L'événement de fin signale que notre processus est terminé. L'objectif du workflow est de passer de l'événement de départ à l'événement final. Dans le fichier, introduction/create.php, vous verrez comment nous les créons.
$response = $pmio->addEvent($process->getId(), new EventCreateItem([ data" => new Event([ attributs" => nouveaux EventAttributes([ nom" => "début", type" => "START", definition' => EventAttributes::DEFINITION_MESSAGE ]) ]) ])) ; $startEvent = $response->getData() ; $response = $pmio->addEvent($process->getId(), new EventCreateItem([ data" => new Event([ attributs" => nouveaux EventAttributes([ nom" => "fin", type" => "END", definition' => EventAttributes::DEFINITION_NONE ]) ]) ])) ; $endEvent = $response->getData() ;
Création de la tâche d'envoi d'un courrier électronique
Dans notre flux de travail, nous voulons envoyer un courriel lorsque le client soumet le formulaire de contact. Pour ce faire, nous devons utiliser une tâche de service. Une tâche représente quelque chose d'actionnable dans un workflow et qui doit être impliqué. Une Service Task s'exécute en arrière-plan et ne nécessite pas d'intervention humaine. C'est exactement ce que nous voulons pour que notre flux de travail envoie un courrier électronique.
$response = $pmio->addTask($process->getId(), new TaskCreateItem([ données" => nouvelle tâche ([ attributs" => nouveaux TaskAttributes([ nom" => "Envoyer le formulaire de contact par e-mail", type" => "Tâche de service ]) ]) ])) ; $serviceTask = $response->getData() ;
Nous devons indiquer à notre ServiceTask les détails de sa mise en œuvre. Nous utiliserons l'un des connecteurs de ProcessMaker.IO pour pouvoir envoyer du courrier. ProcessMaker.IO dispose de nombreux connecteurs qui permettent d'interagir avec des services tiers. Des connecteurs pour Slack, Mailchimp, Google Apps et d'autres sont disponibles.
Commençons par créer notre modèle de courrier électronique afin de pouvoir dire à notre connecteur de l'utiliser.
$template = << Name: {name} Email: {email} Subject: {subject} Message: {message} EOM;
$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 ] ]) ]) ]));
Assurez-vous que vous avez bien modifié l'ADRESSE_COURRIER_ CIBLE dans votre fichier .env. Vous pouvez le voir référencé dans l'exemple de code.
Le câblage de l'ensemble des flux
Maintenant que nous avons nos événements et nos tâches, nous devons définir le chemin qui mène de l'événement de départ à l'événement final. Les flux définissent ces chemins. Un flux doit avoir une source et une cible. Par exemple, notre premier flux commence par notre événement de départ et se termine par la tâche de service. Un autre flux passe de la Tâche de service à l'événement final. Créons-les maintenant.
$pmio->addFlow($process->getId(), nouveau FlowCreateItem([ données" => nouveau flux ([ attributs" => nouveaux FlowAttributes([ nom" => "Start to Service Task", from_object_id' => $startEvent->getId(), from_object_type' => $startEvent->getType(), to_object_id' => $serviceTask->getId(), to_object_type' => $serviceTask->getType() ]) ]) ])) ; $pmio->addFlow($process->getId(), nouveau FlowCreateItem([ données" => nouveau flux ([ attributs" => nouveaux FlowAttributes([ name" => "Service Task to End", from_object_id' => $serviceTask->getId(), from_object_type' => $serviceTask->getType(), to_object_id' => $endEvent->getId(), to_object_type' => $endEvent->getType() ]) ]) ])) ;
Conserver notre ID de processus et notre ID de début d'événement pour une utilisation future
Une fois que nous avons défini notre processus, nous devons connaître l'ID du processus et l'événement de départ. Nous utiliserons ces valeurs lorsque nous appellerons notre API avec les données de notre formulaire HTML.
print("Process ID : " . $process->getId() . "n") ; print("Start Event ID : " . $startEvent->getId() . "n") ;
Exécution de votre script de création
Lors de l'exécution de votre script, vous obtiendrez votre ID de processus final et votre ID de début d'événement
$ php ./introduction/create.php ID du processus : b78fc897-91f8-4f38-b8e3-7d60267d9b67 Start Event ID : 271bf2f1-47bb-4616-9edb-3892b5696710
Préparation du formulaire HTML
Notez que l'URL contient à la fois l'ID du processus et l'ID de l'événement de départ. Le point final du webhook nous permet d'envoyer un POSTE HTTP avec les données du formulaire. Ces données de formulaire représentent le modèle de données lorsque le flux de travail s'exécute.
Pour notre exemple, nous utilisons jQuery pour soumettre le formulaire à notre webhook. Nous utilisons un appel AJAX. Si l'appel aboutit, nous envoyons un message agréable à l'utilisateur et notre flux de travail démarre.
$('#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; });
Soumettre le formulaire
Si vous chargez le fichier HTML dans votre navigateur, vous pourrez soumettre le formulaire et voir un message de réussite. En coulisses, il s'agit de l'événement de démarrage de notre flux de travail, appelé webhook. Il est vivant !
Le cycle de vie de l'instance de workflow
- Le jeton a commencé au moment de l'événement de départ, en remplissant le modèle de données.
- Le jeton est passé à la ServiceTask, exécutant le SendMailConnector
- Le jeton est passé de la tâche de service à l'événement final, signalant l'achèvement du flux de travail.