Executrix

NOTICE: This gem is deprecated as of July 28th. Please consider using the sucessor of this gem: bulkforce.

DISCLAIMER: This gem is a rewrite of the salesforce_bulk gem. As the original maintainer didn't respond to my pull-request I decided to rerelease the gem under different name.

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. This gem only supports the functionality provided by the bulk API.

Installation

$ sudo gem install executrix

How to use

Using this gem is simple and straight forward.

Initialize

require 'executrix'
salesforce = Executrix::Api.new('YOUR_SALESFORCE_USERNAME', 'YOUR_SALESFORCE_PASSWORD+YOUR_SALESFORCE_TOKEN')

To use sandbox:

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

OrgId

After you created the client object you can fetch the OrgId via org_id.

This will fetch the 15 digit OrgId.

salesforce.org_id # '00D50000000IehZ'

Operations

# 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}"

# 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)

# 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

# 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)

# 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.

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.

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:

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:

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}"

executrix

Development

Runtime