This is a fork of the originial 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.
Bulkforce 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.
$ sudo gem install bulkforceAfter requiring using this gem is simple and straight forward.
require "bulkforce"The authentication is heavily inspired by Restforce
If you already have a session id and a instance you can directly authenticate against Salesforce:
salesforce = Bulkforce.new(
session_id: "YOUR_SESSION_ID",
instance: "YOUR_INSTANCE",
)Bulkforce supports basic authentication via username, password and security token.
salesforce = Bulkforce.new(
username: "YOUR_SALESFORCE_USERNAME",
password: "YOUR_SALESFORCE_PASSWORD",
security_token: "YOUR_SALESFORCE_TOKEN,
)You can also authenticate via OAuth. Therefore you need the client_id, client_secret and refresh_token.
salesforce = Bulkforce.new(
client_id: "YOUR_CLIENT_ID",
client_secret: "YOUR_CLIENT_SECRET",
refresh_token: "YOUR_REFRESH_TOKEN,
)If you define credentials for multiple authentication methods, the following priority applies:
- Session ID
- OAuth
- User/Password/Security Token
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:
Bulkforce.newTo use the bulkforce against your salesforce sandbox, change the host to test.salesforce.com
salesforce = Bulkforce.new(
# credentials
host: "test.salesforce.com",
)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"# 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.inspectFor 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)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}"Copyright (c) 2012 Jorge Valdivia. Copyright (c) 2015 Leif Gensert, Propertybase GmbH
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent