10 minute guide Activiti improvements

Technology adoption is a tricky business. I think Hibernate and Spring were successful in a large part due to their abundance of documentation and example code.

Activiti has fairly decent documentation at least from a reference standpoint. It could use some more high-level descriptions (like where the different pieces run). I was able to figure some of this out through trial and error and from a variety of resources on the web (I plan on documenting them in a future blog post 0-60 undestanding what Activiti is or something of the ilk.)

One thing that I feel Activiti lacks is a good getting started tutorial that covers some basic usages. They have a 10 minute guide that drops the user in the middle of using Activiti. It shows them using classes that they did not instantiate that somehow magically show up. Keep in mind that this 10 minute guide is on page 20 of a 93 page document (as of 2/3/2011). It is an exercise for the user to go through the previous 19 pages and guess which combination of options will get them a working example.

My point being that the tutorial should be closer to the front of the document and it should describe in detail how to get things running. Don't show references to classes we did not instantiate.

At this point, you may think, why didn't you just look at the sample code. Well the sample code was all based on unit tests. Also, the sample code was more like a test suite than true getting started examples. It is good to look at test suites when you are trying to learn things or get to the next level, but it does not make sense for samples when you are just starting out.

I say this because I think Activiti is a good project and it deserves to be successful. This is not criticism out of hatred but criticism out of fondness and a wish for continued success and wider adoption.

I was able to get things working by posting on the forums (and getting answers), reading blogs and watching slide decks and videos. The information is out there, but it really belongs in the Activiti user manual.

I wanted the 10 minute guide to show me how to run a workflow standalone and as part of the Activiti system, i.e., toolable via the activiti-modeler, activiti-probe, activiti-cycle, etc.

To create a working pom file, I used one of the example pom files as a basis. Later, I found that I could also use the Activiti Eclipse Plugin to generate an activiti project, then you just run mvn eclipse:eclipse to configure the .classpath and .project for Eclipse. (I will show the pom at the end.)

Here is the complete Java source for a working example based on the one in the 10 minute guide.

package com.demo;
package com.demo;

import java.util.List;

import org.activiti.engine.ProcessEngine;
import org.activiti.engine.ProcessEngineConfiguration;
import org.activiti.engine.task.Task;

public class Demo {

    public static void main(String[] args) {
        // Process engine that is standalone in memory. Good for testing and
        // trying out examples.
        // ProcessEngine processEngine =
        // ProcessEngineConfiguration.createStandaloneInMemProcessEngineConfiguration()
        // .setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_FALSE)
        // .setJdbcUrl("jdbc:h2:mem:my-own-db;DB_CLOSE_DELAY=1000")
        // .setDatabaseSchemaUpdate("create-drop")
        // .setJobExecutorActivate(true)
        // .buildProcessEngine();

        // Process engine that will work with the way they deploy Activiti with
        // the demo
        ProcessEngine processEngine = ProcessEngineConfiguration
                .createStandaloneProcessEngineConfiguration()
                .buildProcessEngine();

        // Deploy the xml file that contains the process flow.
        processEngine.getRepositoryService().createDeployment()
                .addClasspathResource("com/demo/demo-flow.bpmn20.xml").deploy();

        // Start the process by id.
        processEngine.getRuntimeService().startProcessInstanceByKey(
                "financialReport2");

        List tasks = processEngine.getTaskService().createTaskQuery()
                .taskCandidateUser("fozzie").list();

        System.out.println("Got some tasks for fozzie" + tasks + "\n");
        for (Task task : tasks) {
            System.out.println(task.getId());
        }

        Task task = tasks.get(0);
        System.out.println(task.getName());

        processEngine.getTaskService().claim(task.getId(), "fozzie");
        // do some work
        processEngine.getTaskService().complete(task.getId());
        System.out.println("Done");

        tasks = processEngine.getTaskService().createTaskQuery()
                .taskCandidateUser("fozzie").list();

        System.out.println("Looking for some tasks for kermit" + tasks + "\n");
        tasks = processEngine.getTaskService().createTaskQuery()
                .taskCandidateUser("kermit").list();

        System.out.println("Got some tasks for kermit" + tasks + "\n");
        for (Task t : tasks) {
            System.out.println(t.getId());
            System.out.println(t.getName());
            // claim it and complete it
            processEngine.getTaskService().claim(t.getId(), "kermit");
            processEngine.getTaskService().complete(t.getId());
        }

    }

}

I believe the 10 minute guide does a fairly good explanation of what the various steps do.

The working process XML ("com/demo/demo-flow.bpmn20.xml") is as follows:

NOTE: The actual XML is slightly different than what I have below. The syntax highlighter chews it up. To see the actual XML do a view source on this page and search for XXJJ.

 

  
  
    
  
    
  
    
      Write monthly financial report for publication to shareholders.
    
    
      
        accountancy
      
    
  
    
  
      
  
    
      Verify monthly financial report composed by the accountancy department.
      This financial report is going to be sent to all the company shareholders.  
    
    
      
        management
      
    
  
    
  
      
  
      

The XML in the guide was short a few elements. This could be mitigated if they ship with the 10 minute guide example.

Lastly, here is the pom.xml file (if you don't know what a pom.xml file is, then read a getting started with maven2 guide).

  4.0.0

  Activiti Engine Examples
  BPM and workflow engine
  org.activiti
  activiti-engine-examples

  jar
  1.0

  
  
    
      org.activiti
      activiti-engine
      5.1
    
    
    
      junit
      junit
      4.8.1
      test
    
    
      com.h2database
      h2
      1.2.132
      test
    
    
    
      org.subethamail
      subethasmtp-wiser
      1.2
      test
    
    
  

  
    
      alfresco
      http://maven.alfresco.com/nexus/content/groups/public
    
    
        Activiti third party
        http://maven.alfresco.com/nexus/content/repositories/activiti-thirdparty/
     
    
      spring-extensions-milestone
      Spring Extensions Milestone Repository
      http://extensions.springframework.org/milestone
    
  

  
    
      maven2.java.net
      Java.net Repository for Maven 2
      http://download.java.net/maven/2/
    
  

  
    
      src/test/resources
      src/main/process
    
    
      
        maven-compiler-plugin
        
          1.5
          1.5
          true
          true
          true
        
      
      
        maven-surefire-plugin
        
          false
          false
          true
          
            **/*TestCase.java
          
        
      
    
  

  
    
      Apache v2
      http://www.apache.org/licenses/LICENSE-2.0.html
    
  

Happy Hunting!