Manuel d'intégration

  1. Intégration technique
    1. Création de modèles de workflow
    2. Déclaration de variables
    3. Utilisation des variables
    4. Spécificités des définitions de workflow
      1. Action d'initialisation
      2. Action de modification
      3. Etat final
      4. Assignation de personnes aux transitions
      5. Assignation du créateur du processus aux transitions
      6. Envoi de mail de notification
      7. Mise à jour de l'état de workflow courant
    5. Exemple complet de définition de workflow
  2. Intégration graphique
    1. Visualisation d'un processus

 

Le BPM ajoute des nouvelles définitions de noeuds JCR.
Si vous installez le plugin BPM dans une application Ametys qui contient déjà des données, supprimez le fichier AMETYS_HOME/data/repository/repository/nodetypes/custom_nodetypes.xml avant de redémarrer le serveur.

Intégration technique

Création de modèles de workflow

Pour pouvoir créer des workflows pour vos processus, il faut d'abord définir des définitions de worflow (ou modèles).

Les définitions de workflow BPM sont des fichiers XML de workflow au sens habituel Ametys, avec la liste des états, des transitions et des variables.
Les variables permettent de paramétrer le workflow, par exemple pour définir les personnes affectées aux transitions.

Les fichiers de workflow utilisés par le module BPM doivent être déclarés avec un nom du workflow qui doit être préfixé par "bpm-". Voir la page Paramètrage du workflow

 

 

Déclaration de variables

Le plugin BPM permet de définir des variables dans les fichiers de définition de workflows.

Les variables se définissent dans la section <registers>, à la racine de la balise <workflow>. Elles sont de type="avalon", avec n'importe quel "variable-name" unique dans le fichier.

Exemple de variables

<registers> 
    <register type="avalon" variable-name="FirstUsersForValidation"> 
     <arg name="role">org.ametys.plugins.bpm.workflowsdef.RegisterVariable</arg> 
        <arg name="type">user</arg> 
        <arg name="multiple">true</arg> 
        <arg name="mandatory">true</arg> 
        <arg name="variableId">FirstUsersForValidation</arg> 
        <arg name="label">plugin.default-bpm-workflow:WORKFLOW_BPM_FIRST_GROUP_FOR_VALIDATION</arg> 
        <arg name="description">plugin.default-bpm-workflow:WORKFLOW_BPM_FIRST_GROUP_FOR_VALIDATION_DESC</arg> 
    </register> 
 <register type="avalon" variable-name="text"> 
        <arg name="role">org.ametys.plugins.bpm.workflowsdef.RegisterVariable</arg> 
        <arg name="type">string</arg> 
        <arg name="variableId">text</arg> 
        <arg name="label">plugin.default-bpm-workflow:WORKFLOW_BPM_TEXT</arg> 
        <arg name="description">plugin.default-bpm-workflow:WORKFLOW_BPM_TEXT_DESC</arg> 
    </register> 
</registers> 

Les arguments <arg> sont :

  • role: obligatoirement "org.ametys.plugins.bpm.workflowsdef.RegisterVariable"
  • type: obligatoire, défini le type de la variable. "user" est probablement le type le plus couramment utilisé, même si un type "string" ou "date" est tout à fait valable
  • label, description: obligatoires, clé i18n représentant le label et la description affichée dans le CMS lors de la création d'un workflow, pour savoir à quoi correspond la variable.
  • variableId: obligatoire, utiliser comme identifiant pour stocker la valeur de la variable. Doit être unique parmi toutes les variables du workflow. Une bonne pratique consiste à utiliser la même valeur pour le "variable-name" et le "variableId".
  • multiple: falcultatif, "false" par défaut, permet d'autoriser des valeurs multiples
  • mandatory: facultatif, "false" par défaut, la valeur "true" permet de forcer la variable à être remplie lors de la création du workflow

Utilisation des variables

Les variables définies peuvent ensuite être utilisées dans les actions du workflow au format: ${variable-name}.

Par exemple, pour autoriser une transition aux seuls utilisateurs définis dans la variable ${FirstUsersForValidation} on écrira :

<condition type="avalon"> 
   <arg name="role">org.ametys.plugins.bpm.workflowsdef.CheckAllowedUsersCondition</arg> 
   <arg name="users">${FirstUsersForValidation}</arg> 
</condition> 

 

Spécificités des définitions de workflow

Action d'initialisation

Pour lancer le processus, une action d'initialisation id=1 doit nécessairement être présente dans la section <initial-actions> 

Voici ci-dessous un exemple d'action d'initialisation. Dans cet exemple, un mail sera envoyé suite à la création du processus aux personnes définies dans les variables ${allowedRepresentatives} et ${allowExperts}

<initial-actions> 
 <!-- Initialisation --> 
    <action id="1" name="plugin.default-bpm-workflow:WORKFLOW_ACTION_INITIALIZATION"> 
    <results> 
     <unconditional-result old-status=" " status=" " step="1" /> 
        </results> 
        <post-functions> 
         <function type="avalon"> 
             <arg name="role">org.ametys.plugins.bpm.workflowsdef.SendProcessMailFunction</arg>  
                <arg name="users">${allowedRepresentatives}</arg> 
                <arg name="subjectKey">plugin.default-bpm-workflow:WORKFLOW_BPM_MAIL_SUBJECT_ACTION_CREATE</arg> 
                <arg name="bodyKey">plugin.default-bpm-workflow:WORKFLOW_BPM_MAIL_BODY_ACTION_CREATE</arg> 
            </function> 
            <function type="avalon"> 
             <arg name="role">org.ametys.plugins.bpm.workflowsdef.SendProcessMailFunction</arg>  
                <arg name="users">${allowExperts}</arg> 
                <arg name="subjectKey">plugin.default-bpm-workflow:WORKFLOW_BPM_MAIL_SUBJECT_ACTION_CREATE</arg> 
                <arg name="bodyKey">plugin.default-bpm-workflow:WORKFLOW_BPM_MAIL_BODY_ACTION_CREATE</arg> 
           </function> 
            <function type="avalon"> 
             <arg name="role">org.ametys.plugins.bpm.workflow.SetProcessCurrentStepId</arg> 
            </function> 
        </post-functions> 
  </action> 
</initial-actions> 

Action de modification

L'action avec id=2 est réservée à la modification du processus (pour modifier les pièces jointes par exemple).
Elle doit obligatoirement contenir la pre-function org.ametys.plugins.bpm.process.EditProcessFunction

L'action 2 est facultative, si vous ne voulez pas que les processus soient modifiables après création.

Pour permettre la modification d'un processus quelque soit soit état d'avancement, pour pouvez créer une action commune comme dans l'exemple ci-après.
Dans cet exemple, la modification d'un processus ne modifie pas son état courant, le processus reste dans l'état actuel.

<common-actions> 
        <!-- Modification du processus --> 
        <action name="plugin.default-bpm-workflow:WORKFLOW_ACTION_EDIT" id="2"> 
            <restrict-to> 
                <conditions type="OR"> 
                    <condition type="avalon"> 
                        <arg name="role">org.ametys.plugins.bpm.workflowsdef.CheckAllowedUsersCondition</arg> 
                        <arg name="users">${allowedRepresentatives}</arg> 
                    </condition> 
                    <condition type="avalon"> 
                        <arg name="role">org.ametys.plugins.bpm.workflowsdef.CheckAllowedUsersCondition</arg> 
                        <arg name="users">${allowExperts}</arg> 
                    </condition> 
                </conditions> 
            </restrict-to> 
            <pre-functions> 
                <function type="avalon"> 
                    <arg name="role">org.ametys.plugins.bpm.process.EditProcessFunction</arg> 
                </function> 
            </pre-functions> 
            <results> 
                <result step="2" status=" " old-status=" "> 
                    <conditions type="AND"> 
                        <condition type="avalon"> 
                            <arg name="role">org.ametys.plugins.bpm.workflowsdef.ProcessCurrentStepCondition</arg> 
                            <arg name="step">2</arg> 
                        </condition> 
                    </conditions> 
                </result> 
                <result step="3" status=" " old-status=" "> 
                    <conditions type="AND"> 
                        <condition type="avalon"> 
                            <arg name="role">org.ametys.plugins.bpm.workflowsdef.ProcessCurrentStepCondition</arg> 
                            <arg name="step">3</arg> 
                        </condition> 
                    </conditions> 
                </result> 
                <result step="4" status=" " old-status=" "> 
                    <conditions type="AND"> 
                        <condition type="avalon"> 
                            <arg name="role">org.ametys.plugins.bpm.workflowsdef.ProcessCurrentStepCondition</arg> 
                            <arg name="step">4</arg> 
                        </condition> 
                    </conditions> 
                </result> 
                <unconditional-result step="1" status=" " old-status=" "/> 
            </results> 
            <post-functions> 
                <function type="avalon"> 
                    <arg name="role">org.ametys.plugins.bpm.workflow.SetProcessCurrentStepId</arg> 
                </function> 
            </post-functions> 
        </action> 
</common-actions> 

Etat final

Un processus est terminé lorsqu'il arrive dans son état final. Un état final est un état (step) qui ne contient aucune action possible.

Un processus terminé peut être supprimé par son créateur..

Assignation de personnes aux transitions

Pour autoriser une transition (action de workflow) à une ou plusieurs personnes définies par une variable, vous devez utiliser la condition org.ametys.plugins.bpm.workflowsdef.CheckAllowedUsersCondition

Cette condition vérifie que l'utilisateur connecté est l'un des utilisateurs autorisés par la variable (ici $allowExperts). Si ce n'est pas le cas, l'action ne sera pas disponible pour l'utilisateur courant.

<condition type="avalon"> 
 <arg name="role">org.ametys.plugins.bpm.workflowsdef.CheckAllowedUsersCondition</arg> 
    <arg name="users">${allowExperts}</arg> 
</condition> 

Assignation du créateur du processus aux transitions

Pour autoriser une transition (action de workflow) au créateur du processus, vous devez utiliser la condition org.ametys.plugins.bpm.workflowsdef.CheckProcessCreatorCondition

Cette condition vérifie que l'utilisateur connecté est le créateur du processus. Si ce n'est pas le cas, l'action ne sera pas disponible pour l'utilisateur courant.

<condition type="avalon"> 
    <arg name="role">org.ametys.plugins.bpm.workflowsdef.CheckProcessCreatorCondition</arg> 
</condition> 

Envoi de mail de notification

Lors de l'avancement du processus, vous voudrez sans doute que les personnes concernées soient avertis par mail de l'avancement du processus.

Vous pouvez pour cela utiliser la post-fonction org.ametys.plugins.bpm.workflowsdef.SendProcessMailFunction

<post-functions> 
 <function type="avalon"> 
 <arg name="role">org.ametys.plugins.bpm.workflowsdef.SendProcessMailFunction</arg> 
      <arg name="users">${allowExperts}</arg> 
     <arg name="subjectKey">plugin.default-bpm-workflow:WORKFLOW_MAIL_SUBJECT_ACTION_VALIDATED</arg> 
     <arg name="bodyKey">plugin.default-bpm-workflow:WORKFLOW_MAIL_BODY_ACTION_VALIDATED</arg> 
     <arg name="sendToCreator">true</arg> 
 </function> 
</post-functions> 

Les arguments de cette fonction sont :

  • users : permet de passer une variable contenant un ou plusieurs utilisateurs destinataires de la notification par mail (facultatif)
  • sendToCreator : true ou false (false par défaut) Si "true" le créateur du processus sera destinataire de la notification par mail (facultatif)
  • subjectKey : clé 18n (paramétrée) pour le titre du message envoyé. Les paramètres possibles sont :
    • 0 : nom du processus
  • bodyKey: clé 18n (paramétrée) pour le contenu du message envoyé. Les paramètres possibles sont :
    • 0 : utilisateur responsable de la transition (le créateur si le processus vient d'être créé)
    • 1:  créateur du processus
    • 2 : nom du processus
    • 3 : lien vers la page de consultation du processus

 

Exemple de clé i18n pour l'envoi de mail

<message key="WORKFLOW_BPM_MAIL_BODY_ACTION_DESC">{0} a effectué une action sur le processus {2}. Pour vous rendre sur la page du processus, cliquez ou copiez-collez le lien ci-après {3}.</message> 

Mise à jour de l'état de workflow courant

Chaque action (transition) doit contenir la post-fonction org.ametys.plugins.bpm.workflow.SetProcessCurrentStepId

Cette fonction sauvegarde l'état courant sur le processus lui-même.

<post-functions> 
   <function type="avalon"> 
      <arg name="role">org.ametys.plugins.bpm.workflow.SetProcessCurrentStepId</arg> 
  </function> 
</post-functions> 

Exemple complet de définition de workflow

Vous pouvez télécharger un exemple de définition de workflow : workflow-bpm-default.xml

Cet exemple correspond à un processus qui nécessite une double validation (par un expert et un élu). L'ordre de validation n'a pas d'importance, il a donc 2 chemins possibles pour terminer le processus.

Dans l'exemple donné:

  • Les experts et les élus reçoivent une notification par email dès la création du processus.
  • Lors de la validation par un expert, les élus reçoivent une notification par email.
  • Lors de la validation par un élu, les experts reçoivent une notification par email.
  • Le processus peut être modifié à tout moment de son avancement par le créateur lui-même.

Vous pouvez télécharger le plugin de définition des clés i18n correspondant à ce workflow ici : default-bpm-workflow.zip

Intégration graphique

Visualisation d'un processus

Pour visualiser un processus, le gabarit de page utilisé est déterminé suivant l'ordre suivant :

  • utilisation du gabarit "bpm-process" si il existe dans la charte courante
  • sinon, utilisation du gabarit de la page étiquetée "Création de processus" si elle existe
  • sinon, utilisation du gabarit "page" si il existe dans la charte courante
  • sinon utilisation de 1er gabarit trouvé.

Pour surcharger le rendu d'un processus, créez dans votre charte le fichier skins/SKIN_NAME/services/bpm/pages/process.xsl

Ce fichier doit contenir à minima :

<xsl:stylesheet version="1.0" 
                xmlns:i18n="http://apache.org/cocoon/i18n/2.1" 
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> 

    <xsl:import href="plugin:bpm://pages/process.xsl"/> 
    
 <!-- Vos surcharges ici --> 
</xsl:stylesheet> 

 

 

 

Retour en haut

BPM