Start using JBPM fast and easy

JBoss jBPM is a flexible, extensible workflow management system. jBPM combines easy development of workflow-applications with excellent enterprise application integration (EAI) capabilities. it includes a web-application and a scheduler and can be used in the simplest environment like an ant task and scale up to a clustered J2EE application.
The jBPM enables the creation of a workflow management system that bridges the gap between managers and developers by giving them a common language: the JBoss jBPM Process definition language (jPdl).
This article is an introduction and hopefully will help you start using JBPM easily and fast enough. As a first step you can take a look at this reference jbpm reference guide

Eclipse plug-in:
JBPM project supports the design of JBoss jBPM management system workflows within Eclipse: for example: jbpm-jpdl-designer-site-3.1.7.zip on eclipse 3.5.1
http://repository.jboss.com/maven2/org/jbpm/jbpm3/jbpm-jpdl-designer-sit...
http://repository.jboss.com/maven2/org/jbpm/jbpm4/jbpm-jpdl/4.3/

Let's start write some code
First define in workflowJBPMApplicationContext.xml, the Jbpm Templates and work flows (Process Definition FactoryBean).

<!-- jBPM configuration  -->
<bean id="jbpmConfiguration"    class="org.springmodules.workflow.jbpm31.LocalJbpmConfigurationFactoryBean">
	    <property name="sessionFactory" ref="sessionFactory"/>
	    <property name="configuration" value="classpath:jbpm.cfg.xml"/>
	    <property name="createSchema" value="false"/>
	    <property name="processDefinitionsResources">
	     <list>
<!-- list of all the workflows  -->   <value>classpath:com/example/plugin/jbpm/flows/purchaseContent/processdefinition.xml</value>
	     </list>
	    </property>
	  </bean>
<!—define ProcessDefinitionFactoryBean for each workflow  --> 
<bean id="purchaseContentWorkflow" class="org.springmodules.workflow.jbpm31.definition.ProcessDefinitionFactoryBean">
<property name="definitionLocation" 
value="classpath:com/example/plugin/jbpm/flows/purchaseContent/processdefinition.xml"/>
</bean>

<!—define Templates  --> 
		<bean id="purchaseContentJbpmTemplate" class="org.springmodules.workflow.jbpm31.JbpmTemplate">
		 <constructor-arg index="0" ref="jbpmConfiguration"/>
		 <constructor-arg index="1" ref="purchaseContentWorkflow"/>
		</bean>

Now let's add some Action Handlers and Decision Handlers:

<bean id="jbpmAddTuneAction" class="com.example.plugin.jbpm.handlers.actions.AddTuneActionHandler" />

And its Java code example:
public class AddTuneActionHandler implements org.jbpm.graph.def.ActionHandler
Inside the execute function: public void execute(ExecutionContext executionContext) you can get workflow variables Integer expiration = (Integer)executionContext.getVariable(JBPMConstants.EXPIRATION.toString());
Or setting them: executionContext.setVariable (JBPMConstants.NEW_TUNE.toString(), tune);
Throwing a rollBackException is also possible and this will be discussed later: throw new RollBackPurchaseContentException(subscriberId);

Decision Handlers:

<bean id="jbpmIsSongExistDecision" class="com.example.plugin.jbpm.handlers.decisions.IsSongExistDecisionHandler" />

public class IsSongExistDecisionHandler implements DecisionHandler
public String decide(ExecutionContext executionContext) throws Exception {

return the right String to continue the flow
The next step is to define the service which will trigger the template

<bean id="businessFlowServiceWS" class="com.example.plugin.webservices.impl.BusinessFlowWSImpl">

This class will contain the JbpmTemplate

@Resource
private JbpmTemplate purchaseContentJbpmTemplate;

The flow will be triggered in the following way:

ProcessInstance processInstance = purchaseContentJbpmTemplate.getProcessDefinition().createProcessInstance();	
		try{		
processInstance.setKey(Long.toString(processInstance.getId()));			
//you can set variables for the flow like the following:
processInstance.getContextInstance().setVariable(JBPMConstants.SUBSCRIBER_ID.toString(), subscriberId);
//and start trigger the work flow			
while (!processInstance.isTerminatedImplicitly()) processInstance.signal();	
		} catch (Exception exception) {
//See that exceptions can be sent through the context		
BusinessException error = (BusinessException)  processInstance. getContextInstance().getVariable(JBPMConstants.EXCEPTION.toString());
		} 
		finally {
			processInstance = null;
		}	

WorkFlow process defenition

As mentioned above, processdefinition.xml defines the workflow:
The flow needs to have a start state

<start-state name="start"><transition to="Is Song Exist?"></transition></start-state>

Every Decision or actions declare its configuration and which bean will be used.
Define in The transitions, how the workflow continues from each point.

<decision name="is user registered?">
   	  <handler config-type="bean" class="org.springmodules.workflow.jbpm31.JbpmHandlerProxy">
		<targetBean>jbpmIsUserRegisteredDecision</targetBean>
		<factoryKey>jbpmConfiguration</factoryKey>
		</handler>
		<transition name="yes" to="does user has song?"></transition>
		<transition to="Register to Service Billing" name="no"></transition>
   </decision>

Action node example:

<node name="Add Tune">
		<action name="addTune" config-type="bean" class="org.springmodules.workflow.jbpm31.JbpmHandlerProxy">
			<targetBean>jbpmAddTuneAction</targetBean>
			<factoryKey>jbpmConfiguration</factoryKey>
		</action>
		<transition to="Caller Id parameter"></transition>
	</node>

Exception handlers – enables to do rollback actions or any other action you want to perform.

<exception-handler exception-class = "com.example.plugin.jbpm.RollBackExceptions.RollBackPurchaseContentException">
<action name="refund billing" config-type="bean" class= "org.springmodules.workflow.jbpm31.JbpmHandlerProxy">
		<targetBean>jbpmUnRegisterToServiceAction</targetBean>
		<factoryKey>jbpmConfiguration</factoryKey>	
		</action>
		<action name="exit flow" class="com.example.plugin.jbpm.handlers.actions.ExitFlowActionHandler"></action>
	</exception-handler>

And at last an end state:

<end-state name="end" />

Just few more cool things you can do:

JbpmContext jbpmContext = JbpmConfiguration.getInstance().createJbpmContext();
ProcessInstance processInstance = jbpmContext.newProcessInstance(EXAMPLE_ADD_CONTACT);

And trigger it with:

while (!processInstance.isTerminatedImplicitly()) processInstance.signal();
finally {jbpmContext.close();	}

example for the complete workflow image:

That’s all, now you are ready to write your own flow and enjoy JBPM.