= Workflow

=== THIS COPY IS UNMAINTAINED: LINK TO ACTIVE FORK!

Hello! This copy of Workflow isn’t currently being maintained. The active fork is located here:

http://github.com/geekq/workflow/tree/master

Cheers!

=== MAILING LIST!

Hi! We’ve now got a mailing list to talk about Workflow, and that’s good! Come visit and post your problems or ideas or anything!!!

http://groups.google.com/group/ruby-workflow

See you there!

=== 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 random 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. Explaining all that is a pain in the arse. Here is the expression of this workflow using the API:

Workflow.specify ‘Article 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

Much better, isn’t it!

The initial state is :new – in this example that’s somewhat meaningless. (?) However, the :submit event :transitions_to => :being_reviewed. So, lets instantiate an instance of this Workflow:

workflow = Workflow.new(‘Article Workflow’)
workflow.state # => :new

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

workflow.submit
workflow.state # => :awaiting_review

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.

Given this workflow is now :awaiting_approval, we have a :review event, that we call when someone begins to review the article, which puts the workflow into the :being_reviewed state.

States can also be queried via predicates for convenience like so:

workflow = Workflow.new(‘Article Workflow’)
workflow.new? # => true
workflow.awaiting_review? # => false
workflow.submit
workflow.new? # => false
workflow.awaiting_review? # => true

Lets say that the business rule is that only one person can review an article at a time – having a state :being_reviewed allows for doing things like checking which articles are being reviewed, and being able to select from a pool of articles that are awaiting review, etc. (rewrite?)

Now lets say another business rule is that we need to keep track of who is currently reviewing what, how do we do this? We’ll now introduce the concept of an action by rewriting our :review event.

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

By using Ruby blocks we’ve now introduced extra code to be fired when an event is called. The block parameters are treated as method arguments on the event, so, given we have a reference to the reviewer, the event call becomes:

we gots a reviewer

workflow.reivew(reviewer)

OK, so how do we store the reviewer? What is the scope inside that block? Ah, we’ll get to that in a bit. An instance of a workflow isn’t as useful as a workflow bound to an instance of another class. We’ll introduce you to plain old Class integration and ActiveRecord integration later in this document.

So we’ve covered events, states, transitions and actions (as Ruby blocks). Now we’re going to go over some hooks you have access to in a workflow. These are on_exit, on_entry and on_transition.

When states transition, they are entered into, and exited out of, we can hook into this and do fancy junk.

state :being_reviewed do
event :accept, :transitions_to => :accepted
event :reject, :transitions_to => :rejected
on_exit do |new_state, triggering_event, *event_args|
# do something related to coming out of :being_reviewed
end
end

state :accepted do
on_entry do |prior_state, triggering_event, *event_args|
# do something relevant to coming in to :accepted
end
end

Now why don’t we just put this code into an action block? Well, you might not have only one event that transitions into a state, you may have multiple events that transition to a particular state, so by using the on_entry and on_exit hooks you’re guaranteeing that a certain bit of code is executed, regardless what event fires the transition.

Billy Bob the Manager comes to you and says “I need to know EVERYTHING THAT HAPPENS EVERYWHERE AT ANY TIME FOR EVERYTHING”. For whatever reasons you have to record the history of the entire workflow. That’s easy using on_transition.

on_transition do |from, to, triggering_event, *event_args|
# record everything, or something
end

Workflow doesn’t try to tell you how to store your log messages, (but we’d suggest using a *splat and storing that somewhere, and keep your log messages flexible).

Finite state machines have the concept of a guard. The idea is that if a certain set of arbitrary conditions are not fulfilled, it will halt the transition from one state to another. We haven’t really figured out how to do this, and we don’t like the idea of going :guard => Proc.new {}, coz that’s a bit lame, so instead we have halt!

The halt! method is the implementation of the guard concept. Let’s take a look.

state :being_reviewed do
event :accept, :transitions_to => :accepted do
halt if true # does not transition to :accepted
end
end

Inline with how ActiveRecord does things, halt! also can be called via halt, which makes the event return false, so you can trap it with if workflow.event instead of using a rescue block. Using halt returns false.

using halt

workflow.state # => :being_reviewed
workflow.accept # => false
workflow.halted? # => true
workflow.state # => :being_reviewed

using halt!

workflow.state # => :being_reviewed
begin
workflow.accept
rescue Workflow::Halted => e
# we gots an exception
end
workflow.halted? # => true
workflow.state # => :being_reviewed

Furthermore, halt! and halt accept an argument, which is the message why the workflow was halted.

state :being_reviewed do
event :accept, :transitions_to => :accepted do
halt ‘coz I said so!’ if true # does not transition to :accepted
end
end

And the API for, like, getting this message, with both halt and halt!:

using halt

workflow.state # => :being_reviewed
workflow.accept # => false
workflow.halted? # => true
workflow.halted_because # => ‘coz I said so!’
workflow.state # => :being_reviewed

using halt!

workflow.state # => :being_reviewed
begin
workflow.accept
rescue Workflow::Halted => e
e.halted_because # => ‘coz I said so!’
end
workflow.halted? # => true
workflow.state # => :being_reviewed

We can reflect off the workflow to (attempt) to automate as much as we can. There are two types of reflection in Workflow - reflection and meta-reflection. We’ll explain the former first.

workflow.states # => [:new, :awaiting_review, :being_reviewed, :accepted, :rejected]
workflow.states(:new).events # => [:submit]
workflow.states(:being_reviewed).events # => [:accept, :reject]
workflow.states(:being_reviewed).events(:accept).transitions_to # => :accepted

Meta-reflection allows you to add further information to your states, events in order to allow you to build whatever interface/controller/etc you require for your application. If reflection were Batman then meta-reflection is Robin, always there to lend a helping hand when Batman just isn’t enough.

state :new, :meta => :ui_widget => :radio_buttons do
event :submit, :meta => :label => ‘Upload…’
end

And as per the last example, getting yo meta is very similar:

workflow.states(:new).meta # => {:ui_widget => :radio_buttons}
workflow.states(:new).meta[:ui_widget] # => :radio_buttons
workflow.states(:new).meta.ui_widget # => :radio_buttons

workflow.states(:new).events(:submit).meta # => {:label => ‘Upload…’}
workflow.states(:new).events(:submit).meta[:label] # => ‘Upload…’
workflow.states(:new).events(:submit).meta.label # => ‘Upload…’

Thankfully, meta responds to each so you can iterate over your values if you’re so inclined.

workflow.states(:new).meta.each { |key, value| puts key, value }

The order of which things are fired when an event are as follows:

• action
• on_transition (if action didn’t halt)
• on_exit
• WORKFLOW STATE CHANGES, i.e. transition
• on_entry

Note that any event arguments are passed by reference, so if you modify action arguments in the action, or any of the hooks, it may affect hooked fired later.

We promised that we’d show you how to integrate workflow with your existing classes and instances, let look.

class Article
include Workflow
workflow do
state :new do
event :submit, :transitions_to => :awaiting_review
end
state :awaiting_review do
event :approve, :transitions_to => :approved
end
state :approved
# …
end
end

article = Article.new
article.state # => :new
article.submit
article.state # => :awaiting_review
article.approve
article.state # => :approved

And as ActiveRecord is all the rage these days, all you need is a string field on the table called “workflow_state”, which is used to store the current state. Workflow handles auto-setting of a state after a find, yet it doesn’t save a record after a transition (though you could make it do this in on_transition).

class Article < ActiveRecord::Base
include Workflow
workflow do
# …
end
end

When integrating with other classes, behind the scenes, Workflow sets up a Proxy to method missing. A probable common error would be to call an event that doesn’t exist, so we catch +NoMethodError+'s and helpfully let you know what available events exist:

class Article
include Workflow
workflow do
state :new do
event :submit, :transitions_to => :awaiting_review
end
state :awaiting_review do
event :approve, :transitions_to => :approved
end
state :approved
# …
end
end

article = Article.new
article.aaaa
NoMethodError: undefined method `aaaa’ for #Article:0xe4e8, conversely, if you were looking to call an event for its workflow, you’re in the :new state, and the available events are [:submit]

So just incase you screw something up (like I did while testing this library), it’ll give you a useful message.

You can blatter existing workflows, by simply opening them up again (similar to how Ruby works!).

Workflow.specify ‘Blatter’ do
state :opened do
event :close, :transitions_to => :closed
end
state :closed
end

workflow = Workflow.new(‘Blatter’)
workflow.close
workflow.state # => :closed
workflow.open # => raises a (nice) NoMethodError exception!

Workflow.specify ‘Blatter’ do
state :closed do
event :open, :transitions_to => :opened
end
end

workflow.open
workflow.state # => :opened

Workflow.specify ‘Blatter’ do
state :open do
event :close, :transitions_to => :jammed # the door is now faulty 😃
end
state :jammed
end

workflow.close
workflow.state # => :jammed

Why can we do this? Well, we needed it for our production app, so there.

And that’s about it. A update to the implementation may allow multiple workflows per instance of a class or ActiveRecord, but we haven’t figured out if that’s required or appropriate.

Ryan Allen, March 2008.