bamboozled-gitlab 0.2.9

data/examples/employees_over_time.rb

@@ -0,0 +1,53 @@
+# File: employees_over_time.rb
+# Date Created: 2014-08-07
+# Author(s): Mark Rickert (mjar81@gmail.com) / Skookum Digital Works (http://skookum.com)
+#
+# Description: This example script grabs all the historical users in BambooHR
+# and determines how many employees there were at the end of each of the
+# previous 12 months.
+#
+# Run this script with: ruby employees_over_time.rb
+
+require '../lib/bamboozled/'
+require 'active_support'
+require 'active_support/core_ext/integer'
+require 'active_support/core_ext/date'
+
+@subdomain = 'your_subdomain'
+@api_key   = 'your_api_key'
+
+def main
+  client = Bamboozled.client(subdomain:@subdomain, api_key:@api_key)
+
+  # Get all users in the system. Even terminated employees.
+  # Calling client.employee.all only gets active users.
+  employee_data = client.meta.users.map do |e|
+    # Sometimes employees are in the system but don't have an emaployee ID.
+    # This makes them unqueryable and they're usually a duplicate or admin user.
+    next unless e[:employeeId]
+
+    # Get each employee's start_date and termination date
+    client.employee.find(e[:employeeId], %w(displayName department hireDate terminationDate))
+  end.compact.reject{|e| e['hireDate'] == '0000-00-00'}
+
+  # Start from today and go back 12 months and print out how many employees were
+  # at the company on that date.
+  d = (Date.today - 1.month).end_of_month
+  12.times do
+    d = (d - 1.month).end_of_month
+    puts "#{d},#{employees_on_date(employee_data, d)}"
+  end
+
+end
+
+# Simple method to compare hire and termination dates and get the count of employees
+# who were with the company on that day.
+def employees_on_date(employees, date)
+  employees.map do |e|
+    hire_date = Date.parse(e["hireDate"]) rescue nil
+    termination_date = Date.parse(e["terminationDate"]) rescue nil
+    (hire_date <= date && (termination_date.nil? || termination_date >= date)) ? 1 : 0
+  end.inject(:+)
+end
+
+main

data/lib/bamboozled.rb

@@ -0,0 +1,24 @@
+require "httparty"
+require "json"
+require "uri"
+
+require "bamboozled/version"
+require "bamboozled/base"
+require "bamboozled/errors"
+require "bamboozled/ext/yesno"
+require "bamboozled/api/base"
+require "bamboozled/api/field_collection"
+require "bamboozled/api/employee"
+require "bamboozled/api/report"
+require "bamboozled/api/time_off"
+require "bamboozled/api/time_tracking"
+require "bamboozled/api/meta"
+
+module Bamboozled
+  class << self
+    # Creates a standard client that will raise all errors it encounters
+    def client(subdomain: nil, api_key: nil, httparty_options: {})
+      Bamboozled::Base.new(subdomain: subdomain, api_key: api_key, httparty_options: httparty_options)
+    end
+  end
+end

data/lib/bamboozled/api/base.rb

@@ -0,0 +1,101 @@
+require 'json'
+require "time"
+
+module Bamboozled
+  module API
+    class Base
+      attr_reader :subdomain, :api_key
+
+      def initialize(subdomain, api_key, httparty_options = {})
+        @subdomain = subdomain
+        @api_key = api_key
+        @httparty_options = httparty_options || {}
+      end
+
+      protected
+
+      def post_file(path, options)
+        response = HTTParty.post(
+          "#{path_prefix}#{path}",
+          multipart: true,
+          basic_auth: auth,
+          body: options
+        )
+        parse_response(response, options)
+      end
+
+      def request(method, path, options = {})
+        params = {
+          path:    path,
+          options: options,
+          method:  method
+        }
+
+        httparty_options = @httparty_options.merge({
+          query:  options[:query],
+          body:   options[:body],
+          format: :plain,
+          basic_auth: auth,
+          headers: {
+            "Accept"       => "application/json",
+            "User-Agent"   => "Bamboozled/#{Bamboozled::VERSION}"
+          }.update(options[:headers] || {})
+        })
+
+        response = HTTParty.send(method, "#{path_prefix}#{path}", httparty_options)
+        params[:response] = response.inspect.to_s
+        parse_response(response, params)
+      end
+
+      private
+
+      def auth
+        { username: api_key, password: "x" }
+      end
+
+      def path_prefix
+        "https://api.bamboohr.com/api/gateway.php/#{subdomain}/v1/"
+      end
+
+      def parse_response(response, params)
+        case response.code
+        when 200..201
+          begin
+            if response.body.to_s.empty?
+              { "headers" => response.headers }
+            else
+              JSON.parse(response)
+            end
+          rescue
+            typecast = options.fetch(:typecast_values, true)
+            MultiXml.parse(response,
+                           symbolize_keys: true,
+                           typecast_xml_value: typecast)
+          end
+        when 400
+          raise Bamboozled::BadRequest.new(response, params, 'The request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error.')
+        when 401
+          raise Bamboozled::AuthenticationFailed.new(response, params, 'Your API key is missing.')
+        when 403
+          raise Bamboozled::Forbidden.new(response, params, 'The application is attempting to perform an action it does not have privileges to access. Verify your API key belongs to an enabled user with the required permissions.')
+        when 404
+          raise Bamboozled::NotFound.new(response, params, 'The resource was not found with the given identifier. Either the URL given is not a valid API, or the ID of the object specified in the request is invalid.')
+        when 406
+          raise Bamboozled::NotAcceptable.new(response, params, 'The request contains references to non-existent fields.')
+        when 409
+          raise Bamboozled::Conflict.new(response, params, 'The request attempts to create a duplicate. For employees, duplicate emails are not allowed. For lists, duplicate values are not allowed.')
+        when 429
+          raise Bamboozled::LimitExceeded.new(response, params, 'The account has reached its employee limit. No additional employees could be added.')
+        when 500
+          raise Bamboozled::InternalServerError.new(response, params, 'The server encountered an error while processing your request and failed.')
+        when 502
+          raise Bamboozled::GatewayError.new(response, params, 'The load balancer or web server had trouble connecting to the Bamboo app. Please try the request again.')
+        when 503
+          raise Bamboozled::ServiceUnavailable.new(response, params, 'The service is temporarily unavailable. Please try the request again.')
+        else
+          raise Bamboozled::InformBamboo.new(response, params, 'An error occurred that we do not now how to handle. Please contact BambooHR.')
+        end
+      end
+    end
+  end
+end

data/lib/bamboozled/api/employee.rb

@@ -0,0 +1,118 @@
+module Bamboozled
+  module API
+    class Employee < Base
+
+      def all(fields = nil)
+        response = request(:get, "employees/directory")
+
+        if fields.nil? || fields == :default
+          Array(response['employees'])
+        else
+          employees = []
+          response['employees'].map{|e| e['id']}.each do |id|
+            employees << find(id, fields)
+          end
+          employees
+        end
+      end
+
+      def find(employee_id, fields = nil)
+        fields = FieldCollection.wrap(fields).to_csv
+
+        request(:get, "employees/#{employee_id}?fields=#{fields}&onlyCurrent=false")
+      end
+
+      def last_changed(date = "2011-06-05T00:00:00+00:00", type = nil)
+        query = Hash.new
+        query[:since] = date.respond_to?(:iso8601) ? date.iso8601 : date
+        query[:type] = type unless type.nil?
+
+        response = request(:get, "employees/changed", query: query)
+        response["employees"]
+      end
+
+      # Tabular data
+      [:job_info, :employment_status, :compensation, :dependents, :contacts].each do |action|
+        define_method(action.to_s) do |argument_id|
+          request(:get, "employees/#{argument_id}/tables/#{action.to_s.gsub(/_(.)/) {|e| $1.upcase}}")
+        end
+      end
+
+      def add_table_row(employee_id, table_name, table_row_data)
+        details = generate_xml(table_row_data)
+        options = {body: details}
+        request(:post, "employees/#{employee_id}/tables/#{table_name}", options)
+      end
+
+      def update_table_row(employee_id, table_name, row_id, table_row_data)
+        details = generate_xml(table_row_data)
+        options = {body: details}
+        request(:post, "employees/#{employee_id}/tables/#{table_name}/#{row_id}", options)
+      end
+
+      def table_data(employee_id, table_name)
+        request(:get, "employees/#{employee_id}/tables/#{table_name}")
+      end
+
+      def time_off_estimate(employee_id, end_date)
+        end_date = end_date.strftime("%F") unless end_date.is_a?(String)
+        request(:get, "employees/#{employee_id}/time_off/calculator?end=#{end_date}")
+      end
+
+      def photo_binary(employee_id)
+        request(:get, "employees/#{employee_id}/photo/small")
+      end
+
+      def photo_url(employee)
+        if (Float(employee) rescue false)
+          e = find(employee, ['workEmail', 'homeEmail'])
+          employee = e['workEmail'].nil? ? e['homeEmail'] : e['workEmail']
+        end
+
+        digest = Digest::MD5.new
+        digest.update(employee.strip.downcase)
+        "http://#{@subdomain}.bamboohr.com/employees/photos/?h=#{digest}"
+      end
+
+      def add(employee_details)
+        details = generate_xml(employee_details)
+        options = {body: details}
+
+        request(:post, "employees/", options)
+      end
+
+      def update(bamboo_id, employee_details)
+        details = generate_xml(employee_details)
+        options = { body: details }
+
+        request(:post, "employees/#{bamboo_id}", options)
+      end
+
+      def files(employee_id)
+        request(:get, "employees/#{employee_id}/files/view/")
+      end
+
+      def add_file(employee_id, file_details)
+        post_file("employees/#{employee_id}/files", file_details)
+      end
+
+      private
+
+      def generate_xml(employee_details)
+        "".tap do |xml|
+          xml << "<employee>"
+          employee_details.each do |k, v|
+            if v.is_a?(Hash)
+              value = Integer(v[:value], exception: false) ? v[:value] : v[:value].encode(xml: :text)
+              xml <<  "<field id='#{k}' currency='#{v[:currency]}'>#{value}</field>"
+            else
+              value = Integer(v, exception: false) ? v : v.encode(xml: :text)
+              xml << "<field id='#{k}'>#{value}</field>"
+            end
+          end
+          xml << "</employee>"
+        end
+      end
+    end
+  end
+end

data/lib/bamboozled/api/field_collection.rb

@@ -0,0 +1,107 @@
+module Bamboozled
+  module API
+    class FieldCollection
+      def self.wrap(fields)
+        fields = all_names if fields == :all
+        fields = fields.split(",") if fields.is_a?(String)
+        new(fields)
+      end
+
+      def self.all_names # rubocop:disable Metrics/MethodLength
+        %w[
+          address1
+          address2
+          age
+          bestEmail
+          birthday
+          bonusAmount
+          bonusComment
+          bonusDate
+          bonusReason
+          city
+          commisionDate
+          commissionAmount
+          commissionComment
+          commissionDate
+          country
+          dateOfBirth
+          department
+          displayName
+          division
+          eeo
+          employeeNumber
+          employmentHistoryStatus
+          ethnicity
+          exempt
+          firstName
+          flsaCode
+          fullName1
+          fullName2
+          fullName3
+          fullName4
+          fullName5
+          gender
+          hireDate
+          homeEmail
+          homePhone
+          id
+          includeInPayroll
+          isPhotoUploaded
+          jobTitle
+          lastChanged
+          lastName
+          location
+          maritalStatus
+          middleName
+          mobilePhone
+          originalHireDate
+          paidPer
+          payChangeReason
+          payFrequency
+          payGroup
+          payGroupId
+          payPer
+          payRate
+          payRateEffectiveDate
+          paySchedule
+          payScheduleId
+          payType
+          preferredName
+          sin
+          ssn
+          standardHoursPerWeek
+          state
+          stateCode
+          status
+          supervisor
+          supervisorEId
+          supervisorId
+          terminationDate
+          workEmail
+          workPhone
+          workPhoneExtension
+          workPhonePlusExtension
+          zipcode
+        ]
+      end
+
+      def initialize(fields)
+        self.fields = fields || []
+      end
+
+      def to_csv
+        fields.join(",")
+      end
+
+      def to_xml
+        "<fields>" +
+          fields.map { |field| "<field id=\"#{field}\" />" }.join +
+          "</fields>"
+      end
+
+      private
+
+      attr_accessor :fields
+    end
+  end
+end

data/lib/bamboozled/api/meta.rb

@@ -0,0 +1,25 @@
+module Bamboozled
+  module API
+    class Meta < Base
+      def users
+        request(:get, "meta/users").values
+      end
+
+      def fields
+        request(:get, "meta/fields")
+      end
+
+      def lists
+        request(:get, "meta/lists")
+      end
+
+      def tables
+        request(
+          :get, "meta/tables",
+          typecast_values: false)
+      end
+
+    end
+  end
+end
+

data/lib/bamboozled/api/report.rb

@@ -0,0 +1,20 @@
+module Bamboozled
+  module API
+    class Report < Base
+
+      def find(number, format = "JSON", fd_param = true)
+        response = request(:get, "reports/#{number}?format=#{format.upcase}&fd=#{fd_param.yesno}")
+        response["employees"]
+      end
+
+      def custom(fields, format = "JSON", only_current = false)
+        options = {
+          body: "<report>#{FieldCollection.wrap(fields).to_xml}</report>"
+        }
+
+        response = request(:post, "reports/custom?format=#{format.upcase}&onlyCurrent=#{only_current}", options)
+        response["employees"]
+      end
+    end
+  end
+end