Tuesday, December 20, 2016

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.

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:

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.

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.

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.

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.

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.

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

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.

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.

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.

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

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.

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.

Wednesday, August 31, 2016

Using the Activiti 6 Angular app

The Activiti 6 Angular app has been updated with a number of new features in Beta3. This article shows a number of these new features and will guide you in creating an app definition that can be deployed on the Activiti Engine.

Start with downloading the Beta3 distribution from the Activiti download page. In the wars folder you can find the activiti-app.war that can be deployed on a Tomcat server or another servlet container of your choice. By default it will run with an in-memory H2 database. If you want to use a different database you can change the configuration in the WEB-INF/classes/META-INF/activiti-app/activiti-app.properties file, like the following example for MySQL:



Don't forget to change the Hibernate dialect as well and of course add the necessary database driver JAR to the WEB-INF/lib folder.

When the Activiti app has been booted you can see that the Activiti Engine is also included in the Activiti app and will create the Activiti database tables when not present. In addition, also the new Activiti DMN and Form Engine are booted and both engines will also create their database tables when needed (using Liquibase).

Now you can open your web browser and point it to http://localhost:8080/activiti-app and a login screen will be presented. The default user is admin with password test. The dashboard view is now presented:

The Kickstart App can be used to model processes, forms, decision tables and app definitions. The Task app is a general Activiti Engine app that shows all tasks and processes deployed on the Engine. The Identity management component allows you to edit your profile and if you have admin rights (like the default admin user), to create new users and groups.

Let's start with modeling a simple process in the BPMN editor by opening the Kickstart App and create a process in the process tab. In the popup a model name and key have to be filled-in. The model key will be used as the process identifier / logical key.

For this example process we will model a very simple order process, starting with a order start form. When you select the start event on the canvas there's a referenced form property you can click on. This will open a popup where all created forms are available. But you can also click on the new form button to create a new form. Again a form name and form key needs to be filled-in, and the form key will be used as the logical key to lookup the form in the form engine. The form key also has to be unique for every new form you create. When you would use the same form key twice the form engine will think it's the same form and will deploy it as a new version of the previous form with the same form key.

The form editor is opened and you can start dragging form fields on the canvas. Let's add a product name text field and an amount number field to the canvas. 

Click the save button and choose the save and close editor button to go back to the BPMN editor. The order start form is now connected to the start event of the order process. The next step in the process is to execute a decision table to decide on what needs to happen with the new order. In the activities palette group, a decision task can be dragged onto the canvas and connect it to the start event.

The decision task is a new type of service task in the Activiti Engine, which will invoke a decision table deployed on the DMN engine. Similar to attaching a form to the start event, you can select the decision table reference property after selecting the decision task on the canvas. The decision table key needs to be a unique logical key as it will be used as an unique identifier when deploying the decision table on the DMN engine.

Let's create a decision table that checks on a product name and an amount combination, and will return a reviewNeeded boolean variable. Select the first input header and fill-in productname for the variable field. Add another input, and fill-in amount for this variable field. For the output field you can fill-in the reviewNeeded variable name and select the boolean variable type. To fill-in an input or output value in the decision table, you have to double-click on the specific cell. The resulting decision table should look similar to the following screenshot:

We can now use the reviewNeeded variable in the next steps of the process. Let's save and close the decision table editor and add an exclusive gateway as the next step in the order process. Complete the order process like shown in this order process screenshot:

The sequence flow to the review task should have the following flow condition:


And the other sequence flow to the closing exclusive gateway can be the negative of this flow condition like:


For the review task, let's add a very simple review form with an expression field. An expression field can be used to included process variables in a label text on a form. Let's fill it with the following expression:

Now the process design, together with forms and decision table is completed and we can use an app definition to deploy this as a bundle to the Activiti Engine. An app definition also needs a unique logical key and it will be persisted in the key property of the Activiti deployment. Let's create the following order app definition and included the order process model.

When clicking the save button, you can select the publish checkbox, which will deploy the process, forms and decision table to the Activiti Engine in a regular deployment. By default, the Activiti Engine will ignore the form (with extension .form) and decision table (with extension .dmn) files. But when the Activiti DMN and/or the Activiti Form Engine has been enabled for the Activiti Engine this changes. The DMN and Form engine can be enabled using a configurator, and can be configured in an activiti.cfg.xml file or in Java like this:

FormEngineConfiguration formEngineConfiguration = new FormEngineConfiguration();
FormEngineConfigurator formEngineConfigurator = new FormEngineConfigurator();
DmnEngineConfiguration dmnEngineConfiguration = new DmnEngineConfiguration();
DmnEngineConfigurator dmnEngineConfigurator = new DmnEngineConfigurator();

The Form Engine configurator is included in the activiti-form-engine-configurator module and the DMN Engine configurator in activiti-dmn-engine-configurator. When the Form Engine configurator is added every .form file in a deployment will be processed on the Activiti Form Engine and deployed as a new form or a new form version. The same is true for the DMN Engine configurator with .dmn files.

In the Activiti app, the DMN and Form Engine are included by default, so the deployment with the .form and .dmn files will also be processed by the Form and DMN Engine and results in two deployed forms and one deployed decision table. 

These configurators also expose 2 new services each in the Activiti Engine. The Form Engine exposes the FormEngineRepositoryService and FormEngineFormService service interfaces and the DMN Engine exposes the DmnEngineRepositoryService and DmnEngineRuleService service interfaces. These services can be used to retrieve a form definition or submit a completed form to the Form Engine for example. Or execute a decision table in the DMN Engine.

By using the configurator approach we tried to decouple the DMN and Form Engine as much as possible from the Activiti Engine. If you don't want to use it then there are only two required dependencies with a few classes, activiti-form-api and activiti-dmn-api, to expose the service interfaces to the Activiti Engine. 

But coming back to the publish action when saving the app definition. This will deploy the BPMN process on the Activiti Engine, the forms on the Activiti Form Engine, and the DMN decision table on the Activiti DMN Engine. When we go back to the dashboard by clicking on the Activiti logo in the top left of the screen, we can see a new app has appeared.

In the app, you can create new standalone tasks and start new order process instances. Let's start a new process instance and fill-in the start form.

The start form is retrieved form the Form Engine using the logical key we've chosen. After clicking the start process button the decision task will be executed and with this example input we would expect the reviewNeeded variable to be set to true and a review task to be created. 

This concludes the introduction to the new Activiti 6 Angular app included in the Beta3 release. With the introduction of the Form Engine and the DMN Engine things have changed quite a bit since Beta2. But we need only a few additional tables now and the components are modularized and made optional. Let us know what you think about these changes, any feedback is valuable to get this app ready for the first Activiti 6 release.

Activiti 6.0.0.Beta3 released

Today Activiti 6.0.0.Beta3 was released and calling it feature packed doesn't cut it this time. A lot of features have been added and we now are feature complete on an Engine level for the final version 6. We are very aware of the fact that a lot of people are waiting for a final version 6 release. But we also want to make the first version 6 release a high quality product. With this Beta 3 release we are making a big leap towards the final version 6 release, with only issue fixing after community testing, documentation update and improvements and small refactoring of the Angular apps left.

The release plan is to do a release candidate 1 that should be fully feature complete. Based on the community response we'll do a new release candidate release or a final version in short cycles after the release candidate 1. For all people wanting a final version 6 release, you can really help us with doing extensive testing and providing feedback.

The full details of the Beta 3 release:


  • Introduction of 2 new engines, a DMN (Decision Model Notation) Rule Engine and a Form Engine. The DMN Engine allows you to create decision tables and get an outcome based on the input values and the rules defined in the decision table. These decision tables can be invoked from a decision rule task in a BPMN definition, but also independently of a process instance. The Form Engine centralises the form logic that was introduced with the new Activiti 6 UI. Forms can be deployed with BPMN process definitions but also separately. A start or task form references a form definition defined in a JSON format with a logical key. The Activiti 6 UI includes the new Rule Engine and Form Engine by default.
  • Ad-hoc sub process support was added, a blog post is available here.
  • The job executor has been refactored. In Activiti 6 there's only one job executor (based on the async executor from Activiti 5. Jobs are now divided into 4 different tables: executable jobs, timer jobs, suspended jobs and deadletter jobs. All jobs in the executable jobs table can be executed as soon as possible. Timer jobs are now stored in a separate table and a thread will look for timer jobs that are due and then the timer jobs due will be moved to the executable jobs table. When a process instance is suspended, the suspended jobs will be moved to the suspended jobs table. And when the retries of a job have been exhausted, the job will be moved to the deadletter jobs table. This refactoring was done mainly to improve the job queries, that were very complicated because it had to take into account due timer jobs, suspended jobs and deadletter jobs. The job query to look for executable jobs is now a lot less complex, because every job in the executable jobs table needs to execute.
  • Implementation of a message queue based Activiti job executor, you can read more about it here.
  • Introduction of transient variables. Transient variables won't be persisted in the Activiti variable tables, but are still available on the execution for the duration of a single transaction. Transient variables can for example be used to store a REST response that is only needed to create a request to another REST service, or to use a Java service task result in the next Java service task without it getting persisted.
  • Introduction of two new experimental performance flags: 'eager execution tree fetching' will fetch a complete execution tree while fetching a part of a process instance, as typically following parts of the tree are needed when continuing a process instance. 'Execution relationship counting' keeps a count of various related objects to an execution and thus removes the need for explicit checking and deleting related objects when an execution is removed (which happens frequently). First performance benchmarks using these flags gave some great results. The flags have been tested against the Activiti test suite and all test pass, but the flags are currently not enabled by default.
  • Introduction of transaction dependent listeners. You can now register a listener which will be executed before commit, after commit or on rollback. The transaction dependent listener is an addition to the already existing execution, task and event listeners and provides more ways to listen to the execution of a process instance in the Activiti Engine.
  • A simple DMN editor has been added to the Activiti 6 UI app.
  • Added terminate multi instance end behaviour: this allows to use an end event that will end all instances of a multi instance.
  • Optimise the compensation activity behaviour and added support for the use of subprocesses as compensation activity.
  • Expose start time and start user id on runtime process instance and executions. Expose claim time on runtime task. Before: only on historical counterpart.
  • Fix the use of database schema's (oracle/postgres) properly (workarounds were needed before).
  • Fix historical data capturing (vs Beta2 especially, but also against certain v5 cases).
  • Lots of refactoring in the Activiti 6 UI app, for example app definitions are now deployed as normal Activiti deployments without separate app definition tables.
  • Lots of improvements to Activiti 6 QA.
  • Various and many small bug fixes all around.

Release remarks

  • The Activiti 6 Engine is now considered feature complete for a final version 6 release and mainly needs community testing and bug fixes when issues are found.
  • A first refactor of the user guide has been completed for version 6, but there's still work left.
  • A lot of changes were made to the Activiti 6 UI app and we expect there will still be breaking changes before the final version 6 release.
  • The DMN and Form Engine are feature complete but there can still be some changes before the final version 6.
  • An Admin application has been added to the Activiti Github project but is not yet included in the Beta 3 release. The Admin application will provide query capabilities on deployments, process instances, tasks, jobs, forms and decision tables. For the final version 6 release the Admin application will be added to the release.

Wednesday, February 10, 2016

Activiti 6 adds ad-hoc sub process support

With the first official release of Activiti 6 approaching we have added support for ad-hoc sub processes. It's a feature that shows the strength of the Engine refactoring we have been doing, because it's a fairly simple implementation on an Engine level. Let's have a look at what's possible with ad-hoc sub processes in Activiti 6.

We haven't updated the BPMN editor yet with the ad-hoc sub process symbols and properties, as this is an Engine feature in its current state. But the editor part will be added as well of course. So let's imagine the following embedded sub process to be ad-hoc.

The ad-hoc sub process contains two tasks without any sequence flow being defined. When a process instance is started from this process definition, an ad-hoc sub process execution is created in the Activiti Engine and no user task is created yet. For an ad-hoc sub process you can get a list of enabled activities, which refers to the activities that are available within the ad-hoc sub process to work on. So you can work on Task 1 and Task 2 in any order. With the following API call you can get a list of enabled activities from the Engine.


This gives back a list of FlowNode objects that are enabled in the ad-hoc sub process for which the execution identifier is passed as parameter. In this example there will be two UserTask objects returned by this API call. So you can imagine a UI / application where a user can choose which task to work on next. The API call to start one of these tasks looks like this:

runtimeService.executeActivityInAdhocSubProcess(executionId, id);

So again the execution identifier of the ad-hoc sub process is provided, and in addition an identifier of the user task to select is provided as well. This identifier matches the id attribute of the user task element in the BPMN XML of the process definition. When this call is executed for Task 1 for example, the Activiti Engine will create a new user task, which will be available just like any other user task. 

An ad-hoc sub process by default can execute multiple enabled activities at the same time. This is defined with the ordering attribute in the BPMN XML definition. This means that we could also execute Task 2 in our example, while also having Task 1 active at the same time.

And what happens when Task 1 and/or Task 2 are completed. Without defining a completionCondition attribute in the BPMN XML, the Activiti Engine will not end the ad-hoc sub process execution automatically. The RuntimeService API provides the following method to complete an ad-hoc sub process when there are no active child executions (for example user tasks) anymore:


After invoking this method our example process will continue to the After task activity and the ad-hoc sub process will be ended.

But invoking a method to complete an ad-hoc sub process isn't appropriate for a lot of use cases. So let's look at an BPMN XML example with a defined completion condition.

<adHocSubProcess id="adhocSubProcess" ordering="Sequential">
    <userTask id="subProcessTask" name="Task in subprocess" />
    <userTask id="subProcessTask2" name="Task2 in subprocess" />


There are two differences with the previous example process definition. The first difference is the ordering attribute, which is set to Sequential. This means that only one of the user tasks can be executed at the same time. The Activiti Engine will not allow a second user task to be executed, when the first user task hasn't been completed yet. The second difference is the completion condition. This ad-hoc sub process will be automatically completed when the ${completed} expression evaluates to true. So, when we execute the first user task in the ad-hoc sub process and complete it together with a variable completed of true, the ad-hoc will end automatically after completing the user task.

Until now we have been demonstrating individual user tasks within an ad-hoc sub process only. But it's also possible to define individual task together with flows as well. Let's look at an example process model.

In this example Task 1 and Task 2 are enabled when the ad-hoc sub process is started by the Activiti Engine. So it's not possible to execute the other user tasks yet. When Task 1 is executed and completed, the Next task will be automatically created by the Engine, just like it would happen in a normal flow in a process definition. Using the completion condition, you can still determine when the ad-hoc sub process can be completed. And using the cancelRemainingInstances attribute it's possible to define whether the ad-hoc sub process should cancel any remaining executions / tasks when the completion condition evaluates to true. By default the Activiti Engine will cancel all other running executions / tasks, but when setting this attribute to false, the ad-hoc sub process will not complete before all executions / tasks have been ended.

The Activiti 6 Engine opens up a whole new range of dynamic behaviour in process instances. Because of its well defined execution structure and flexible API, there are a lot of new possibilities to add to the Engine. Ad-hoc sub processes is just an example as you will see more functionality appearing in Activiti 6 in the near future.

You can already play around with the ad-hoc sub process functionality on the activiti6 branch on Github (https://github.com/Activiti/Activiti/tree/activiti6). We are looking for feedback from the community about this feature and other BPMN related features you would like to see implemented in Activiti 6.

Thursday, November 5, 2015

Activiti 5.19.0 released

Today we have released Activiti 5.19.0! This release provides a new feature that prevents you from needing to redeploy a process definition when you only want to change a service task class name, or a task assignment etc. 

You can also expect a new beta release of Activiti 6 next week, which will bring us one step closer to a production ready release of version 6 of the Engine.

Activiti 5.19.0 has the following highlights.

  • We introduced a new service DynamicBpmnService that allows you to change a defined set of properties of a process definition without needing to redeploy http://bpmn20inaction.blogspot.com/2015/10/adding-dynamic-behaviour-to-activiti.html
  • Improved support for the terminate end event. According to the BPMN spec a terminate end event should only terminate the current scope. So in case of a multi instance sub process, a terminate end event inside that multi instance sub process should only kill a single instance and the rest of the instances (of the multi instance) will continue. And in case a call activity kicks off a sub process, a terminate end event in the sub process will only kill the sub process instance, and the parent process will continue. We've added a new attribute on the terminate end event (activiti:terminateAll) that allows you to terminate all parent scopes if the value is set to true. By default only the current scope is killed.
  • ACT-4072 was fixed, a repeating timer (time cycle) now works according to the defined duration values.
  • Various bug fixes.
For more information you can read the release notesEnjoy the release.

Friday, October 23, 2015

Adding dynamic behaviour to the Activiti Engine

We have added a new feature to the Activiti Engine that I would like to share with you even before it's available as part of an official release. The new feature is the ability to change a defined number of properties of a process definition without needing to redeploy the process definition.

Before I'll go into details about this feature, some examples of needing to redeploy a process definition would be good to set the context. One example is a service task with a defined class name in the process definition. This service task is part of a big process definition, and process instances can be active for over a year. After deploying the first version of the process definition to the production environment the requirements of the process execution have changed and a new Java class should be executed for the service task instead. This means that new deployment of the process definition is needed and existing process instances need to be migrated to this new process definition.

Another example is a user task with a candidate group management. Over time, the requirements have changed and the sales group needs to be set as the candidate group for this user task. Again, this would mean a new deployment of the process definition and migration of existing process instances.

With the addition of the DynamicBpmnService interface these use cases can be solved differently, without the need to redeploy the process definition. For example, the DynamicBpmnService interface has a method to change the class name of a specific service task named changeServiceTaskClassName. Let's look at a code example to change the class name of the exampleTask service task.

<serviceTask id="exampleTask" 
  activiti:class="org.activiti.PreviousTask" />

ObjectNode infoNode = dynamicBpmnService.changeServiceTaskClassName(
      "exampleTask", "org.activiti.NewTask");
dynamicBpmnService.saveProcessDefinitionInfo("procDefId", infoNode);

After the invocation of the saveProcessDefinitionInfo method the Activiti Engine will now execute the NewTask class instead of the PreviousTask defined in the BPMN XML. As you can see we are using Jackson JSON for storing the overriding process definition information in the Activiti database. Every process definition can have zero or one entry in the new ACT_PROCDEF_INFO table. All changes for a process definition are defined in the same JSON object and stored as a BLOB in the Activiti database. The cache that's used to retrieve the process definition info data is versioned and designed to work in a clustered Activiti environment.

Let's look at one more example, changing the candidateGroup of a user task:

<userTask id="exampleTask" activiti:candidateGroup="management" />

ObjectNode infoNode = dynamicBpmnService.changeUserTaskCandidateGroup(
      "exampleTask", "sales", true);
dynamicBpmnService.saveProcessDefinitionInfo("procDefId", infoNode);

Again, after saving the JSON object, the Activiti Engine will use the sales candidate group for the exampleTask user task instead of the management group.

If you want to override multiple properties of a specific process definition in different steps you need to get the currently stored JSON object first. This is easy to do like this:

ObjectNode infoNode = dynamicBpmnService.getProcessDefinitionInfo("procDefId");

These are the properties we currently support to change with this approach:

  1. Service task - class name
  2. Service task - expression
  3. Service task - delegate expression
  4. User task - name
  5. User task - description
  6. User task - due date
  7. User task - priority
  8. User task - category
  9. User task - form key
  10. User task - assignee
  11. User task - owner
  12. User task - candidate users
  13. User task - candidate groups
And there's an additional feature we have implemented with the same approach, which is localisation. It's now possible to store the user task name and description in multiple languages in the process definition info table and when you query for tasks you can set a locale to use. The returned tasks will then contain the localised name and description as defined in the process definition info table. Let's look at an example:

<userTask id="exampleTask" name="Name" />

ObjectNode infoNode = dynamicBpmnService.changeLocalizationName(
      "es", "exampleTask", "Nombre");
dynamicBpmnService.saveProcessDefinitionInfo("procDefId", infoNode);

Task task = taskService.createTaskQuery().locale("es").singleResult();

The returned task instance will now have Nombre as the name of the task.

We are really excited about this new feature that's available in both the Activiti 5 and 6 code that's in Github, and we are eager to get feedback about this new feature. Let us know what you think about it and maybe come up with suggestions of which properties we could add to this approach in addition to the current supported list. We'll do a 5.18.1 release in a couple weeks time, together with a new beta release for Activiti 6, that will include this feature. And you can already create your own build using the code on Github of course.

Monday, September 7, 2015

Getting started with the new Activiti 6 UI

We launched Activiti 6 with a new UI that replaces the Vaadin based Activiti Explorer application. The new UI is written in AngularJS and contains a number of new features that we'll introduce in this article.

But let's first get started with download the Activiti 6 beta package from the Activiti website: http://activiti.org/download.html. The package contains the JAR files files of the different Activiti modules including the Engine JAR file. It also contains the userguide, javadocs, readme files, database scripts and the two WAR files for the REST application and the new Angular web application (the focus of this article).

So when you downloaded and unzipped the Activiti 6 package, copy the wars/activiti-app.war file to a local Tomcat 7 or 8 installation. Before you start Tomcat, first the database needs to be taken of. By default, the application is configured for a MySQL database with name activiti6ui and username/password alfresco/alfresco. If you would like to change the database settings you can change the WEB-INF/classes/META-INF/activiti-app/activiti-app.properties file in the activiti-app.war file or create a copy of this file in the Tomcat lib folder. By default the H2 and MySQL database drivers are provided by default with the activiti-app.war file, so if you want to use another database, make sure you copy the database driver to the WEB-INF/lib folder.

Now we're ready to start the Tomcat server. The database tables will be created automatically using Liquibase. When the Tomcat server is started you can open a web browser to http://localhost:8080/activiti-app and you should get a login screen. The default username/password is admin@app.activiti.com/test. The dashboard page is now presented, showing the Kickstart (editor), Task and Identity management apps.

If you would like to create addition user and/or groups you can do this in the identity management application. But we'll go ahead with designing a simple process using the Kickstart app. You can see there are three main editor types supported, processes, forms and apps. Let's start with the process type and create a new process using the BPMN editor.

The BPMN editor hasn't changed so much when compared with the editor we shipped as part of the Activiti Explorer application. The main difference is that we added integration with the form editor. So let's add a form to the start event to be able to fill-in a BPM related buzzword. Click on the start event and select the Referenced form property.  A popup will be shown where you can select a form, but since we started with an empty database, no forms will be available yet. So click New form, and fill-in a name and an optional description to create a new form. The form editor will be opened and you can start dragging form fields to the canvas to create a start form.

There are a number of field types to choose from and you can also change the outcome buttons of the form. The default outcome button is Complete, if no other outcomes are defined. For this simple example, we only use a text field with label Buzzword. The value of this text field will be available in the process with variable name buzzword (the identifier of the form field, which can be defined in the configuration of the field).

Let's continue with defined sequence flow conditions for all three flows that are outgoing of the exclusive gateway. You can for example use the following conditions:

  1. ${buzzword == 'BPMN'}
  2. ${buzzword == 'BPEL'}
  3. empty, select default flow for this sequence flow.
Now let's configure the Great buzzword user task and define the assignment.

In addition to the static values and expressions you could fill-in in the previous BPMN editor version, you can now directly reference a group or a user you defined in the identity management application. You can also assign the task to the process initiator, and that's what we'll do for this process.

We also have to define a task form, to give feedback to the user. The value of the buzzword text field can be used to show a display text field like shown in the image.

You can add similar task forms to the other two user tasks to complete the process design. The next step is to create an app definition using the app editor. When you create a new app definition, you can define the icon, theme color and processes you would like to include in the app definition.

All the processes included will be available as part of the app, so it's basically a categorisation of processes. When you save the app definition, make sure you select the publish checkbox as well, so the app will be deployed to the Activiti Engine. In addition, you can choose to share the app definition with other user and/or groups and all users that are included there, will have the option to add the app to their dashboard.

When the app is published you'll notice that the app and process are automatically versioned. This ensures that there's always an exact version to point back to from a deployed application and process model. Go back to the dashboard by clicking on the Alfresco Activiti logo in the left top. You can add the newly deployed app to your dashboard by clicking the + button in the grey rectangle and choosing the app in the popup and clicking the Deploy button. The app is available in the dashboard now.

When opening the Buzzword app, a view with a task and process section is shown. We can now start a new process instance of the Buzzword process by filling in a buzzword.

After starting the process with buzzword BPMN, a new process instance is created and the Great buzzword user task is available.

There are a lot of options you can explore in the process instance details view and task view. For example, there's the possibility to show the process diagram.

But also the possibility to add comments to a running process or task. In the task details view, you can fill-in and complete the form, but also involve other people in the task and add file attachments. Take your time to explore and tryout these options and let us now if you think we should add specific actions and/or information.

There's a lot more to talk about regarding the new Activiti 6 UI, but this should be sufficient for a first introduction. Let us know what you think, this should be the start of great new UI to work with the Activiti Engine and we are looking for feedback on how to improve it.