bumbleworks 0.0.4

data/.gitignore

@@ -0,0 +1,2 @@
+coverage
+pkg/*

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format=nested
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+1.9.3-p392

data/.watchr

@@ -0,0 +1,89 @@
+if __FILE__ == $0
+  puts "Run with: watchr #{__FILE__}. \n\nRequired gems: watchr rev"
+  exit 1
+end
+
+# --------------------------------------------------
+# Convenience Methods
+# --------------------------------------------------
+def run(cmd)
+  sleep(2)
+  puts("%s %s [%s]" % ["|\n" * 5 , cmd , Time.now.to_s])
+  $last_test = cmd
+  system(cmd)
+end
+
+def run_all_specs
+  tags = "--tag #{ARGV[1]}" if ARGV[1]
+  run "bundle exec rake -s spec SPEC_OPTS='--order rand #{tags.to_s}'"
+end
+
+def run_last_test
+  run($last_test)
+end
+
+def run_single_spec *spec
+  tags = "--tag #{ARGV[1]}" if ARGV[1]
+  spec = spec.join(' ')
+  run "bundle exec rspec  #{spec} -d --order rand #{tags}"
+end
+
+def run_specs_with_shared_examples(shared_example_filename, spec_path = 'spec')
+
+  # Returns the names of the shared examples in filename
+  def shared_examples(filename)
+    lines = File.readlines(filename)
+    lines.grep(/shared_examples_for[\s'"]+(.+)['"]\s*[do|\{]/) do |matching_line|
+      $1
+    end
+  end
+
+  # Returns array with filenames of the specs using shared_example
+  def specs_with_shared_example(shared_example, path)
+    command = "grep -lrE 'it_should_behave_like .(#{shared_example}).' #{path}"
+    `#{command}`.split
+  end
+
+  shared_examples(shared_example_filename).each do |shared_example|
+    specs_to_run = specs_with_shared_example(shared_example, spec_path)
+    run_single_spec(specs_to_run) unless specs_to_run.empty?
+  end
+
+end
+
+def run_cucumber_scenario scenario_path
+  if scenario_path !~ /.*\.feature$/
+    scenario_path = $last_scenario
+  end
+  $last_scenario = scenario_path
+  run "bundle exec cucumber #{scenario_path} --tags @dev"
+end
+
+# --------------------------------------------------
+# Watchr Rules
+# --------------------------------------------------
+watch( '^spec/spec_helper\.rb'                    ) {     run_all_specs }
+watch( '^spec/fixtures/sample_app.*\.rb'          ) {     run_last_test }
+watch( '^spec/.*_spec\.rb'                        ) { |m| run_single_spec(m[0]) }
+watch( '^lib/(.*)\.rb'                            ) { |m| run_last_test }
+
+
+# --------------------------------------------------
+# Signal Handling
+# --------------------------------------------------
+# Ctrl-\
+Signal.trap('QUIT') do
+  puts " --- Running all tests ---\n\n"
+  run_all_specs
+end
+
+# Ctrl-T
+Signal.trap('TSTP') do
+  puts " --- Running last test --\n\n"
+  run_cucumber_scenario nil
+end
+
+# Ctrl-C
+Signal.trap('INT') { abort("\n") }
+
+puts "Watching.." 

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in bumbleworks.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,84 @@
+PATH
+  remote: .
+  specs:
+    bumbleworks (0.0.4)
+      ruote
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    blankslate (2.1.2.4)
+    columnize (0.3.6)
+    debugger (1.5.0)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.2.0)
+      debugger-ruby_core_source (~> 1.2.0)
+    debugger-linecache (1.2.0)
+    debugger-ruby_core_source (1.2.0)
+    diff-lcs (1.2.4)
+    file-tail (1.0.12)
+      tins (~> 0.5)
+    multi_json (1.7.3)
+    parslet (1.4.0)
+      blankslate (~> 2.0)
+    rake (10.0.4)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    ruby2ruby (1.3.1)
+      ruby_parser (~> 2.0)
+      sexp_processor (~> 3.0)
+    ruby_parser (2.3.1)
+      sexp_processor (~> 3.0)
+    rufus-cloche (1.0.4)
+      rufus-json (>= 1.0.3)
+    rufus-dollar (1.0.4)
+    rufus-json (1.0.4)
+    rufus-mnemo (1.2.3)
+    rufus-scheduler (2.0.19)
+      tzinfo (>= 0.3.23)
+    rufus-treechecker (1.0.8)
+      ruby_parser (>= 2.0.5)
+    ruote (2.3.0.2)
+      blankslate (= 2.1.2.4)
+      parslet (= 1.4.0)
+      ruby_parser (~> 2.3)
+      rufus-cloche (>= 1.0.2)
+      rufus-dollar (>= 1.0.4)
+      rufus-json (>= 1.0.1)
+      rufus-mnemo (>= 1.2.2)
+      rufus-scheduler (>= 2.0.16)
+      rufus-treechecker (>= 1.0.8)
+      sourcify (= 0.5.0)
+    sexp_processor (3.2.0)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    sourcify (0.5.0)
+      file-tail (>= 1.0.5)
+      ruby2ruby (>= 1.2.5)
+      ruby_parser (>= 2.0.5)
+      sexp_processor (>= 3.0.5)
+    sqlite3 (1.3.7)
+    tins (0.8.0)
+    tzinfo (0.3.37)
+    watchr (0.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bumbleworks!
+  bundler (~> 1.3)
+  debugger
+  rake
+  rspec
+  simplecov
+  sqlite3
+  watchr

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Bumbleworks
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,160 @@
+# Bumbleworks
+
+**NOTE**: This product is still pre-release, and implementation is *not* in sync with documentation yet - hence the pre-release version.  We'll follow [the Semantic Versioning Specification (Semver)](http://semver.org/), so you can assume anything at 0.x.x still has an unstable API.  But we *are* actively developing this.
+
+Bumbleworks is a gem that adds a workflow engine (via [ruote](http://github.com/jmettraux/ruote)) to your Ruby application, and adds tools for task authorization and locking.  It also establishes conventions for easily loading process definitions and registering participant classes based on configurable file locations.
+
+Bumbleworks itself does not include a presentation layer; however, it is easily integrated into your application, and we're working on concocting several examples of how to integrate into different frameworks.
+
+## Installation
+
+If you're using bundler, just add it to your Gemfile:
+
+```ruby
+gem 'bumbleworks'
+```
+
+and then execute:
+
+    $ bundle
+
+Or you can install it yourself using
+
+    $ gem install bumbleworks
+
+## Configuration
+
+### The Process Storage
+
+Bumbleworks uses a dedicated key-value storage for process information; this is where all process instance state is stored.  We consider it a best practice to keep this storage in a separate place from your business information; see Process vs. Business Information for more discussion.
+
+Before you can load process definitions, register participants, and spin up workers in Bumbleworks, you need to configure Bumbleworks's process storage.  Right now, Bumbleworks supports two storage methods - [Redis](http://redis.io/) and [Sequel](http://sequel.rubyforge.org/) (an ORM that itself supports MySQL, Postgres, etc.).
+
+#### Redis
+
+If you want to use Redis:
+
+1. Add the gem to your Gemfile:
+
+  ```ruby
+  gem 'bumbleworks-redis'
+  ```
+
+2. Set Bumbleworks.storage to a Redis instance.  In a configure block, this looks like:
+
+  ```ruby
+  Bumbleworks.configure do |c|
+    c.storage = Redis.new(:host => '127.0.0.1', :db => 0, :thread_safe => true)
+    # ...
+  end
+  ```
+
+#### Sequel
+
+If you want to use Sequel:
+
+1. Add the gem to your Gemfile:
+
+  ```ruby
+  gem 'bumbleworks-sequel'
+  ```
+
+2. Set Bumbleworks.storage to a Sequel database connection.  You can use Sequel.connect for this.  In a configure block, this looks like:
+
+  ```ruby
+  Bumbleworks.configure do |c|
+    c.storage = Sequel.connect('postgres://user:password@host:port/database_name')
+    # ...
+  end
+  ```
+
+### Process Definition Loading
+
+Bumbleworks uses [ruote](http://github.com/jmettraux/ruote), which allows process definitions to be written using a [Ruby DSL](http://ruote.rubyforge.org/definitions.html#ruby).  By default, your process definitions will be loaded from the `lib/process_definitions` directory at `Bumbleworks.root` (see Determining the Root Directory for more info).  This directory can have as many subdirectories as you want, and Bumbleworks will load everything recursively; note, however, that the directory hierarchy doesn't mean anything to Bumbleworks, and is only for your own organization.  The directory is configurable by setting Bumbleworks.definitions_directory:
+
+```ruby
+Bumbleworks.configure do |c|
+  c.definitions_directory = '/absolute/path/to/your/process/definitions/directory'
+  # ...
+end
+```
+
+Note that if you override the default path, you can either specify an absolute path or a relative path - just use a leading slash if you want it to be interpreted as absolute.
+
+## Participant Class Registration
+
+Registering participants with Bumbleworks is done using Bumbleworks.register_participants, which takes a block, and follows [Ruote's #register syntax](http://ruote.rubyforge.org/participants.html#registering).  For example:
+
+```ruby
+Bumbleworks.register_participants do
+  update_status StatusChangerParticipant
+  acquire_lock LockerParticipant, 'action' => 'acquire'
+  release_lock LockerParticipant, 'action' => 'release'
+  notify_applicant ApplicantNotifierParticipant
+end
+```
+
+By default, Bumbleworks will register a "catchall" participant at the end of your participant list, which will catch any workitems not picked up by a participant higher in the list.  Those workitems then fall into ruote's StorageParticipant, from where Bumbleworks will assemble its task queue.
+
+If your app has a `participants` or `app/participants` directory at the root (see Determining the Root Directory), Bumbleworks will require all files in that directory by default before running the `register_participants` block.  You can customize this directory by setting Bumbleworks.participants_directory:
+
+```ruby
+Bumbleworks.configure do |c|
+  c.participants_directory = '/absolute/path/to/your/participant/class/files'
+  # ...
+end
+```
+
+### Determining the Root Directory
+
+By default, Bumbleworks will attempt in several ways to find your root directory.  In the most common cases (Rails, Sinatra, running via Rake), it usually won't have trouble guessing the directory.
+
+## Usage
+
+### Starting Work
+
+Without running a "worker," Bumbleworks won't do anything behind the scenes - no workitems will proceed through their workflow, no schedules will be checked, etc.  To run a worker, you can either set the `autostart_worker` option in configuration, before starting Bumbleworks:
+
+```ruby
+Bumbleworks.configure do |c|
+  # ...
+  # NOTE: NOT RECOMMENDED IN PRODUCTION!
+  c.autostart_worker = true
+end
+
+Bumbleworks.start! # this will now start a worker automatically
+```
+
+... but, while this is handy in development and testing, it's not a good practice to follow in production.  In an actual production environment, you will likely have multiple workers running in their own threads, or even on separate servers.  So the **preferred way** is to do the following (most likely in a Rake task that has your environment loaded):
+
+```ruby
+Bumbleworks.start_worker!
+```
+
+> Strictly speaking, the entire environment doesn't need to be loaded; only Bumbleworks.storage needs to be set before starting a worker.  However, it's best practice to configure Bumbleworks in one place, to ensure you don't get your storage configurations out of sync.
+
+You can run as many workers as you want in parallel, and as long as they're accessing the same storage, no concurrency issues should arise.
+
+### The Task Queue
+
+When a worker encounters an expression that doesn't match a subprocess or a participant, it gets dropped into the storage and waits to be picked up and dealt with.  Using the Bumbleworks::Task class, Bumbleworks makes available any of these items that have a param called "task."  Let's use the following expressions as an example:
+
+```ruby
+concurrence do
+  trombonist :task => 'have_a_little_too_much_fun'
+  admin :task => 'clean_up_after_trombone_quintet'
+  rooster :do => 'something_nice'
+end
+```
+
+If you call Bumbleworks::Task.all, both of the first two will be returned as Task instances - the third one will be ignored.  You can also do:
+
+```ruby
+Bumbleworks::Task.for_role('trombonist') # returns first task
+Bumbleworks::Task.for_role('admin') # returns second task
+Bumbleworks::Task.for_roles(['trombonist', 'admin']) # returns both tasks
+```
+
+Call Bumbleworks::Task#complete to finish a task and proceed to the next expression.
+
+See the Bumbleworks::Task class for more details.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => [:spec]
+
+Rake::TaskManager.record_task_metadata = true

data/bumbleworks.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bumbleworks/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bumbleworks"
+  spec.version       = Bumbleworks::VERSION
+  spec.authors       = ["Maher Hawash", "Ravi Gadad", "Laurie Kemmerer", "David Miller"]
+  spec.email         = ["mhawash@renewfund.com", "ravi@renewfund.com", "laurie@renewfund.com", "dave.miller@renewfund.com"]
+  spec.description   = %q{Bumbleworks adds a workflow engine (via ruote[http://github.com/jmettraux/ruote] to your application.}
+  spec.summary       = %q{Framework around ruote[http://github.com/jmettraux/ruote] workflow engine}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "ruote"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'watchr'
+  spec.add_development_dependency 'debugger'
+  spec.add_development_dependency 'sqlite3'
+  spec.add_development_dependency 'simplecov'
+end

data/doc/GUIDE.md

@@ -0,0 +1,337 @@
+# Bumbleworks
+
+**NOTE**: This product is still pre-release, and implementation is *not* in sync with documentation yet - hence the pre-release version.  We'll follow [the Semantic Versioning Specification (Semver)](http://semver.org/), so you can assume anything at 0.x.x still has an unstable API.  But we *are* actively developing this.
+
+## The Zen Clock
+
+Imagine you just got your MBA.
+
+You've got a friend in Morocco who's inexplicably excited about a new product she's invented - the Zen Clock - and is anxious to get it out of her head and onto the nightstands and wicker end tables of millions of customers.  She's never sold anything bought or processed, or bought anything sold or processed, or processed anything sold, bought, or processed, and neither have you.  Honestly, this is *at best* a risky business move, and at worst your first step towards total emotional and financial collapse, but let's put rationality aside for now.
+
+We've already designed the clock, sourced its parts, built a prototype, and subjected it to a rigorous 2-day testing period (from which the only lingering issue is the Clock's dismal failure at estimating the current time).  We've settled on four models, each one slightly larger and slightly more yellow than the last.
+
+Now let's build a Zen Clock factory.
+
+## The Plan
+
+The first thing you'll need (aside from a deep breath and some Xanax) is a Plan.  The plan will be the blueprint for how we'll set up the assembly line, and what work will actually happen on that line.
+
+Here's a first draft:
+
+#### The Zen Clock Assembly Line Plan
+
+  1. Receive an order
+  2. Place box of parts on conveyor belt
+  3. Make clock
+  4. Ship clock to excited customers
+  5. Receive angry calls
+  6. Go into hiding
+
+Looks great!  But you know what?  We're agile, and extreme, and cross-country-functional, and 2.0, so let's just go ahead and start building our factory - we'll develop it iteratively.
+
+## Our First Bumbleworks App
+
+First, let's start a new [Rails](http://rubyonrails.org) app.  You'll need, um, the Rails gem, and Ruby, and a computer, and.. you know what?  We're just going to assume you've got the Rails gem installed.  If not, [there are places you can go](http://rubyonrails.org/download) to find out how.
+
+> Look, I know you just wrote your own web framework for Ruby, and it uses DCI, and Octagonal Composition, and the Observitating De-executor Pattern from Lowland & Michael's PTTD 7th Edition, and your eyelashes literally pucker in disgust when someone suggests you use "off the shelf software."  But we're still going to use Rails for our tutorial, because we're too good for elitists like you.
+
+### Rails
+
+Do this in a shell:
+
+    $ rails new zen_clock_factory
+    $ cd zen_clock_factory
+
+A bunch of crazy words will show up on your screen, probably in green text against a black background, unless you're lame.  Congratulations!  You know how to copy and paste.
+
+### Adding the Bumbleworks Gem
+
+The first thing we need to do is corrupt our fresh Rails install with the Bumbleworks gem.  Edit `Gemfile` and add:
+
+```ruby
+gem 'bumbleworks'
+```
+
+And then, back in your shell:
+
+    $ bundle install
+
+Once again, your screen will fill up with nonsense words, making you appear esoterically smart.  Men and/or women (choose which one(s) you want to impress) love that.
+
+### Initializing Bumbleworks
+
+Put the following in a `config/initializers/bumbleworks.rb` file:
+
+```ruby
+
+Bumbleworks.configure do |c|
+  c.storage = {}
+  c.autostart_worker = true
+end
+
+Bumbleworks.start!
+```
+
+#### The Bumbleworks Data Store
+
+*What does `c.storage = {}` do?*
+
+It tells Bumbleworks to use a Hash for its process storage.
+
+Bumbleworks needs its own data store, used only for process state.  We'll explore why this is important later, but for now, just accept that Bumbleworks had neglectful parents and is bad at sharing.
+
+Out of the box, Bumbleworks supports three storage types - [Redis](http://redis.io), [Sequel](http://sequel.rubyforge.org), and a simple Ruby Hash.  We're using the latter for now, since it requires no setup.  You would never use the Hash storage type for production - it's in-memory and in-process, so it won't survive a restart and you can't run multiple workers.  But for testing, it's ideal.
+
+#### Auto-starting Workers
+
+*Okay, intelligent pants.  What about `c.autostart_worker = true`?*
+
+In a production environment, your "workers" - Ruby processes that actually run the workflow, stepping through your process definitions and generating task queues, etc. - should be instantiated in separate daemon processes.
+
+To support this best practice, we don't run a worker by default when you call `Bumbleworks.start!`.  This means launching processes won't actually do anything, and you'll slowly succumb to a suffocating despair.  For ease of development and testing, you can set `autostart_worker` to true, which will (surprisingly) automatically start a worker when you call `Bumbleworks.start!`.
+
+## Writing our First Process Definition
+
+Bumbleworks, by default, will load all files in `lib/process_definitions`.  Go ahead and create that directory, and we'll put our first process definition in there.
+
+In Bumbleworks, our plan above (for now, we'll ignore steps 5 and 6, mostly because we're in denial) might look something like the following (save this to `lib/process_definitions/build_zen_clock.rb`):
+
+```ruby
+Bumbleworks.define_process 'build_zen_clock' do
+  make
+  ship
+end
+```
+
+#### Running the Process
+
+Open a rails console:
+
+    $ rails console
+
+And then, at the console prompt:
+
+```ruby
+>> Bumbleworks.launch!('build_zen_clock')
+# => "20130511-0257-rokigiza-kanenaju"
+```
+
+Bumbleworks will return a seemingly random string of characters (assembled by tapping into the collective unconscious and salted with your own Qi) - this is the unique ID for the process instance you just launched.
+
+You did it!  Bumbleworks now has a running instance of the `build_zen_clock` process, though it stopped at the `make` step, since it doesn't know what that means.  Go ahead and exit the rails console.
+
+> Technically, when Bumbleworks encounters the `make` step, it does the following:
+
+> 1. Check to see if it knows about any process definitions named `make`, and if found, launch a subprocess using that definition
+> 1. If no process definition was found, find the first registered participant in the participant list whose regex matches `make`, and if found, send the workitem to an instance of that participant
+> 1. Finally, if neither a definition or participant was found, drop the workitem into the storage participant, where it will have to be fetched and proceeded manually
+
+> In this case, we fell through to the third step, and the workitem was dropped into the storage.  Since we're using a hash, the storage gets cleared when we exit the Rails console, so you don't need to worry about orphaned processes.
+
+Hold on a second, though - where are steps 1 and 2 from our original plan ("Receive an order" and "Place box of parts on conveyor belt")?  Good question!  You're really paying attention, here.  Has anyone ever told you you're very detail-oriented?
+
+## The Lifecycle of a Zen Clock
+
+Let's take a step back, and think about the life cycle of a Zen Clock.  To simplify things (and because we're admittedly not that business-savvy), we're not going to concern ourselves with inventory or volume or anything like that.  We're selling one clock at a time.
+
+### How A Zen Clock is Born
+
+Our bleary-eyed customer (we'll call him Roanoke, after the similarly ill-fated American colony), having stayed awake well past the 11pm news, sees the Zen Clock on an infomercial, and in a fit of bad judgement decides to order one.  He calls the toll free number, gives his information, and his fate is sealed.
+
+A Zen Clock comes into existence the moment someone places an order, even before it is tangible in the physical realm.  How very like a Zen Clock.
+
+### Modeling the Zen Clock
+
+Let's create a class for the Zen Clock.  We're not using ActiveRecord yet, because, well, we don't have to.  Put the following in `app/models/zen_clock.rb`:
+
+```ruby
+class ZenClock
+  attr_reader :customer
+
+  def initialize(customer)
+    @customer = customer
+  end
+end
+
+Now we can accomplish step 1 ("Receive an order") of our original plan.  When the order comes in, we instantiate a new ZenClock to prepare for building it:
+
+```ruby
+>> zen_clock = ZenClock.new('Roanoke')
+# => #<ZenClock:0x007f90b17dcb40 @customer="Roanoke">
+>> zen_clock.customer
+# => "Roanoke"
+```
+
+(You can try this in a Rails console if you want, but by now I'd think you'd just trust everything we say.)
+
+We've created a ZenClock class, and given it an initializer method.  The initializer takes, as its single argument, the customer who ordered it, and sets this as an instance variable.  We've gone ahead and instantiated our first ZenClock, for our insomniac friend Roanoke.
+
+Unfortunately, Roanoke won't be able to enjoy the fruits of his semi-conscious nocturnal mail-order adventure until we actually *build* his Zen Clock, and ship it to him.  But how do we do that?
+
+```ruby
+class ZenClock
+  # ...
+
+  def build!
+    Bumbleworks.launch!('build_zen_clock',
+      :parts => [
+        :essence_of_time,
+        :the_waterless_waterfall
+      ]
+    )
+  end
+end
+```
+
+Try this in a new Rails console:
+
+```ruby
+# Receive the new order, and start the build process:
+>> zen_clock = ZenClock.new('Roanoke')
+# => #<ZenClock:0x007f90b17dcb40 @customer="Roanoke">
+>> zen_clock.build!
+# => "20130511-0259-nurejipo-musonaso"
+```
+
+Now there's a `#build!` method, which is where we finally launch the process we defined earlier.  This `#build!` method, conceptually, "places a box of parts on the conveyor belt" (which, as you may recall, is step 2 in our original plan).  The second argument to `Bumbleworks.launch!` takes a hash, which ends up being the initial "payload" for the process.  In this case, we're providing the box of parts we'll need for assembling a Zen Clock.
+
+We're doing great!  We received an order, and we placed a box of parts on the conveyor belt.  Now we'll just have our employees start building the.. oh, wait.  We forgot to hire employees.
+
+## Hiring the Staff
+
+The Zen Clock, being at once a highly technical affair and a pseudo-spiritual scam, will require both robots and real humans to build it.  Let's flesh out the `build_zen_clock` process by expanding our previous `make` step (go ahead and change your `lib/process_definitions/build_zen_clock.rb` file to look like this):
+
+```ruby
+Bumbleworks.define_process 'build_zen_clock' do
+  any_human :task => 'check_essence_of_time_for_leaks'
+  smart_human :task => 'contemplate_solitude_of_static_universe'
+  any_human :task => 'glue_parts_together'
+  robot :task => 'add_batteries'
+  ship
+end
+```
+
+What's all this `:task => ...` nonsense?  In a Bumbleworks process plan, specifying a task that needs to be performed takes the following syntax:
+
+```ruby
+role :task => 'task_name'
+```
+
+When Bumbleworks is running a plan and encounters a line like this, it will place a Task in the queue, name it 'task_name', and make it available to any users who possess the relevant role.  For those of you who pay attention to capitalization, you'll notice we introduced a new concepts: the Task.
+
+### The Bumbleworks Task
+
+A Task (actually, Bumbleworks::Task) instance is a representation of a step on the assembly line that has to be completed by an "employee."  The conveyor belt stops temporarily until the activity is complete.
+
+If we were building something useful, this might be something like carving, painting, cleaning, filling, soldering, et cetera.  In the case of the Zen Clock, the assembly line works like this:
+
+```ruby
+1.  any_human :task => 'check_essence_of_time_for_leaks'
+2.  smart_human :task => 'contemplate_solitude_of_static_universe'
+3.  any_human :task => 'glue_parts_together'
+4.  robot :task => 'add_batteries'
+```
+
+1. The box of parts stops at a staffed workstation, where a lowly peon checks the Essence of Time part for leaks.  After verifying the part is intact, this peon pushes a button that starts the belt back up, moving the box of parts on to..
+
+2. .. another workstation, this time staffed by a high-paid human with decades of spiritual experience (and a certificate of attendance from the 2004 Zen Conference at Universal Studios Hollywood).  This human spends several hours imbuing the box of parts with the Collected Wisdom of the Stillness of the Unchanging but Infinite Cosmos, then pushes a button that starts the belt back up, moving the box of parts on to..
+
+3. .. the last human workstation, where a grizzled old human (whose hands were birthing foals before you were born) finally assembles the Clock, gradually becoming more and more convinced of its metaphysical qualities as the glue fumes rise.  The Clock is placed on the conveyor belt, a button is pushes, the belt starts back up, and we move on to our final destination..
+
+4. .. a robot, whose only task is to insert the required fourteen AA batteries.  Because, yes, the Zen Clock *does* include batteries.
+
+When a Bumbleworks process runs, it steps through the process definition sequentially (well, not always - but more about this later), and for each line it encounters, it:
+
+1. Creates a task for the given role,
+1. Waits for someone with that role to complete the task, and
+1. Moves on to the next line
+
+Remember when we added a `#build!` method to our ZenClock class, which in turn called `Bumbleworks.launch!` to start the build_zen_clock process?  As soon as that process starts, and the Bumbleworks parser hits the first line, a Task ("check_essence_of_time_for_leaks") is generated for the given Role ("any_human") and dropped in the queue.
+
+You can see it for yourself.  In a new Rails console:
+
+```ruby
+>> tasks = Bumbleworks::Task.all
+# => []
+>> zen_clock = ZenClock.new('Roanoke')
+# => #<ZenClock:0x007f90b17dcb40 @customer="Roanoke">
+>> zen_clock.build!
+# => "20130511-0259-nurejipo-musonaso"
+>> tasks = Bumbleworks::Task.all
+# => [#<Bumbleworks::Task:0x007faf9d08be30...>]
+>> tasks.count
+# => 1
+>> tasks.first.nickname
+# => "check_essence_of_time_for_leaks"
+>> tasks.first.role
+# => "any_human"
+```
+
+But who completes it?  Who is this mythical "any_human"?
+
+### Bumbleworks Doesn't Care About Users
+
+Bumbleworks itself has no idea what a "user" is, nor does it care.  It won't do any authentication or authorization for you.  Instead, it assumes you've determined what roles a given user is authorized for, and you just want to know what tasks are available to those roles.
+
+#### Looking Up Tasks By Roles
+
+Let's pretend we have three users - a peon, a guru, and a robot.  The peon and the robot only have one role each: "any_human" and "robot," respectively. The guru has two roles: "any_human" and "smart_human."
+
+```ruby
+>> zen_clock = ZenClock.new('Roanoke')
+# => #<ZenClock:0x007f90b17dcb40 @customer="Roanoke">
+>> zen_clock.build!
+# => "20130511-0259-nurejipo-musonaso"
+>> Bumbleworks::Task.for_role('any_human') # get tasks for peon
+# => [#<Bumbleworks::Task:0x007faf9d08be30...>]
+>> Bumbleworks::Task.for_role('robot') # get tasks for robot
+# => []
+>> Bumbleworks::Task.for_roles(['any_human', 'smart_human']) # get tasks for guru
+# => [#<Bumbleworks::Task:0x007faf9d08be30...>]
+```
+
+Because only one task is in the queue when we first launch the process (`any_human :task => 'check_essence_of_time_for_leaks'`), the robot has no available tasks.  The peon and the guru both see the task, since both of them have the role of 'any_human'.
+
+Let's see what happens when we `#complete` the task:
+
+```ruby
+>> zen_clock = ZenClock.new('Roanoke'); zen_clock.build!
+# => "20130511-0259-nurejipo-musonaso"
+>> task = Bumbleworks::Task.for_role('any_human').first # get first task for peon
+# => #<Bumbleworks::Task:0x007faf9d08be30...>
+>> task.complete
+# => nil
+>> Bumbleworks::Task.for_role('any_human') # any any_human tasks left?
+# => [] # nope
+>> task = Bumbleworks::Task.for_roles(['any_human', 'smart_human']).first # get first task for guru
+# => #<Bumbleworks::Task:0x007ffef337dd00...> # look, a different task!
+>> [task.nickname, task.role]
+# => ["contemplate_solitude_of_static_universe", "smart_human"]
+
+# (continued below)
+```
+
+Hey, look - now our peon has no tasks available, and can finally get back to whittling a scale model of the Library of Congress.  Our guru, however, now has a new task available - one that only shows up for smart humans (it's sort of the opposite of the Emperor's New Clothing).
+
+We'll go ahead and complete this task, then walk through the remaining two tasks (`glue_parts_together` and `add_batteries`):
+
+```ruby
+# (continued from before)
+
+>> task.complete
+# => nil
+>> task = Bumbleworks::Task.for_roles(['any_human']).first
+# => #<Bumbleworks::Task:0x007fbed991ab33...> # `glue_parts_together`
+>> [task.nickname, task.role]
+# => ["glue_parts_together", "any_human"]
+>> task.complete
+# => nil
+>> task = Bumbleworks::Task.for_roles(['robot']).first
+# => #<Bumbleworks::Task:0x007fbed991ab33...> # `add_batteries`
+>> [task.nickname, task.role]
+# => ["add_batteries", "robot"]
+>> task.complete
+# => nil
+>> Bumbleworks::Task.all
+# => [] # all tasks are done!
+```