rwojsznis/workable

Simple workable.com API wrapper

Workable

Dead-simple Ruby API client for workable.com. No extra runtime dependencies.

Uses v3 API provided by workable.

Installation

Add this line to your application's Gemfile:

gem 'workable'

And then execute:

$ bundle

Or install it yourself as:

$ gem install workable

Usage

Gem covers all endpoints mentioned in official v3 workable API documentation (https://workable.readme.io/docs/).

Example

For detailed documentation please refer to: http://www.rubydoc.info/gems/workable

client = Workable::Client.new(api_key: 'api_key', subdomain: 'your_subdomain')

# takes optional phase argument (string): 'published' (default), 'draft', 'closed' or 'archived'
client.jobs # => Workable::Collection

# Workable::Collection example
jobs = client.jobs
loop do
  jobs.each do |job|
    # Do something with the job
  end
  break unless jobs.next_page?
  jobs = jobs.fetch_next_page
end

shortcode = client.jobs.first["shortcode"]

# API queries are not cached (at all) - it's up to you to cache results one way or another

client.stages     # => Array of hashes
client.recruiters # => Array of hashes
client.members    # => Array of hashes

client.job_details(shortcode)    # => Hash
client.job_questions(shortcode)  # => Array of hashes
client.job_application_form(shortcode) # => Hash
client.job_candidates(shortcode, :stage => stage_slug, :limit => 100) # => Array of hashes:
#   if given stage limits to given stage
#   if given limit lists the last `limit` added candidates

# Adding candidates - candidate is a Hash as described in:
#   http://resources.workable.com/add-candidates-using-api

client.create_job_candidate(candidate, shortcode, stage_slug) # => Hash (stage_slug is optional)

# managing candidates
client.disqualify(candidate_id, member_id, reason)
client.revert(candidate_id, member_id) # reverts disqualification
client.copy(candidate_id, member_id, shortcode, stage)
client.relocate(candidate_id, member_id, shortcode, stage)
client.move(candidate_id, member_id, stage)
client.create_rating(candidate_id, member_id, comment, score)
client.create_comment(candidate_id, member_id, comment_text, attachment)

# Possible errors (each one inherits from Workable::Errors::WorkableError)
Workable::Errors::InvalidConfiguration # missing api_key / subdomain
Workable::Errors::NotAuthorized   # wrong api key
Workable::Errors::InvalidResponse # something went wrong during the request?
Workable::Errors::NotFound        # 404 from workable
Workable::Errors::RequestToLong   # When the requested result takes to long to calculate, try limiting your query

Transformations

When creating Client you can specify extra methods/Procs for automated transformation of results and input.

Example

client = Workable::Client.new(
  api_key: 'api_key',
  subdomain: 'your_subdomain'
  transform_to: {
    candidate: OpenStruct.method(:new)
  }
  transform_from: {
    candidate: Proc.new { |input| input.to_h }
  }
)

The first transformation to will make the Client return OpenStruct.new(result) instead of just plain result everywhere where candidate is expected. In case of Arrays the transformation will be applied to every element.

The second transformation from will expect an instance of OpenStruct instead of raw data and will execute the to_h on the instance before sending it to workable API.

The rest of result will be returned as Arrays/Hashes, no transformation will be applied if not defined - raw data will be returned.

Contributing

1. Fork it ( https://github.com/emq/workable/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request