Jenkins : JBPM Plugin

Plugin Information

No information for the plugin 'jbpm' is available. It may have been removed from distribution.

This plugin integrates JBoss JBPM with Hudson. It lets you define your own build, test and release workflows in a graphical designer, and execute them inside Hudson.
It is a work in progress, and no releases have been made yet.

Why a workflow plugin ?

 Hudson already has some workflow features. You can configure that one project should be build automatically after another build has completed. Dependencies between builds are also tracked and this is used by the promotion plugin to automate build promotion. So why do we need a separate workflow plugin ?

Using JBPM has a number of advantages:

  • It is possible to model almost arbitrarily complex workflows using a graphical designer. The graphical representation allows non-developers to reason about and help design processes. It also gives a much better view of the state of a process at runtime. At a glance anyone can get an idea of wat is happening with a build.
  • Workflows can create tasks for human users too, e.g. manual testing or signing off on releases. Before, Hudson had no ability to query the user for information during a build.
  • Workflow definitions not only contain the workflow graph, but also the Java code that performs the actions triggered by the workflow. Both are versioned, whicn enables long-running processes. When new workflows definitions are deployed, existing processes are not affected.
  • Using workflows you can model the entire life of a build. Not only development and automated testing, but also various other stages of validation, release and deployment. Hudson becomes the central hub for information about your build, thanks to integration with other systems like SCM repositories and issue trackers.

Background Information

You can find more information about JBoss JBPM on the JBPM website. The JBPM manual in particular is very useful.

The JBPM plugin is currently not compatible with the trunk (released) version of Hudson. It is developed on a branch, since some additional feature were required in the Hudson core. However it is certainly the intention that all work done on the branch is eventually merged to the trunk.

Staged Release Demo


To demonstrate what the JBPM integration is capable of, I wrote a small demo workflow. It tries to model part of the release process used by the Apache Maven project, as described here.The workflow is the following:

  • Somebody (the release manager) starts the release process by starting the 'release-workflow' build.
  • A first task will get some required information from the user: the release version, and email aliases to send announcement mails to.
  • The release build is executed, but not uploaded to the release repository. Instead the artifacts are put into a staging repository that is served by Hudson.
  • A mail is sent out announcing this staged release, and asking people to vote.
  • Registered users can cast a vote on the Hudson build page.
  • The release is finalized when the release manager completes the 'End Vote' task.
  • The votes are counted, and if the result is positive, then the artifacts in the staging repository are uploaded to the release repository. A mail is also sent to the announcement email address.

Of course a video says more than a thousand words... (I'm working on producing a video with better quality)

Build Promotion Demo (TODO)

This demo will show how you can model complex release and test processes. The workflow is triggered after the software has been released, and will drive both automated and manual testing and promotion of the build.

Setup

Some setup is currently required to start developing and/or running workflows.

  • Check out and build the right branch: https://hudson.dev.java.net/svn/hudson/branches/tom. The jbpm plugin is under plugins/jbpm/jbpm.
  • You need a database. By default the jbpm-plugin uses a MySQL database on localhost with connection url: jdbc:mysql://localhost:3306/jbpm (user/password: jbpm). If you want to change this, modify hibernate.cfg.xml inside the plugin. TODO: this should be a configuration option.
  • When you run the first time, hibernate will create or update the required tables in your database
  • Set your smtp server in jbpm.cfg.xml. TODO: find a way to use the value already configured in Hudson
  • Start Hudson in development mode by running 'mvn hpi:run' in the jbpm plugin directory.
  • Download and install the graphical designer for developing and deploying workflows. This is an Eclipse plugin.
  • Import at least the JBPM plugin and optionally the example workflows.

...

Designing a workflow

 To create a new workflow, create a new project in Eclipse, and add dependencies on the jbpm plugin and any other plugin you want to use in your code. You can then develop your workflow as described in the JBPM documentation. For integration with Hudson, a number of variables and action handlers are available.

  •  When you configured a workflow to start after the completion of a build, both the Run object and the corresponding Job are available as the 'build' and 'project' process variables.
  • The 'hudson' object is always available, referring to the Hudson singleton.
  • To start a build as part of a workflow:
    • create a task node
    • assign the task to actor 'hudson'
    • on the task-create event, execute the hudson.jbpm.workflow.StartProjectActionHandler, and set projectName to the project you want to build
  • To create a human task, you also create a task and then assign it to the user who should perform it. Use the hudson.jbpm.workflow.ProjectMemberAssignmentHandler if the task can be executed by any member of the triggering project. A member is defined here as anyone who has 'configure' permissions on the Hudson project.
  • You can define a form that should be used for displaying a human task:
    • Create a form controller, extending from hudson.jbpm.model.Form. Configure the class name of the form by executing the hudson.jbp.workflow.FormActionHandler on the task-create event.
    • Create side files for your Form, in the usual Stapler way. You can create a start.jelly, inprogress.jelly and/or completed.jelly script that will be shown when the task is in the corresponding state. Alternatively create a form.jelly which is used for any state of the task. Your form controller will be the 'it' object.
    • The default implementations of these form let the user start a task, and then choose between the possible transitions.
    • Implement the handle() method of Form to process the submitted form, and trigger a transition to the next task if needed.

 Deployment

The hudson jbpm plugin interfaces with the graphical designer to allow deploying workflows from Eclipse into Hudson. On the deployment tab of your process, use the host name and port of your Hudson server, with path '/plugin/jbpm/upload/' . Don't forget to check all the classes and resources you want to deploy. Files that are not directly referenced from your process definition will be disabled by default.

Starting a workflow process

The plugin contributes a build publisher. That lets you specify a process that should be started after a build completes. 

Attachments:

staging-workflow.zip (application/zip)
processimage.jpg (image/jpeg)
processimage.jpg (image/jpeg)
staging-release.png (image/png)
staging-release.png (image/png)
test-workflow.png (image/png)