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:

datasource.driver=com.mysql.jdbc.Driver
datasource.url=jdbc:mysql://127.0.0.1:3306/activiti6ui?characterEncoding=UTF-8
datasource.username=mysql
datasource.password=test

hibernate.dialect=org.hibernate.dialect.MySQLDialect

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:

${reviewNeeded}

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

${!reviewNeeded}

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();
formEngineConfiguration.setDataSource(dataSource);
    
FormEngineConfigurator formEngineConfigurator = new FormEngineConfigurator();
formEngineConfigurator.setFormEngineConfiguration(formEngineConfiguration);
processEngineConfiguration.addConfigurator(formEngineConfigurator);
    
DmnEngineConfiguration dmnEngineConfiguration = new DmnEngineConfiguration();
dmnEngineConfiguration.setDataSource(dataSource);
      
DmnEngineConfigurator dmnEngineConfigurator = new DmnEngineConfigurator();
dmnEngineConfigurator.setDmnEngineConfiguration(dmnEngineConfiguration);
processEngineConfiguration.addConfigurator(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:

Highlights

  • 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.