bulkforce 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bd81802354ece9013e686bedab350cd6be171e7d
+  data.tar.gz: 57c3d0d6afe27d36e796b2cf017a47f0579a7623
+SHA512:
+  metadata.gz: 65771ee34113f04a2d22c4bb6b1ede93356d0f66a84845f595b61cedafa0fb793a1702fb9bf55e3e866f66376dd54d84e762acb135fa4520ae53537fd65196e4
+  data.tar.gz: 375ea76a3395feada554bd313db8e80df6c4ee45377f81895454c573bc4f2574ae1258d35662336e28db17eb2125c919c2979af740bd47e13831776d27202b73

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+/.env
+/vendor/bundle
+/tmp
+/coverage

data/.rspec

@@ -0,0 +1 @@
+--tty --color --format documentation

data/.ruby-version

@@ -0,0 +1 @@
+2.2.2

data/.travis.yml

@@ -0,0 +1,19 @@
+language: ruby
+cache: bundler
+bundler_args: --without documentation production
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.5
+  - 2.2.2
+  - jruby-19mode
+  - rbx
+  - ruby-head
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head
+  fast_finish: true
+script:
+  - bundle exec rake spec

data/Gemfile

@@ -0,0 +1,14 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :test, :development do
+  gem "coveralls", require: false
+  gem "guard"
+  gem "guard-rspec"
+  gem "dotenv"
+
+  gem "rb-inotify", require: false
+  gem "rb-fsevent", require: false
+  gem "rb-fchange", require: false
+end

data/Guardfile

@@ -0,0 +1,8 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec, cmd: "rspec --tag ~type:integration" do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch("spec/spec_helper.rb")  { "spec" }
+end

data/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+Copyright (c) 2012 Jorge Valdivia
+Copyright (c) 2013 Leif Gensert, Propertybase GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,211 @@
+# Bulkforce
+
+[![Build Status](https://travis-ci.org/propertybase/bulkforce.png?branch=master)](https://travis-ci.org/propertybase/bulkforce) [![Coverage Status](https://coveralls.io/repos/propertybase/bulkforce/badge.png?branch=master)](https://coveralls.io/r/propertybase/bulkforce) [![Code Climate](https://codeclimate.com/github/propertybase/bulkforce.png)](https://codeclimate.com/github/propertybase/bulkforce) [![Dependency Status](https://gemnasium.com/propertybase/bulkforce.png)](https://gemnasium.com/propertybase/bulkforce) [![Gem Version](https://badge.fury.io/rb/bulkforce.png)](http://badge.fury.io/rb/bulkforce)
+
+This is a fork of the originial [Executrix](http://github.com/propertybase/executrix) gem with some breaking API changes. In the long term, this gem will replace Executrix.
+
+It is a Ruby MRI 2.1+ gem only.
+
+## Overview
+
+Bulkforce is a simple ruby gem for connecting to and using the [Salesforce Bulk API](http://www.salesforce.com/us/developer/docs/api_asynch/index.htm). This gem only supports the functionality provided by the bulk API.
+
+## Installation
+
+~~~ sh
+$ sudo gem install bulkforce
+~~~
+
+## How to use
+
+After requiring using this gem is simple and straight forward.
+
+~~~ ruby
+require "bulkforce"
+~~~
+
+### Authentication
+
+The authentication is heavily inspired by [Restforce](https://github.com/ejholmes/restforce)
+
+### Session ID and instance
+
+If you already have a session id and a instance you can directly authenticate against Salesforce:
+
+~~~ ruby
+salesforce = Bulkforce.new(
+  session_id: "YOUR_SESSION_ID",
+  instance: "YOUR_INSTANCE",
+)
+~~~
+
+#### Username/Password/Security Token
+
+Bulkforce supports basic authentication via username, password and security token.
+
+~~~ ruby
+salesforce = Bulkforce.new(
+  username: "YOUR_SALESFORCE_USERNAME",
+  password: "YOUR_SALESFORCE_PASSWORD",
+  security_token: "YOUR_SALESFORCE_TOKEN,
+)
+~~~
+
+#### OAuth
+
+You can also authenticate via OAuth. Therefore you need the `client_id`, `client_secret` and `refresh_token`.
+
+~~~ ruby
+salesforce = Bulkforce.new(
+  client_id: "YOUR_CLIENT_ID",
+  client_secret: "YOUR_CLIENT_SECRET",
+  refresh_token: "YOUR_REFRESH_TOKEN,
+)
+~~~
+
+#### Priority
+
+If you define credentials for multiple authentication methods, the following priority applies:
+
+  - Session ID
+  - OAuth
+  - User/Password/Security Token
+
+#### ENV variables
+
+You can also define the credentials in Environment variables which are as following:
+
+~~~
+SALESFORCE_API_VERSION=...
+SALESFORCE_USERNAME=...
+SALESFORCE_PASSWORD=...
+SALESFORCE_SECURITY_TOKEN=...
+SALESFORCE_HOST=...
+SALESFORCE_CLIENT_ID=...
+SALESFORCE_CLIENT_SECRET=...
+SALESFORCE_INSTANCE=...
+SALESFORCE_REFRESH_TOKEN=...
+~~~
+
+Afterwards you can just instantiate the client:
+
+~~~ ruby
+Bulkforce.new
+~~~
+
+### Sandbox
+
+To use the bulkforce against your salesforce sandbox, change the host to `test.salesforce.com`
+
+~~~ ruby
+salesforce = Bulkforce.new(
+  # credentials
+  host: "test.salesforce.com",
+)
+~~~
+
+### OrgId
+
+After you created the client object you can fetch the OrgId via `org_id`.
+
+This will fetch the 15 digit OrgId.
+
+~~~ ruby
+salesforce.org_id # "00D50000000IehZ"
+~~~
+
+### Operations
+
+~~~ ruby
+# Insert
+new_account = {"name" => "Test Account", "type" => "Other"} # Add as many fields per record as needed.
+records_to_insert = []
+records_to_insert << new_account # You can add as many records as you want here, just keep in mind that Salesforce has governor limits.
+result = salesforce.insert("Account", records_to_insert)
+puts "reference to the bulk job: #{result.inspect}"
+~~~
+
+~~~ ruby
+# Update
+updated_account = {"name" => "Test Account -- Updated", "id" => "a00A0001009zA2m"} # Nearly identical to an insert, but we need to pass the salesforce id.
+records_to_update = []
+records_to_update.push(updated_account)
+salesforce.update("Account", records_to_update)
+~~~
+
+~~~ ruby
+# Upsert
+upserted_account = {"name" => "Test Account -- Upserted", "External_Field_Name" => "123456"} # Fields to be updated. External field must be included
+records_to_upsert = []
+records_to_upsert.push(upserted_account)
+salesforce.upsert("Account", records_to_upsert, "External_Field_Name") # Note that upsert accepts an extra parameter for the external field name
+~~~
+
+~~~ ruby
+# Delete
+deleted_account = {"id" => "a00A0001009zA2m"} # We only specify the id of the records to delete
+records_to_delete = []
+records_to_delete.push(deleted_account)
+salesforce.delete("Account", records_to_delete)
+~~~
+
+~~~ ruby
+# Query
+res = salesforce.query("Account", "select id, name, createddate from Account limit 3") # We just need to pass the sobject name and the query string
+puts res.result.records.inspect
+~~~
+
+## File Upload
+
+For file uploads, just add a `File` object to the binary columns.
+~~~ ruby
+attachment = {"ParentId" => "00Kk0001908kqkDEAQ", "Name" => "attachment.pdf", "Body" => File.new("tmp/attachment.pdf")}
+records_to_insert = []
+records_to_insert << attachment
+salesforce.insert("Attachment", records_to_insert)
+~~~
+
+### Query status
+
+The above examples all return immediately after sending the data to the Bulk API. If you want to wait, until the batch finished, call the final_status method on the batch-reference.
+
+~~~ ruby
+new_account = {"name" => "Test Account", "type" => "Other"} # Add as many fields per record as needed.
+records_to_insert = []
+records_to_insert << new_account # You can add as many records as you want here, just keep in mind that Salesforce has governor limits.
+batch_reference = salesforce.insert("Account", records_to_insert)
+results = batch_reference.final_status
+puts "the results: #{results.inspect}"
+~~~
+
+Additionally you cann pass in a block to query the current state of the batch job:
+
+~~~ ruby
+new_account = {"name" => "Test Account", "type" => "Other"} # Add as many fields per record as needed.
+records_to_insert = []
+records_to_insert << new_account # You can add as many records as you want here, just keep in mind that Salesforce has governor limits.
+batch_reference = salesforce.insert("Account", records_to_insert)
+results = batch_reference.final_status do |status|
+  puts "running: #{status.inspect}"
+end
+puts "the results: #{results.inspect}"
+~~~
+
+The block will yield every 2 seconds, but you can also specify the poll interval:
+
+~~~ ruby
+new_account = {"name" => "Test Account", "type" => "Other"} # Add as many fields per record as needed.
+records_to_insert = []
+records_to_insert << new_account # You can add as many records as you want here, just keep in mind that Salesforce has governor limits.
+batch_reference = salesforce.insert("Account", records_to_insert)
+poll_interval = 10
+results = batch_reference.final_status(poll_interval) do |status|
+  puts "running: #{status.inspect}"
+end
+puts "the results: #{results.inspect}"
+~~~
+
+## Copyright
+
+Copyright (c) 2012 Jorge Valdivia.
+Copyright (c) 2015 Leif Gensert, [Propertybase GmbH](http://propertybase.com)

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+task default: :spec
+
+RSpec::Core::RakeTask.new(:spec)

data/bulkforce.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "bulkforce/version"
+
+Gem::Specification.new do |gem|
+  gem.name        = "bulkforce"
+  gem.version     = Bulkforce::VERSION
+  gem.authors     = ["Jorge Valdivia", "Leif Gensert"]
+  gem.email       = ["jorge@valdivia.me", "leif@propertybase.com"]
+  gem.homepage    = "https://github.com/propertybase/bulkforce"
+  gem.summary     = %q{Ruby support for the Salesforce Bulk API}
+  gem.description = %q{This gem provides a super simple interface for the Salesforce Bulk API. It provides support for insert, update, upsert, delete, and query.}
+  gem.license     = "MIT"
+
+  gem.rubyforge_project = "bulkforce"
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "rake"
+  gem.add_dependency "json"
+  gem.add_dependency "nori", "< 2.7"
+  gem.add_dependency "nokogiri", "< 1.7"
+  gem.add_dependency "rubyzip", ">= 1.0" ,"< 1.2"
+  gem.add_development_dependency "rspec", "< 3.4"
+  gem.add_development_dependency "webmock", "< 1.22"
+  if RUBY_ENGINE == "rbx"
+    gem.add_dependency "rubysl", "< 2.2"
+    gem.add_development_dependency "racc", "< 1.5"
+    gem.add_development_dependency "rubinius-coverage", "< 2.1"
+  end
+end

data/lib/bulkforce.rb

@@ -0,0 +1,109 @@
+require "bulkforce/version"
+require "bulkforce/configuration"
+require "bulkforce/helper"
+require "bulkforce/batch"
+require "bulkforce/http"
+require "bulkforce/connection_builder"
+require "bulkforce/connection"
+require "zip"
+
+class Bulkforce
+  SALESFORCE_API_VERSION = "33.0"
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  def initialize(options = {})
+    configuration = self.class.configuration || Configuration.new
+    merged_opts = configuration.to_h.merge(options)
+
+    unless merged_opts[:host] =~ /salesforce.com\/?$/
+      warn("WARNING: You are submitting credentials to a host other than salesforce.com")
+    end
+
+    @connection = Bulkforce::ConnectionBuilder.new(merged_opts).build
+  end
+
+  def org_id
+    @connection.org_id
+  end
+
+  def upsert(sobject, records, external_field)
+    start_job("upsert", sobject, records, external_field)
+  end
+
+  def update(sobject, records)
+    start_job("update", sobject, records)
+  end
+
+  def insert(sobject, records)
+    start_job("insert", sobject, records)
+  end
+
+  def delete(sobject, records)
+    start_job("delete", sobject, records)
+  end
+
+  def query(sobject, query)
+    job_id = @connection.create_job(
+      "query",
+      sobject,
+      "CSV",
+      nil)
+    batch_id = @connection.add_query(job_id, query)
+    @connection.close_job job_id
+    batch_reference = Bulkforce::Batch.new @connection, job_id, batch_id
+    batch_reference.final_status
+  end
+
+  def self.configure(&block)
+    self.configuration = Configuration.new
+    block.call(self.configuration)
+  end
+
+  private
+  def start_job(operation, sobject, records, external_field=nil)
+    attachment_keys = Bulkforce::Helper.attachment_keys(records)
+
+    content_type = "CSV"
+    zip_filename = nil
+    request_filename = nil
+    batch_id = -1
+    if not attachment_keys.empty?
+      tmp_filename = Dir::Tmpname.make_tmpname("bulk_upload", ".zip")
+      zip_filename = "#{Dir.tmpdir}/#{tmp_filename}"
+      Zip::File.open(zip_filename, Zip::File::CREATE) do |zipfile|
+        Bulkforce::Helper.transform_values!(records, attachment_keys) do |path|
+          relative_path = Bulkforce::Helper.absolute_to_relative_path(path, "")
+          zipfile.add(relative_path, path) rescue Zip::ZipEntryExistsError
+        end
+        tmp_filename = Dir::Tmpname.make_tmpname("request", ".txt")
+        request_filename = "#{Dir.tmpdir}/#{tmp_filename}"
+        File.open(request_filename, "w") do |file|
+          file.write(Bulkforce::Helper.records_to_csv(records))
+        end
+        zipfile.add("request.txt", request_filename)
+      end
+
+      content_type = "ZIP_CSV"
+    end
+
+    job_id = @connection.create_job(
+      operation,
+      sobject,
+      content_type,
+      external_field)
+    if zip_filename
+      batch_id = @connection.add_file_upload_batch job_id, zip_filename
+      [zip_filename, request_filename].each do |file|
+        File.delete(file) if file
+      end
+    else
+      batch_id = @connection.add_batch job_id, records
+    end
+
+    @connection.close_job job_id
+    Bulkforce::Batch.new @connection, job_id, batch_id
+  end
+end