Ruby Gem

Installation

As a Gem

gem install shared_workforce

Using Bundler

Add the following to your Gemfile, then run bundle install

gem "shared_workforce"

Using Rails 2.3.x

Add the gem to your environment.rb:

config.gem "shared_workforce"

Configuration

Client Options

api_key: Given to you when you sign up. You can find it in your app settings.
callback_host: Forms the basis for callbacks to your server.

Configuration with Rails

In config/initializers/shared_workforce.rb

SharedWorkforce.configure do |config|
  config.callback_host = "http://your-website-host"
  config.api_key = "acdc30b2-14c5-46ee-ba35-11d50edc65ec"
end

Configuration with Other Ruby Apps

If you're not using Rails, simply require the gem or include it in your Gemfile, set the client configuration settings as above.

Defining Tasks

In this example, we might have an uploaded photo that we would like to moderate.

app/tasks/tag_photo.rb:

class TagPhotoTask
  include SharedWorkforce::Task
  
  title 'Please tag our photo'
  instruction 'Take a good look at this photo. Tick all that apply.'
  
  answer_type :tags
  answer_options ['Offensive', 'Contains Nudity', 'Blurry or low quality', 'Upside down or sideways']
  
  responses_required 1
  
  on_success :moderate_photo
  
  def setup(photo)
    self.image_url = photo.url
  end
  
  def moderate_photo(photo, responses)
    responses # => [{:answer=>['Offensive', 'Contains Nudity']}]
    # custom actions based on responses
    …
  end
end

Task Values

Class level attributes are a handy way of defining data that doesn't change between each task. Attributes set on the instance will always override attributes set at the class level.

In most cases, you'll want to explicitly set default task values at the class level (like title and instruction). Setting text and image_url values (i.e. the content in question) will usually be done in the setup method.

title: What you'd like to call the task. e.g. Check gender from photo.
<string>
instruction: The actions a worker should take to complete the task. e.g. Look at this photo. Is the person male or female?
<string>
answer_type: One of the following: "choice", "tags", "edit", "crop" or "rotate".
<string>
answer_options: The options for the worker to choose from e.g. ["Male", "Female"]. Not required when answer_type is "edit".
<array_of_strings>
responses_required: The number of times you'd like to have the task completed
<integer>
replace: Specifies whether to overwrite/update any existing tasks with the same name
<boolean>
text: The text in question (to be included in the task content).
<string>
image_url: The url of an image to include in the task content. sharedworkforce.com must be authorised to see the photo.
<string>
image_crop_ratio: The ratio to use when cropping an image. (e.g. a value of 1 would be square)
<integer>
on_success: Callback when a worker responds a task.
<symbol>
on_failure: Callback when a worker is unable to respond to a task e.g. the photo does not load.
<symbol>
on_complete: Callback when a task is completed regardless of whether a worker was able to respond to it.
<symbol>

Requesting Tasks

Publishing a task is simply a case of creating a new TagPhotoTask object, passing in the relevant photo as an argument. In this way, the photo object is passed to the setup method to aid initialization.

If you are using Rails, requesting a task could be done in an after_save callback on a model:

class Photo < ActiveRecord::Base

  after_create :request_tags

  def request_tags
    TagPhotoTask.create(self)
  end
end

Collecting Responses

When your responses are received by your app, your on_success method in your task definition will be called.

During development

A rake task is provided to collect the task responses:

$ rake sw:collect

In production

The callback host you configured will be used to send the responses to your app when they are ready.