module Restforce::Concerns::API
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 create(*args)
Returns the String Id of the newly created sobject.
# => '0016000000MRatd'
client.create('Account', Name: 'Foobar Inc.')
# Add a new account
Examples
attrs - Hash of attributes to set on the new record.
sobject - String name of the sobject.
Public: Insert a new record.
def create(*args) create!(*args) rescue *exceptions false end
def create!(sobject, attrs)
Returns the String Id of the newly created sobject.
# => '0016000000MRatd'
client.create!('Account', Name: 'Foobar Inc.')
# Add a new account
Examples
attrs - Hash of attributes to set on the new record.
sobject - String name of the sobject.
Public: Insert a new record.
def create!(sobject, attrs) api_post("sobjects/#{sobject}", attrs).body['id'] end
def describe(sobject = nil)
# => { ... }
client.describe('Account')
# get the describe for the Account object
# => { ... }
client.describe
# get the global describe for all sobjects
Examples
sobject - Stringish name of the sobject (default: nil).
Public: Returns a detailed describe result for the specified sobject
def describe(sobject = nil) if sobject api_get("sobjects/#{sobject.to_s}/describe").body else api_get('sobjects').body['sobjects'] end end
def describe_layouts(sobject, layout_id = nil)
# => { ... }
client.describe_layouts('Account', '012E0000000RHEp')
# get the layout for the specified Id for the sobject
# => { ... }
client.describe_layouts('Account')
# get the layouts for the sobject
Examples:
This resource was introduced in version 28.0.
multiple Record Types.
specified sobject type, or URIs for layouts if the sobject has
Public: Returns a detailed description of the Page Layout for the
def describe_layouts(sobject, layout_id = nil) if layout_id api_get("sobjects/#{sobject.to_s}/describe/layouts/#{layout_id}").body else api_get("sobjects/#{sobject.to_s}/describe/layouts").body end end
def destroy(*args)
Returns true if the sobject was successfully deleted.
client.destroy('Account', '0016000000MRatd')
# Delete the Account with Id '0016000000MRatd'
Examples
id - The Salesforce ID of the record.
sobject - String name of the sobject.
Public: Delete a record.
def destroy(*args) destroy!(*args) rescue *exceptions false end
def destroy!(sobject, id)
Returns true of the sobject was successfully deleted.
client.destroy('Account', '0016000000MRatd')
# Delete the Account with Id '0016000000MRatd'
Examples
id - The Salesforce ID of the record.
sobject - String name of the sobject.
Public: Delete a record.
def destroy!(sobject, id) api_delete "sobjects/#{sobject}/#{id}" true end
def exceptions
def exceptions [Faraday::Error::ClientError] end
def find(sobject, id, field=nil)
field - External ID field to use (default: nil).
of the external field.
id - The id of the record. If field is specified, id should be the id
sobject - The String name of the sobject.
Public: Finds a single record and returns all fields.
def find(sobject, id, field=nil) api_get(field ? "sobjects/#{sobject}/#{field}/#{id}" : "sobjects/#{sobject}/#{id}").body 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.collect { |sobject| sobject['name'] } 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) api_get('search', :q => sosl).body end
def select(sobject, id, select, field=nil)
field - External ID field to use (default: nil).
is passed, all fields are selected.
select - A String array denoting the fields to select. If nil or empty array
of the external field.
id - The id of the record. If field is specified, id should be the id
sobject - The String name of the sobject.
Public: Finds a single record and returns select fields.
def select(sobject, id, select, field=nil) path = field ? "sobjects/#{sobject}/#{field}/#{id}" : "sobjects/#{sobject}/#{id}" path << "?fields=#{select.join(",")}" if select && select.any? api_get(path).body end
def update(*args)
Returns true if the sobject was successfully updated.
client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
# Update the Account with Id '0016000000MRatd'
Examples
attrs - Hash of attributes to set on the record.
sobject - String name of the sobject.
Public: Update a record.
def update(*args) update!(*args) rescue *exceptions false end
def update!(sobject, attrs)
Returns true if the sobject was successfully updated.
client.update!('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')
# Update the Account with Id '0016000000MRatd'
Examples
attrs - Hash of attributes to set on the record.
sobject - String name of the sobject.
Public: Update a record.
def update!(sobject, attrs) id = attrs.delete(attrs.keys.find { |k| k.to_s.downcase == 'id' }) raise ArgumentError, 'Id field missing from attrs.' unless id api_patch "sobjects/#{sobject}/#{id}", attrs true end
def upsert(*args)
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(*args) upsert!(*args) 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.
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) external_id = attrs.delete(attrs.keys.find { |k| k.to_s.downcase == field.to_s.downcase }) response = api_patch "sobjects/#{sobject}/#{field.to_s}/#{external_id}", attrs (response.body && response.body['id']) ? response.body['id'] : true end