Jahia works with a business process engine to manage its workflows. It is mainly used for publication operation, which usually require user validation and eventual interaction with external systems. However, it is possible to use the process engine for other operations, either operations related to Jahia, or purely business oriented workflow.
Jahia is bundled and configured with the jBPM process engine.
Workflow can be started and executed on a node. Workflow are always tied to a node - it can be a page, user, or any simple node - workflow rules (which workflow can be started) and roles (who can execute the tasks) will be set on these nodes, or on parent nodes, and are inherited on all sub nodes.
Workflow rules define which workflow can be started on which node. This can be set in the workflow tab of the edit engine.
For every workflow type listed on the left, a drop-down menu allows to select (or deselect) a workflow. The "same workflow as parent" checkbox must be unchecked to select a new workflow.
Once saved, the workflow will be available for the users having the permission to start it.
Workflow is about interaction between users - some users can start a workflow, which will require other action by other users. Jahia permissions and roles allow to set up the possible actions for every user and group in the system.
When declaring a workflow, a mapping between workflow actions and Jahia permissions is defined. In order to start a workflow or being able to assign and execute a task, a user must have the matching permission, via a role. If no specific mapping is specified, a permission is automatically created for every task in /permissions/workflow-tasks/. See Workflow declaration on how to declare a workflow and a custom permission mapping.
Workflow permissions, like other permissions, are assigned to roles via the roles manager in the administration :
Users and groups are assigned to roles with the Roles tab of the edit engine.
Once a workflow rule has been set, a user who has the right to start a workflow on a node should see it in the workflow / start workflow menu :
A workflow will probably create tasks that will be assigned to users who have a role matching the required permissions. A user who has waiting task can execute them by opening his dasboard in workflow / Workflow Dashboard :
For more information about jBPM, see http://docs.jboss.com/jbpm/v4/userguide/html_single/ .
The jBPM provider configuration file is the following :
WEB-INF/etc/spring/workflow/applicationcontext-jBPM.xml
This file contains references to other services, the path used by jBPM to get the process definitions, and location of the jBPM configfile.
As you can see in the jBPM configuration file, we use a wildcard classpath lookup to search for the jPDL workflow process definition files. This means that you can simply put in your module in the proper package (by default org.jahia.services.workflow) a file with the extension jpdl.xml and it will be picked-up on Jahia's startup. In order to be fully available in Jahia, the process must be declared in a configuration file - see Workflow declaration
jBPM allows to associate a form to a task - in Jahia, this form is actually defined by a simple node type. This node type will create the form, and the data will be stored like a standard JCR node in the process engine.
Here, the "request" task uses the "jnt:translationRequest" as a form :
<task name="request" form="jnt:translationRequest">
...The type jnt:translationRequest is defined in a .cnd file with :
[jnt:translationRequest] > mix:title - request (string, richtext) - translateTo (string, choicelist[siteLocales])
The execution of this task will display a form that the user will need to fill. Data entered in this form can later be used in other activities.
jBPM needs to know how to assign new tasks to users. Depending on the roles assigned to the node, the task won't be assigned to the same users and groups. jBPM allows embedding system to set an assignement-handler to correctly handle task assignation. Jahia provides an assignement handler, that must be used for every task defined in your process. It can be declared in a jpdl file like the following :
<task name="request" form="jnt:translationRequest">
<assignment-handler class="org.jahia.services.workflow.jbpm.JBPMTaskAssignmentListener"/>
...
</task>At one point of the process, it can be required that the process need to interact with Jahia services. For instance, a publication workflow will probably need to publish some nodes after a validation. There's multiple ways to do this with jBPM, but the simplest way is to create custom activities - a few custom activities are provided with Jahia, to lock/unlock nodes and publish/unpublish nodes. They are located in org.jahia.services.workflow.jbpm.custom.* .
An optional resource bundle file can be created along with the jpdl file to internationalize the name and labels of the process - the resource bundle must be named with the key of the jBPM process. If the process has the key "translation-workflow", the file need to be named translation-workflow.properties . This file can include resources for process name, actions, and action outcomes.
The standard mail system from jBPM can be used. You can create a mail activity in your process to send a mail.
Jahia provide some keyword that you can use in the from and recipients fields to define to which people you want to send the mail.
<mail name="done"> <from users="jahiaSettingsProperty"/> <to users="currentWorkflowStarter"/> <cc users="previousTaskAssignable"/> <subject>Your request for translation has been accepted</subject> <text>Your request for translation has been accepted</text> <transition to="end"/> </mail>
jahiaSettingsProperty will return the mail_from property defined in jahia.properties or the administration center.
currentWorkflowStarter refer to the person who have started the workflow.
previousTaskAssignable or nextTaskAssignable refer to the people that can participate to the previous task or the next one in your process flow.
However, if you need to send more dynamic mails, it can be easier to use mail templates, using a custom mail producer. First you need to create a mail template - mail templates are found like workflows, in a path specified in the applicationcontext-jBPM.xml file. By default all resources in the package org.jahia.services.workflow with the extension .mail are taken. The following example, start-publication-template.mail , defines a mail that will be sent when we start a publication workflow :
to: #if( $user.properties.get('j:email') ) ${user.properties.get('j:email')} #end
to-users: nextTaskAssignable
subject: Publication workflow by ${user.getUsername()}
text: Hi,
A publication workflow with one validation step has been started on ${date.format("short","short",$submissionDate,$locale)} by ${user.getUsername()}, on the following items :
#foreach( $node in $nodes )
#if( $velocityCount <= 10)
- ${node.getDisplayableName()}
#end
#end
html: Hi,
<br>
<br>
<div>
A publication workflow with one validation step has been started on ${date.format("short","short",$submissionDate,$locale)} by ${user.getUsername()}, on the following items :
</div>
<div>
<ul>
#foreach( $node in $nodes )
#if( $velocityCount <= 10)
<li>${node.getDisplayableName()}</li>
#end
#end
</ul>
<br>
</div>The template contains both text and html versions of the mails, and use velocity language to get dynamic informations. Another script language (as defined by the JSR 223) can be used by using the key language: in the template file. The following variables are bound when executing the script : bundle, user, date, submissionDate, locale, workspace, nodes.
It is also possible to declare one template per locale, by suffixing the template name by the language code : start-publication-template.fr.mail will be used when the workflow locale is french.
The template can be used in a JPDL mail activity using the following syntax :
<mail class="org.jahia.services.workflow.jbpm.JBPMMailProducer" name="sendStartMail">
<property name="templateKey">
<string value="start-publication-template"/>
</property>
<transition to="review"/>
</mail>Workflow processes need to be deployed into the process engine and declared in Jahia to be used by the site administrator and end-users.
See "Using jBPM" for information about how to create and deploy process with the jBPM process engine.
Once the workflow is available in the process engine, it has to be registered to the workflow service. This can be done by creating a spring bean org.jahia.services.workflow.WorklowTypeRegistration
<bean name="translationWorkflow" class="org.jahia.services.workflow.WorklowTypeRegistration">
<property name="type" value="translation"/>
<property name="definition" value="translation-workflow"/>
<property name="permissions" >
<map>
<entry key="start" value="/repository-permissions/jcr:all_default/jcr:read_default"/>
<entry key="request" value="/repository-permissions/jcr:write_default/jcr:modifyProperties_default_$translateTo"/>
</map>
</property>
</bean>This can also be done in the code by calling the method registerWorkflowType() in WorkflowService:
public void registerWorkflowType(String type, String definition, Map<String,String> perms)
The following properties / parameters are required :
Jahia's workflow service uses an external back-end, by default the jBPM workflow implementation, but that can be replaced by other implementations if need be.
Adding a new provider can be done by implementing the interface org.jahia.services.workflow.WorkflowProvider. The provider must provide a key and need to register to the service at startup. A spring bean can be used to declare and instantiate the new provider. The JBPMProvider , used to connect to the jBPM engine, can be used as an example. The provider is registered via the spring file applicationcontext-jBPM.xml .