- Technical integration
- Graphic integration
BPM adds new node definitions JCR.
If you are installing plugin BPM in a Ametys application that already contains data, delete the AMETYS_HOME/data/repository/repository/nodetypes/custom_nodetypes file .xml before restarting the server.
Technical integration
Creating workflow templates
To create workflows for your processes, you first need to define worflow definitions (or templates).
BPM workflow definitions are XML workflow files in the usual sense Ametys, with a list of states, transitions and variables.
Variables are used to parameterize the workflow, for example to define the people assigned to transitions.
Workflow files used by the BPM module must be declared with a workflow name prefixed with "bpm-". See Workflow settings page
Variable declaration
plugin BPM lets you define variables in workflow definition files.
Variables are defined in the <registers>at the root of the <workflow>. They are of type="avalon", with any unique "variable-name" in the file.
Example of 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>
The arguments <arg> are :
- role: mandatory "org.ametys.plugins.bpm.workflowsdef.RegisterVariable"
- type: mandatory, defines the type of the variable. "user" is probably the most commonly used type, although "string" or "date" are perfectly valid.
- label, description: mandatory, key i18n representing the label and description displayed in CMS when a workflow is created, so you know what the variable corresponds to.
- variableId: mandatory, used as identifier to store variable value. Must be unique among all workflow variables. A good practice is to use the same value for "variable-name" and "variableId".
- multiple: falcultative, "false" by default, to allow multiple values
- mandatory: optional, "false" by default, the value "true" is used to force the variable to be filled in when the workflow is created.
Using variables
The variables defined can then be used in workflow actions in the format: ${variable-name}.
For example, to authorize a transition only for users defined in the variable ${FirstUsersForValidation} we write :
<condition type="avalon">
<arg name="role">org.ametys.plugins.bpm.workflowsdef.CheckAllowedUsersCondition</arg>
<arg name="users">${FirstUsersForValidation}</arg>
</condition>
Workflow definition specifics
Initialization action
To start the process, an initialization action id=1 must be present in the <initial-actions>
Here's an example of an initialization action. In this example, a mail will be sent following process creation to the people defined in the variables ${allowedRepresentatives} and ${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> Modification action
Action with id=2 is reserved for modifying the process (to change attachments, for example).
It must contain the pre-function org.ametys.plugins.bpm.process.EditProcessFunction
Action 2 is optional, if you don't want processes to be modifiable after creation.
To enable a process to be modified regardless of its current state, you can create a common action, as shown in the example below.
In this example, modifying a process does not modify its current state; the process remains in its current state.
<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> Final state
A process is complete when it reaches its final state. A final state is a state (step) in which no action is possible.
A terminated process can be deleted by its creator.
Assigning people to transitions
To authorize a transition (workflow action) to one or more persons defined by a variable, you must use the condition org.ametys.plugins.bpm.workflowsdef.CheckAllowedUsersCondition
This condition checks that the logged-in user is one of the users authorized by the variable (in this case $allowExperts). If this is not the case, the action will not be available to the current user.
<condition type="avalon">
<arg name="role">org.ametys.plugins.bpm.workflowsdef.CheckAllowedUsersCondition</arg>
<arg name="users">${allowExperts}</arg>
</condition> Process creator assignment to transitions
To authorize a transition (workflow action) to the process creator, you must use the condition org.ametys.plugins.bpm.workflowsdef.CheckProcessCreatorCondition
This condition verifies that the logged-in user is the process creator. If this is not the case, the action will not be available to the current user.
<condition type="avalon"> <arg name="role">org.ametys.plugins.bpm.workflowsdef.CheckProcessCreatorCondition</arg> </condition>
Send mail notification
As the process moves forward, you'll probably want to keep those concerned informed by sending an e-mail to mail .
You can use the 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> The arguments to this function are :
- users: pass a variable containing one or more users to be notified by mail (optional)
- sendToCreator: true or false (false by default) If "true", the process creator will be notified by mail (optional)
- subjectKey key 18n (set) for the title of the message sent. Possible parameters are :
- 0: process name
- bodyKey: key 18n (set) for the content of the message sent. Possible parameters are :
- 0: user responsible for transition (the creator if the process has just been created)
- 1: process creator
- 2: process name
- 3: link to the process consultation page
Example of a i18n key for sending 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> Update current workflow status
Each action (transition) must contain the post-function org.ametys.plugins.bpm.workflow.SetProcessCurrentStepId
This function saves the current state on the process itself.
<post-functions> <function type="avalon"> <arg name="role">org.ametys.plugins.bpm.workflow.SetProcessCurrentStepId</arg> </function> </post-functions>
Complete example of workflow definition
You can download a sample workflow definition: workflow-bpm-default. xml
This example corresponds to a process requiring double validation (by an expert and an elected representative). The order of validation is irrelevant, so there are 2 possible paths to complete the process.
In the example given:
- Experts and elected representatives are notified by email as soon as the process is created.
- Upon validation by an expert, elected representatives are notified by email.
- Upon validation by an elected official, experts are notified by email.
- The process can be modified at any stage by the creator himself.
You can download the plugin key definition i18n corresponding to this workflow here: default-bpm-workflow.zip
Graphic integration
Process visualization
To view a process, the page template used is determined in the following order:
- use of the"bpm-process" template if it exists in the current charter
- otherwise, use the template on the page labelled "Process creation" if it exists
- otherwise, use the "page" template if it exists in the current charter
- otherwise use 1st template found.
To override the rendering of a process, create the file skins/SKIN_NAME/services/bpm/pages/process.xsl
This file must contain at least :
<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>
Back to top