be_taskable 0.5.0

data/readme.md

@@ -0,0 +1,292 @@
+BeTaskable
+==========
+
+BeTaskable is a small framework for creating and maintaining tasks / chores / assignments. Meaning something that someone has to do.
+
+Concepts
+--------
+
+### Taskable
+
+Any object that needs action, e.g. a document. The taskable can have different actions e.g. publish, authorise
+
+### Assignee
+
+Object that has to do the task. E.g. user
+
+### Task
+
+An object representing an action that needs to be done for a particular taskable.
+e.g. Publish document #29
+
+A task can have many assignees (See Task Assignments).
+
+### Task Assignment
+
+An object linking a task and a assignee.
+e.g. User #80 can publish document #29
+
+### Resolver
+
+An object linked to a taskable that has the business logic for your particular application.
+
+Usage
+-----
+
+### Taskable Model
+
+Make a model taskable
+
+	class Taskable < ActiveRecord::Base
+		be_taskable
+	end
+
+### Task Resolver
+
+A resolver is a class that should provide the business logic for each particular task.
+The resolver name is composed of the following parts:
+
+- Name of the taskable model e.g. Document
+- + the name of the action e.g. Publish
+- + 'TaskResolver'
+
+	class DocumentPublishTaskResolver < BeTaskable::TaskResolver
+		
+	end
+
+A resolver object should provide the following methods:
+
+	class DocumentPublishTaskResolver < BeTaskable::TaskResolver
+		
+		def consensus?(task)
+			# This method should decide if the task is completed based on the assigments
+			# return true or false
+
+			# Some possible scenarios are:
+
+			# any assignment is completed then return true
+			# task.any_assignment_done?
+
+			# the majority of assignments are completed then return true
+			# task.majority_of_assignments_done?
+
+			# all task are completed then return true
+			# task.all_assignments_done?
+
+			# use task.assignments to calculate consensus manually
+		end
+
+		def is_task_relevant?(task)
+			true
+		end
+
+		def assignees_for_task(task)
+			# Return a list of assignees for this particular task
+		end
+
+		def due_date_for_assignment(assignment)
+			# called each time an assignment is created
+			# return here when the assignment should be completed by
+			# e.g. DateTime.now + two.weeks
+			# return nil = no due date
+		end
+
+		def visible_date_for_assignment(assignment)
+			# this sets the visible_at property on the assignment
+			# this is useful if you don't want an assignment to be visible until some time in the future
+		end
+
+		def label_for_task(task)
+			# return a label (name or description) for the task (if you need to show it on the ui)
+			# get the taskable by calling task.taskable
+		end
+
+		def label_for_assigment(assignment)
+			# return a label for the assignment
+			# get the taskable by calling assignment.taskable
+		end
+
+		def url_for_assignment(assignment)
+			# return a url where to go for the assigment
+			# get the taskable by calling assignment.taskable
+		end
+
+		# hooks
+		def on_creation(task)
+			# called when a task is created
+		end
+
+		def on_completion(task)
+			# will be called when a task is completed
+		end
+
+		def on_expiration(task)
+			# will be called when a task is expired
+		end
+
+	end
+
+Create a resolver class for each taskable/action combination.
+
+### Creating a task
+
+Given a taskable model, create a new task like this:
+
+	task = document.create_task_for_action('publish')
+
+This creates the task and the assignments. You don't assign assignees to a task manually, they are assigned by the resolver. 
+
+Also there is a `create_or_refresh_task_for_action` method. This will reuse an existing task if present and is __not completed__ and __not expired__.
+
+### Completing a task
+
+After completing an action you will usually have the taskable in hand. Using the taskable you can find the task like so:
+
+	task = taskable.last_task_for_action('publish') # will give you the last task
+	task.complete_by(assignee)
+
+You may complete the task by using:
+
+	taskable.complete_task_for('publish', assignee)
+
+When a task is completed several things will happen:
+
+- Task will find the assignment for that particular assignee
+- It will set the assignment as completed
+- It will call the .consensus? method in the task resolver
+- If consensus? returns true then it will set all the assignment to completed and the task as completed
+
+You can check if a task is completed by doing:
+
+	task.completed?
+
+Other options:
+
+	task.complete!
+	# completes the task regardless for all assignees. Marks all the assignments as completed.
+
+	taskable.complete_task_for_action('publish')
+	# same as task.complete!
+
+Task.refresh
+------------
+
+When task.refresh is called the following will happen:
+
+- Mark all the current task assignments as 'unconfirmed'
+- Find the list of assignees
+- Find or create an assignment for each assignee
+- Set those assignment to confirmed
+- Delete all the assignments that are still left as 'unconfirmed'
+
+This means that if the business rules change in your resolver or the assignees change (e.g. you have more users) then `task.refresh` will create and deleted assignments as needed.
+`task.refresh` has no effect if the task is already completed. Also it won't delete assignments that are already completed.
+
+Task.tally
+----------
+
+This checks if the task can be considered done, it uses the `consensus?` method in the resolver to decide this. If the task is done then all assignments will be marked as completed.
+
+Task.audit
+--------
+
+Calls `task.refresh` and `task.tally` immediatelly.
+
+This is useful for an audit of process that runs everyday to check the validity of the assignments in your application, e.g.
+
+	BeTaskable::Task.find_each do |task|
+		task.audit
+	end
+
+Task.expire
+-----------
+
+This sets the task as no longer valid, it expires all the assignments and calls the on_expiration method on the resolver
+
+	task.expire
+
+Label and url
+-------------
+
+When task.run is called task.label, assignment.label and assignment.url are generated (using the resolver) and stored in the database. They are re-generated each time task.run is called.
+When you call task.label, assignment.label and assignment.url they will be retrieved from the cached attribute stored in the database.
+If you want to use the no-cached version use task.label!, assignment.label! and assignment.url! these will ask the resolver directly.
+
+Who did the task?
+-----------------
+
+To find out who did a particular task do the following:
+
+	assignments = tasks.enacted_assignments # this are the assignments that were actually completed by their assignees
+	assignees = assignments.map(&:assignee)
+
+Task Assignment Scopes
+---------------------
+
+The following scopes are available for task assignments:
+
+- completed
+- uncompled
+- visible
+- expired
+- unexpired
+- overdue
+- not_overdue
+- current: which are uncompled + visible + unexpired + not_overdue
+
+Assignee
+---------
+This is the object doing a task. e.g. User
+
+Mixin in `be_tasker` into your model to access the BeTaskable methods:
+
+	class User < ActiveRecord::Base
+		be_tasker
+	end
+
+	user.task_assignments #=> array with all assignments
+	user.task_assignments.current #=> array of current assignments
+
+Testing (rspec)
+-------
+
+To stub a resolver do the following:
+
+	resolver = DocumentAuthorizeTaskResolver.new
+
+	# stub the taskable class
+	Document.stub(:_task_resolver_for_action).and_return(resolver)
+
+	# now you can stub the resolver
+	resolver.stub(:assignees_for_task).and_return([user1, user2])
+
+	document = Document.create
+	document.create_task_for_action('authorize') # this will use the stubbed resolver
+
+Generators
+----------
+
+A handy generator is provided for creating the necessary tables
+
+	rails g be_taskable:migration
+
+Also a genator for task resolvers is provided:
+
+	rails g be_taskable:resolver document publish
+
+
+Testing this Gem
+----------------
+
+	bundle
+	rspec
+
+License
+-------
+
+MIT
+
+
+
+
+

data/spec/be_taskable/integration/end_to_end_spec.rb

@@ -0,0 +1,79 @@
+require File.expand_path('../../../spec_helper', __FILE__)
+
+describe 'End to End' do
+
+	let(:user1) { User.create }
+	let(:user2) { User.create }
+	let(:user3) { User.create }
+	let(:assignees) { [user1, user2] }
+	let(:taskable) { Taskable.create }
+	let(:resolver) { TaskableReviewTaskResolver.new }
+
+	before do
+		user1
+		user2
+		user3
+
+		resolver.stub(:assignees_for_task).and_return(assignees)
+
+		TaskableReviewTaskResolver.stub(:new).and_return(resolver)
+	end
+
+	# Create a task
+	# make sure assignees are assigned
+	# complete an assignment
+	# complete another assignment (that triggers consensus)
+	# task should be completed
+	it 'works' do
+		# resolver should receive on_creation when a task is created
+		resolver.should_receive(:on_creation)
+
+		task = taskable.create_task_for_action('review')
+
+		# there should be two assigments now
+		expect(BeTaskable::TaskAssignment.count).to eq(2)
+
+		# add more assignees
+		assignees.push(user3)
+
+		# task should have a label provided by the resolver
+		expect(task.label).to eq("Task label #{task.id}")
+
+		task.refresh
+
+		# there should be 3 assigments now
+		expect(BeTaskable::TaskAssignment.count).to eq(3)
+
+		# assignment should have a label provided by the resolver
+		assignment = BeTaskable::TaskAssignment.first
+		expect(assignment.label).to eq("Assignment label #{assignment.id}")
+
+		# assignment should have a url provided by the resolver
+		expect(assignment.url).to eq("Assignment url #{assignment.id}")
+
+		# assignment should have due date as provided by the resolver
+		expect(assignment.complete_by).to be_within(1.minute).of(DateTime.now + 10.days)
+
+		# complete the task for one of the assignees
+		taskable.complete_task_for('review', user1)
+
+		# the task should still be uncompleted
+		expect(task).not_to be_completed
+
+		# change the consensus
+		resolver.stub(:consensus?).and_return true
+
+		# the resolver shoud receive on_completion
+		resolver.should_receive(:on_completion)
+
+		# complete another task
+		taskable.complete_task_for('review', user2)
+
+		# task should be completed
+		task.reload
+		# puts task.state
+		# puts task.assignments.inspect
+		expect(task).to be_completed
+	end
+
+end

data/spec/be_taskable/integration/irrelevance_spec.rb

@@ -0,0 +1,70 @@
+require File.expand_path('../../../spec_helper', __FILE__)
+
+describe "Irrelevance" do 
+
+	let(:user1) { User.create }
+	let(:user2) { User.create }
+	let(:assignees) { [user1, user2] }
+	let(:taskable) { Taskable.create }
+	let(:resolver) { TaskableReviewTaskResolver.new }
+	let(:task) { taskable.create_task_for_action('review') }
+
+	before do
+		user1
+		user2
+
+		resolver.stub(:assignees_for_task).and_return(assignees)
+		TaskableReviewTaskResolver.stub(:new).and_return(resolver)
+
+		task
+	end
+
+	steps "irrelevant" do
+
+		it "creates the assigments when relevant" do
+			expect(task).to be_open
+
+			# there should be two assigments now
+			expect(BeTaskable::TaskAssignment.count).to eq(2)
+		end
+
+		it "deletes the assignments when irrelevant" do
+			# expect(BeTaskable::TaskAssignment.count).to eq(2)
+
+			# make the task irrelevant
+			resolver.stub(:is_task_relevant?).and_return(false)
+
+			task.refresh
+
+			expect(task).to be_irrelevant
+			expect(BeTaskable::TaskAssignment.count).to eq(0)
+		end
+
+		it "recreates the assignments when relevant again" do
+
+			# make task relevant again
+			resolver.unstub(:is_task_relevant?)
+
+			task.refresh
+
+			expect(task).to be_open
+			# there should be two assigments now
+			expect(BeTaskable::TaskAssignment.count).to eq(2)
+		end
+
+		it "doesnt delete already completed assignments" do
+			expect(BeTaskable::TaskAssignment.count).to eq(2)
+
+			resolver.stub(:is_task_relevant?).and_return(false)
+			resolver.stub(:consensus?).and_return(false)
+
+			BeTaskable::TaskAssignment.first.complete
+			
+			task.refresh
+
+			expect(BeTaskable::TaskAssignment.count).to eq(1)
+		end
+
+	end
+	
+end

data/spec/be_taskable/unit/be_taskable_spec.rb

@@ -0,0 +1,17 @@
+require File.expand_path('../../../spec_helper', __FILE__)
+
+describe 'BeTaskable' do
+
+	describe "#be_taskable" do
+
+		it "should provide a class method be_taskable" do
+			expect(ActiveRecord::Base).to respond_to('be_taskable')
+		end
+
+		it "should provide a class method be_tasker" do
+			expect(ActiveRecord::Base).to respond_to('be_tasker')
+		end
+
+	end
+
+end

data/spec/be_taskable/unit/task_assignment_spec.rb

@@ -0,0 +1,185 @@
+require File.expand_path('../../../spec_helper', __FILE__)
+
+describe 'BeTaskable::TaskAssignment' do
+
+	let(:task) { double.as_null_object }
+	let(:resolver) { double.as_null_object }
+	let(:assignment) { BeTaskable::TaskAssignment.new }
+
+	before do
+		assignment.stub(:task).and_return(task)
+		assignment.stub(:resolver).and_return(resolver)
+	end
+
+	describe "#completed" do
+		it "finds the completed" do
+			a1 = BeTaskable::TaskAssignment.create(completed_at: DateTime.now)
+			a2 = BeTaskable::TaskAssignment.create()
+			res = BeTaskable::TaskAssignment.completed.all
+			expect(res).to eq([a1])
+		end
+	end
+
+	describe "#uncompleted" do
+		it "finds the uncompleted" do
+			a1 = BeTaskable::TaskAssignment.create(completed_at: DateTime.now)
+			a2 = BeTaskable::TaskAssignment.create()
+			res = BeTaskable::TaskAssignment.uncompleted.all
+			expect(res).to eq([a2])
+		end
+	end
+
+	describe "#overdue" do
+		it "finds the overdue" do
+			a1 = BeTaskable::TaskAssignment.create(complete_by: DateTime.now - 1.day)
+			a2 = BeTaskable::TaskAssignment.create(complete_by: DateTime.now + 1.day)
+			a3 = BeTaskable::TaskAssignment.create()
+			res = BeTaskable::TaskAssignment.overdue.all
+			expect(res).to eq([a1])
+		end
+	end
+
+	describe "#not_overdue" do
+		it "finds the not_overdue" do
+			a1 = BeTaskable::TaskAssignment.create(complete_by: DateTime.now - 1.day)
+			a2 = BeTaskable::TaskAssignment.create(complete_by: DateTime.now + 1.day)
+			a3 = BeTaskable::TaskAssignment.create()
+			res = BeTaskable::TaskAssignment.not_overdue.all
+			expect(res).to eq([a2, a3])
+		end
+	end
+
+	describe "#visible" do
+		it "finds the visible" do
+			a1 = BeTaskable::TaskAssignment.create(visible_at: DateTime.now - 1.day)
+			a2 = BeTaskable::TaskAssignment.create()
+			a3 = BeTaskable::TaskAssignment.create(visible_at: DateTime.now + 1.day)
+			res = BeTaskable::TaskAssignment.visible.all
+			expect(res).to eq([a1, a2])
+		end
+	end
+
+	describe "#expired" do
+		it "finds the expired" do
+			a1 = BeTaskable::TaskAssignment.create(expired_at: DateTime.now - 1.day)
+			a2 = BeTaskable::TaskAssignment.create()
+			res = BeTaskable::TaskAssignment.expired.all
+			expect(res).to eq([a1])
+		end
+	end
+
+	describe "#unexpired" do
+		it "finds the unexpired" do
+			a1 = BeTaskable::TaskAssignment.create(expired_at: DateTime.now - 1.day)
+			a2 = BeTaskable::TaskAssignment.create()
+			res = BeTaskable::TaskAssignment.unexpired.all
+			expect(res).to eq([a2])
+		end
+	end
+
+	describe "#current" do
+
+		let(:a1) { BeTaskable::TaskAssignment.create() }
+		let(:a2) { BeTaskable::TaskAssignment.create(expired_at: DateTime.now - 1.day) }
+		let(:a3) { BeTaskable::TaskAssignment.create(complete_by: DateTime.now - 1.day) }
+		let(:a4) { BeTaskable::TaskAssignment.create(complete_by: DateTime.now + 1.day) }
+		let(:a5) { BeTaskable::TaskAssignment.create(completed_at: DateTime.now - 1.day) }
+		let(:a6) { BeTaskable::TaskAssignment.create(visible_at: DateTime.now + 1.day) }
+
+		before do
+			a1;a2;a3;a4;a5;a6
+		end
+
+		it "finds them" do
+			res = BeTaskable::TaskAssignment.current.all
+			expect(res).to eq([a1, a4])
+		end
+
+		it "doesnt find expired" do
+			res = BeTaskable::TaskAssignment.current.all
+			expect(res).not_to include(a2)
+		end
+
+		it "doesnt find overdue" do
+			res = BeTaskable::TaskAssignment.current.all
+			expect(res).not_to include(a3)
+		end
+
+		it "doesnt find completed" do
+			res = BeTaskable::TaskAssignment.current.all
+			expect(res).not_to include(a5)
+		end
+
+		it "doesnt find invisibles" do
+			res = BeTaskable::TaskAssignment.current.all
+			expect(res).not_to include(a6)
+		end
+
+	end
+
+	describe ".taskable" do
+		it "ask the task" do
+			task.should_receive(:taskable)
+			assignment.taskable
+		end
+	end
+
+	describe ".resolver" do
+		it 'asks the task' do
+			assignment.unstub(:resolver)
+			task.should_receive(:resolver)
+			assignment.resolver
+		end
+	end
+
+	describe ".complete" do
+		it 'sets the completed_at' do
+			assignment.complete
+			expect(assignment.completed_at).to be_within(1.minute).of(DateTime.now)
+		end
+
+		it "calls on_assignment_completed on task" do
+			task.should_receive(:on_assignment_completed).with(assignment)
+			assignment.complete
+		end
+
+		it "returns true" do
+			res = assignment.complete
+			expect(res).to be_true
+		end
+
+		it "returns false if assignment has already been completed" do
+			assignment.update_attribute(:completed_at, DateTime.now)
+			res = assignment.complete
+			expect(res).to be_false
+		end
+
+		it "sets an errors array if it returns false" do
+			assignment.update_attribute(:completed_at, DateTime.now)
+			res = assignment.complete
+			expect(res).to be_false
+			#expect(res.errors.size).not_to be_empty
+		end
+
+		it "sets enacted" do
+			res = assignment.complete
+			# assignment.reload
+			expect(assignment).to be_enacted
+		end
+	end
+
+	describe ".label!" do
+		it "asks the resolver" do
+			resolver.should_receive(:label_for_assignment)
+			assignment.label!
+		end
+	end
+
+	describe ".url!" do
+		it "asks the resolver" do
+			resolver.should_receive(:url_for_assignment)
+			assignment.url!
+		end
+	end
+
+end