Un tutoriel d'introduction à ProcessMaker.IO pour les développeurs

Matt McClintock 28 septembre 2017 Flux de travail

Bonjour à tous. Je m'appelle Taylor Dondich et je suis le directeur technique de ProcessMaker. ProcessMaker.IO est notre moteur de workflow performant dans le nuage et je suis ravie de vous montrer comment démarrer. La meilleure façon de vous montrer comment c'est avec du code réel.
 
Ce premier article est le premier d'une série de tutoriels qui vous présenteront d'abord ProcessMaker.IO. Chaque nouveau billet vous présentera de nouveaux concepts et la façon de les utiliser. Vous commencerez par un flux de travail simple, puis vous passerez à des scénarios plus complexes. Ces scénarios vous montreront quelques-unes des fonctionnalités intéressantes de ProcessMaker.IO.
 
ProcessMaker.IO est libre de s'inscrire et commencer. Une fois que vous avez votre compte, vous pouvez obtenir le code pour ces tutoriels dans notre dépôt GitHub.
Pour notre exemple, supposons que nous soyons un développeur de Widget Co. Notre patron veut que nous construisions un formulaire qui permette à nos clients de nous contacter pour n'importe quelle raison. S'ils remplissent le formulaire, nous devrions recevoir un e-mail avec les détails que le client a fournis.
 
C'est un exemple simple et parfait pour se mouiller les pieds.

S'inscrire et démarrer votre premier moteur de workflow

Tout d'abord, visitez la page d'enregistrement de ProcessMaker.IO pour créer votre compte.

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.

Vous verrez le tableau de bord ProcessMaker.IO. Ce tableau de bord affiche la liste de vos moteurs de workflow. Comme vous n'en avez pas, cliquez sur le bouton "Create Instance" pour créer votre propre moteur.

À propos des moteurs de workflow

Chaque moteur de workflow est un environnement isolé qui possède son propre point d'extrémité API et ses propres données. Ce niveau d'isolement permet de disposer de plusieurs moteurs pour différents scénarios. Vous pouvez avoir un moteur pour un environnement de mise en scène et un autre pour la production. Vous pouvez avoir des moteurs distincts pour différentes unités commerciales. La manière dont vous organisez vos moteurs dépend de vous. Chaque moteur a ses propres données et ne peut pas voir les données d'un autre moteur dans votre compte.

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 connaissez 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 au BPMN. Si vous êtes familier avec BPMN, vous vous sentirez à l'aise en utilisant 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 vous présenter 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;
Ceci est un modèle de courriel en HTML. Vous pouvez voir certains champs entourés de bretelles bouclées. ProcessMaker.IO peut injecter des valeurs dans ces espaces. Le modèle de données du processus en cours contient ces valeurs. Dans notre exemple, la soumission du formulaire HTML représente le modèle de données.
 
Créons notre connecteur et disons-lui de s'associer à notre 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
            ]
        ])
    ])
]));

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

Maintenant que nous avons un flux de travail défini dans notre moteur, nous pouvons préparer notre formulaire HTML. Dans nos exemples de code, un formulaire est déjà préparé dans le fichier introduction/form.html.
 
Nous voulons mettre à jour le fichier pour définir une variable qui représente un point final de l'API de notre moteur. Ce point d'extrémité est la boucle de notre événement de démarrage.

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

Les événements Start créent de nouvelles instances d'un flux de travail. Ces instances ont leur propre cycle de vie indépendant ainsi que leur propre modèle de données. L'instance de workflow crée un jeton qui voyage à travers le workflow.
 
À partir de l'événement de départ, il traverse le flux de travail, en exécutant des tâches en cours de route. Les tâches du flux de travail peuvent utiliser le modèle de données dans leur exécution ou le modifier après l'exécution.
 
Le modèle de données est un document JSON qui peut contenir des types de données complexes. Dans notre exemple, le modèle de données est la collecte des valeurs des champs du formulaire inclus dans la soumission ajax.
 
Une fois que le jeton atteint l'événement final, le cycle de vie de l'instance est terminé. L'instance a le statut "COMPLET".
 
Dans notre exemple, le cycle de vie du flux de travail comportait ces étapes :
  1. Le jeton a commencé au moment de l'événement de départ, en remplissant le modèle de données.
  2. Le jeton est passé à la ServiceTask, exécutant le SendMailConnector
  3. Le jeton est passé de la tâche de service à l'événement final, signalant l'achèvement du flux de travail.
Ce cycle de vie se produit dans le moteur et est asynchrone par rapport à l'appel ajax. Si vous avez suivi, vous devriez avoir reçu un courriel dans votre boîte de réception.

Prochaines étapes

Notre méthode de travail est très simple, mais elle nous a permis de couvrir certains concepts fondamentaux. La plupart des flux de travail ne seront pas aussi simples. Comme dans notre exemple, tous les flux de travail contiendront un mélange d'événements, de tâches et de flux.
 
Dans notre prochain tutoriel, nous commencerons à introduire la logique dans notre flux de travail. Nous utiliserons la logique pour envoyer à différents destinataires de courrier électronique en nous basant sur les valeurs d'évaluation de notre modèle de données.

Demander une démo

    Consentement à la politique de confidentialité En cochant cette case, vous consentez à Déclaration de confidentialité du fabricant de processus.



    Mise à jour sur la protection de la vie privée
    Nous utilisons des cookies pour rendre les interactions avec notre site web et nos services faciles et significatives. Les cookies nous aident à mieux comprendre comment notre site web est utilisé et à adapter la publicité en conséquence.

    Accepter