bumbleworks 0.0.9 → 0.0.10

data/doc/GUIDE.md

@@ -98,9 +98,9 @@ When we're developing locally or running tests, though, running a separate worke
 
 ## 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.
+Bumbleworks, by default, will load all files in `lib/bumbleworks/process_definitions`, or `lib/bumbleworks/processes` if you prefer.  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`):
+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/bumbleworks/process_definitions/build_zen_clock.rb`):
 
 ```ruby
 Bumbleworks.define_process 'build_zen_clock' do
@@ -205,7 +205,7 @@ We're doing great!  We received an order, and we placed a box of parts on the co
 
 ## 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):
+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/bumbleworks/process_definitions/build_zen_clock.rb` file to look like this):
 
 ```ruby
 Bumbleworks.define_process 'build_zen_clock' do

data/doc/QUICKSTART.md

@@ -31,7 +31,7 @@
     Bumbleworks.load_definitions!
   ```
 
-1. Add your first process definition at `lib/process_definitions/`:
+1. Add your first process definition at `lib/bumbleworks/process_definitions/` (or `lib/bumbleworks/processes`):
 
   ```ruby
   Bumbleworks.define_process do
@@ -41,7 +41,7 @@
 
   Process definitions follow the same syntax as [ruote](http://ruote.rubyforge.org/definitions.html), but are defined using `Bumbleworks.define_process` instead of `Ruote.define`.
 
-1. (*optional*) Put any [custom participants](http://ruote.rubyforge.org/implementing_participants.html) in `app/participants` or `participants`.
+1. (*optional*) Put any [custom participants](http://ruote.rubyforge.org/implementing_participants.html) in `lib/bumbleworks/participants`.
 
 1. Create an initializer file (e.g. `config/initializers/bumbleworks.rb` for Rails) with the following:
 
@@ -62,6 +62,6 @@
     Bumbleworks.start_worker!
   ```
 
-1. You can now launch processes using `Bumbleworks.launch!('process_definition_name')`.
+1. You can now launch processes using `Bumbleworks.launch!('process_definition_name')`.  `#launch!` takes a hash as an optional second argument - anything set here will become workitem fields.  A special key, `:entity`, can be used to specify a persistent business entity for the process, which will be retrievable from process tasks (using `Task#entity`).
 
 1. Any expressions of the form `[role] :task => [task_name]` will be turned into tasks retrievable at `Bumbleworks::Task.all`; you can get tasks specific to a role or roles using `Bumbleworks::Task.for_roles([role1, role2, ...])`.

data/lib/bumbleworks.rb

@@ -12,6 +12,7 @@ module Bumbleworks
   class UnsupportedMode < StandardError; end
   class UndefinedSetting < StandardError; end
   class InvalidSetting < StandardError; end
+  class InvalidEntity < StandardError; end
 
   class << self
     extend Forwardable
@@ -85,6 +86,13 @@ module Bumbleworks
       Bumbleworks::Ruote.register_participants(&block)
     end
 
+    # @public
+    # Autoloads all files in the configured tasks_directory.
+    #
+    def register_tasks(&block)
+      Bumbleworks::Task.autoload_all
+    end
+
     # @public
     # Registers all process_definitions in the configured definitions_directory
     # with the Ruote engine.
@@ -105,10 +113,28 @@ module Bumbleworks
 
     # @public
     # Launches the process definition with the given process name, as long as
-    # that definition name is already registered with Bumbleworks.
+    # that definition name is already registered with Bumbleworks.  If options
+    # has an :entity key, attempts to extract the id and class name before
+    # sending it, so it can be properly stored in workitem fields (and
+    # re-instantiated later).
     #
     def launch!(process_definition_name, options = {})
+      extract_entity_from_options!(options)
       Bumbleworks::Ruote.launch(process_definition_name, options)
     end
+
+  private
+
+    def extract_entity_from_options!(options)
+      begin
+        if entity = options.delete(:entity)
+          options[:entity_id] = entity.respond_to?(:identifier) ? entity.identifier : entity.id
+          options[:entity_type] = entity.class.name
+          raise InvalidEntity, "Entity#id must be non-null" unless options[:entity_id]
+        end
+      rescue NoMethodError => e
+        raise InvalidEntity, "Entity must respond to #id and #class.name"
+      end
+    end
   end
 end

data/lib/bumbleworks/configuration.rb

@@ -42,16 +42,24 @@ module Bumbleworks
     # will load all definition files by recursively traversing the directory
     # tree under this folder. No specific loading order is guaranteed
     #
-    # default: ${Bumbleworks.root}/lib/process_definitions
+    # default: ${Bumbleworks.root}/lib/bumbleworks/process_definitions then ${Bumbleworks.root}/lib/bumbleworks/processes
     define_setting :definitions_directory
 
     # Path to the folder which holds the ruote participant files. Bumbleworks
     # will recursively traverse the directory tree under this folder and ensure
     # that all found files are autoloaded before registration of participants.
     #
-    # default: ${Bumbleworks.root}/participants then ${Bumbleworks.root}/app/participants
+    # default: ${Bumbleworks.root}/lib/bumbleworks/participants
     define_setting :participants_directory
 
+    # Path to the folder which holds the optional task module files, which are
+    # used to dynamically extend tasks (to override methods, or implement
+    # callbacks). Bumbleworks will recursively traverse the directory tree under
+    # this folder and ensure that all found files are autoloaded.
+    #
+    # default: ${Bumbleworks.root}/lib/bumbleworks/tasks
+    define_setting :tasks_directory
+
     # Bumbleworks requires a dedicated key-value storage for process information.  Three
     # storage solutions are currently supported: Hash, Redis and Sequel.  The latter
     # two require the bumbleworks-redis and bumbleworks-sequel gems, respectively.
@@ -85,6 +93,14 @@ module Bumbleworks
       @participants_folder ||= default_participant_directory
     end
 
+    # Path where Bumbleworks will look for task modules to load.
+    # The path can be relative or absolute.  Relative paths are
+    # relative to Bumbleworks.root.
+    #
+    def tasks_directory
+      @tasks_folder ||= default_tasks_directory
+    end
+
     # Root folder where Bumbleworks looks for ruote assets (participants,
     # process_definitions, etc.)  The root path must be absolute.
     # It can be defined through a configuration block:
@@ -123,7 +139,7 @@ module Bumbleworks
     def clear!
       defined_settings.each {|setting| instance_variable_set("@#{setting}", nil)}
       @storage_adapters = []
-      @definitions_folder = @participants_folder = nil
+      @definitions_folder = @participants_folder = @tasks_folder = nil
     end
 
     private
@@ -132,15 +148,20 @@ module Bumbleworks
     end
 
     def default_definition_directory
-      default_folders = ['lib/process_definitions']
+      default_folders = ['lib/bumbleworks/process_definitions', 'lib/bumbleworks/processes']
       find_folder(default_folders, @definitions_directory, "Definitions folder not found")
     end
 
     def default_participant_directory
-      default_folders = ['participants', 'app/participants']
+      default_folders = ['lib/bumbleworks/participants']
       find_folder(default_folders, @participants_directory, "Participants folder not found")
     end
 
+    def default_tasks_directory
+      default_folders = ['lib/bumbleworks/tasks']
+      find_folder(default_folders, @tasks_directory, "Tasks folder not found")
+    end
+
     def find_folder(default_directories, defined_directory, message)
       # use defined directory structure if defined
       if defined_directory

data/lib/bumbleworks/support.rb

@@ -17,5 +17,21 @@ module Bumbleworks
         memo
       end
     end
+
+    def constantize(name)
+      name_parts = name.split('::')
+      name_parts.shift if name_parts.first.empty?
+      constant = Object
+
+      name_parts.each do |name_part|
+        constant_defined = if Module.method(:const_defined?).arity == 1
+          constant.const_defined?(name_part)
+        else
+          constant.const_defined?(name_part, false)
+        end
+        constant = constant_defined ? constant.const_get(name_part) : constant.const_missing(name_part)
+      end
+      constant
+    end
   end
 end

data/lib/bumbleworks/task.rb

@@ -1,7 +1,10 @@
+require "bumbleworks/tasks/base"
+
 module Bumbleworks
   class Task
     class AlreadyClaimed < StandardError; end
     class MissingWorkitem < StandardError; end
+    class EntityNotFound < StandardError; end
 
     extend Forwardable
     delegate [:sid, :fei, :fields, :params, :participant_name, :wfid, :wf_name] => :@workitem
@@ -9,6 +12,20 @@ module Bumbleworks
     alias_method :id, :sid
 
     class << self
+      # @public
+      # Autoload all task modules defined in files in the
+      # tasks_directory.  The symbol for autoload comes from the
+      # camelized version of the filename, so this method is dependent on
+      # following that convention.  For example, file `chew_cud_task.rb`
+      # should define `ChewCudTask`.
+      #
+      def autoload_all(options = {})
+        options[:directory] ||= Bumbleworks.tasks_directory
+        Bumbleworks::Support.all_files(options[:directory], :camelize => true).each do |path, name|
+          Object.autoload name.to_sym, path
+        end
+      end
+
       def for_role(identifier)
         for_roles([identifier])
       end
@@ -50,6 +67,20 @@ module Bumbleworks
         raise ArgumentError, "Not a valid workitem"
       end
       @nickname = params['task']
+      extend_module
+    end
+
+    def entity
+      if has_entity_fields?
+        klass = Bumbleworks::Support.constantize(fields['entity_type'])
+        entity = klass.first_by_identifier(fields['entity_id'])
+      end
+      raise EntityNotFound unless entity
+      entity
+    end
+
+    def has_entity_fields?
+      fields['entity_id'] && fields['entity_type']
     end
 
     # alias for fields[] (fields delegated to workitem)
@@ -66,14 +97,28 @@ module Bumbleworks
       participant_name
     end
 
+    def extend_module
+      extend Bumbleworks::Tasks::Base
+      extend task_module if nickname
+    rescue NameError
+    end
+
+    def task_module
+      return nil unless nickname
+      klass_name = Bumbleworks::Support.camelize(nickname)
+      klass = Bumbleworks::Support.constantize("#{klass_name}Task")
+    end
+
     # update workitem with changes to fields & params
-    def save
-      storage_participant.update(@workitem)
+    def update(params = {})
+      before_update(params)
+      update_workitem
+      after_update(params)
     end
 
     # proceed workitem (saving changes to fields)
-    def complete
-      storage_participant.proceed(@workitem)
+    def complete(params = {})
+      proceed_workitem
     end
 
     # Token used to claim task, nil if not claimed
@@ -96,11 +141,20 @@ module Bumbleworks
       set_claimant(nil)
     end
 
-    private
+  private
+
     def storage_participant
       self.class.storage_participant
     end
 
+    def update_workitem
+      storage_participant.update(@workitem)
+    end
+
+    def proceed_workitem
+      storage_participant.proceed(@workitem)
+    end
+
     def set_claimant(token)
       if token && claimant && token != claimant
         raise AlreadyClaimed, "Already claimed by #{claimant}"

data/lib/bumbleworks/tasks/base.rb

@@ -0,0 +1,11 @@
+module Bumbleworks
+  module Tasks
+    module Base
+      def before_update(params)
+      end
+
+      def after_update(params)
+      end
+    end
+  end
+end

data/lib/bumbleworks/version.rb

@@ -1,3 +1,3 @@
 module Bumbleworks
-  VERSION = "0.0.9"
+  VERSION = "0.0.10"
 end

data/spec/fixtures/apps/with_default_directories/full_initializer.rb

@@ -8,5 +8,6 @@ Bumbleworks.register_participants do
   molasses_maker MolassesParticipant
 end
 
+Bumbleworks.register_tasks
 Bumbleworks.load_definitions!
 Bumbleworks.start_worker!

data/spec/fixtures/apps/with_default_directories/lib/bumbleworks/tasks/make_some_honey_task.rb

@@ -0,0 +1,5 @@
+module MakeSomeHoneyTask
+  def before_update(params)
+    fields['what_happened'] = params['happening']
+  end
+end

data/spec/fixtures/apps/with_default_directories/lib/bumbleworks/tasks/taste_that_molasses_task.rb

@@ -0,0 +1,2 @@
+module TasteThatMolassesTask
+end

data/spec/integration/configuration_spec.rb

@@ -19,7 +19,7 @@ describe Bumbleworks::Configuration do
 
     it 'returns default directory when not set in configuration' do
       load default_initializer
-      Bumbleworks.definitions_directory.should == File.join(default_app_path, 'lib', 'process_definitions')
+      Bumbleworks.definitions_directory.should == File.join(default_app_path, 'lib', 'bumbleworks', 'process_definitions')
     end
   end
 
@@ -31,13 +31,7 @@ describe Bumbleworks::Configuration do
 
     it 'returns default directory when not set in configuration' do
       load default_initializer
-      Bumbleworks.participants_directory.should == File.join(default_app_path, 'app', 'participants')
-    end
-
-    it 'returns second default directory if first not found' do
-      load default_initializer
-      Bumbleworks.root = File.join(default_app_path, 'app')
-      Bumbleworks.participants_directory.should == File.join(default_app_path, 'app', 'participants')
+      Bumbleworks.participants_directory.should == File.join(default_app_path, 'lib', 'bumbleworks', 'participants')
     end
   end
 end

data/spec/integration/sample_application_spec.rb

@@ -1,14 +1,14 @@
 describe 'Bumbleworks Sample Application' do
-  describe 'initializer' do
-    let(:app_root) {
-      File.expand_path(File.join(fixtures_path, 'apps', 'with_default_directories'))
-    }
+  let(:app_root) {
+    File.expand_path(File.join(fixtures_path, 'apps', 'with_default_directories'))
+  }
 
-    before :each do
-      Bumbleworks.reset!
-      load File.join(app_root, 'full_initializer.rb')
-    end
+  before :each do
+    Bumbleworks.reset!
+    load File.join(app_root, 'full_initializer.rb')
+  end
 
+  describe 'initializer' do
     it 'registers participants' do
       Bumbleworks.dashboard.participant_list.should have(3).items
       Bumbleworks.dashboard.participant_list.map(&:classname).should =~ ['HoneyParticipant', 'MolassesParticipant', 'Ruote::StorageParticipant']
@@ -26,14 +26,16 @@ describe 'Bumbleworks Sample Application' do
           {},
           [["dave", {"task"=>"make_some_molasses"}, []], ["sam", {"task"=>"taste_that_molasses"}, []]]]]]
     end
+  end
 
-    it 'automatically starts engine and waits for first task in catchall participant' do
+  describe 'launching process' do
+    it 'waits for first task in catchall participant' do
       Bumbleworks.launch!('make_honey')
       Bumbleworks.dashboard.wait_for(:dave)
       Bumbleworks::Task.all.should have(1).item
     end
 
-    it 'automatically starts engine and waits for first task in catchall participant' do
+    it 'creates tasks for concurrent workflows' do
       Bumbleworks.launch!('make_molasses')
       Bumbleworks.dashboard.wait_for(:dave)
       Bumbleworks::Task.all.should have(2).item
@@ -41,5 +43,15 @@ describe 'Bumbleworks Sample Application' do
       Bumbleworks::Task.for_role('sam').should have(1).item
     end
   end
+
+  describe 'updating a task' do
+    it 'calls callbacks' do
+      Bumbleworks.launch!('make_honey')
+      Bumbleworks.dashboard.wait_for(:dave)
+      task = Bumbleworks::Task.for_role('dave').first
+      task.update('happening' => 'update')
+      task['what_happened'].should == 'update'
+    end
+  end
 end
 

data/spec/lib/bumbleworks/configuration_spec.rb

@@ -60,7 +60,14 @@ describe Bumbleworks::Configuration do
     it 'returns the default folder if not set by client app' do
       File.stub(:directory? => true)
       configuration.root = '/Root'
-      configuration.definitions_directory.should == '/Root/lib/process_definitions'
+      configuration.definitions_directory.should == '/Root/lib/bumbleworks/process_definitions'
+    end
+
+    it 'returns the second default folder if first does not exist' do
+      File.stub(:directory?).with('/Root/lib/bumbleworks/process_definitions').and_return(false)
+      File.stub(:directory?).with('/Root/lib/bumbleworks/processes').and_return(true)
+      configuration.root = '/Root'
+      configuration.definitions_directory.should == '/Root/lib/bumbleworks/processes'
     end
 
     it 'raises an error if default folder not found' do
@@ -82,10 +89,9 @@ describe Bumbleworks::Configuration do
     end
 
     it 'returns the default folder if not set by client app' do
-      File.stub(:directory? => false)
-      File.stub(:directory?).with('/Root/app/participants').and_return(true)
+      File.stub(:directory?).with('/Root/lib/bumbleworks/participants').and_return(true)
       configuration.root = '/Root'
-      configuration.participants_directory.should == '/Root/app/participants'
+      configuration.participants_directory.should == '/Root/lib/bumbleworks/participants'
     end
 
     it 'raises an error if default folder not found' do
@@ -99,6 +105,30 @@ describe Bumbleworks::Configuration do
     end
   end
 
+  describe "#tasks_directory" do
+    it 'returns the folder which was set by the client app' do
+      File.stub(:directory?).with('/dog/ate/my/homework').and_return(true)
+      configuration.tasks_directory = '/dog/ate/my/homework'
+      configuration.tasks_directory.should == '/dog/ate/my/homework'
+    end
+
+    it 'returns the default folder if not set by client app' do
+      File.stub(:directory?).with('/Root/lib/bumbleworks/tasks').and_return(true)
+      configuration.root = '/Root'
+      configuration.tasks_directory.should == '/Root/lib/bumbleworks/tasks'
+    end
+
+    it 'raises an error if default folder not found' do
+      configuration.root = '/Root'
+      expect{configuration.tasks_directory}.to raise_error Bumbleworks::InvalidSetting
+    end
+
+    it 'raises an error if specific folder not found' do
+      configuration.tasks_directory = '/mumbo/jumbo'
+      expect{configuration.tasks_directory}.to raise_error Bumbleworks::InvalidSetting
+    end
+  end
+
   describe "#storage" do
     it 'can set storage directly' do
       storage = double("Storage")
@@ -141,7 +171,7 @@ describe Bumbleworks::Configuration do
       configuration.clear!
 
       configuration.root = '/Root'
-      configuration.definitions_directory.should == '/Root/lib/process_definitions'
+      configuration.definitions_directory.should == '/Root/lib/bumbleworks/process_definitions'
     end
   end
 end

data/spec/lib/bumbleworks/participant_registration_spec.rb

@@ -4,9 +4,9 @@ describe Bumbleworks::ParticipantRegistration do
       Bumbleworks.reset!
       Bumbleworks.root = File.join(fixtures_path, 'apps', 'with_default_directories')
       Object.should_receive(:autoload).with(:HoneyParticipant,
-        File.join(Bumbleworks.root, 'app', 'participants', 'honey_participant.rb'))
+        File.join(Bumbleworks.root, 'lib', 'bumbleworks', 'participants', 'honey_participant.rb'))
       Object.should_receive(:autoload).with(:MolassesParticipant,
-        File.join(Bumbleworks.root, 'app', 'participants', 'molasses_participant.rb'))
+        File.join(Bumbleworks.root, 'lib', 'bumbleworks', 'participants', 'molasses_participant.rb'))
       Bumbleworks::ParticipantRegistration.autoload_all
     end
   end

data/spec/lib/bumbleworks/support_spec.rb

@@ -31,4 +31,32 @@ describe Bumbleworks::Support do
         'TestNestedProcess'
     end
   end
+
+  describe '.constantize' do
+    before :each do
+      class Whatever
+        Smoothies = 'tasty'
+      end
+      class Boojus
+      end
+    end
+
+    after :each do
+      Object.send(:remove_const, :Whatever)
+    end
+
+    it 'returns value of constant with given name' do
+      described_class.constantize('Whatever')::Smoothies.should == 'tasty'
+    end
+
+    it 'works with nested constants' do
+      described_class.constantize('Whatever::Smoothies').should == 'tasty'
+    end
+
+    it 'does not check inheritance tree' do
+      expect {
+        described_class.constantize('Whatever::Boojus')
+      }.to raise_error(NameError)
+    end
+  end
 end

data/spec/lib/bumbleworks/task_spec.rb

@@ -8,6 +8,17 @@ describe Bumbleworks::Task do
     Bumbleworks.start_worker!
   end
 
+  describe '.autoload_all' do
+    it 'autoloads all task modules in directory' do
+      Bumbleworks.root = File.join(fixtures_path, 'apps', 'with_default_directories')
+      Object.should_receive(:autoload).with(:MakeSomeHoneyTask,
+        File.join(Bumbleworks.root, 'lib', 'bumbleworks', 'tasks', 'make_some_honey_task.rb'))
+      Object.should_receive(:autoload).with(:TasteThatMolassesTask,
+        File.join(Bumbleworks.root, 'lib', 'bumbleworks', 'tasks', 'taste_that_molasses_task.rb'))
+      Bumbleworks::Task.autoload_all
+    end
+  end
+
   describe '.new' do
     it 'raises an error if workitem is nil' do
       expect {
@@ -26,6 +37,53 @@ describe Bumbleworks::Task do
         described_class.new(workflow_item)
       }.not_to raise_error
     end
+
+    it 'extends new object with task module' do
+      described_class.any_instance.should_receive(:extend_module)
+      described_class.new(workflow_item)
+    end
+  end
+
+  describe '#extend_module' do
+    it 'extends with base module and task module' do
+      task = described_class.new(workflow_item)
+      task.should_receive(:task_module).and_return(:task_module_double)
+      task.should_receive(:extend).with(Bumbleworks::Tasks::Base).ordered
+      task.should_receive(:extend).with(:task_module_double).ordered
+      task.extend_module
+    end
+
+    it 'extends only with base module if no nickname' do
+      task = described_class.new(workflow_item)
+      task.stub(:nickname).and_return(nil)
+      task.should_receive(:extend).with(Bumbleworks::Tasks::Base)
+      task.extend_module
+    end
+
+    it 'extends only with base module if task module does not exist' do
+      task = described_class.new(workflow_item)
+      task.should_receive(:extend).with(Bumbleworks::Tasks::Base)
+      task.extend_module
+    end
+  end
+
+  describe '#task_module' do
+    # def task_module
+    #   return nil unless nickname
+    #   klass_name = Bumbleworks::Support.camelize(nickname)
+    #   klass = Bumbleworks::Support.constantize("Bumbleworks::Tasks::#{klass_name}")
+    # end
+    it 'returns nil if no nickname' do
+      task = described_class.new(workflow_item)
+      task.stub(:nickname).and_return(nil)
+      task.task_module.should be_nil
+    end
+
+    it 'returns constantized task nickname with "Task" appended' do
+      task = described_class.new(workflow_item)
+      Bumbleworks::Support.stub(:constantize).with("GoToWorkTask").and_return(:the_task_module)
+      task.task_module.should == :the_task_module
+    end
   end
 
   describe '#id' do
@@ -243,17 +301,25 @@ describe Bumbleworks::Task do
       Bumbleworks.launch!('dog-lifecycle')
     end
 
-    describe '#save' do
+    describe '#update' do
       it 'saves fields and params, but does not proceed process' do
         event = Bumbleworks.dashboard.wait_for :dog_mouth
         task = described_class.for_role('dog_mouth').first
         task.params['state'] = 'is ready'
         task.fields['meal'] = 'salted_rhubarb'
-        task.save
+        task.update
         task = described_class.for_role('dog_mouth').first
         task.params['state'].should == 'is ready'
         task.fields['meal'].should == 'salted_rhubarb'
       end
+
+      it 'calls before_update and after_update callbacks' do
+        task = described_class.new(workflow_item)
+        task.should_receive(:before_update).with(:argue_mints).ordered
+        task.should_receive(:update_workitem).ordered
+        task.should_receive(:after_update).with(:argue_mints).ordered
+        task.update(:argue_mints)
+      end
     end
 
     describe '#complete' do
@@ -270,5 +336,56 @@ describe Bumbleworks::Task do
         task.fields['meal'].should == 'root beer and a kite'
       end
     end
+
+    describe '#has_entity_fields?' do
+      it 'returns true if workitem fields include entity fields' do
+        task = described_class.new(workflow_item)
+        task['entity_id'] = '1'
+        task['entity_type'] = 'SomeEntity'
+        task.should have_entity_fields
+      end
+
+      it 'returns false if workitem fields do not include entity fields' do
+        task = described_class.new(workflow_item)
+        task.should_not have_entity_fields
+      end
+    end
+
+    describe '#entity' do
+      class LovelyEntity
+        def self.first_by_identifier(identifier)
+          return nil unless identifier
+          "Object #{identifier}"
+        end
+      end
+
+      let(:entitied_workflow_item) {
+        Ruote::Workitem.new('fields' => {
+          'entity_id' => '15',
+          'entity_type' => 'LovelyEntity',
+          'params' => {'task' => 'go_to_work'}
+        })
+      }
+
+      it 'attempts to instantiate business entity from _id and _type fields' do
+        task = described_class.new(entitied_workflow_item)
+        task.entity.should == 'Object 15'
+      end
+
+      it 'throw exception if entity fields not present' do
+        task = described_class.new(workflow_item)
+        expect {
+          task.entity
+        }.to raise_error Bumbleworks::Task::EntityNotFound
+      end
+
+      it 'throw exception if entity returns nil' do
+        task = described_class.new(entitied_workflow_item)
+        task['entity_id'] = nil
+        expect {
+          task.entity
+        }.to raise_error Bumbleworks::Task::EntityNotFound
+      end
+    end
   end
 end

data/spec/lib/bumbleworks_spec.rb

@@ -51,6 +51,13 @@ describe Bumbleworks do
     end
   end
 
+  describe '.register_tasks' do
+    it 'autoloads task modules' do
+      Bumbleworks::Task.should_receive(:autoload_all)
+      described_class.register_tasks
+    end
+  end
+
   describe '.register_participants' do
     it 'autoloads and registers participants' do
       the_block = lambda {  }
@@ -105,4 +112,42 @@ describe Bumbleworks do
       Bumbleworks.start_worker!.should == :lets_do_it
     end
   end
+
+  describe '.launch!' do
+    class LovelyEntity
+      attr_accessor :id
+      def initialize(id)
+        @id = id
+      end
+    end
+
+    it 'delegates to Bumbleworks::Ruote.launch' do
+      Bumbleworks::Ruote.should_receive(:launch).with(:amazing_process, :hugs => :love)
+      Bumbleworks.launch!(:amazing_process, :hugs => :love)
+    end
+
+    it 'expands entity params when entity object provided' do
+      Bumbleworks::Ruote.should_receive(:launch).with(:amazing_process, :entity_id => :wiley_e_coyote, :entity_type => 'LovelyEntity')
+      Bumbleworks.launch!(:amazing_process, :entity => LovelyEntity.new(:wiley_e_coyote))
+    end
+
+    it 'uses "identifier" method instead of id, if entity has one' do
+      entity = LovelyEntity.new(5)
+      entity.stub(:identifier).and_return(:five)
+      Bumbleworks::Ruote.should_receive(:launch).with(:amazing_process, :entity_id => :five, :entity_type => 'LovelyEntity')
+      Bumbleworks.launch!(:amazing_process, :entity => entity)
+    end
+
+    it 'throws exception if entity has nil id' do
+      expect {
+        Bumbleworks.launch!(:amazing_process, :entity => LovelyEntity.new(nil))
+      }.to raise_error(Bumbleworks::InvalidEntity)
+    end
+
+    it 'throws exception if entity is invalid object' do
+      expect {
+        Bumbleworks.launch!(:amazing_process, :entity => :give_me_a_break)
+      }.to raise_error(Bumbleworks::InvalidEntity)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bumbleworks
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.10
   prerelease: 
 platform: ruby
 authors:
@@ -12,7 +12,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-26 00:00:00.000000000 Z
+date: 2013-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruote
@@ -175,16 +175,19 @@ files:
 - lib/bumbleworks/storage_adapter.rb
 - lib/bumbleworks/support.rb
 - lib/bumbleworks/task.rb
+- lib/bumbleworks/tasks/base.rb
 - lib/bumbleworks/tree_builder.rb
 - lib/bumbleworks/version.rb
 - lib/tasks/bumbleworks.rake
-- spec/fixtures/apps/with_default_directories/app/participants/honey_participant.rb
-- spec/fixtures/apps/with_default_directories/app/participants/molasses_participant.rb
 - spec/fixtures/apps/with_default_directories/config_initializer.rb
 - spec/fixtures/apps/with_default_directories/full_initializer.rb
-- spec/fixtures/apps/with_default_directories/lib/process_definitions/garbage_collector.rb
-- spec/fixtures/apps/with_default_directories/lib/process_definitions/make_honey.rb
-- spec/fixtures/apps/with_default_directories/lib/process_definitions/make_molasses.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/participants/honey_participant.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/participants/molasses_participant.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/process_definitions/garbage_collector.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/process_definitions/make_honey.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/process_definitions/make_molasses.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/tasks/make_some_honey_task.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/tasks/taste_that_molasses_task.rb
 - spec/fixtures/apps/with_specified_directories/config_initializer.rb
 - spec/fixtures/apps/with_specified_directories/specific_directory/definitions/.gitkeep
 - spec/fixtures/apps/with_specified_directories/specific_directory/participants/.gitkeep
@@ -217,18 +220,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -2621503672602724538
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -2621503672602724538
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -236,13 +233,15 @@ signing_key:
 specification_version: 3
 summary: Framework around ruote[http://github.com/jmettraux/ruote] workflow engine
 test_files:
-- spec/fixtures/apps/with_default_directories/app/participants/honey_participant.rb
-- spec/fixtures/apps/with_default_directories/app/participants/molasses_participant.rb
 - spec/fixtures/apps/with_default_directories/config_initializer.rb
 - spec/fixtures/apps/with_default_directories/full_initializer.rb
-- spec/fixtures/apps/with_default_directories/lib/process_definitions/garbage_collector.rb
-- spec/fixtures/apps/with_default_directories/lib/process_definitions/make_honey.rb
-- spec/fixtures/apps/with_default_directories/lib/process_definitions/make_molasses.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/participants/honey_participant.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/participants/molasses_participant.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/process_definitions/garbage_collector.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/process_definitions/make_honey.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/process_definitions/make_molasses.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/tasks/make_some_honey_task.rb
+- spec/fixtures/apps/with_default_directories/lib/bumbleworks/tasks/taste_that_molasses_task.rb
 - spec/fixtures/apps/with_specified_directories/config_initializer.rb
 - spec/fixtures/apps/with_specified_directories/specific_directory/definitions/.gitkeep
 - spec/fixtures/apps/with_specified_directories/specific_directory/participants/.gitkeep
@@ -262,3 +261,4 @@ test_files:
 - spec/lib/bumbleworks_spec.rb
 - spec/spec_helper.rb
 - spec/support/path_helpers.rb
+has_rdoc: