class Restforce::Client
def api_path(path)
api_path('sobjects')
Examples
Internal: Returns a path to an api endpoint
def api_path(path) "/services/data/v#{@options[:api_version]}/#{path}" end
def authenticate!
def authenticate! connection.headers['X-ForceAuthenticate'] = true get nil ensure connection.headers.delete('X-ForceAuthenticate') end
def authentication_middleware
def authentication_middleware if username_password? Restforce::Middleware::Authentication::Password elsif oauth_refresh? Restforce::Middleware::Authentication::Token end end
def connection
def connection @connection ||= Faraday.new do |builder| builder.use Restforce::Middleware::Mashify, self, @options builder.use Restforce::Middleware::Multipart builder.request :json builder.use authentication_middleware, self, @options if authentication_middleware builder.use Restforce::Middleware::Authorization, self, @options builder.use Restforce::Middleware::InstanceURL, self, @options builder.use Restforce::Middleware::RaiseError builder.response :logger, Restforce.configuration.logger if Restforce.log? builder.response :json builder.adapter Faraday.default_adapter end @connection end
def create(sobject, attrs)
Returns the String Id of the newly created sobject. Returns false if
# => '0016000000MRatd'
client.create('Account', Name: 'Foobar Inc.')
# Add a new account
Examples
Public: Insert a new record.
def create(sobject, attrs) create!(sobject, attrs) rescue *exceptions false end
def create!(sobject, attrs)
Returns the String Id of the newly created sobject. Raises an error if
See .create
def create!(sobject, attrs) response = api_post "sobjects/#{sobject}", attrs response.body['id'] end
def describe(sobject)
# => { ... }
client.describe('Account')
# get the describe for the Account object
Examples
sobject - Stringish name of the sobject (default: nil).
Public: Returns a detailed describe result for the specified sobject
def describe(sobject) response = api_get "sobject/#{sobject.to_s}/describe" response.body end
def describe_sobjects
Public: Get the global describe for all sobjects.
def describe_sobjects response = api_get 'sobjects' response.body['sobjects'] end
def destroy(sobject, id)
client.delete('Account', '0016000000MRatd')
# Delete the Account with Id '0016000000MRatd'
Examples
Public: Delete a record.
def destroy(sobject, id) destroy!(sobject, id) rescue *exceptions false end
def destroy!(sobject, id)
Returns true of the sobject was successfully deleted, raises an error
See .destroy
def destroy!(sobject, id) api_delete "sobjects/#{sobject}/#{id}" true end
def exceptions
def exceptions [Faraday::Error::ClientError] end
def faye
def faye @faye ||= Faye::Client.new("#{@options[:instance_url]}/cometd/#{@options[:api_version]}").tap do |client| client.set_header 'Authorization', "OAuth #{@options[:oauth_token]}" client.bind 'transport:down' do Restforce.log "[COMETD DOWN]" end client.bind 'transport:up' do Restforce.log "[COMETD UP]" end end end
def initialize(options = {})
:instance_url => 'https://na1.salesforce.com'
Restforce::Client.new :oauth_token => 'access token',
# Initialize a new client with using any authentication middleware:
# => #
:client_secret => 'client secret'
:client_id => 'client id',
:instance_url => 'https://na1.salesforce.com',
:refresh_token => 'refresh token',
Restforce::Client.new :oauth_token => 'access token',
# Initialize a new client using oauth authentication:
# => #
:client_secret => 'client secret'
:client_id => 'client id',
:security_token => 'security token',
:password => 'pass',
Restforce::Client.new :username => 'user',
# Initialize a new client using password authentication:
Examples
:api_version - The String REST api version to use (default: '24.0')
authentication requests (default: 'login.salesforce.com').
:host - The String hostname to use during
:client_secret - The oauth client secret to use.
password and oauth authentication
:client_id - The oauth client id to use. Needed for both
(required if oauth authentication is used).
:instance_url - The String base url for all api requests
authentication is used).
oauth access tokens (required if oauth
:refresh_token - The String refresh token to obtain fresh
authentication is used).
calls (required unless password
:oauth_token - The String oauth access token to authenticate api
(required for password authentication).
:security_token - The String security token to use
:password - The String password to use (required for password authentication).
:username - The String username to use (required for password authentication).
options - A hash of options to be passed in (default: {}).
Public: Creates a new client instance
def initialize(options = {}) raise 'Please specify a hash of options' unless options.is_a?(Hash) @options = {}.tap do |options| [:username, :password, :security_token, :client_id, :client_secret, :host, :api_version, :oauth_token, :refresh_token, :instance_url].each do |option| options[option] = Restforce.configuration.send option end end @options.merge!(options) end
def list_sobjects
# => ['Account', 'Lead', ... ]
client.list_sobjects
# get the names of all sobjects on the org
Examples
Public: Get the names of all sobjects on the org.
def list_sobjects describe_sobjects.collect { |sobject| sobject['name'] } end
def mashify?
Internal: Returns true if the middlware stack includes the
def mashify? connection.builder.handlers.find { |handler| handler == Restforce::Middleware::Mashify } end
def oauth_refresh?
Internal: Returns true if oauth token refresh flow should be used for
def oauth_refresh? @options[:refresh_token] && @options[:client_id] && @options[:client_secret] end
def org_id
# => '00Dx0000000BV7z'
client.org_id
Examples
Public: Get the current organization's Id.
def org_id query('select id from Organization').first['Id'] end
def query(soql)
Returns a Restforce::Collection if Restforce.configuration.mashify is true.
# => ['Foo Bar Inc.', 'Whizbang Corp']
client.query('select Name from Account').map(&:Name)
# Find the names of all Accounts
Examples
soql - A SOQL expression.
Public: Executs a SOQL query and returns the result.
def query(soql) response = api_get 'query', q: soql mashify? ? response.body : response.body['records'] end
def search(sosl)
Returns a Restforce::Collection if Restforce.configuration.mashify is true.
# => ['GenePoint']
client.search('FIND {genepoint} RETURNING Account (Name)').map(&:Name)
# Find accounts match the term 'genepoint' and return the Name field
# => #
client.search('FIND {bar}')
# Find all occurrences of 'bar'
Examples
sosl - A SOSL expression.
Public: Perform a SOSL search
def search(sosl) response = api_get 'search', q: sosl response.body end
def subscribe(channel, &block)
block - A block to run when a new message is received.
channel - The name of the PushTopic channel to subscribe to.
Public: Subscribe to a PushTopic
def subscribe(channel, &block) faye.subscribe "/topic/#{channel}", &block end
def update(sobject, attrs)
client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
# Update the Account with Id '0016000000MRatd'
Examples
Public: Update a record.
def update(sobject, attrs) update!(sobject, attrs) rescue *exceptions false end
def update!(sobject, attrs)
Returns true if the sobject was successfully updated, raises an error
See .update
def update!(sobject, attrs) id = attrs.has_key?(:Id) ? attrs.delete(:Id) : attrs.delete('Id') api_patch "sobjects/#{sobject}/#{id}", attrs true end
def upsert(sobject, field, attrs)
Returns the Id of the newly created record if the record was created.
Returns true if the record was found and updated.
client.upsert('Account', 'External__c', External__c: 12, Name: 'Foobar')
# Update the record with external ID of 12
Examples
attrs - Hash of attributes for the record.
field - The name of the external Id field to match against.
sobject - The name of the sobject to created.
Public: Update or Create a record based on an external ID
def upsert(sobject, field, attrs) upsert!(sobject, field, attrs) rescue *exceptions false end
def upsert!(sobject, field, attrs)
Returns the Id of the newly created record if the record was created.
Returns true if the record was found and updated.
See .upsert
def upsert!(sobject, field, attrs) external_id = attrs.has_key?(field.to_sym) ? attrs.delete(field.to_sym) : attrs.delete(field.to_s) response = api_patch "sobjects/#{sobject}/#{field.to_s}/#{external_id}", attrs (response.body && response.body['id']) ? response.body['id'] : true end
def username_password?
Internal: Returns true if username/password (autonomous) flow should be used for
def username_password? @options[:username] && @options[:password] && @options[:security_token] && @options[:client_id] && @options[:client_secret] end