executrix 1.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    M2I4ZDNlY2E3NzEyMjNiOThiMDFjMTg0Yjk0ZmM0ZDIxOThlOTgxNw==
+  data.tar.gz: !binary |-
+    MzllZDVhODY1NDNhNTY4ZmIwMmE0M2NjZmM1NWNhZDA1NTE4MzA2Nw==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NDg4ODI3NWZhYjU0MjZiNWE5MzIwYmNjOTg0YTUzODE5ODlkYmMxMjMxODE3
+    MTVjYWU5ZGQxZjIwNzVkNzBiZmQ4ZWJlNGU5OGE1MWEyZDY4Nzk5NTQ1ZjRm
+    NzRlYjgwYzA3YWFmOTQ3ZmMwMTcwYzY5MDgyMjdkMzFjYTQ3OTM=
+  data.tar.gz: !binary |-
+    NjM0ZjQ3YTg1MWJiNDBmYWM2YWE2YTI2ZTZiNmY3YzYyZGI1ZDBhOGEwYmIx
+    M2RkZTRlOTQ2ODI1Y2E3ZDhjOWIwZjEwNDc1M2QzOGY5MDRjZWY0MWY2M2Q3
+    ZDU3MjRmYWVkOWM2YmViYTNhYzBhMjk0YTZiMDEyNTJjMzdlZjM=

data/.gitignore

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

data/.rspec

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

data/.ruby-version

@@ -0,0 +1 @@
+1.9.3-p392

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+bundler_args: --without documentation production
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - jruby-19mode
+  - rbx-19mode
+matrix:
+  allow_failures:
+    - rvm: rbx-19mode
+script:
+  - rake spec

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test, :development do
+  gem 'coveralls', require: false
+  gem 'guard'
+  gem 'guard-rspec'
+
+  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 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,120 @@
+# Executrix
+
+DISCLAIMER: This gem is a rewrite of the [salesforce_bulk](https://github.com/jorgevaldivia/salesforce_bulk) gem. As the original maintainer didn't respon to my [pull-request](https://github.com/jorgevaldivia/salesforce_bulk/pull/14) I decided to rerelease the gem under different name. This is it.
+
+The original Copyright Notice and all the original commit logs have been retained.
+
+## Overview
+
+Executrix 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 executrix
+~~~
+
+## How to use
+
+Using this gem is simple and straight forward.
+
+### Initialize
+
+~~~ ruby
+require 'executrix'
+salesforce = Executrix::Api.new('YOUR_SALESFORCE_USERNAME', 'YOUR_SALESFORCE_PASSWORD+YOUR_SALESFORCE_TOKEN')
+~~~
+
+To use sandbox:
+
+~~~ ruby
+salesforce = Executrix::Api.new('YOUR_SALESFORCE_SANDBOX_USERNAME', 'YOUR_SALESFORCE_PASSWORD+YOUR_SALESFORCE_SANDBOX_TOKEN', true)
+~~~
+
+Note: the second parameter is a combination of your Salesforce token and password. So if your password is xxxx and your token is yyyy, the second parameter will be xxxxyyyy
+
+### 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
+~~~
+
+### 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) 2013 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/executrix.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'executrix/version'
+
+Gem::Specification.new do |gem|
+  gem.name        = 'executrix'
+  gem.version     = Executrix::VERSION
+  gem.authors     = ["Jorge Valdivia"]
+  gem.email       = ["jorge@valdivia.me"]
+  gem.homepage    = 'https://github.com/propertybase/executrix'
+  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.rubyforge_project = 'executrix'
+
+  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 'nori', '~> 2.0'
+  gem.add_dependency 'nokogiri', '~> 1.5'
+  gem.add_development_dependency 'rspec', '~> 2.13'
+  gem.add_development_dependency 'webmock', '~> 1.11'
+end

data/lib/executrix.rb

@@ -0,0 +1,58 @@
+require 'executrix/version'
+require 'executrix/helper'
+require 'executrix/batch'
+require 'executrix/http'
+require 'executrix/connection'
+
+module Executrix
+  class Api
+    SALESFORCE_API_VERSION = '27.0'
+
+    def initialize(username, password, sandbox = false, api_version = SALESFORCE_API_VERSION)
+      @connection = Executrix::Connection.connect(
+        username,
+        password,
+        api_version,
+        sandbox)
+    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,
+        nil)
+      batch_id = @connection.add_query(job_id, query)
+      @connection.close_job job_id
+      batch_reference = Executrix::Batch.new @connection, job_id, batch_id
+      batch_reference.init_result_id
+      batch_reference.final_status
+    end
+
+    private
+    def start_job(operation, sobject, records, external_field=nil)
+      job_id = @connection.create_job(
+        operation,
+        sobject,
+        external_field)
+      batch_id = @connection.add_batch job_id, records
+      @connection.close_job job_id
+      Executrix::Batch.new @connection, job_id, batch_id
+    end
+  end
+end

data/lib/executrix/batch.rb

@@ -0,0 +1,51 @@
+module Executrix
+  class Batch
+    def initialize connection, job_id, batch_id
+      @connection = connection
+      @job_id = job_id
+      @batch_id = batch_id
+
+      if @batch_id == -1
+        @final_status = {
+          state: 'Completed',
+          state_message: 'Empty Request'
+        }
+      end
+    end
+
+    def final_status poll_interval=2
+      return @final_status if @final_status
+
+      @final_status = self.status
+      while ['Queued', 'InProgress'].include?(@final_status[:state])
+        sleep poll_interval
+        @final_status = self.status
+        yield @final_status if block_given?
+      end
+
+      raise @final_status[:state_message] if @final_status[:state] == 'Failed'
+
+      @final_status.merge({
+          results: results
+        })
+    end
+
+    def status
+      @connection.query_batch @job_id, @batch_id
+    end
+
+    # only needed for query
+    def init_result_id
+      max_retries = 5
+      retry_count = 0
+      while @result_id.nil? && retry_count < max_retries
+        @result_id = @connection.query_batch_result_id(@job_id, @batch_id)[:result]
+        retry_count += 1
+      end
+    end
+
+    def results
+      @connection.query_batch_result_data(@job_id, @batch_id, @result_id)
+    end
+  end
+end

data/lib/executrix/connection.rb

@@ -0,0 +1,95 @@
+module Executrix
+  class Connection
+    def initialize(username, password, api_version, sandbox)
+      @username = username
+      @password = password
+      @api_version = api_version
+      @sandbox = sandbox
+    end
+
+    def login
+      response = Executrix::Http.login(
+        @sandbox,
+        @username,
+        @password,
+        @api_version)
+
+      @session_id = response[:session_id]
+      @instance = response[:instance]
+      self
+    end
+
+    def create_job operation, sobject, external_field
+      Executrix::Http.create_job(
+        @instance,
+        @session_id,
+        operation,
+        sobject,
+        @api_version,
+        external_field)[:id]
+    end
+
+    def close_job job_id
+      Executrix::Http.close_job(
+        @instance,
+        @session_id,
+        job_id,
+        @api_version)[:id]
+    end
+
+    def add_query job_id, data_or_soql
+      Executrix::Http.add_batch(
+        @instance,
+        @session_id,
+        job_id,
+        data_or_soql,
+        @api_version)[:id]
+    end
+
+    def query_batch job_id, batch_id
+      Executrix::Http.query_batch(
+        @instance,
+        @session_id,
+        job_id,
+        batch_id,
+        @api_version,
+      )
+    end
+
+    def query_batch_result_id job_id, batch_id
+      Executrix::Http.query_batch_result_id(
+        @instance,
+        @session_id,
+        job_id,
+        batch_id,
+        @api_version,
+      )
+    end
+
+    def query_batch_result_data job_id, batch_id, result_id
+      Executrix::Http.query_batch_result_data(
+        @instance,
+        @session_id,
+        job_id,
+        batch_id,
+        result_id,
+        @api_version,
+      )
+    end
+
+    def add_batch job_id, records
+      return -1 if records.nil? || records.empty?
+
+      Executrix::Http.add_batch(
+        @instance,
+        @session_id,
+        job_id,
+        Executrix::Helper.records_to_csv(records),
+        @api_version)[:id]
+    end
+
+    def self.connect(username, password, api_version, sandbox)
+      self.new(username, password, api_version, sandbox).login
+    end
+  end
+end