Trying out Activiti: Examples that leverage Alfresco’s new workflow engine

I’ve been playing with Activiti. It’s an open source, BPMN 2.0 compliant business process engine. The project is sponsored by Alfresco, who hired Tom Baeyens and Joram Barrez, the founders of jBPM, to create the Apache-licensed engine (take a look at the rest of Activiti’s all-star cast).

The first thing I did was head over to Activiti’s site and read through the user guide. I followed the tutorial and got a standalone instance of Activiti going with very little fuss. The concepts and terminology aren’t terribly different from jBPM, so if you’ve used jBPM, you’ll be familiar with the basics of Activiti in no time. The user guide is well-written so I urge everyone to start there.

Last week, Alfresco released a preview release of their Community product, labeled 3.4.e. This release, which I stress is only for preview purposes, was made available to let everyone get a first look at Alfresco’s integration of Activiti. If you watched the screencast showing an Alfresco workflow based on Activiti you may have thought, “Gee, that looks just like a jBPM-based workflow,” and you’re right–from a user standpoint, it is nearly identical. The difference, of course, is how the processes are described and the underlying implementation that executes the processes.

The screencast showed that the end users won’t see much of a change. That’s good, but I was anxious to find out how big a deal this transition will be from a developer’s perspective. The 3.4.e release gave me the perfect opportunity to dig in. I decided to take the examples from the Advanced Workflow chapter in the Alfresco Developer Guide (2008, Packt) and make them work with Alfresco’s embedded Activiti engine in 3.4.e. In this post, I’ll talk about how that went and I’ll give you the code so you can try it out yourself.

The code that accompanies this blog post includes the same set of four workflows implemented both in jBPM and Activiti as well as a readme that explains how to install and run everything. I’ll let you inspect that to see what the exact differences are rather than go over them here. Instead, I’ll spend the rest of the post covering the major differences in general.

Before we go any further, I guess we should have a quick terminology discussion. First, in jBPM, everything is a node. Specialized node types do different things like joins, splits, decisions, wait-states, sub-processes, and enclose tasks that get assigned to humans. In Activiti (and really, in BPMN) there are essentially events (start, stop, timer), tasks, and gateways. Of course, I’m simplifying greatly here–you should read the spec and the Activiti user guide. The important thing to note for people coming from jBPM is that in Activiti a “task” might be something a human does (“userTask”) or it could be automated (“scriptTask”, “serviceTask”, etc.). In jBPM connections between nodes are called “transitions” while in Activiti they are called “sequenceFlows”.

Designing Processes

I use Eclipse, so the first step was to get the Activiti BPMN 2.0 Designer plug-in working. Installation is well-documented on the Activiti wiki and it installs just like any other Eclipse plug-in, so it went fairly smooth. I had some sort of dependency conflict that I had to deal with, but nothing major.

All in all, designing processes in Activiti works just like it does in jBPM. The tool is different, but you’re still laying out a business process graphically, connecting steps in the workflow, and setting properties on those objects.

There are some known issues with the Designer that made creating and editing processes painful at times. I’m not going to call every one of those out in this post because this is a preview release–I expected to work through a few bumps. I will warn you of a few to hopefully save you some time:

  • You cannot save the diagram until it is syntactically correct. This means the BPMN 2.0 XML will not get generated until the diagram is correct. On a new process, when the editor complains about the diagram, you’d kind of like to just drop in to the XML source and fix what needs fixing. If that’s what you want to do, you have to open the .activiti file in the XML editor, make the change, re-open in the diagram, and then make a change and save to force the generation of the BPMN 2.0 XML.
  • You cannot change things like IDs, names, form keys, and task assignment in the BPMN 2.0 XML. You have to change these in the Activiti diagram. If you change the BPMN 2.0 XML the settings in the Activiti diagram will overwrite the BPMN XML. This doesn’t sound like a big deal until you come across the next issue.
  • There is a known problem enabling the properties for an object in the diagram: clicking an object in the diagram doesn’t refresh the properties view. I worked around it by first clicking some other tab in the properties view, then double-clicking on the object (and sometimes repeating that) until the properties view refreshed with the appropriate property set.

Again, I didn’t expect everything to be fully functional, so I am not complaining. I just want you to have your expectations properly set when you play with this on your own.

I should mention that the overall look-and-feel of the Activiti Designer seems a lot crisper and more visually appealing than the JBoss Graphical Process Designer (GPD) Eclipse plug-in. As an example, I loved the alignment helper rules. And I liked that you can bend sequence flows.

Adding Business Logic to Processes

My goal was to take four Alfresco jBPM processes and port them to Activiti. The first three are variations on Hello World. The fourth is a more real-life process that is used to review and approve whitepapers. In the book, the Publish Whitepaper workflow uses an action to set properties on the approved whitepaper. And I show how to combine a wait state with a mail action and a web script to allow third parties without direct access to Alfresco to participate in a workflow. For the initial cut at this exercise, I skipped all of that. For now, I really wanted to focus on the basics of the workflow engine. But the state idea and the web script interaction are interesting so I’ll do that later and will provide the update in a future blog post.

Challenge 1: Alfresco JavaScript in automated steps

The first problem I came to was how to handle workflow steps that have no human intervention. In jBPM those steps are implemented as nodes. Alfresco JavaScript can live inside events within the node or on transitions between nodes. Tasks assigned to users are typically enclosed in a task-node. In Activiti, tasks assigned to users are called userTasks. All of Alfresco’s sample Activiti workflows consist entirely of userTasks. But Activiti includes several node types that aren’t user tasks: a scriptTask uses JavaScript or Groovy to implement its logic and a serviceTask delegates to a Java class. My helloWorld processes consist entirely of automated steps, so a scriptTask sounded good to me. The problem was that scriptTask uses Activiti’s JavaScript implementation, not Alfresco’s JavaScript. So doing something simple like invoking the “logger” root object doesn’t work in a scriptTask.

Fine, I thought, I’ll use one of Alfresco’s listener classes to wrap my logger call and stick that listener in the scriptTask. But that didn’t work either because in the current release Alfresco’s listener classes don’t fully implement the interface necessary to run in a scriptTask.

After confirming these issues with the Activiti guys I decided I’d put my Alfresco JavaScript in listeners either on a userTask or on a sequenceFlow (we called those “transitions” in jBPM) depending on what I needed to do. Hopefully at some point we’ll be able to use scriptTask for Alfresco JavaScript because there are times when you need automated steps in your process that can deal with the Alfresco JavaScript root objects you’re used to.

Challenge 2: Processes without user tasks

As I mentioned, my overly simple Hello World examples are nothing but automated steps. I could implement those without userTasks by placing my Alfresco JavaScript on sequenceFlows. But Alfresco complained when I tried to run workflows that didn’t contain at least one user task. I didn’t debug this, and it is possible I could have worked through it, but I decided for now, the Activiti versions of my Hello World examples would all have at least one userTask.

Challenge 3: Known issue causes iBatis exceptions

In 3.4.e, there is a known issue in which user tasks will cause read-only iBatis exceptions unless you set the due date and priority. Search my examples for “ACT-765” to find the workaround.

Challenge 4: Letting a user pick between multiple output paths

Suppose you have a task in which a human must decide whether to “Approve” or “Reject”. In Alfresco jBPM, you’d simply have two transitions and you’d set the label for those transitions in a properties bundle. In Alfresco Activiti that is handled a bit differently. Instead of having two transitions leaving the task, you have a single transition to an “exclusive gateway” (called a “decision”, in polite company). The task presents the “outcome” options–in this case “Approve” and “Reject”–to the user in a dropdown, as if it were any other piece of metadata on the task. Once the user picks an outcome and completes the task, the exclusive gateway checks the outcome value and takes the appropriate sequence flow. This difference will impact your business process logic, your workflow content model, and your end user experience so it is a significant difference.

For comparison, here’s what this looks like in the Alfresco Explorer UI for jBPM (click to enlarge):

And here is what it looks like in the Alfresco Explorer UI for Activiti (click to enlarge):

So in Explorer, with jBPM, the user can just click “Approve” or “Reject” while in Activiti, the user must make a dropdown selection and then click “Next”.

Here is the same task managed through the Alfresco Share UI for jBPM:

Versus Alfresco Share for Activiti:

Similar to the Explorer differences, in Share, with jBPM, the user gets a set of buttons while with Activiti, the user makes a dropdown selection.

One open question I have about this is how to localize the transition steps for Activiti workflows if the steps are stored as constraints in the content model. On a past client project we implemented a Share-based customization to localize constraint list items but our approach won’t work in Explorer. Maybe the Activiti guys can help me out on that one.

Exposing Process to the Alfresco User Interface

And that brings us to user interface configuration. Overall, the process is exactly the same. First, you work on your process definition, then you create a workflow content model. Once the workflow content model is in place, you expose it to the user interface through the normal Alfresco user interface configuration approach. For the Explorer client that means web-client-config-custom. For the Share client that means share-config-custom. Labels, workflow titles, and workflow descriptions are localized via properties bundles.

One minor difference is that in jBPM, task names are identical to corresponding type names in your workflow content model. In Activiti, a userTask has an attribute called “activiti:formKey” that is used to map the task to the appropriate content type in the workflow content model.

Assigning Tasks to Users and Groups

The out-of-the-box workflows for both jBPM and Activiti show how to use pickers to let workflow initiators assign users and groups to workflows. My example workflows use hardcoded references rather than pickers so that you’ll have an example of both approaches. In my Hello World examples, I assign the userTask to the workflow initiator. This is done by using the “activiti:assignee” attribute on userTask, like this:

<userTask id="usertask3" name="User Task" activiti:assignee="${initiator.properties.userName}" activiti:formKey="bpm:task">

If you need to use a more complex expression there’s a longer form that uses a “humanPerformer” tag. See the User Guide.

In the Publish Whitepaper example I use pooled group assignment by using the “activiti:candidateGroups” attribute on userTask, like this:

<userTask id="usertask7" name="Operations Review" activiti:candidateGroups="GROUP_Operations" activiti:formKey="scwf:activitiOperationsReview">

Again, if you need to, there’s a longer form that uses a “potentialOwner” tag.

In my jBPM examples I use swimlanes for task assignment. I didn’t get a chance to use the equivalent in Activiti.

Deploying Processes

In standalone Activiti there are multiple options for deploying process definitions to the engine, including uploading a BAR (Business Archive) file into the running engine. I couldn’t find the equivalent of that in Alfresco’s embedded Activiti implementation or the equivalent of the jBPM deployer servlet, so for this exercise I used Spring configuration for both Activiti and jBPM processes. I hope by the time the code goes into Enterprise there will be a dynamic deployment option because that’s really helpful during development.

Workflow Console

Alfresco’s workflow console is a critical tool for anyone doing anything with advanced workflow. It has always been a puzzle to me as to why the workflow console (along with others) can only be navigated to directly using an unpublished URL. That head-scratcher still remains, but rest assured, all of your favorite console commands now work for both jBPM and Activiti workflows.

Summary

I hope this post has given you a small taste of the new Activiti engine embedded in Alfresco. I haven’t spent any time talking about the higher level benefits to Activiti. And there are many more details and features I didn’t have time to go into. My goal was to give all of you who have experience with Alfresco jBPM some start at getting your head around the new option for advanced workflow.

If you haven’t done so, grab a copy of Alfresco 3.4.e, download these examples, and play around. The zip is an Eclipse project that will deploy the workflows and associated configuration to your Alfresco and Share web applications via ant. The included readme file has step-by-step directions for running through each jBPM and Activiti example.

It is entirely possible that I’ve done something boneheaded. If so, do let me know so that all of us can benefit.

Resources

33 comments

  1. As this is an early preview, I guess there are still things to come for the final Activiti implementation. What I would like to see is a more user friendly Workflow console, something where an admin easily can monitor ongoing workflows, and cancel and delete if needed. That is to hard today, most (many?) admins wont be die hard terminal type of guys.

    Also, to me, what happens in a workflow is part of your business records. You may add notes there, and who made what decision and so on. Once a workflow is completed, there is no way from a document navigate to the workflows a document has been part of, and audit your business records. It hides itself in a big unknown. I now it is still there (from the not so easy to use workflow console) but should be more accessible. You can of course implement your wf so that it is recorded in metadata, or store an outcome history record file as a subnode to your doc, or similar. Still, the workflows need to be readily available once completed.

    Anyway, thanks for the activiti intro write-up.
    (but the code download link doesn’t work)

  2. Jeff,

    First of all, thanks for the very good and complete blog-post about the activiti integration. Since Gavin, Nick and myself did the actual Activiti integration into Alfresco, I’m more than happy to clarify some bits and pieces:

    About the transitions on activiti-workflows, they do support rendering 2 buttons (eg. Approve, Reject) instead of the dropdown in Share UI. You can use a special property on your task-definition to indicate which property is actually a decision. The review and approve example shipped with alfresco shows how this is done.

    About the l12n of the labels of the “transitions”. Since the buttons are based on a property with a list-constraint, we’re kinda stuck with the limitation that list-constraint values aren’t localizable. As you mentioned, activiti (and BPMN 2.0) has no notion of different transitions from one node to different paths and we didn’t want to make up a new mechanism for describing the possible “transitions” -> thats why we chose to use a list-constraint for this.

    An issue is raised for the script-task you mentioned. When fixed, you’ll be able to use an automated step (serviceTask) inside your process, which runs your script against ScriptService.

    For deploying processes to alfresco’s activiti engine, Activiti Probe (or similar management app) can be used in the future on alfresco.

    Thanks again for the blog-post, hope to read more posts on this topic 😉

  3. Igor Blanco says:

    Hi Jeff,

    Interesting article to get in touch with AlfrescoActiviti integration. It would be great if the activity modeler could be integrated also.

    There seems to be a problem with the link to the code, the zip is not found.

    Thanks.

  4. Shaun Davey says:

    Jeff,

    A great article – I was planning to try this out over the weekend so thanks for the headstart!!

    Just one thing, the code link is coming back with a file not found error..?

    From my limited experience of these tools (Global360/Pega/Lombardi) a raw BPMS would be very much in the driving seat, feeding and pulling data in and out of other applications i.e web services, databases, rules engines and EDRMS and acting as single point of co-ordination.

    With that in mind where do you see activiti being positioned in the long term – some of the tools in Activiti i.e Kickstart would be great in Alfresco too, but the notion of a BPMS suggests that it’s scope and so management consoles etc would have to encompass more than just its Alfresco interactions?

    Your thoughts?

  5. jpotts says:

    Peter,

    I agree with what I’d call a “workflow dashboard” requirement. Standalone Activiti actually does a pretty good job of this. Maybe some of it will make it into the embedded version.

    I also agree that it needs to be easier to capture historical data without adding a bunch of stuff into your process definition.

    The code download link works now.

    Jeff

  6. jpotts says:

    Igor,

    That would be cool. The standalone Activiti has a web-based modeler. It would be nice to see that in Alfresco as well. Not just for modeling but also for showing a visualization to end-users of where they are in the process.

    Jeff

  7. jpotts says:

    Shaun,

    I’ll let the Activiti product team chime in on that one, but my hunch is that the primary use case for Activiti embedded in Alfresco is for human-centric business processes related to collaborating on content stored in the Alfresco repository and not for other types of processes. Yes, your Alfresco Activiti workflows will interact with other systems but I don’t think the intent is to use Alfresco’s version of Activiti to coordinate processes that have nothing to do with Alfresco content.

    A standalone install of Activiti could do that and it could also interact with content in one or more Alfresco repositories. Additionally, a standalone Activiti can scale independently of the repository, which is important when you start thinking of it in terms of those other systems you mentioned. At least in the short-term, the Activiti embedded within Alfresco runs in the same JVM as the repository.

    Jeff

  8. Jörg Sauer says:

    Hi Jeff, great review. I haven’t found the time to dig into it yet. What I wonder if Alfresco allowes folders to be attached to a workflow by now.

    I raised this at DEV CON Paris and the Activity guys grinned and promissed to address this.

    I have done some customizations to Alfresco to allow this, but this is just kind of a workaround and does not work through all of the use cases…

    Maybe we all should put some pressure on this as well.

    Thanks again for the review.
    Jörg

  9. Tijs Rademakers says:

    Hi Jeff,

    Great article.
    I’ve one comment on the refresh problem with the Activiti Designer. This problem only occurs when you are using the latest Eclipse version (3.6.2) and works fine with 3.6.1. This is due to a problem in the Eclipse MultiPageEditor of 3.6.2 and there’s an issue in the Eclipse JIRA for this. So when using the previous version of Eclipse (3.6.2) this should work fine.

    Best regards,

    Tijs

  10. Elmo says:

    Hi Jeff,

    thank you for this great article that provided us with brief introduction with Activiti integration.

    I would like to ask you few questions regarding future of workflows in Alfresco.
    After Activiti is fully integrated in both community and enterprise versions of Alfresco is there a plan to keep supporting jBPM or is it going to be replaced by Activiti? Quote from Alfresco press release “The replacement of jBPM with Activiti in Alfresco is just the beginning.”

    Also, is jBPM 5.0 supported in current version of Alfresco?

    Best regards,
    Elmo

  11. jpotts says:

    In the preview release of Community that includes Activiti (3.4.e), both engines sit side-by-side. I am not a product manager, but I think it is safe to assume that will be the case in the first Enterprise release that includes Activiti. I honestly don’t know what the plan is going forward, but I assume they will both continue to be offered for a time because there are a lot of workflows out there that will need to be migrated.

    Alfresco embeds jBPM 3 in the latest Community and Enterprise releases. All of the workflow-related efforts are around Activiti, so I would assume that an upgrade of jBPM will not be forthcoming.

    Again, these statements are completely unofficial. I’ll see if anyone on the product side wants to comment further. I think we’ll be having a webinar on Activiti at some point in the near future and these would be great questions to ask there.

    Jeff

  12. jpotts says:

    Elmo,

    Just talked to Tom Baeyens and Paul Holmes-Higgin, the VP of Engineering. They say that jBPM will continue to be supported in the foreseeable future.

    Jeff

  13. jpotts says:

    I think we discussed this in IRC and in the forums. The issue is that the Share form config wasn’t deployed to the Share WAR, which meant that when you tried to manage the workflow task, there were some fields being shown that shouldn’t be and some that should be there were missing.

    The sample project in the blog post will work on 3.4.e if you run “ant deploy” which ensures that both the repository tier and the Share tier customizations are deployed appropriately.

    Jeff

  14. mike says:

    Great tutorial and demo! I’ve found these very helpful. I am still confused with the deployment of activiti workflows into alfresco. I’ve written my own workflow and attempted to add these into your someco-activiti-config-alfresco-extension-workflows-activiti folder and then running ant deploy from the setup file… I was hoping that this would make my additional workflow work like it did yours but I had no luck. The workflow I created is very simple… start->javascript to write “hello” to a file C:\test\test.txt”-> finish.

    Have you discovered how to deploy .bar files? and also, can you explain to me how I could deploy a workflow with access to the .activiti, .bpm20.xml, .png files?

    Thanks so much! keep up the good work

  15. Ayusman says:

    hi,
    I was looking at the activiti user guide and did not see a section that describes how to use activiti as a standalone java program.

    I have used jbpm 4 as a standalone java program and it runs fine. It was a lot of tweaking, but I can run jbpm 4.4 as a java program without any container (tomcat/jboss or otherwise)..

    Could you please point me to where this information is available?

    Thanks,
    Ayusman

  16. Ayusman says:

    @Jeff
    Where do I see the standalone deployment of activiti?
    This is just the home page of activiti BPM; this does not talk about the specific question I was asking. Can you help?

  17. jpotts says:

    Maybe I’m misunderstanding what you are looking for. If you go to that page and click on “Download Activiti Now” you are downloading the standalone Activiti engine. You can then click on 10 Minute Tutorial and walk through those steps which shows you how to create a process and deploy it to the standalone process engine. In short, nothing on Activiti.org is Alfresco-specific. It all has to do with the standalone Activiti engine. So I think everything you need is in the download, the docs, and the forum on that site.

    Jeff

  18. Ayusman says:

    @Jeff
    Thanks a lot.
    I get it now. The reference to the demo setup just before the standalone setup was confusing me. Now it’s OK. I can see the standalone part clearly and of course it is fairly (well almost) similar to jbpm4.4 setup 🙂

  19. Susan says:

    I am working with 4.0 Community and the Activi workflow console is not available. The wiki for the 4.0 release specifically includes an icon that reads ‘Enterprise only’. I take it to mean this tool was not released with the 4.0 Community version?

    Will this be available for Community users in the future? Just curious as I’m learning the ropes and would like to give this a try …

    Wiki link: http://docs.alfresco.com/4.0/index.jsp?topic=%2Fcom.alfresco.enterprise.doc%2Ftasks%2Fadminconsole-workflow-activiti-console.html

  20. jpotts says:

    Correct, the Activiti Workflow Console is not currently available in Community. We would like to get it added and are working toward doing that, but I don’t have a date to give you when you could expect it.

    The Alfresco Explorer-based workflow console, which is at http://localhost:8080/alfresco/faces/jsp/admin/workflow-console.jsp, does work with both jBPM and Activiti in both Community and Enterprise.

    By the way, stay tuned to this blog. I should have my old jBPM based Advanced Workflows tutorial updated for Activiti and Share published in the next week or so.

    Jeff

  21. David Keith says:

    For those looking to increase your understanding of the VAST flexibiity of Activiti, check out Activiti In Action (Manning Publications). It’s currently under the MEAP program (Manning Early Access Program). The book is still being developed, but much of it is already available as a Manning MEAP.
    Excellent book, awesome software.

  22. nikhil says:

    I have one task but don’t have any idea and struck in the starting of the task.The question is
    Can we publish custom task in ACTIVITI FLOW ??

  23. jpotts says:

    Yes, you can have custom tasks in Activiti business processes. If you are having trouble starting your workflow, I’d suggest turning on debug by setting log4j.logger.org.alfresco.repo.workflow to DEBUG in $TOMCAT_HOME/webapps/alfresco/WEB-INF/classes/log4j.properties.

  24. Guillermo Velasquez says:

    Hi Jeff, I’m working with Alfresco and Activiti developing an advanced workflow using your document “Alfresco Developer Series Advanced Workflows” and I have some difficulties, I first want to know how I can put three buttons on a task, this tasks take me to three different tasks and second as I can customize the name of these buttons. Thank you very much in advance. I work at a software consulting company in Peru.

  25. Rutaveej Shah says:

    Hi jeff !
    I am want to create a hierarchy based workflow.
    Means if i am sending you a document than if you approve the document than it should come to some another one and propagate as per hierarchy define.
    I am using activiti engine for creating Workflow.
    If you have any idea on this please reply as early as possible.

  26. jpotts says:

    Rutaveej,

    Put your logic into one or more Java classes. Your code can look up the hierarchy in LDAP or or a database or through some arbitrary service. Then you code can spawn one task for every person in the hierarchy.

    Without specifics on what you’ve tried so far or what you are struggling with, it is hard for me to be more specific than that.

    Jeff

  27. I’m trying helloWorldUI, but I’m receiving this error:
    org.activiti.engine.ActivitiException: Exception while invoking TaskListener: org.alfresco.repo.workflow.activiti.listener.ScriptExecutionListener doesn’t implement interface org.activiti.engine.delegate.TaskListener

    I’m using Alfresco 4.2f and the bpmn process is the same HelloWorldUI.bpmn that I found in your tutorial here:
    https://ecmarchitect.com/alfresco-developer-series-tutorials/workflow/tutorial/tutorial.html

  28. Jeff Potts says:

    Luca,

    Thanks for reading the tutorial and for your question.

    I suspect that you may not have used the Alfresco Script Task from the palette. When you use an Alfresco Script Task, Activiti expects your script to be in a serviceTask that has a class like this: activiti:class=”org.alfresco.repo.workflow.activiti.script.AlfrescoScriptDelegate”.

    The other scripts in that section are on taskListeners and they have a class like this: class=”org.alfresco.repo.workflow.activiti.tasklistener.ScriptTaskListener”

    So check to make sure that your three logic sections in that step are all using the appropriate task type and class.

    Jeff

  29. Hi Jeff,
    thank you for your quick response, but I was probably using an old wrong deployed version of the workflow. I cleaned up through the workflow console (show workflows all; delete workflow activiti$331; deploy activiti path-to-workflow). Now it works!

Comments are closed.