= Activiti Migraton Guide : Activiti v5 to Activiti v6
v 6.0.0-SNAPSHOT
:doctype: book
:toc: left
:toclevels: 5
:icons: font
:numbered:
:source-highlighter: pygments
:pygments-css: class
:pygments-linenums-mode: table
:compat-mode:
== Introduction
This guide describes the various things that are needed when migrating from Activiti v 5.x to Activiti version 6. This is a preliminary version of the migration guide, which will be updated while alpha/beta releases of Activiti v6 are being pushed out. As it goes with such releases, many things can still change on the road to a stable version. At that point, the migration guide will be formalized and the regular user guide will be updated to reflect all the features and capabilities in Activiti v6, as was the case for Activiti v5.
*This current Activiti v6 release is for testing purposes only! Do not use in production yet.* The main goal of this release is to gather feedback, report issues and to have people test out their process definitions on v6. Of course, as before, all contributions are more than welcomed through our Github page. The Activiti v6 code lives currently link:$$https://github.com/Activiti/Activiti/tree/activiti6$$[on the _activiti6_ branch]
== Design goals
The design goals of version 6 are:
* Complete backwards compatibility with version 5: database-wise, concept-wise and code-wise.
* Rewrite of the core engine: direct execution of BPMN 2.0 (vs transformation to intermediate model)
* Simpler and cleaner runtime execution data structure, where predictability of the structure is crucial
* Decoupling of persistence layers for future possible different implementations
== Database migration
There is no database migration when moving from v5 to v6: the database schema is the same for v5 and v6. All data produced by Activiti v5 can simply remain in the database. When the v6 engine is started for the first time, it will do a small automatic update (as with any v5 version) to the schema.
== Conceptual changes
The main reason for calling this activiti version _6_ is because the core engine has been completely rewritten. The way core engine operations are executed has changed completely, along with a direct execution of BPMN (in V5 there is an intermediate model). Also the way runtime executions are represented (the _execution tree_) changed. In general, both areas have been simplified significantly, making execution simpler and clearer while also making the writing of custom behavior easier and more accessible.
In the future, we'll describe the inner workings of the engine in detail. An introduction to the version 6 basics can be found at the link:$$http://www.jorambarrez.be/blog/2015/06/18/activiti-6-launch/$$[Activiti 6 launch recording].
== Breaking changes
The following changes are breaking changes (ie there will be a compile error most likely)..
=== PVM classes
All classes from the org.activiti.engine.impl.pvm package (and subpackages) have been removed. This is because the _PVM_ (Process Virtual Machine) model has been removed and replaced by a simpler and more lightweight model.
This means that usages of _ActivitiImpl_, _ProcessDefinitionImpl_, _ExecutionImpl_, _TransitionImpl_ are invalid.
Generally, most of the usage of these classes in version 5 came down to getting information that was contained in the process definition. In version 6, all the process definition information can be found through the _BpmnModel_, which is a Java representation of the BPMN 2.0 XML for the process definition (enhanced to make certain operations and searches easier).
The quickest way to get the _BpmnModel_ for a process definition is to use the org.activiti.engine.impl.util.ProcessDefinitionUtil class:
In version 5, there always was confusion about _signaling an execution_, when using for example _runtimeService.signal(executionI);_. As a _signal_ is a valid BPMN 2.0 concept and feature, it conflicts conceptually.
In version 6, the _signal()_ methods have been renamed to _trigger()_..
This also means that _SignalableActivityBehavior_, the interface to be implemented for behaviors that can be _triggered_ from external sources, is now called _TriggerableActivityBehavior_.
=== Checked Exceptions
In version 5, the delegate classes like _JavaDelegate_ and _ActivityBevior_ had _throws Exception_ in their signature. As with any modern framework, the use of checked Exceptions has been removed in version 6.
=== Delegate classes
_org.activiti.engine.impl.pvm.delegate.ActivityBehavior_ has changed package and lives now in _org.activiti.engine.impl.delegate_.
The following methods have been removed from _ActivityExecution_:
* end()
* createdExecution()
They have been replaced by calls to the ExecutionEntityManager, which can be fetched through Context.getCommandContext.getExecutionEntityManager().
=== EntityManagers
In Activiti version 5, all EntityManager (responsible for persistence but also certain logic) classes did not have an interface. In version 6, all EntityManager classes have been renamed to have _Impl_ as suffix and an interface without the suffix. This effectively means that the version 5 EntityManager class name is now the name of the corresponding interface.
All EntityManager interfaces extend the generic org.activiti.engine.impl.persistence.entity.EntityManager interface. All implementation classes extend a generic _AbstractEntityManager_ interface.
Also, for consistency:
* The UserIdentityManager interface has been renamed to UserIdentityManager
* The GroupIdentityManager interface has been renamed to GroupEntityManager
=== Future breaking changes
The following changes will most likely be applied in a next beta release of Activiti v6:
* _org.activiti.engine.impl.delegate.ActivityExecution_ (which is passed for example in ActivityBehaviour) will be removed and replaced by _org.activiti.engine.delegate.DelegateExecution_. The original idea was that ActivityBehavior and JavaDelegate would have different use cases and thus the need for different interfaces, but practice has shown that this does not matter.
* The entity cache that is created and used during the execution of a command will be moved up the hierarchy, to be at the same level as the entity managers.
* The persistence operations will be moved to a separate interface out of the EntityManager classes to allow pluggability.
== V5 compatibility
When migrating to Activiti version 6 (which basically means replacing the jar on the classpath), all current deployments and process definitions are _tagged_ as being a _version 5_ artifact. At various points (completing a task, starting a new process instance, task assignment, ... quite a long list) the engine will check whether the involved process definition has that _version 5 tag_. If so, it will delegate execution to an _embedded mini version 5 engine_.
This means that the compatibility approach we opted for is that of a phase out: let the current process definitions run in _'version 5 mode_ until the behaviour has been verified and tested to be identical on version 6.
To enable this behavior (by default it is _disabled_!), add the following to the engine config:
*and* add the *activiti5-compatibility* jar to your classpath (manually or through a dependency mechanism like Maven)..
In case the default implementation _org.activiti.compatibility.DefaultActiviti5CompatibilityHandler_ is insufficient, as custom implementation can be created. Set the _activiti5CompatibilityHandlerFactory_ property of the engine configuration to the fully qualified classname to make that happen. That Factory class should produce an instance of the handler responsible for bridging from version 6 to 5.
To move a process definition to run on the version 6 engine, simply redeploy it. New process instances will be running in _version 6 mode_, while existing process instances will run in _version 5 mode).
If for some reason, you'd still want to deploy a new version of a process definition to run in _version 5 mode_, the following code can be used:
