Add applicant tracking API interface

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### New Features
 
+* [#62](https://github.com/Skookum/bamboozled/issues/62): Add applicant tracking API interface ([@danhealy][])
+
 ### Changes
 
 ### Bug Fixes
@@ -46,3 +48,4 @@
 [@chrisman]: https://github.com/chrisman
 [@ivanovv]: https://github.com/ivanovv
 [@nlively]: https://github.com/nlively
+[@danhealy]: https://github.com/danhealy

README.md

@@ -136,6 +136,31 @@ client.report.custom(fields, format = "JSON")
 client.report.find(report_number, format = "JSON", fd = true)
 ```
 
+### Applicant Tracking System
+The ATS API is currently in **beta**. Please note that BambooHR may make breaking changes without
+warning. Refer to the [documentation](https://www.bamboohr.com/api/documentation/ats.php) for
+details.
+
+```ruby
+# Get a list of job summaries
+client.applicant_tracking.job_summaries
+
+# Get a list of applications, following pagination
+client.applicant_tracking.applications(page_limit: 10)
+
+# Get the details of an application
+client.applicant_tracking.application(123)
+
+# Add comments to an application
+client.applicant_tracking.add_comment(123, "Great Application!")
+
+# Get a list of statuses for a company
+client.applicant_tracking.statuses
+
+# Change applicant's status
+client.applicant_tracking.change_status(123, 3)
+```
+
 ### Metadata
 
 ```ruby

lib/bamboozled.rb

@@ -8,6 +8,7 @@
 require "bamboozled/ext/yesno"
 require "bamboozled/api/base"
 require "bamboozled/api/field_collection"
+require "bamboozled/api/applicant_tracking"
 require "bamboozled/api/employee"
 require "bamboozled/api/report"
 require "bamboozled/api/time_off"

lib/bamboozled/api/applicant_tracking.rb

@@ -0,0 +1,77 @@
+# Implement endpoints for Bamboo HR's Applicant Tracking System
+# https://www.bamboohr.com/api/documentation/ats.php
+module Bamboozled
+  module API
+    class ApplicantTracking < Base
+      APPLICATION_STATUS_GROUPS = %w[ALL ALL_ACTIVE NEW ACTIVE INACTIVE HIRED].freeze
+
+      JOB_STATUS_GROUPS = [
+        "ALL", "DRAFT_AND_OPEN", "Open", "Filled", "Draft", "Deleted", "On Hold", "Canceled"
+      ].freeze
+
+      # Get a list of job summaries -- GET /jobs
+      def job_summaries(params = {}) # rubocop:disable Style/OptionHash
+        query = {
+          "statusGroups": "ALL",     # JOB_STATUS_GROUPS
+          "sortBy":       "created", # "count", "title", "lead", "created", "status"
+          "sortOrder":    "ASC"      # "ASC", "DESC"
+        }.merge(params)
+
+        request(:get, "applicant_tracking/jobs", query: query)
+      end
+
+      # Get a list of applications, following pagination -- GET /applications
+      def applications(params = {}) # rubocop:disable Style/OptionHash
+        page_limit = params.delete(:page_limit) { 1 }
+
+        applications_array = []
+        1.upto page_limit do |i|
+          response = request_applications(params.merge(page: i))
+          applications_array += response["applications"]
+          break if response["paginationComplete"]
+        end
+        applications_array
+      end
+
+      # Get the details of an application -- GET /applications/:id
+      def application(applicant_id)
+        request(:get, "applicant_tracking/applications/#{applicant_id}")
+      end
+
+      # Add comments to an application -- POST /applications/:id/comments
+      def add_comment(applicant_id, comment)
+        details = { type: "comment", comment: comment }.to_json
+        options = { body: details, headers: { "Content-Type" => "application/json" } }
+
+        request(:post, "applicant_tracking/applications/#{applicant_id}/comments", options)
+      end
+
+      # Get a list of statuses for a company -- GET /statuses
+      def statuses
+        request(:get, "applicant_tracking/statuses")
+      end
+
+      # Change applicant's status -- POST /applications/:id/status
+      def change_status(applicant_id, status_id)
+        details = { status: status_id.to_i }.to_json
+        options = { body: details, headers: { "Content-Type" => "application/json" } }
+
+        request(:post, "applicant_tracking/applications/#{applicant_id}/status", options)
+      end
+
+      protected
+
+      def request_applications(params = {}) # rubocop:disable Style/OptionHash
+        # Also supported:
+        # page, jobId, applicationStatusId, applicationStatus (APPLICATION_STATUS_GROUPS),
+        # jobStatusGroups (JOB_STATUS_GROUPS), searchString
+        query = {
+          "sortBy":    "created_date", # "first_name", "job_title", "rating", "phone", "status", "last_updated", "created_date"
+          "sortOrder": "ASC"           # "ASC", "DESC"
+        }.merge(params)
+
+        request(:get, "applicant_tracking/applications", query: query)
+      end
+    end
+  end
+end

lib/bamboozled/base.rb

@@ -27,5 +27,9 @@ def time_off
     def time_tracking
       @time_tracking ||= Bamboozled::API::TimeTracking.new(@subdomain, @api_key, @httparty_options)
     end
+
+    def applicant_tracking
+      @applicant_tracking ||= Bamboozled::API::ApplicantTracking.new(@subdomain, @api_key, @httparty_options)
+    end
   end
 end

spec/fixtures/applicant_statuses.json

@@ -0,0 +1,177 @@
+HTTP/1.1 200 OK
+content-type: application/json; charset=utf-8
+date: Tue, 28 May 2019 19:25:35 UTC
+
+[
+    {
+        "code": "NEW",
+        "description": null,
+        "enabled": true,
+        "id": "1",
+        "manageable": false,
+        "name": "New",
+        "translatedName": "New"
+    },
+    {
+        "code": "REVIEWED",
+        "description": null,
+        "enabled": true,
+        "id": "2",
+        "manageable": false,
+        "name": "Reviewed",
+        "translatedName": "Reviewed"
+    },
+    {
+        "code": "SCHEDPHONE",
+        "description": null,
+        "enabled": true,
+        "id": "3",
+        "manageable": false,
+        "name": "Schedule Phone Screen",
+        "translatedName": "Schedule Phone Screen"
+    },
+    {
+        "code": "PHONED",
+        "description": null,
+        "enabled": true,
+        "id": "4",
+        "manageable": false,
+        "name": "Phone Screened",
+        "translatedName": "Phone Screened"
+    },
+    {
+        "code": "SCHEDINT",
+        "description": null,
+        "enabled": true,
+        "id": "5",
+        "manageable": false,
+        "name": "Schedule Interview",
+        "translatedName": "Schedule Interview"
+    },
+    {
+        "code": "INTERVIEW",
+        "description": null,
+        "enabled": true,
+        "id": "6",
+        "manageable": false,
+        "name": "Interviewed",
+        "translatedName": "Interviewed"
+    },
+    {
+        "code": "ONHOLD",
+        "description": null,
+        "enabled": true,
+        "id": "7",
+        "manageable": false,
+        "name": "Put on Hold",
+        "translatedName": "Put on Hold"
+    },
+    {
+        "code": "REFCHECK",
+        "description": null,
+        "enabled": true,
+        "id": "8",
+        "manageable": false,
+        "name": "Checking References",
+        "translatedName": "Checking References"
+    },
+    {
+        "code": "OFFER",
+        "description": null,
+        "enabled": false,
+        "id": "9",
+        "manageable": false,
+        "name": "Made an Offer",
+        "translatedName": "Made an Offer"
+    },
+    {
+        "code": "NOFIT",
+        "description": null,
+        "enabled": true,
+        "id": "10",
+        "manageable": false,
+        "name": "Not a Fit",
+        "translatedName": "Not a Fit"
+    },
+    {
+        "code": "DECLINED",
+        "description": null,
+        "enabled": true,
+        "id": "11",
+        "manageable": false,
+        "name": "Declined Offer",
+        "translatedName": "Declined Offer"
+    },
+    {
+        "code": "NOQUAL",
+        "description": null,
+        "enabled": true,
+        "id": "12",
+        "manageable": false,
+        "name": "Not Qualified",
+        "translatedName": "Not Qualified"
+    },
+    {
+        "code": "OVERQUAL",
+        "description": null,
+        "enabled": true,
+        "id": "13",
+        "manageable": false,
+        "name": "Over Qualified",
+        "translatedName": "Over Qualified"
+    },
+    {
+        "code": "POACHED",
+        "description": null,
+        "enabled": true,
+        "id": "14",
+        "manageable": false,
+        "name": "Hired Elsewhere",
+        "translatedName": "Hired Elsewhere"
+    },
+    {
+        "code": "HIRED",
+        "description": null,
+        "enabled": true,
+        "id": "15",
+        "manageable": false,
+        "name": "Hired",
+        "translatedName": "Hired"
+    },
+    {
+        "code": "OLSENT",
+        "description": null,
+        "enabled": true,
+        "id": "16",
+        "manageable": false,
+        "name": "Offer Sent",
+        "translatedName": "Offer Sent"
+    },
+    {
+        "code": "OLSIGNED",
+        "description": null,
+        "enabled": true,
+        "id": "17",
+        "manageable": false,
+        "name": "Offer Signed",
+        "translatedName": "Offer Signed"
+    },
+    {
+        "code": "DELETED",
+        "description": null,
+        "enabled": false,
+        "id": "18",
+        "manageable": false,
+        "name": "Deleted",
+        "translatedName": "Deleted"
+    },
+    {
+        "code": "MOVED",
+        "description": null,
+        "enabled": false,
+        "id": "19",
+        "manageable": false,
+        "name": "Moved",
+        "translatedName": "Moved"
+    }
+]