geekQ workflow library

What is workflow?

Workflow is a finite-state-machine-inspired API for modeling and interacting with what we tend to refer to as ‘workflow’.

A lot of business modeling tends to involve workflow-like concepts, and the aim of this library is to make the expression of these concepts as clear as possible, using similar terminology as found in state machine theory.

So, a workflow has a state. It can only be in one state at a time. When a workflow changes state, we call that a transition. Transitions occur on an event, so events cause transitions to occur. Additionally, when an event fires, other arbitrary code can be executed, we call those actions. So any given state has a bunch of events, any event in a state causes a transition to another state and potentially causes code to be executed (an action). We can hook into states when they are entered, and exited from, and we can cause transitions to fail (guards), and we can hook in to every transition that occurs ever for whatever reason we can come up with.

Now, all that’s a mouthful, but we’ll demonstrate the API bit by bit with a real-ish world example.

Let’s say we’re modeling article submission from journalists. An article is written, then submitted. When it’s submitted, it’s awaiting review. Someone reviews the article, and then either accepts or rejects it. Here is the expression of this workflow using the API:

class Article
  include Workflow
  workflow do
    state :new do
      event :submit, :transitions_to => :awaiting_review
    end
    state :awaiting_review do
      event :review, :transitions_to => :being_reviewed
    end
    state :being_reviewed do
      event :accept, :transitions_to => :accepted
      event :reject, :transitions_to => :rejected
    end
    state :accepted
    state :rejected
  end
end

Nice, isn’t it!

Note: the first state in the definition (:new in the example, but you can name it as you wish) is used as the initial state - newly created objects start their life cycle in that state.

Let’s create an article instance and check in which state it is:

article = Article.new
article.accepted? # => false
article.new? # => true

You can also access the whole current_state object including the list of possible events and other meta information:

article.current_state 
=> #<Workflow::State:0x7f1e3d6731f0 @events={
  :submit=>#<Workflow::Event:0x7f1e3d6730d8 @action=nil, 
    @transitions_to=:awaiting_review, @name=:submit, @meta={}>}, 
  name:new, meta{}

Now we can call the submit event, which transitions to the :awaiting_review state:

article.submit!
article.awaiting_review? # => true

Events are actually instance methods on a workflow, and depending on the state you’re in, you’ll have a different set of events used to transition to other states.

It is also easy to check, if a certain transition is possible from the current state . article.can_submit? checks if there is a :submit event (transition) defined for the current state.

Installation

gem install workflow

Alternatively you can just download the lib/workflow.rb and put it in the lib folder of your Rails or Ruby application.

Ruby 1.9

Workflow gem does not work with some (but very widespread) Ruby 1.9 builds due to a known bug in Ruby 1.9. Either

use newer ruby build, 1.9.2-p136 and -p180 tested to work
or compile your Ruby 1.9 from source
or comment out some lines in workflow (reduces functionality).

Examples

After installation or downloading of the library you can easily try out all the example code from this README in irb.

$ irb
require 'rubygems'
require 'workflow'

Now just copy and paste the source code from the beginning of this README file snippet by snippet and observe the output.

Transition event handler

The best way is to use convention over configuration and to define a method with the same name as the event. Then it is automatically invoked when event is raised. For the Article workflow defined earlier it would be:

class Article
  def reject
    puts 'sending email to the author explaining the reason...'
  end
end

article.review!; article.reject! will cause a state transition, persist the new state (if integrated with ActiveRecord) and invoke this user defined reject method.

You can also define event handler accepting/requiring additional arguments:

class Article
  def review(reviewer = '')
    puts "[#{reviewer}] is now reviewing the article"
  end
end

article2 = Article.new
article2.submit!
article2.review!('Homer Simpson') # => [Homer Simpson] is now reviewing the article

The old, deprecated way

The old way, using a block is still supported but deprecated:

event :review, :transitions_to => :being_reviewed do |reviewer|
  # store the reviewer
end

We’ve noticed, that mixing the list of events and states with the blocks invoked for particular transitions leads to a bumpy and poorly readable code due to a deep nesting. We tried (and dismissed) lambdas for this. Eventually we decided to invoke an optional user defined callback method with the same name as the event (convention over configuration) as explained before.

Integration with ActiveRecord

Workflow library can handle the state persistence fully automatically. You only need to define a string field on the table called workflow_state and include the workflow mixin in your model class as usual:

class Order < ActiveRecord::Base
  include Workflow
  workflow do
    # list states and transitions here
  end
end

On a database record loading all the state check methods e.g. article.state, article.awaiting_review? are immediately available. For new records or if the workflow_state field is not set the state defaults to the first state declared in the workflow specification. In our example it is :new, so Article.new.new? returns true and Article.new.approved? returns false.

At the end of a successful state transition like article.approve! the new state is immediately saved in the database.

You can change this behaviour by overriding persist_workflow_state method.

Custom workflow database column

meuble contributed a solution for using custom persistence column easily, e.g. for a legacy database schema:

class LegacyOrder < ActiveRecord::Base
  include Workflow
  
  workflow_column :foo_bar # use this legacy database column for
                           # persistence
end

Single table inheritance

Single table inheritance is also supported. Descendant classes can either inherit the workflow definition from the parent or override with its own definition.

Custom workflow state persistence

If you do not use a relational database and ActiveRecord, you can still integrate the workflow very easily. To implement persistence you just need to override load_workflow_state and persist_workflow_state(new_value) methods. Next section contains an example for using CouchDB, a document oriented database.

Tim Lossen implemented support for remodel / redis key-value store.

Integration with CouchDB

We are using the compact couchtiny library here. But the implementation would look similar for the popular couchrest library.

require 'couchtiny'
require 'couchtiny/document'
require 'workflow'

class User < CouchTiny::Document
  include Workflow
  workflow do
    state :submitted do
      event :activate_via_link, :transitions_to => :proved_email
    end
    state :proved_email
  end

  def load_workflow_state
    self[:workflow_state]
  end

  def persist_workflow_state(new_value)
    self[:workflow_state] = new_value
    save!
  end
end

Please also have a look at the full source code.

Integration with Mongoid

You can integrate with Mongoid following the example above for CouchDB, but there is a gem that does that for you (and includes extensive tests): workflow_on_mongoid

Accessing your workflow specification

You can easily reflect on workflow specification programmatically - for the whole class or for the current object. Examples:

article2.current_state.events # lists possible events from here
article2.current_state.events[:reject].transitions_to # => :rejected

Article.workflow_spec.states.keys
#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]

Article.workflow_spec.state_names
#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]

# list all events for all states
Article.workflow_spec.states.values.collect &:events

You can also store and later retrieve additional meta data for every state and every event:

class MyProcess
  include Workflow
  workflow do
    state :main, :meta => {:importance => 8}
    state :supplemental, :meta => {:importance => 1}
  end
end
puts MyProcess.workflow_spec.states[:supplemental].meta[:importance] # => 1

The workflow library itself uses this feature to tweak the graphical representation of the workflow. See below.

Advanced transition hooks

on_entry/on_exit

We already had a look at the declaring callbacks for particular workflow events. If you would like to react to all transitions to/from the same state in the same way you can use the on_entry/on_exit hooks. You can either define it with a block inside the workflow definition or through naming convention, e.g. for the state :pending just define the method on_pending_exit(new_state, event, *args) somewhere in your class.

on_transition

If you want to be informed about everything happening everywhere, e.g. for logging then you can use the universal on_transition hook:

workflow do
  state :one do
    event :increment, :transitions_to => :two
  end
  state :two
  on_transition do |from, to, triggering_event, *event_args|
    Log.info "#{from} -> #{to}"
  end
end

Please also have a look at the advanced end to end example.

Guards

If you want to halt the transition conditionally, you can just raise an exception in your transition event handler. There is a helper called halt!, which raises the Workflow::TransitionHalted exception. You can provide an additional halted_because parameter.

def reject(reason)
  halt! 'We do not reject articles unless the reason is important' \
    unless reason =~ /important/i
end

The traditional halt (without the exclamation mark) is still supported too. This just prevents the state change without raising an exception.

You can check halted? and halted_because values later.

Hook order

The whole event sequence is as follows:

* before_transition
* event specific action
* on_transition (if action did not halt)
* on_exit
* PERSIST WORKFLOW STATE, i.e. transition
* on_entry
* after_transition

Multiple Workflows

I am frequently asked if it’s possible to represent multiple “workflows” in an ActiveRecord class.

The solution depends on your business logic and how you want to structure your implementation.

Use Single Table Inheritance

One solution can be to do it on the class level and use a class hierarchy. You can use single table inheritance so there is only single orders table in the database. Read more in the chapter “Single Table Inheritance” of the ActiveRecord documentation. Then you define your different classes:

class Order < ActiveRecord::Base
  include Workflow
end

class SmallOrder < Order
  workflow do
    # workflow definition for small orders goes here
  end
end

class BigOrder < Order
  workflow do
    # workflow for big orders, probably with a longer approval chain
  end
end

Individual workflows for objects

Another solution would be to connect different workflows to object instances via metaclass, e.g.

# Load an object from the database
booking = Booking.find(1234)

# Now define a workflow - exclusively for this object,
# probably depending on some condition or database field
if # some condition
  class << booking
    include Workflow
    workflow do
      state :state1
      state :state2
    end
  end
# if some other condition, use a different workflow

You can also encapsulate this in a class method or even put in some ActiveRecord callback. Please also have a look at the full working example!

Documenting with diagrams

You can generate a graphical representation of your workflow for documentation purposes. S. Workflow::create_workflow_diagram.

Earlier versions

The workflow library was originally written by Ryan Allen.

The version 0.3 was almost completely (including ActiveRecord integration, API for accessing workflow specification, method_missing free implementation) rewritten by Vladimir Dobriakov keeping the original workflow DSL spirit.

Migration from the original Ryan’s library

Credit: Michael (rockrep)

Accessing workflow specification

my_instance.workflow # old
MyClass.workflow_spec # new

Accessing states, events, meta, e.g.

my_instance.workflow.states(:some_state).events(:some_event).meta[:some_meta_tag] # old
MyClass.workflow_spec.states[:some_state].events[:some_event].meta[:some_meta_tag] # new

Causing state transitions

my_instance.workflow.my_event # old
my_instance.my_event! # new

when using both a block and a callback method for an event, the block executes prior to the callback

Changelog

New in the version 0.8.0

check if a certain transition possible from the current state with can_....?
fix workflow_state persistence for multiple_workflows example
add before_transition and after_transition hooks as suggested by kasperbn

New in the version 0.7.0

fix issue#10 Workflow::create_workflow_diagram documentation and path escaping
fix issue#7 workflow_column does not work STI (single table inheritance) ActiveRecord models
fix issue#5 Diagram generation fails for models in modules

New in the version 0.6.0

enable multiple workflows by connecting workflow to object instances (using metaclass) instead of connecting to a class, s. “Multiple Workflows” section

New in the version 0.5.0

fix issue#3 change the behaviour of halt! to immediately raise an exception. See also http://github.com/geekq/workflow/issues/#issue/3

New in the version 0.4.0

completely rewritten the documentation to match my branch
switch to jeweler for building gems
use gemcutter for gem distribution
every described feature is backed up by an automated test

New in the version 0.3.0

Intermixing of transition graph definition (states, transitions) on the one side and implementation of the actions on the other side for a bigger state machine can introduce clutter.

To reduce this clutter it is now possible to use state entry- and exit- hooks defined through a naming convention. For example, if there is a state :pending, then instead of using a block:

state :pending do
  on_entry do
    # your implementation here
  end
end

you can hook in by defining method

def on_pending_exit(new_state, event, *args)
  # your implementation here
end

anywhere in your class. You can also use a simpler function signature like def on_pending_exit(*args) if your are not interested in arguments. Please note: def on_pending_exit() with an empty list would not work.

If both a function with a name according to naming convention and the on_entry/on_exit block are given, then only on_entry/on_exit block is used.

Support

Reporting bugs

http://github.com/geekq/workflow/issues

About

Author: Vladimir Dobriakov, http://www.innoq.com/blog/vd, http://blog.geekq.net/

Based on the work of Ryan Allen and Scott Barron

Licensed under MIT license, see the MIT-LICENSE file.

workflow gem