Rapid Alfresco Workflow Development With Activiti Kickstart

The Activiti Designer 5.14.0 has been released recently and comes with a new component, called Activiti Kickstart.

The tool allows for easy creation of Activiti workflows used in Alfresco. Not only does it create the process-definitions, but it also takes care of the required content-models, forms and configuration to have a fully functional workflow in an Alfresco environment.

This blog-post will give an insight in the technical implementation of the tool as well as a quick overview of how to use it. The tool was first revealed and presented in November 2013, on the Alfresco Summit by Joram Barrez in Boston and by myself in Barcelona. These talks contain a live demo of the tool, covering a lot of the features that are available. The recordings of these talks are made available for anyone to watch, as is done with all the Summit talks:

History

When the Activiti project was started about 4 years ago. From that moment on, Activiti has been used as the component inside Alfresco, catering for all things workflow.

The Alfresco mechanism for connecting forms and properties with workflows could be leveraged in order to get a powerful way of defining both process flow and the human interaction with it. Although flexible, this approach involves multiple artifacts which cross-reference each other and need to be kept in sync. This process is error-prone and time-consuming.

We thought it was time to create more tooling around this, in order to take some of the pain away involved in creating Alfresco workflows. The initial idea was to create an app that was part of the Alfresco environment and ran in the browser, allowing users to model simple processes, without the need to know all nuts and blots involved in BPMN and content-modelling. The technical implementation was done, but the development of the web app has not yet started. We decided to make use of the technical implementation we had and release it rather sooner than later in the wild – with an Eclipse/Graphiti-based frontend instead. This does not mean that the Activiti Kickstart Elipse Plugin is just demo-ware or just a prototype, it’s a working tool and will be maintained in the future.

What does it do?

The tool contains 2 new editors: a process editor and a form editor.

The process-editor is really different from the existing BPMN editor that is already present in the Designer. It abstracts away the somewhat complex nature of BPMN-diagrams and goes for a sequential approach, laying out the steps top-down. This is easier to follow for people not familiar with BPMN notation. The number of available steps you can use is limited but cover a lot of the features needed for document-centric processes with a lot of human interaction, some decision making and email capabilities.

The form-editor allows you to add forms to certain steps (or create a start form, shown when the workflow is started). It allows you to drag/drop form-components and group them. It supports a lot of different input-types: text, numbers, boolean, value in a predefined list, alfresco user selection, content selection, dates, … It allows the user to group the form fields into groups using the layout that best for the type of input required.

Once the workflow steps and the forms are designed, the workflow is ready to be exported and used in Alfresco. When exporting a kickstart process, a number of artefacts is created for you:

  • A BPMN, containing the process definition
  • An Alfresco content model XML, containing the content types for all tasks in the
    process.
  • An Alfresco form configuration, containing the appearance of the task-forms ant the task-form.
  • A spring context file, which bootstraps the workflow and models in the repository.
  • A custom Alfresco Surf configuration file to hook up the new forms.

When these artifacts are dropped in the right location in your Alfresco environment, you’ll be able to use them. On top of that, we made sure that the time it takes to deploy a kickstart workflow is reduced to the absolute minimum. By leveraging the dynamic workflow-deployment and model-deployment through CMIS (or data dictionary), no repository-reboots are needed. Also, with a bit of creativity, we made a share extension to be used in development only to reload the form-config without rebooting the share container (see the github project page for this hack creative solution).

In case more advanced usacases are needed (and cannot be solved using a script-step), the generated artefacts can be used as a solid foundation to extend and refine to your specific needs. Ofcourse, converting back from the “complex” representation to the “simple” model is not possible. Doing incremental changes to existing “simple” models is definitely possible.

Below you see a screenshot of the workflow-editor, the form-editor and the full BPMN-representation of the exported process.

Technical details

The “simple” model used to define steps and forms in a workflow are represented as a POJO-model with built-in conversion from and to a JSON-structure. This model is available in the activiti-simple-workflow module. This module is also responsible for generating the (Alfresco independent) BPMN-representation, based on this simple format.

To add the Alfresco-specific bits, an additional module is plugged in (activiti-simple-worklfow-alfresco) and takes care of generating the additional artefacts (content-model, forms) according to best-practices for workflow-related modelling.

Currently, the only fully functional implementation/usage of this simple model and conversion is the Alfresco-usecase. However, we envision an implementation (in the near future) that is Alfresco-agnostic an can generate workflows and forms to use in a pure Activiti-environment.

The Activiti designer plugin contains Graphiti-based editors that manipulate this simple model and allows calling the conversion and export. However, the conversion and creation of these artefacts can also be done using the activiti-simple-workflow-alfresco module, independent of the eclipse UI. The eclipse editors are just an easy way to construct this simple model.

As with all Activiti projects/modules, the sources are Apache 2.0 licensed and bug/requests can be logged though the usual channels (Activiti Jira, forum).

Summary

The current state of the Activiti Kickstart plugin is stable and offers a solid base for creating Alfresco workflows with zero XML-fiddling, without the requirement to know the details about content-modeling and form-rendering in Alfresco. Generated artefacts are also usable as a base for extending and work without any modifications to the Alfresco Repository itself (4.0+ compatibility, since this is the first version that included the Activiti engine).

I recommend watching one of the two talks which are linked in the beginning of this post, to get a good overview of what the tool can and cannot do for you. No doubt, the recording of Joram’s talk in Boston will be more amusing to listen to and watch than mine, due to his superior speaking skills and warm romantic voice ;)

Custom variable representations in Activiti REST

The new Activiti REST api offers a consistent way to handle variables of different types in the JSON requests/responses. When getting variables, values for primitive types – together with Strings and Dates – are included in the response:

Binary and Serializable variables on the other hand, cannot be included directly in the response but rather include an additional URL, referencing the raw value of the variable:

When you’re using your own POJO’s in Activiti (either serializable or stored using a custom variable type), it makes sense to have these variables represented inline rather than using the indirection created by the “valueUrl”. This post will show how this can be done using the new Activiti REST-API.

I’ll be using code-snippets from this project on Github.

Engine & REST setup

Instead of using the activiti-webapp-rest web, we’ll be using a plain Java-main (CustomVariableRepresentationMain) to bootstrap the engine and REST. To make it easier to try out the custom type, we’ll add a user and start a process instance right away:

Custom type implementation

In our CustomRestResponseFactory, we wire in an additional RestVariableConverter which is responsible for converting the MyPojo instances from and to a more complex representation:

Taking it for a spin

After starting the Java-main, the Restlet server is listening on port 8182. When listing all process instances, we see the one we started when the server booted. Fething the variables results in the result below:

When updating the variable, we just do a PUT with the complex JSON-body, representing the new state of the “testVariable”. The body of the put-request looks like this:

The PUT returns the new value of the variable and we can verify that the value of the MyPojo-fields have actually changed.

We added some minimal validation of the object that is passed in the JSON-body. If we omit the “email” field in the JSON-body, we get an error, as expected.

Activiti gets brand new REST-API in 5.13 release

We are proud to announced a brand new REST-API, included in Activiti 5.13. It’s a solid feature-complete API on top of the engine. But why did we build it from scratch?

  • The old API doesn’t cover all features offered by the Java API. The new version covers 99% of all methods in the API services (RuntimeService, RepositoryService, HistoryService, …), which opens up the full potential of the engine through REST. This allows other programing languages to benefit from the power of the Activiti engine.
  • As requirements and use cases came along, the old API grew and evolved. Because of the use-case driven additions, there wasn’t really a common approach followed when adding new REST-calls. This resulted in differences in naming and handling between resources. The new API has introduced a uniform approach.
  • The new API applies the REST-principles more strictly (resource naming, appropriate HTTP-verbs used for resource actions, use of URL’s in responses referencing other resources, using the right HTTP-response codes).

On top of the improvements listed above, here are some other highlights for the new API:

  • Improved error-handling. In addition to returning the most suited HTTP-response code for errors that occur, the description of the error is available in the response-body as JSON instead of the default HTML that Restlet provides.
  • Support of all types of variables (including binary and serializable) and additional pluggability to allow custom variable-type and conversion in REST requests. You can control the way your custom variable-types are represented in REST, so your variable customizations can be used.
  • Authentication and authorization is pluggable. It’s now easier than ever to do per-request/url authorization and authentication.

Keep an eye on this blog, there are more posts on their way about the REST-API, diving deeper into certain topics.

In the screencast below you can see a couple of REST-calls in action. Although this is just a fraction of the available methods, it gives a good idea of the possibilities.

What about the existing API?

The existing REST-API (referred to as the “legacy” API) will not be removed any time soon, so don’t worry if you’ve built a solution on top of it. Also, the internals haven’t been changed (still using Restlet combined with Jackson) which allows you to port any custom REST-resources you have created on top of the existing ones without any issues.

However, we recommend switching to the new API over time. No new functionality will be added to the legacy API, only critical bug fixes will be done if needed.

Usable in different environments

You can use the vanilla activiti-rest.war we provide to get started real quick with REST-api, without any configuration needed. It also comes with some demo-data (similar to the data in the Activiti Explorer). Just drop the war in a container and you’re ready to go, it uses an in-memory database. The engine can be configured to run against other databases as well, of course.

It’s also possible to include the REST-API in your existing application (which may already have an Activiti-engine in it). We tried to make the REST-module (and the other modules as well, by the way) as easy to embed as possible. Just add the activiti-rest.jar as a dependency with all of it’s transitive dependencies and configure the Activiti Restlet Application. If you app runs in a web-container, Restlet is configured as a single servlet. When your application is not in a servlet-environment, you can run a standalone Restlet server to expose the REST-API for your engine.

Dynamic Process Creation and Deployment in 100 Lines of Code

We recently released the 5.12 version of Activiti and it’s packed with a lot of new features and improvements. As of the 5.11 version, it’s possible to build BPMN 2.0 processes using a POJO-model. In the latest release, we embrace that POJO-model even more and use it in the core of Activiti as a means of retrieving and deploying process-definitions (on top of the existing deployment formats) using the API.

Combined with other features of Activiti this allows us to build a process, deploy it, start it, test it and retrieve the process definition diagram in under 100 lines of code. By leveraging the new activiti-bpmn-autolayout module, the process elements can be automatically layout, getting the graphical information (BPMN-DI) for free.

The code

I started off with an Activiti unit-test template, which uses a default Activiti-engine running on an in-memory H2 database. The code is written as a simple unit-test, using the built-in JUnit 4 support to have a fully initialized engine and API ready to use when the test starts to run. Full version of the code below can be found on Github.

  1. Using the BPMN-model, we create a simple process containing a start-event, 2 usertaks, an end-event and the nessecairy flows connecting them.
  2. We use the BpmnAutoLayout class, found in the activiti-bpmn-autolayout module, to make sure all processes in the BpmnModel have a graphical representation defined.
  3. Using the new addBpmnModel(…) method on DeploymentBuilder, we make sure out created process gets deployed in the engine.
  4. We start a new instance of our process by using the process-key we defined in our process.
  5. Fetch all waiting tasks for the started process and check if the task’s name and assignee are correct.
  6. To check what the process actually looks like, we save the diagram-image (created based on the BPMN-DI information):Process-definition diagram
  7. Finally, save the BPMN 2.0 xml representation of this process. This allows us to, for example, further refine the process in other modeling tools like Activiti Designer.

Possibilities

For demonstration purposes I created a relatively simple process, but you can imagine the potential if you consider that the POJO-model allows you to use all supported BPMN 2.0 constructs as well as all Activiti-specific extentions.

Using this approach you can create processes at runtime without the need for a design-tool or having to juggle around with XML. It can be used, for example, to create a process-model based on your own “intermediate model” or “building-blocks”, hiding complexity to end-users without sacrificing the richness of the BPMN language.