Coding introduction with Flowable 6

With the release candidate of Flowable 6 available, now is a good time to go back to the basics and look at how you can get started with using the Flowable 6 engine from scratch. Looking at all the modules available in Flowable 6, things can be a bit overwhelming. But with this simple introduction you'll see that it's really easy to get started.

All examples used in this article are available in the Flowable examples Github repository. The flowable-intro Maven project can be imported into your favourite IDE and you can play with the examples from there.

Now let's get started with a simple BPMN example project by creating a new Maven project and add the Flowable Engine as a dependency, like you can see in the following snippet.

	<?xml version="1.0" encoding="UTF-8"?>
	<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<name>Flowable Intro</name>
	<groupId>org.flowable.examples</groupId>
	<artifactId>flowable-intro</artifactId>
	<packaging>jar</packaging>
	<version>1.0</version>
	<dependencies>
	<!-- Flowable dependencies -->
	<dependency>
	<groupId>org.flowable</groupId>
	<artifactId>flowable-engine</artifactId>
	<version>6.0.0.RC1</version>
	</dependency>
	<dependency>
	<groupId>com.h2database</groupId>
	<artifactId>h2</artifactId>
	<version>1.3.176</version>
	</dependency>
	<dependency>
	<groupId>org.slf4j</groupId>
	<artifactId>slf4j-api</artifactId>
	<version>1.7.6</version>
	</dependency>
	<dependency>
	<groupId>org.slf4j</groupId>
	<artifactId>slf4j-log4j12</artifactId>
	<version>1.7.6</version>
	</dependency>
	<dependency>
	<groupId>junit</groupId>
	<artifactId>junit</artifactId>
	<version>4.11</version>
	<scope>test</scope>
	</dependency>
	</dependencies>
	</project>

view raw Flowable 6 intro pom.xml hosted with ❤ by GitHub

Of course this pom file has a few more dependencies, like the H2 database and SLF4j API, but the only thing specific for the Flowable Engine is the flowable-engine dependency. Now we need to create a flowable.cfg.xml configuration file in the src/main/resources (or src/test/resources) folder:

	<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
	<bean id="processEngineConfiguration"
	class="org.flowable.engine.impl.cfg.StandaloneProcessEngineConfiguration">
	<property name="jdbcUrl" value="jdbc:h2:mem:flowable;DB_CLOSE_DELAY=1000;MVCC=TRUE" />
	<property name="jdbcDriver" value="org.h2.Driver" />
	<property name="jdbcUsername" value="sa" />
	<property name="jdbcPassword" value="" />
	<property name="databaseSchemaUpdate" value="true" />
	</bean>
	</beans>

view raw Flowable 6 config.xml hosted with ❤ by GitHub

We will use an in-memory H2 database to run the Flowable Engine. With the project setup and configuration file in place we can now create a BPMN process definition that executes a Java service task.

	<?xml version="1.0" encoding="UTF-8"?>
	<definitions id="introExample"
	xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
	xmlns:flowable="http://flowable.org/bpmn"
	targetNamespace="http://flowable.org/examples">
	<process id="intro">
	<startEvent id="start"/>
	<sequenceFlow id="flow1" sourceRef="start" targetRef="introTask" />
	<serviceTask id="introTask" flowable:class="org.flowable.intro.IntroTask" />
	<sequenceFlow id="flow2" sourceRef="introTask" targetRef="end" />
	<endEvent id="end" />
	</process>
	</definitions>

view raw Flowable 6 intro bpmn20.xml hosted with ❤ by GitHub

The IntroTask Java class will be executed when a new process instance is started for this process definition. This service task will set a variablePresent variable when the intro variable is present in the process instance.

	public class IntroTask implements JavaDelegate {
	public void execute(DelegateExecution execution) {
	if (execution.hasVariable("intro")) {
	System.out.println("Intro variable available with value " + execution.getVariable("intro"));
	execution.setVariable("variablePresent", true);
	} else {
	System.out.println("Intro variable not available");
	execution.setVariable("variablePresent", false);
	}
	}
	}

view raw Flowable 6 IntroTask.java hosted with ❤ by GitHub

Now let's implement a unit test that starts the Flowable Engine and runs a few tests for this process definition. In the first part of the unit test the Flowable Engine is started and the intro process definition is deployed to the Engine and a new process instance is started.

	@Test
	public void testIntroProcess() {
	// Create Flowable engine
	ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine();
	// Get main service interfaces
	RepositoryService repositoryService = processEngine.getRepositoryService();
	RuntimeService runtimeService = processEngine.getRuntimeService();
	HistoryService historyService = processEngine.getHistoryService();
	// Deploy intro process definition
	repositoryService.createDeployment().name("intro")
	.addClasspathResource("intro.bpmn20.xml")
	.deploy();
	// Start intro process instance
	ProcessInstance processInstance = runtimeService.startProcessInstanceByKey("intro");
	assertTrue(processInstance.isEnded());
	....
	}

view raw Flowable 6 Part 1 IntroTest.java hosted with ❤ by GitHub

In the second part of the unit test we validate that in the first run the variablePresent value is equal to false, and in the second run (with an intro variable), the variablePresent value is true.

	@Test
	public testIntroProcess() {
	....
	HistoricVariableInstance historicVariable = historyService.createHistoricVariableInstanceQuery()
	.processInstanceId(processInstance.getId())
	.singleResult();
	assertEquals("variablePresent", historicVariable.getVariableName());
	assertEquals(false, historicVariable.getValue());
	processInstance = runtimeService.startProcessInstanceByKey("intro", Collections.singletonMap("intro", (Object) "a test intro value"));
	List<HistoricVariableInstance> historicVariables = historyService
	.createHistoricVariableInstanceQuery()
	.processInstanceId(processInstance.getId())
	.orderByVariableName()
	.asc()
	.list();
	assertEquals("intro", historicVariables.get(0).getVariableName());
	assertEquals("a test intro value", historicVariables.get(0).getValue());
	assertEquals("variablePresent", historicVariables.get(1).getVariableName());
	assertEquals(true, historicVariables.get(1).getValue());
	processEngine.close();
	}

view raw Flowable 6 Part 2 IntroTest.java hosted with ❤ by GitHub

So with a few setup and configuration files, together with a service task class and process definition, it's really easy to start the Flowable Engine and execute a few test runs. You basically only need the flowable-engine dependency and a few supporting dependencies for the database and logging. Now let's enhance this setup and add the Flowable DMN engine to the configuration and unit test as well. First we need to add a few dependencies to add the DMN engine to the Maven project classpath.

	<dependency>
	<groupId>org.flowable</groupId>
	<artifactId>flowable-dmn-engine</artifactId>
	<version>6.0.0.RC1</version>
	</dependency>
	<dependency>
	<groupId>org.flowable</groupId>
	<artifactId>flowable-dmn-engine-configurator</artifactId>
	<version>6.0.0.RC1</version>
	</dependency>

view raw Flowable6 DMN intro pom.xml hosted with ❤ by GitHub

With the DMN engine and configurator dependencies available we can now add the initialization of the DMN engine to the Flowable configuration.

	<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
	<bean id="processEngineConfiguration"
	class="org.flowable.engine.impl.cfg.StandaloneProcessEngineConfiguration">
	<property name="jdbcUrl" value="jdbc:h2:mem:flowable;DB_CLOSE_DELAY=1000;MVCC=TRUE" />
	<property name="jdbcDriver" value="org.h2.Driver" />
	<property name="jdbcUsername" value="sa" />
	<property name="jdbcPassword" value="" />
	<property name="databaseSchemaUpdate" value="true" />
	<property name="configurators">
	<list>
	<ref bean="dmnEngineConfigurator"/>
	</list>
	</property>
	</bean>
	<bean id="dmnEngineConfigurator" class="org.flowable.dmn.engine.configurator.DmnEngineConfigurator" />
	</beans>

view raw Flowable6 DMN engine configuration.xml hosted with ❤ by GitHub

This is all that is needed to run the DMN Engine together with the BPMN Engine and enable the DMN Task in the BPMN XML process definition. The database connection will be automatically shared in this configuration. It's of course also possible to run the DMN Engine separately. Let's change the simple BPMN example and add a DMN task instead of a service task.

	<?xml version="1.0" encoding="UTF-8"?>
	<definitions id="dmnExample"
	xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
	xmlns:flowable="http://flowable.org/bpmn"
	targetNamespace="http://flowable.org/examples">
	<process id="dmn">
	<startEvent id="start"/>
	<sequenceFlow id="flow1" sourceRef="start" targetRef="dmnTask" />
	<serviceTask id="dmnTask" flowable:type="dmn">
	<extensionElements>
	<flowable:field name="decisionTableReferenceKey">
	<flowable:string><![CDATA[intro]]></flowable:string>
	</flowable:field>
	</extensionElements>
	</serviceTask>
	<sequenceFlow id="flow2" sourceRef="dmnTask" targetRef="end" />
	<endEvent id="end" />
	</process>
	</definitions>

view raw Flowable 6 intro DMN bpmn20.xml hosted with ❤ by GitHub

The DMN task will execute the DMN decision table with key "intro" in the DMN Engine. The intro decision table will check if the name variable is equal to "Flowable" and set a resultVariable with value "is cool". If the name variable value is different, then the resultVariable is set to value "really?". The DMN definition can be found here.

With all definitions in place we can now test this setup and run the BPMN Engine together with the DMN Engine. The main difference is that we need to deploy both the BPMN XML file as well as the DMN XML file.

	// Deploy intro process definition
	repositoryService.createDeployment().name("dmn")
	.addClasspathResource("dmn.bpmn20.xml")
	.addClasspathResource("intro.dmn")
	.deploy();

view raw Flowable 6 DMN test.java hosted with ❤ by GitHub

When the DMN Engine is available, the DMN file will be picked up by the DmnDeployer and will deploy it to the DMN Engine. The BPM Engine deployment id is set as a reference in the DMN Engine deployment, so the BPMN Engine is always able to correlate the DMN artefact to the process definition when that's requested. The rest of the unit test is very similar to the unit test we used earlier, and validates the process variable values. So by instantiating the DmnEngineConfigurator and adding it as a configurator to the process engine, we are able to use the DMN Engine via the DMN task. The DMN Engine is fully optional, but can easily be plugged-in when that's needed. A similar pattern is used for the Content Engine, to store process and/or task attachments.

To complete the introduction, let's also have a quick look on how to enable the Flowable 5 embedded engine. The Flowable 5 embedded engine is a handy way to migrate from the Flowable 5 Engine to the Flowable 6 Engine. All running process instances will be executed with the same logic as the Flowable 5 Engine, and existing process definitions will be labeled with the version 5 tag. New process definitions will be deployed as Flowable 6 process definitions by default, but this can be overridden using a deployment property. A possible migration strategy is to let the running process instances end on the Flowable 5 logic, and let all new process instances run with the new Flowable 6 logic.

To run the embedded Flowable 5 engine we need to add the compatibility dependency, that is again an optional component for the Flowable 6 engine.

	<dependency>
	<groupId>org.flowable</groupId>
	<artifactId>flowable5-compatibility</artifactId>
	<version>6.0.0.RC1</version>
	</dependency>

view raw Flowable 6 embedded5 pom.xml hosted with ❤ by GitHub

We now need to enable the embedded Flowable 5 engine in the configuration file with the flowable5CompatibilityEnabled property.

	<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
	<bean id="processEngineConfiguration"
	class="org.flowable.engine.impl.cfg.StandaloneProcessEngineConfiguration">
	<property name="jdbcUrl" value="jdbc:h2:mem:flowable;DB_CLOSE_DELAY=1000;MVCC=TRUE" />
	<property name="jdbcDriver" value="org.h2.Driver" />
	<property name="jdbcUsername" value="sa" />
	<property name="jdbcPassword" value="" />
	<property name="databaseSchemaUpdate" value="true" />
	<property name="flowable5CompatibilityEnabled" value="true" />
	</bean>
	</beans>

view raw Flowable 6 embedded 5 config.xml hosted with ❤ by GitHub

When activating the Flowable 5 embedded engine on an existing Flowable database with running process instances, all existing process definitions and deployments will be marked as version 5 artefacts. This ensures that all running process instances will keep running against the same Flowable 5 logic. But in this test we start with a clean database, so let's now mark a new deployment as a Flowable 5 deployment.

	// Deploy intro process definition
	Deployment deployment = repositoryService.createDeployment().name("intro")
	.addClasspathResource("intro.bpmn20.xml")
	.deploymentProperty(DeploymentProperties.DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION, true)
	.deploy();
	ProcessDefinition processDefinition = repositoryService.createProcessDefinitionQuery()
	.deploymentId(deployment.getId())
	.singleResult();
	assertEquals("intro", processDefinition.getKey());
	assertEquals("v5", processDefinition.getEngineVersion());

view raw Flowable 6 embedded intro.java hosted with ❤ by GitHub

With the DEPLOY_AS_FLOWABLE5_PROCESS_DEFINITION deployment property, this deployment is marked as a Flowable 5 deployment, and new process instances will execute with the embedded Flowable 5 Engine. As you can see in the unit test, the process definition is also marked with the "v5" engine version property.

With this article we tried to show that with Flowable 6, the same lightweight and modular approach has been taken as with Flowable 5 and that it's really easy to plugin the DMN engine and enable the Flowable 5 embedded engine. Also, the APIs are still the same so it should be easy to get started with the Flowable 6 Engine. Feedback is always welcome on this article and you can always ask questions and provide feedback on the Flowable forum.