turkee 1.2.0 → 1.2.1

data/README.rdoc

@@ -74,7 +74,7 @@ Inside the config/initializers directory, you'll see the file turkee.rb.  Edit t
 
 3) Change your forms to use the form helper.
 
-    <% turkee_form_for(@survey, params) do |f| %>
+    <%= turkee_form_for(@survey, params) do |f| %>
         <p><%= f.text_area :value, :disabled => @disabled %></p>
         <p><%= f.submit 'Create', :disabled => @disabled %></p>
     <% end %>
@@ -93,7 +93,7 @@ Using the turkee_form_for helper will post the form to the Mechanical Turk sandb
     rake turkee:post_hit[<Host>, <Title>, <Description>, <Model>, <Number of Assignments>, <Reward>, <Lifetime>]
 
     e.g. :
-    rake turkee:post_hit["https://www.yourapp.com","Please complete our survey","Tell us your favorite color.","Survey",100,0.05,2]
+    rake turkee:post_hit["https://www.yourapp.com","Please complete our survey","Tell us your favorite color.","Survey",100,0.05,5,1]
     ** Do not put spaces before or after commas for the rake task parameters
 
 This will insert a row for the requested HIT into the turkee_tasks table.  The turkee_tasks entry stores (along with the other properties) the HIT URL (e.g. http://workersandbox.mturk.com/mturk/preview?groupId=1HGHJJGHQSJB7WMWJ33YS8WM169XNIL ) and HIT ID (e.g. 1J1EXO8SUQ3URTTUYGHJ7EKUT11 ).  These values are returned from Mechanical Turk when the HIT request is posted.
@@ -103,7 +103,7 @@ When a Turk worker views your HIT, the HIT will display your form within an iFra
 5) Allow some time for the Mechanical Turk workers ("Turkers") to respond to your HIT.
 
 6) Run the rake task that retrieves the values from Mechanical Turk and stores the user entered values into your model.
-    rake turkee::get_all_results
+    rake turkee:get_all_results
 
 Rerun this task periodically to retrieve newly entered form values.  You can setup this task as a cronjob to automate this.
 
@@ -124,18 +124,35 @@ As for Mechanical Turk approval, if the row is created and you haven't specified
       end
     end
 
+8) When all specified assignments for a HIT have been completed, Turkee will attempt to call the optional hit_complete class method for the model.  This can be used for any cleanup logic.  E.g. :
+    class Survey < ActiveRecord::Base
+      def self.hit_complete(turkee_task)
+        #do something
+      end
+    end
 
 == Advanced Usage
 
-You can use the params hash to pass object IDs to your forms.  E.g. if you wanted to setup a form of questions about a given URL (let's call the model UrlSurvey), your code would look something like :
+1) You can use the params hash to pass object IDs to your forms.  E.g. if you wanted to setup a form of questions about a given URL (let's call the model UrlSurvey), your code would look something like :
 
-URL.all do |url|
-  Turkee::TurkeeTask.create_hit(host, hit_title, hit_description, UrlSurvey, num_assignments, reward,
-  lifetime, qualifications = {}, params = {:url_id => url.id}, opts = {})
-end
+    URL.all do |url|
+        Turkee::TurkeeTask.create_hit(host, hit_title, hit_description, UrlSurvey, num_assignments, reward,
+            lifetime, duration, {}, {:url_id => url.id}, {})
+    end
 
 Then when displaying your form, you can find the URL object via the params[:url_id] value.
 
+
+2) Turkee assumes that the form url will be the new action for the class passed to create_hit.  If you have a more complex form url which would be the case for nested resources, you can use the :form_url
+option to designate a form url different from the default.
+
+
+    form_url = Rails.application.routes.url_helpers.send("new_user_survey_path",@my_survey)
+
+    Turkee::TurkeeTask.create_hit(host, hit_title, hit_description, :Survey, num_assignments, reward,
+        lifetime, duration, {}, {}, {:form_url => form_url})
+
+
 == Gotchas
 
 1) The application that hosts your external forms preferably should have an https interface (you're going to have to buy an SSL certificate).  If the forms are hosted on an unsecured host (http), because Mechanical Turk defaults to https, you're going to receive the ugly popup from IE regarding "mixed content" (http://msdn.microsoft.com/en-us/library/ee264315%28v=vs.85%29.aspx).

data/lib/generators/turkee/templates/add_hit_duration.rb.erb

@@ -0,0 +1,15 @@
+class AddHitDuration < ActiveRecord::Migration
+
+  def self.up
+    unless column_exists? :turkee_tasks, :hit_duration
+      add_column :turkee_tasks, :hit_duration, :integer
+    end
+  end
+
+  def self.down
+    if column_exists? :turkee_tasks, :hit_duration
+	  remove_column :turkee_tasks, :hit_duration
+	end
+  end
+end
+

data/lib/generators/turkee/templates/add_imported_assignment_details.rb.erb

@@ -0,0 +1,33 @@
+class AddImportedAssignmentDetails < ActiveRecord::Migration
+
+  def self.up
+    unless column_exists? :turkee_imported_assignments, :turkee_task_id
+      add_column :turkee_imported_assignments, :turkee_task_id, :integer
+      add_index :turkee_imported_assignments, :turkee_task_id, :unique => false
+    end
+
+    unless column_exists? :turkee_imported_assignments, :worker_id
+      add_column :turkee_imported_assignments, :worker_id, :string
+    end
+
+    unless column_exists? :turkee_imported_assignments, :result_id
+      add_column :turkee_imported_assignments, :result_id, :integer
+    end
+  end
+
+  def self.down
+	if column_exists? :turkee_imported_assignments, :turkee_task_id
+      remove_column :turkee_imported_assignments, :turkee_task_id
+      remove_index :turkee_imported_assignments, :turkee_task_id
+    end
+
+    if column_exists? :turkee_imported_assignments, :worker_id
+      remove_column :turkee_imported_assignments, :worker_id
+    end
+
+    if column_exists? :turkee_imported_assignments, :result_id
+      remove_column :turkee_imported_assignments, :result_id
+    end
+  end
+end
+

data/lib/generators/turkee/turkee_generator.rb

@@ -25,6 +25,14 @@ class TurkeeGenerator < Rails::Generators::Base
     sleep 1
 
     migration_template "add_completed_tasks.rb.erb", "db/migrate/add_completed_tasks.rb"
+    
+    sleep 1
+
+    migration_template "add_imported_assignment_details.rb.erb", "db/migrate/add_imported_assignment_details.rb"
+
+    sleep 1
+
+    migration_template "add_hit_duration.rb.erb", "db/migrate/add_hit_duration.rb"
 
   end
 

data/lib/tasks/turkee.rb

@@ -2,7 +2,7 @@ require 'rake'
 require 'turkee'
 
 namespace :turkee do
-  desc "Post your form to Mechanical Turk (HIT). Task takes the application's host URL, HIT title, HIT description, model name, number of responses, reward for each response, and number of days the HIT should be valid."
+  desc "Post your form to Mechanical Turk (HIT). Task takes the application's host URL, HIT title, HIT description, model name, number of responses, reward for each response, number of days the HIT should be valid, and number of hours a worker has to complete the HIT."
   task :post_hit, [:host, :title, :description, :model, :num_assignments, :reward, :lifetime] => :environment do |t, args|
     hit = Turkee::TurkeeTask.create_hit(args[:host],args[:title], args[:description], args[:model],
                                         args[:num_assignments], args[:reward], args[:lifetime])

data/lib/turkee.rb

@@ -11,15 +11,16 @@ module Turkee
 
   # Model simply tracks what assignments have been imported
   class TurkeeImportedAssignment < ActiveRecord::Base
+    attr_accessible :assignment_id, :turkee_task_id, :worker_id, :result_id
   end
 
   class TurkeeTask < ActiveRecord::Base
-    attr_accessible :sandbox, :hit_title, :hit_description, :hit_reward, :hit_num_assignments, :hit_lifetime,
+    attr_accessible :sandbox, :hit_title, :hit_description, :hit_reward, :hit_num_assignments, :hit_lifetime, :hit_duration,
                     :form_url, :hit_url, :hit_id, :task_type, :complete
 
     HIT_FRAMEHEIGHT     = 1000
 
-    scope :unprocessed_hits, :conditions => ['complete = ?', false]
+    scope :unprocessed_hits, lambda{ where('complete = ? AND sandbox = ?', false, RTurk.sandbox?) }
 
     # Use this method to go out and retrieve the data for all of the posted Turk Tasks.
     #  Each specific TurkeeTask object (determined by task_type field) is in charge of
@@ -35,7 +36,7 @@ module Turkee
           turks.each do |turk|
             hit   = RTurk::Hit.new(turk.hit_id)
 
-            models = []
+            models = Set.new
             hit.assignments.each do |assignment|
               next unless submitted?(assignment.status)
               next unless TurkeeImportedAssignment.find_by_assignment_id(assignment.id).nil?
@@ -45,14 +46,16 @@ module Turkee
               model      = find_model(param_hash)
 
               next if model.nil?
-              puts "param_hash = #{param_hash}"
+              models << model
+              
+              logger.debug "param_hash = #{param_hash}"
               result = model.create(param_hash[model.to_s.underscore])
 
               # If there's a custom approve? method, see if we should approve the submitted assignment
               #  otherwise just approve it by default
               process_result(assignment, result, turk)
 
-              TurkeeImportedAssignment.create(:assignment_id => assignment.id) rescue nil
+              TurkeeImportedAssignment.create!(:assignment_id => assignment.id, :turkee_task_id => turk.id, :worker_id => assignment.worker_id, :result_id => result.id)
             end
 
             check_hit_completeness(hit, turk, models)
@@ -65,17 +68,16 @@ module Turkee
     end
 
     # Creates a new Mechanical Turk task on AMZN with the given title, desc, etc
-    def self.create_hit(host, hit_title, hit_description, typ, num_assignments, reward, lifetime, qualifications = {}, params = {}, opts = {})
-
+    def self.create_hit(host, hit_title, hit_description, typ, num_assignments, reward, lifetime, duration = nil, qualifications = {}, params = {}, opts = {})
       model    = Object::const_get(typ)
-      duration = lifetime.to_i
-      f_url    = (full_url(opts[:form_url], params) || form_url(host, model, params))
+      f_url    = build_url(host, model, params, opts)
 
       h = RTurk::Hit.create(:title => hit_title) do |hit|
         hit.assignments = num_assignments
         hit.description = hit_description
         hit.reward      = reward
-        hit.lifetime    = duration.days.seconds.to_i
+        hit.lifetime    = lifetime.to_i.days.seconds.to_i
+        hit.duration    = duration.to_i.hours.seconds.to_i if duration
         hit.question(f_url, :frame_height => HIT_FRAMEHEIGHT)
         unless qualifications.empty?
           qualifications.each do |key, value|
@@ -87,9 +89,10 @@ module Turkee
       TurkeeTask.create(:sandbox             => RTurk.sandbox?,
                         :hit_title           => hit_title,    :hit_description     => hit_description,
                         :hit_reward          => reward.to_f,  :hit_num_assignments => num_assignments.to_i,
-                        :hit_lifetime        => lifetime,     :form_url            => f_url,
-                        :hit_url             => h.url,        :hit_id              => h.id,
-                        :task_type           => typ,          :complete            => false)
+                        :hit_lifetime        => lifetime,     :hit_duration => duration,
+                        :form_url            => f_url,        :hit_url             => h.url,
+                        :hit_id              => h.id,         :task_type           => typ,
+                        :complete            => false)
 
     end
 
@@ -140,7 +143,7 @@ module Turkee
     end
 
     def self.check_hit_completeness(hit, turk, models)
-      puts "#### turk.completed_assignments == turk.hit_num_assignments :: #{turk.completed_assignments} == #{turk.hit_num_assignments}"
+      logger.debug "#### turk.completed_assignments == turk.hit_num_assignments :: #{turk.completed_assignments} == #{turk.hit_num_assignments}"
       if turk.completed_assignments == turk.hit_num_assignments
         hit.dispose!
         turk.complete = true
@@ -197,13 +200,24 @@ module Turkee
       end
       nil
     end
+    
+    # Returns custom URL if opts[:form_url] is specified.  Otherwise, builds the default url from the model's :new route    
+    def self.build_url(host, model, params, opts)
+      if opts[:form_url]
+        full_url(opts[:form_url], params)
+      else 
+        form_url(host, model, params)
+      end
+    end
 
+    # Returns the default url of the model's :new route
     def self.form_url(host, typ, params = {})
       @app ||= ActionController::Integration::Session.new(Rails.application)
       url = (host + @app.send("new_#{typ.to_s.underscore}_path"))
       full_url(url, params)
     end
 
+    # Appends params to the url as a query string
     def self.full_url(u, params)
       url = u
       url = "#{u}?#{params.to_query}" unless params.empty?

data/spec/spec_helper.rb

@@ -22,6 +22,7 @@ ActiveRecord::Schema.define(:version => 1) do
     t.decimal  "hit_reward", :precision => 10, :scale => 2
     t.integer  "hit_num_assignments"
     t.integer  "hit_lifetime"
+    t.integer  "hit_duration"
     t.string   "form_url"
     t.boolean  "complete"
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turkee
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-09 00:00:00.000000000Z
+date: 2012-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lockfile
-  requirement: &70100423349140 !ruby/object:Gem::Requirement
+  requirement: &70217997125780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70100423349140
+  version_requirements: *70217997125780
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70100423348080 !ruby/object:Gem::Requirement
+  requirement: &70217997123680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,21 +32,21 @@ dependencies:
         version: 3.1.1
   type: :runtime
   prerelease: false
-  version_requirements: *70100423348080
+  version_requirements: *70217997123680
 - !ruby/object:Gem::Dependency
   name: rturk
-  requirement: &70100423347560 !ruby/object:Gem::Requirement
+  requirement: &70217997120760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: 2.4.0
   type: :runtime
   prerelease: false
-  version_requirements: *70100423347560
+  version_requirements: *70217997120760
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &70100423347160 !ruby/object:Gem::Requirement
+  requirement: &70217997119040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70100423347160
+  version_requirements: *70217997119040
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &70100423346420 !ruby/object:Gem::Requirement
+  requirement: &70217997114560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70100423346420
+  version_requirements: *70217997114560
 - !ruby/object:Gem::Dependency
   name: factory_girl
-  requirement: &70100423345240 !ruby/object:Gem::Requirement
+  requirement: &70217997110980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: 1.3.2
   type: :development
   prerelease: false
-  version_requirements: *70100423345240
+  version_requirements: *70217997110980
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70100423343480 !ruby/object:Gem::Requirement
+  requirement: &70217997110120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,7 +87,7 @@ dependencies:
         version: 2.5.0
   type: :development
   prerelease: false
-  version_requirements: *70100423343480
+  version_requirements: *70217997110120
 description: Turkee will help you to create your Rails forms, post the HITs, and retrieve
   the user entered values from Mechanical Turk.
 email: jjones@aantix.com
@@ -103,6 +103,8 @@ files:
 - lib/generators/turkee/templates/turkee_imported_assignments.rb.erb
 - lib/generators/turkee/templates/add_completed_tasks.rb.erb
 - lib/generators/turkee/templates/turkee_migration.rb.erb
+- lib/generators/turkee/templates/add_imported_assignment_details.rb.erb
+- lib/generators/turkee/templates/add_hit_duration.rb.erb
 - lib/generators/turkee/turkee_generator.rb
 - lib/tasks/turkee.rb
 - lib/turkee.rb