active_force 0.17.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 741f33a6c27d6bc11eaaa7655c2a7fb2ecc772f93d298e608866840b82e94321
-  data.tar.gz: 465abe2c572e35dc61817ab1bf8ac1d6d0e35e6f26eb2e933af3ed1781c2c68a
+  metadata.gz: 38ef881c292f8ecb12be07a0471f759a06b9155af5e3a49c26dbb69e024db87f
+  data.tar.gz: 6a209feb04dc0c6a192c084a95c2e55c64696bbb54636496fc98dc8c56c7b653
 SHA512:
-  metadata.gz: 376ab891dc3a0bf92f030dd3b756aa900c8091bfd42b3424ef1c832ecc2ac14384785f96eeadc20764f22ee02315753cba10c4b0aec067294e2175a09754dc60
-  data.tar.gz: f60cf65275aaee5e96ebb173cc0718cbc663b3cced951bccf8b417df1029055606be56bdf82617e689130d68687b8ce8f8227acab83314c54715e95e6ca28629
+  metadata.gz: 814f0f4844f94acea113a4eabf1e3afd366b2b00255fe5bcca5ccfccb0f5d862651548302373d078a7c070422d6db6c8cf971f33112c360f0d43f133d500c98a
+  data.tar.gz: 48f595e34749ec49adeaeb8320c407911f8841d83fcd433cdd5e7e9bc5b6b8f37d01a0f30f6a96610d91949ab8e30e2cb4b0c3f9aa18692447fc31ed6d4b75fb

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Not released
 
+## 0.19.0
+
+- Bulk API methods. (https://github.com/Beyond-Finance/active_force/pull/65)
+
+## 0.18.0
+
+- Fix eager loading of scoped associations. (https://github.com/Beyond-Finance/active_force/pull/67)
+- Adding `.blank?`, `.present?`, and `.any?` delegators to `ActiveQuery`. (https://github.com/Beyond-Finance/active_force/pull/68)
+- Adding `update` and `update!` class methods on `SObject`. (https://github.com/Beyond-Finance/active_force/pull/66)
+- Allow an argument to `last` allowing the query to select the `last(n)` records. Default is 1. (https://github.com/Beyond-Finance/active_force/pull/66)
+
 ## 0.17.0
 
 - Fix bug with has_many queries due to query method chaining mutating in-place (https://github.com/Beyond-Finance/active_force/pull/10)

data/README.md

@@ -194,7 +194,7 @@ Comment.includes(:post)
 
 It is possible to eager load multi level associations
 
-In order to utilize multi level eager loads, the API version should be set to 58.0 or higher when instantiating a Restforce client 
+In order to utilize multi level eager loads, the API version should be set to 58.0 or higher when instantiating a Restforce client
 
 ```ruby
 Restforce.new({api_version: '58.0'})
@@ -212,8 +212,8 @@ Comment.includes({post: {owner: :account}})
 Summing the values of a column:
 ```ruby
 Transaction.where(offer_id: 'ABD832024').sum(:amount)
-#=> This will query "SELECT SUM(Amount__c) 
-#                    FROM Transaction__c 
+#=> This will query "SELECT SUM(Amount__c)
+#                    FROM Transaction__c
 #                    WHERE offer_id = 'ABD832024'"
 ```
 
@@ -249,6 +249,22 @@ accounts = Account.where(web_enabled: 1).limit(2)
 with data from another API, and will only query the other API once.
 ```
 
+### Bulk Jobs
+
+For more information about usage and limits of the Salesforce Bulk API see the [docs][4].
+
+Convenience class methods have been added to `ActiveForce::SObject` to make it possible to utilize the Salesforce Bulk API v2.0.
+The methods are: `bulk_insert_all`, `bulk_update_all`, & `bulk_delete_all`.  They all expect input as an Array of attributes as a Hash:
+```ruby
+[
+  { id: '11111111', attribute1: 'value1', attribute2: 'value2'},
+  { id: '22222222', attribute1: 'value3', attribute2: 'value4'},
+]
+```
+The attributes will be mapped back to what's expected on the SF side automatically. The response is a `ActiveForce::Bulk::JobResult` object
+which can access `successful` & `failed` results, has some `stats`, and the original `job` object that was used to create and process the
+Bulk job.
+
 ### Model generator
 
 When using rails, you can generate a model with all the fields you have on your SFDC table by running:
@@ -268,4 +284,5 @@ When using rails, you can generate a model with all the fields you have on your
  [1]: http://www.salesforce.com
  [2]: https://github.com/ejholmes/restforce
  [3]: https://github.com/bkeepers/dotenv
+ [4]: https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/bulk_api_2_0.htm
 

data/lib/active_force/active_query.rb

@@ -21,9 +21,9 @@ module ActiveForce
     attr_reader :sobject, :association_mapping, :belongs_to_association_mapping
 
     def_delegators :sobject, :sfdc_client, :build, :table_name, :mappings
-    def_delegators :to_a, :each, :map, :inspect, :pluck, :each_with_object
+    def_delegators :to_a, :blank?, :present?, :any?, :each, :map, :inspect, :pluck, :each_with_object
 
-    def initialize (sobject, custom_table_name = nil)
+    def initialize(sobject, custom_table_name = nil)
       @sobject = sobject
       @association_mapping = {}
       @belongs_to_association_mapping = {}

data/lib/active_force/association/association.rb

@@ -26,6 +26,14 @@ module ActiveForce
         options[:relationship_name] || relation_model.to_s.constantize.table_name
       end
 
+      def scoped_as
+        options[:scoped_as] || nil
+      end
+
+      def scoped?
+        options[:scoped_as].present?
+      end
+
       ###
       # Does this association's relation_model represent
       # +sfdc_table_name+? Examples of +sfdc_table_name+

data/lib/active_force/association/eager_load_projection_builder.rb

@@ -1,5 +1,6 @@
 module ActiveForce
   module Association
+    class InvalidEagerLoadAssociation < StandardError; end
     class EagerLoadProjectionBuilder
       class << self
         def build(association, parent_association_field = nil)
@@ -34,6 +35,13 @@ module ActiveForce
       def projections
         raise "Must define #{self.class.name}#projections"
       end
+
+      def apply_association_scope(query)
+        return query unless association.scoped?
+        raise InvalidEagerLoadAssociation, "Cannot use scopes that expect arguments: #{association.relation_name}" if association.scoped_as.arity.positive?
+
+        query.instance_exec(&association.scoped_as)
+      end
     end
 
     class HasManyAssociationProjectionBuilder < AbstractProjectionBuilder
@@ -43,17 +51,17 @@ module ActiveForce
       # to be pluralized
       def projections
         relationship_name = association.sfdc_association_field
-        query = Query.new relationship_name
+        query = ActiveQuery.new(association.relation_model, relationship_name)
         query.fields association.relation_model.fields
-        ["(#{query.to_s})"]
+        ["(#{apply_association_scope(query).to_s})"]
       end
     end
 
     class HasOneAssociationProjectionBuilder < AbstractProjectionBuilder
       def projections
-        query = Query.new association.sfdc_association_field
+        query = ActiveQuery.new(association.relation_model, association.sfdc_association_field)
         query.fields association.relation_model.fields
-        ["(#{query.to_s})"]
+        ["(#{apply_association_scope(query).to_s})"]
       end
     end
 

data/lib/active_force/bulk/job.rb

@@ -0,0 +1,136 @@
+require 'active_force/bulk/job_result'
+
+module ActiveForce
+  module Bulk
+    class Job
+      attr_reader :operation, :records, :state, :object, :content_url
+      attr_accessor :id
+
+      STATES = {
+        Open: 'Open',
+        UploadComplete: 'UploadComplete',
+        InProgress: 'InProgress',
+        JobComplete: 'JobComplete',
+        Failed: 'Failed',
+        Aborted: 'Aborted',
+        Deleted: 'Deleted'
+      }.freeze
+
+      OPERATIONS = %i[insert delete hardDelete update upsert]
+
+      def initialize(operation:, object:, id: nil, records: nil)
+        @operation = operation.to_sym
+        @object = object
+        @id = id
+        @records = records
+        @state = nil
+        @content_url = nil
+        initialize_state_methods
+      end
+
+      def create
+        request_body = default_job_options.merge(operation: operation, object: object)
+        response = client.post("#{ingest_path}/", request_body)
+        update_attributes_from(response)
+        response
+      end
+
+      def upload
+        headers = {"Content-Type": 'text/csv'}
+        response = client.put(content_url, records.to_csv, headers)
+        response
+      end
+
+      def result
+        ActiveForce::Bulk::JobResult.new(job: self)
+      end
+
+      def self.run(...)
+        job = new(...)
+        job.create
+        job.upload
+        job.run
+        job
+      end
+
+      def failed_results
+        client.get("#{ingest_path}/#{id}/failedResults/")
+      end
+
+      def successful_results
+        client.get("#{ingest_path}/#{id}/successfulResults/")
+      end
+
+      def info
+        response = client.get("#{ingest_path}/#{id}")
+        update_attributes_from(response)
+        response
+      end
+
+      def run
+        change_state(STATES[:UploadComplete])
+      end
+
+      def abort
+        change_state(STATES[:Aborted])
+      end
+
+      def delete
+        response = client.delete("#{ingest_path}/#{id}")
+        response
+      end
+
+      def finished?
+        job_complete? || failed? || aborted?
+      end
+
+      private
+      attr_writer :state, :object, :operation, :content_url
+
+
+      def ingest_path
+        "/services/data/v#{client.options[:api_version]}/jobs/ingest"
+      end
+
+      def client
+        @client ||= ActiveForce.sfdc_client
+      end
+
+      def default_job_options
+        {
+          columnDelimiter: 'COMMA',
+          contentType: 'CSV',
+          lineEnding: 'LF',
+        }
+      end
+
+      def change_state(value)
+        request_body = {state: value}
+        headers = {"Content-Type": "application/json"}
+        response = client.patch("#{ingest_path}/#{id}", request_body, headers)
+        update_attributes_from(response)
+        response
+      end
+
+      def update_attributes_from(response)
+        return unless response.body.present?
+
+        %i[id state object operation contentUrl].each do |attr|
+          self.send("#{attr.to_s.underscore}=", response.body[attr.to_s]) if response.body[attr.to_s].present?
+        end
+      end
+
+      # Defines question methods for various states of the job, e.g. #open?, #in_progress?, etc.
+      def initialize_state_methods
+        STATES.values.each do |state|
+          state_method = <<-STATE_METHOD
+            def #{state.to_s.underscore}?
+              @state == '#{state}'
+            end
+          STATE_METHOD
+          self.class_eval(state_method)
+        end
+      end
+    end
+  end
+end

data/lib/active_force/bulk/job_result.rb

@@ -0,0 +1,48 @@
+module ActiveForce
+  module Bulk
+    class JobResult
+      attr_reader :job, :failed, :successful, :stats, :errors
+
+      def initialize(job:)
+        @job = job
+        @stats = result_from_job_info
+        @failed = failed_results
+        @successful = successful_results
+        @errors = errors_from_failed_results
+      end
+
+      def success?
+        failed.blank? && successful.present?
+      end
+
+      private
+      attr_writer :errors, :failed, :successful
+
+      def errors_from_failed_results
+        return [] if @stats[:number_records_failed].zero? || self.failed.blank?
+
+        self.errors = self.failed.pluck('sf__Error').uniq
+      end
+
+      def failed_results
+        return [] if @stats[:number_records_failed].zero?
+
+        response = job.failed_results
+        self.failed = CSV.parse(response.body, headers: true).map(&:to_h)
+      end
+
+      def successful_results
+        response = job.successful_results
+        self.successful = CSV.parse(response.body, headers: true).map(&:to_h)
+      end
+
+      def job_info
+        job.info
+      end
+
+      def result_from_job_info
+        job_info&.body.slice('numberRecordsProcessed', 'numberRecordsFailed', 'totalProcessingTime').transform_keys { |k| k.to_s.underscore.to_sym }
+      end
+    end
+  end
+end

data/lib/active_force/bulk/records.rb

@@ -0,0 +1,25 @@
+require 'csv'
+
+module ActiveForce
+  module Bulk
+    class Records
+      attr_reader :headers, :data
+      def initialize(headers:, data:)
+        @headers = headers
+        @data = data
+      end
+
+      def to_csv
+        CSV.generate(String.new, headers: headers, write_headers: true) do |csv|
+          data.each { |row| csv << row }
+        end
+      end
+
+      def self.parse_from_attributes(records)
+        headers = records.first.keys.sort.map(&:to_s)
+        data = records.map { |r| r.sort.pluck(-1) }
+        new(headers: headers, data: data)
+      end
+    end
+  end
+end

data/lib/active_force/bulk.rb

@@ -0,0 +1,47 @@
+require 'active_force/bulk/job'
+require 'active_force/bulk/records'
+
+module ActiveForce
+  module Bulk
+    class TimeoutError < Timeout::Error; end
+    TIMEOUT_MESSAGE = 'Bulk job execution expired based on timeout of %{timeout} seconds'.freeze
+
+    def bulk_insert_all(attributes, options={})
+      run_bulk_job(:insert, attributes, options)
+    end
+
+    def bulk_update_all(attributes, options={})
+      run_bulk_job(:update, attributes, options)
+    end
+
+    def bulk_delete_all(attributes, options={})
+      run_bulk_job(:delete, attributes, options)
+    end
+
+    private
+
+    def default_options
+      {
+        timeout: 30,
+        sleep: 0.02 # short sleep so we can end our poll loop more quickly
+      }
+    end
+
+    def run_bulk_job(operation, attributes, options)
+      runtime_options = default_options.merge(options)
+      records = Records.parse_from_attributes(translate_to_sf(attributes))
+      job = Job.run(operation: operation, object: self.table_name, records: records)
+      Timeout.timeout(runtime_options[:timeout], ActiveForce::Bulk::TimeoutError, TIMEOUT_MESSAGE % runtime_options) do
+        until job.finished? do
+          job.info
+          sleep(runtime_options[:sleep])
+        end
+      end
+      job.result
+    end
+
+    def translate_to_sf(attributes)
+      attributes.map{ |r| self.mapping.translate_to_sf(r) }
+    end
+  end
+end

data/lib/active_force/query.rb

@@ -81,8 +81,8 @@ module ActiveForce
       limit 1
     end
 
-    def last
-      order("Id DESC").limit(1)
+    def last(limit = 1)
+      order("Id DESC").limit(limit)
     end
 
     def join object_query

data/lib/active_force/sobject.rb

@@ -1,6 +1,7 @@
 require 'active_model'
 require 'active_force/active_query'
 require 'active_force/association'
+require 'active_force/bulk'
 require 'active_force/mapping'
 require 'yaml'
 require 'forwardable'
@@ -19,6 +20,7 @@ module ActiveForce
     extend ActiveModel::Callbacks
     include ActiveModel::Serializers::JSON
     extend ActiveForce::Association
+    extend ActiveForce::Bulk
 
 
     define_model_callbacks :build, :create, :update, :save, :destroy
@@ -129,6 +131,14 @@ module ActiveForce
       new(args).create!
     end
 
+    def self.update(id, attributes)
+      new(attributes.merge(id: id)).update
+    end
+
+    def self.update!(id, attributes)
+      new(attributes.merge(id: id)).update!
+    end
+
     def save!
       run_callbacks :save do
         if persisted?
@@ -231,7 +241,7 @@ module ActiveForce
     end
 
     def default_attributes
-      @attributes.each_value.select do |value| 
+      @attributes.each_value.select do |value|
         value.is_a?(ActiveModel::Attribute::UserProvidedDefault) || value.instance_values["original_attribute"].is_a?(ActiveModel::Attribute::UserProvidedDefault)
       end.map(&:name)
     end

data/lib/active_force/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveForce
-  VERSION = '0.17.0'
+  VERSION = '0.19.0'
 end

data/lib/active_force.rb

@@ -3,6 +3,7 @@ require 'active_model/type/salesforce/percent'
 require 'active_force/version'
 require 'active_force/sobject'
 require 'active_force/query'
+require 'active_force/bulk'
 
 module ActiveForce
 

data/spec/active_force/active_query_spec.rb

@@ -18,7 +18,6 @@ describe ActiveForce::ActiveQuery do
     ]
   end
 
-
   before do
     allow(active_query).to receive(:sfdc_client).and_return client
     allow(active_query).to receive(:build).and_return Object.new
@@ -40,6 +39,72 @@ describe ActiveForce::ActiveQuery do
     end
   end
 
+  describe '#blank? delegation' do
+    before do
+      allow(client).to receive(:query).and_return(api_result)
+    end
+
+    context 'when there are no records' do
+      let(:api_result) { [] }
+
+      it 'returns true' do
+        result = active_query.where("Text_Label = 'foo'").blank?
+        expect(result).to be true
+      end
+    end
+
+    context 'when records are returned' do
+      it 'returns false' do
+        result = active_query.where("Text_Label = 'foo'").blank?
+        expect(result).to be false
+      end
+    end
+  end
+
+  describe '#present? delegation' do
+    before do
+      allow(client).to receive(:query).and_return(api_result)
+    end
+
+    context 'when there are no records' do
+      let(:api_result) { [] }
+
+      it 'returns false' do
+        result = active_query.where("Text_Label = 'foo'").present?
+        expect(result).to be false
+      end
+    end
+
+    context 'when there are records' do
+      it 'returns true' do
+        result = active_query.where("Text_Label = 'foo'").present?
+        expect(result).to be true
+      end
+    end
+  end
+
+  describe '#any? delegation' do
+    before do
+      allow(client).to receive(:query).and_return(api_result)
+    end
+
+    context 'when there are no records' do
+      let(:api_result) { [] }
+
+      it 'returns true' do
+        result = active_query.where("Text_Label = 'foo'").any?
+        expect(result).to be false
+      end
+    end
+
+    context 'when records are returned' do
+      it 'returns false' do
+        result = active_query.where("Text_Label = 'foo'").any?
+        expect(result).to be true
+      end
+    end
+  end
+
   describe "select only some field using mappings" do
     it "should return a query only with selected field" do
       new_query = active_query.select(:field)

data/spec/active_force/bulk/job_result_spec.rb

@@ -0,0 +1,116 @@
+require 'spec_helper'
+
+describe ActiveForce::Bulk::JobResult do
+  subject { described_class.new(job: job)}
+  let(:job) { instance_double(ActiveForce::Bulk::Job)}
+
+  let(:failed_results_response) do
+    Faraday::Response.new(status: 200, response_body: "\"sf__Id\",\"sf__Error\"\n\"45678\",\"Something failed.\"")
+  end
+
+  let(:successful_results_response) do
+    Faraday::Response.new(status: 200, response_body: "\"sf__Id\",\"sf__Error\"\n\"12354\",\"false\"\n")
+  end
+
+  let(:successful_info) do
+    {"id"=>"22222222222222",
+      "operation"=>"update",
+      "object"=>"FooBar__c",
+      "createdById"=>"11111111111111111",
+      "createdDate"=>"2023-09-22T16:39:09.000+0000",
+      "systemModstamp"=>"2023-09-22T16:39:13.000+0000",
+      "state"=>"JobComplete",
+      "concurrencyMode"=>"Parallel",
+      "contentType"=>"CSV",
+      "apiVersion"=>58.0,
+      "jobType"=>"V2Ingest",
+      "lineEnding"=>"LF",
+      "columnDelimiter"=>"COMMA",
+      "numberRecordsProcessed"=>1,
+      "numberRecordsFailed"=>0,
+      "retries"=>0,
+      "totalProcessingTime"=>713,
+      "apiActiveProcessingTime"=>323,
+      "apexProcessingTime"=>3}
+  end
+
+  let(:failed_info) do
+    {"id"=>"33333333333333",
+      "operation"=>"update",
+      "object"=>"FooBar__c",
+      "createdById"=>"11111111111111111",
+      "createdDate"=>"2023-09-22T16:39:09.000+0000",
+      "systemModstamp"=>"2023-09-22T16:39:13.000+0000",
+      "state"=>"JobComplete",
+      "concurrencyMode"=>"Parallel",
+      "contentType"=>"CSV",
+      "apiVersion"=>58.0,
+      "jobType"=>"V2Ingest",
+      "lineEnding"=>"LF",
+      "columnDelimiter"=>"COMMA",
+      "numberRecordsProcessed"=>1,
+      "numberRecordsFailed"=>1,
+      "retries"=>0,
+      "totalProcessingTime"=>713,
+      "apiActiveProcessingTime"=>323,
+      "apexProcessingTime"=>3}
+  end
+
+  let(:successful_job_info_response) do
+    Faraday::Response.new(status: 200, response_body: successful_info)
+  end
+
+  let(:failed_job_info_response) do
+    Faraday::Response.new(status: 200, response_body: failed_info)
+  end
+
+  before do
+    allow(job).to receive(:failed_results).and_return(failed_results_response)
+    allow(job).to receive(:successful_results).and_return(successful_results_response)
+    allow(job).to receive(:info).and_return(successful_job_info_response)
+  end
+
+  describe '::new' do
+    it 'uses the passed in job object to pull job info' do
+      expect(subject.stats[:total_processing_time]).to eq successful_info['totalProcessingTime']
+      expect(subject.stats[:number_records_processed]).to eq successful_info['numberRecordsProcessed']
+      expect(subject.stats[:number_records_failed]).to eq successful_info['numberRecordsFailed']
+      expect(subject.failed).to be_empty
+      expect(subject.successful.size).to eq 1
+    end
+  end
+
+  describe '#success?' do
+    context 'when no failed results' do
+      it 'returns true' do
+        expect(subject.success?).to be true
+      end
+    end
+    context 'when there are failed results' do
+      before do
+        allow(job).to receive(:info).and_return(failed_job_info_response)
+      end
+      it 'returns false' do
+        expect(subject.success?).to be false
+      end
+    end
+  end
+
+  describe '#errors' do
+    context 'when there are failed results' do
+      before do
+        allow(job).to receive(:info).and_return(failed_job_info_response)
+      end
+      it 'returns an array of errors' do
+        expect(subject.errors).to eq ['Something failed.']
+      end
+    end
+
+    context 'when there are no failed results' do
+      it 'returns an empty array' do
+        expect(subject.errors).to eq []
+      end
+    end
+  end
+end
+

data/spec/active_force/bulk/job_spec.rb

@@ -0,0 +1,113 @@
+require 'spec_helper'
+
+describe ActiveForce::Bulk::Job do
+  subject { described_class.new(**args)}
+  let(:args) { { operation: operation, object: object, id: id, records: records } }
+  let(:operation) { described_class::OPERATIONS.sample }
+  let(:object) { 'Whizbang__c' }
+  let(:id) { nil }
+  let(:records) { instance_double(ActiveForce::Bulk::Records) }
+  let(:sfdc_client) { spy(ActiveForce.sfdc_client.class)}
+  let(:state) { 'Open' }
+  let(:api_version) { '58.0' }
+  let(:ingest_url) { "/services/data/v#{api_version}/jobs/ingest" }
+
+  before do
+    allow(ActiveForce).to receive(:sfdc_client).and_return(sfdc_client)
+    allow(sfdc_client).to receive(:options).and_return({api_version: api_version})
+    allow(records).to receive(:to_csv)
+  end
+
+  describe '#finished?' do
+    let(:finished_state) { described_class::STATES.slice(:JobComplete, :Failed, :Aborted).values.sample }
+    let(:unfinished_state) { described_class::STATES.except(:JobComplete, :Failed, :Aborted).values.sample }
+
+    context 'when job is in one of the finished states' do
+      it 'returns true' do
+        job = subject
+        job.instance_variable_set(:@state, finished_state)
+        expect(job.finished?).to be true
+      end
+    end
+
+    context 'when job is NOT in one of the finished states' do
+      it 'returns false' do
+        job = subject
+        job.instance_variable_set(:@state, unfinished_state)
+        expect(job.finished?).to be false
+      end
+    end
+  end
+
+  describe '::run' do
+    let(:job) { spy(described_class)}
+
+    before do
+      allow(described_class).to receive(:new).and_return(job)
+    end
+
+    it 'creates, uploads, and runs the job via the SF API' do
+      described_class.run(**args)
+      expect(job).to have_received(:create)
+      expect(job).to have_received(:upload)
+      expect(job).to have_received(:run)
+    end
+  end
+
+  describe '#run' do
+    it 'PATCHs the job state to SF API to run the job' do
+      subject.run
+      expect(sfdc_client).to have_received(:patch).with("#{ingest_url}/#{id}", {state: described_class::STATES[:UploadComplete]}, anything)
+    end
+  end
+
+  describe '#abort' do
+    it 'PATCHs the job state to SF API to abort the job' do
+      subject.abort
+      expect(sfdc_client).to have_received(:patch).with("#{ingest_url}/#{id}", {state: described_class::STATES[:Aborted]}, anything)
+    end
+  end
+
+  describe '#delete' do
+    it 'DELETEs the job from SF API' do
+      subject.delete
+      expect(sfdc_client).to have_received(:delete).with("#{ingest_url}/#{id}")
+    end
+  end
+
+  describe '#failed_results' do
+    it 'GETs job info from SF API' do
+      subject.failed_results
+      expect(sfdc_client).to have_received(:get).with("#{ingest_url}/#{id}/failedResults/")
+    end
+  end
+
+  describe '#successful_results' do
+    it 'GETs successful results from SF API' do
+      subject.successful_results
+      expect(sfdc_client).to have_received(:get).with("#{ingest_url}/#{id}/successfulResults/")
+    end
+  end
+
+  describe '#info' do
+    it 'GETs job info from SF API' do
+      subject.info
+      expect(sfdc_client).to have_received(:get).with("#{ingest_url}/#{id}")
+    end
+  end
+
+  describe '#upload' do
+    it 'PUTs CSV to SF API to upload records to job' do
+      subject.upload
+      expect(sfdc_client).to have_received(:put).with(subject.content_url, anything, hash_including("Content-Type": 'text/csv'))
+    end
+  end
+
+  describe '#create' do
+    it 'POSTs to SF API to create a job' do
+      subject.create
+      expect(sfdc_client).to have_received(:post).with("#{ingest_url}/", hash_including(operation: operation, object: object))
+    end
+  end
+end
+

data/spec/active_force/bulk/record_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+describe ActiveForce::Bulk::Records do
+  subject { described_class.new(headers: headers, data: data)}
+  let(:headers) { %w[header1 header2] }
+  let(:data) do
+    [
+      %w[value1 value2],
+      %w[value3 value4],
+    ]
+  end
+  describe '#to_csv' do
+    it 'returns CSV with headers' do
+      expect(subject.to_csv).to eq "header1,header2\nvalue1,value2\nvalue3,value4\n"
+    end
+  end
+  describe '::parse_from_attributes' do
+    subject { described_class.parse_from_attributes(attributes) }
+    let(:attributes) do
+      [
+        { header1: 'value1', header2: 'value2'},
+        { header1: 'value3', header2: 'value4'},
+      ]
+    end
+    it 'parses array of hash attributes into Records object with headers and data' do
+      records = subject
+      expect(records).to be_a described_class
+      expect(records.headers).to eq headers
+      expect(records.data).to eq data
+    end
+  end
+end

data/spec/active_force/bulk_spec.rb

@@ -0,0 +1,110 @@
+require 'spec_helper'
+
+# Set up a new SObject to test the mixin.
+class FooBarSObject < ActiveForce::SObject
+  field :id, from: 'Id'
+  field :baz_id, from: 'Baz_id__c'
+end
+
+describe ActiveForce::Bulk do
+  subject { FooBarSObject }
+  let(:attributes) do
+    [
+      {id: 1, baz_id: 1 },
+      {id: 2, baz_id: 1 },
+      {id: 3, baz_id: 2 },
+    ]
+  end
+  let(:job) { double(ActiveForce::Bulk::Job) }
+  let(:timeout_message) { /Bulk job execution expired based on timeout of/ }
+  before do
+    allow(job).to receive(:result)
+  end
+
+  describe '::bulk_insert_all' do
+    before do
+      allow(ActiveForce::Bulk::Job).to receive(:run).with(hash_including(operation: :insert)).and_return(job)
+    end
+
+    it 'runs a bulk insert job' do
+      allow(job).to receive(:finished?).and_return(true)
+      subject.bulk_insert_all(attributes)
+    end
+
+    context 'when job takes a while to run' do
+      it 'polls job info until job is finished' do
+        allow(job).to receive(:finished?).and_return(false, false, true)
+        allow(job).to receive(:info)
+        subject.bulk_insert_all(attributes)
+      end
+    end
+
+    context 'when job run exceeds timeout' do
+      it 'raises error' do
+        allow(job).to receive(:finished?).and_return(false)
+        allow(job).to receive(:info)
+        expect do
+          subject.bulk_insert_all(attributes, timeout: 0.1)
+        end.to raise_error(ActiveForce::Bulk::TimeoutError, timeout_message)
+      end
+    end
+  end
+
+  describe '::bulk_update_all' do
+    before do
+      allow(ActiveForce::Bulk::Job).to receive(:run).with(hash_including(operation: :update)).and_return(job)
+    end
+
+    it 'runs a bulk insert job' do
+      allow(job).to receive(:finished?).and_return(true)
+      subject.bulk_update_all(attributes)
+    end
+
+    context 'when job takes a while to run' do
+      it 'polls job info until job is finished' do
+        allow(job).to receive(:finished?).and_return(false, false, true)
+        allow(job).to receive(:info)
+        subject.bulk_update_all(attributes)
+      end
+    end
+
+    context 'when job run exceeds timeout' do
+      it 'raises error' do
+        allow(job).to receive(:finished?).and_return(false)
+        allow(job).to receive(:info)
+        expect do
+          subject.bulk_update_all(attributes, timeout: 0.1)
+        end.to raise_error(ActiveForce::Bulk::TimeoutError, timeout_message)
+      end
+    end
+  end
+
+  describe '::bulk_delete_all' do
+    before do
+      allow(ActiveForce::Bulk::Job).to receive(:run).with(hash_including(operation: :delete)).and_return(job)
+    end
+
+    it 'runs a bulk insert job' do
+      allow(job).to receive(:finished?).and_return(true)
+      subject.bulk_delete_all(attributes)
+    end
+
+    context 'when job takes a while to run' do
+      it 'polls job info until job is finished' do
+        allow(job).to receive(:finished?).and_return(false, false, true)
+        allow(job).to receive(:info)
+        subject.bulk_delete_all(attributes)
+      end
+    end
+
+    context 'when job run exceeds timeout' do
+      it 'raises error' do
+        allow(job).to receive(:finished?).and_return(false)
+        allow(job).to receive(:info)
+        expect do
+          subject.bulk_delete_all(attributes, timeout: 0.1)
+        end.to raise_error(ActiveForce::Bulk::TimeoutError, timeout_message)
+      end
+    end
+  end
+end

data/spec/active_force/query_spec.rb

@@ -168,14 +168,30 @@ describe ActiveForce::Query do
   end
 
   describe '.last' do
-    it 'should return the query for the last record' do
-      expect(query.last.to_s).to eq 'SELECT Id, name, etc FROM table_name ORDER BY Id DESC LIMIT 1'
-    end
-
-    it "should not update the original query" do
-      new_query = query.last
-      expect(query.to_s).to eq "SELECT Id, name, etc FROM table_name"
-      expect(new_query.to_s).to eq 'SELECT Id, name, etc FROM table_name ORDER BY Id DESC LIMIT 1'
+    context 'without any argument' do
+      it 'should return the query for the last record' do
+        expect(query.last.to_s).to eq 'SELECT Id, name, etc FROM table_name ORDER BY Id DESC LIMIT 1'
+      end
+
+      it "should not update the original query" do
+        new_query = query.last
+        expect(query.to_s).to eq "SELECT Id, name, etc FROM table_name"
+        expect(new_query.to_s).to eq 'SELECT Id, name, etc FROM table_name ORDER BY Id DESC LIMIT 1'
+      end
+    end
+
+    context 'with an argument' do
+      let(:last_argument) { 3 }
+
+      it 'should return the query for the last n records' do
+        expect(query.last(last_argument).to_s).to eq "SELECT Id, name, etc FROM table_name ORDER BY Id DESC LIMIT #{last_argument}"
+      end
+
+      it "should not update the original query" do
+        new_query = query.last last_argument
+        expect(query.to_s).to eq "SELECT Id, name, etc FROM table_name"
+        expect(new_query.to_s).to eq "SELECT Id, name, etc FROM table_name ORDER BY Id DESC LIMIT #{last_argument}"
+      end
     end
   end
 

data/spec/active_force/sobject/includes_spec.rb

@@ -225,6 +225,13 @@ module ActiveForce
           end
         end
 
+        context 'when assocation has a scope' do
+          it 'formulates the correct SOQL query with the scope applied' do
+            soql = Post.includes(:impossible_comments).where(id: '1234').to_s
+            expect(soql).to eq "SELECT Id, Title__c, BlogId, (SELECT Id, PostId, PosterId__c, FancyPostId, Body__c FROM Comments__r WHERE (1 = 0)) FROM Post__c WHERE (Id = '1234')"
+          end
+        end
+
         context 'with namespaced SObjects' do
           it 'formulates the correct SOQL query' do
             soql = Salesforce::Quota.includes(:prez_clubs).where(id: '123').to_s
@@ -286,9 +293,26 @@ module ActiveForce
         end
       end
 
+      context 'has_one' do
+        context 'when assocation has a scope' do
+          it 'formulates the correct SOQL query with the scope applied' do
+            soql = Post.includes(:last_comment).where(id: '1234').to_s
+            expect(soql).to eq "SELECT Id, Title__c, BlogId, (SELECT Id, PostId, PosterId__c, FancyPostId, Body__c FROM Comment__r WHERE (NOT ((Body__c = NULL))) ORDER BY CreatedDate DESC) FROM Post__c WHERE (Id = '1234')"
+          end
+        end
+
+      end
+
       context 'when invalid associations are passed' do
-        it 'raises an error' do
-          expect { Quota.includes(:invalid).find('123') }.to raise_error(ActiveForce::Association::InvalidAssociationError, 'Association named invalid was not found on Quota')
+        context 'when the association is not defined' do
+          it 'raises an error' do
+            expect { Quota.includes(:invalid).find('123') }.to raise_error(ActiveForce::Association::InvalidAssociationError, 'Association named invalid was not found on Quota')
+          end
+        end
+        context 'when the association is scoped and accepts an argument' do
+          it 'raises and error' do
+            expect { Post.includes(:reply_comments).find('1234')}.to raise_error(ActiveForce::Association::InvalidEagerLoadAssociation)
+          end
         end
       end
     end

data/spec/active_force/sobject_spec.rb

@@ -313,6 +313,24 @@ describe ActiveForce::SObject do
         expect(Whizbang.create(text: 'some text')).to be_instance_of(Whizbang)
       end
     end
+
+    describe 'self.update' do
+      it 'uses the client to update the correct record' do
+        expect(client).to receive(:update!)
+          .with(Whizbang.table_name, { 'Id' => '12345678', 'Text_Label' => 'my text', 'Updated_From__c' => 'Rails' })
+          .and_return(true)
+        Whizbang.update('12345678', text: 'my text')
+      end
+    end
+
+    describe 'self.update!' do
+      it 'uses the client to update the correct record' do
+        expect(client).to receive(:update!)
+          .with(Whizbang.table_name, { 'Id' => '123456789', 'Text_Label' => 'some other text', 'Updated_From__c' => 'Rails' })
+          .and_return(true)
+        Whizbang.update('123456789', text: 'some other text')
+      end
+    end
   end
 
   describe '.count' do

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: active_force
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Eloy Espinaco
 - Pablo Oldani
 - Armando Andini
 - José Piccioni
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-23 00:00:00.000000000 Z
+date: 2023-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -155,6 +155,10 @@ files:
 - lib/active_force/association/has_many_association.rb
 - lib/active_force/association/has_one_association.rb
 - lib/active_force/association/relation_model_builder.rb
+- lib/active_force/bulk.rb
+- lib/active_force/bulk/job.rb
+- lib/active_force/bulk/job_result.rb
+- lib/active_force/bulk/records.rb
 - lib/active_force/field.rb
 - lib/active_force/mapping.rb
 - lib/active_force/query.rb
@@ -170,6 +174,10 @@ files:
 - spec/active_force/active_query_spec.rb
 - spec/active_force/association/relation_model_builder_spec.rb
 - spec/active_force/association_spec.rb
+- spec/active_force/bulk/job_result_spec.rb
+- spec/active_force/bulk/job_spec.rb
+- spec/active_force/bulk/record_spec.rb
+- spec/active_force/bulk_spec.rb
 - spec/active_force/callbacks_spec.rb
 - spec/active_force/field_spec.rb
 - spec/active_force/mapping_spec.rb
@@ -193,7 +201,7 @@ metadata:
   bug_tracker_uri: https://github.com/Beyond-Finance/active_force/issues
   changelog_uri: https://github.com/Beyond-Finance/active_force/blob/main/CHANGELOG.md
   source_code_uri: https://github.com/Beyond-Finance/active_force
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -208,14 +216,18 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.3.26
+signing_key:
 specification_version: 4
 summary: Help you implement models persisting on Sales Force within Rails using RESTForce
 test_files:
 - spec/active_force/active_query_spec.rb
 - spec/active_force/association/relation_model_builder_spec.rb
 - spec/active_force/association_spec.rb
+- spec/active_force/bulk/job_result_spec.rb
+- spec/active_force/bulk/job_spec.rb
+- spec/active_force/bulk/record_spec.rb
+- spec/active_force/bulk_spec.rb
 - spec/active_force/callbacks_spec.rb
 - spec/active_force/field_spec.rb
 - spec/active_force/mapping_spec.rb