module Restforce::Concerns::API

Public Instance Methods

create(*args) click to toggle source

Public: Insert a new record.

sobject - String name of the sobject. attrs - Hash of attributes to set on the new record.

Examples

# Add a new account
client.create('Account', Name: 'Foobar Inc.')
# => '0016000000MRatd'

Returns the String Id of the newly created sobject. Returns false if something bad happens.

# File lib/restforce/concerns/api.rb, line 266
def create(*args)
  create!(*args)
rescue *exceptions
  false
end
Also aliased as: insert
create!(sobject, attrs) click to toggle source

Public: Insert a new record.

sobject - String name of the sobject. attrs - Hash of attributes to set on the new record.

Examples

# Add a new account
client.create!('Account', Name: 'Foobar Inc.')
# => '0016000000MRatd'

Returns the String Id of the newly created sobject. Raises exceptions if an error is returned from Salesforce.

# File lib/restforce/concerns/api.rb, line 286
def create!(sobject, attrs)
  api_post("sobjects/#{sobject}", attrs).body['id']
end
Also aliased as: insert!
describe(sobject = nil) click to toggle source

Public: Returns a detailed describe result for the specified sobject

sobject - Stringish name of the sobject (default: nil).

Examples

# get the global describe for all sobjects
client.describe
# => { ... }

# get the describe for the Account object
client.describe('Account')
# => { ... }

Returns the Hash representation of the describe call.

# File lib/restforce/concerns/api.rb, line 126
def describe(sobject = nil)
  if sobject
    api_get("sobjects/#{sobject}/describe").body
  else
    api_get('sobjects').body['sobjects']
  end
end
describe_layouts(sobject, layout_id = nil) click to toggle source

Public: Returns a detailed description of the Page Layout for the specified sobject type, or URIs for layouts if the sobject has multiple Record Types.

Only available in version 28.0 and later of the Salesforce API.

Examples:

# get the layouts for the sobject
client.describe_layouts('Account')
# => { ... }

# get the layout for the specified Id for the sobject
client.describe_layouts('Account', '012E0000000RHEp')
# => { ... }

Returns the Hash representation of the describe_layouts result

# File lib/restforce/concerns/api.rb, line 150
def describe_layouts(sobject, layout_id = nil)
  version_guard(28.0) do
    if layout_id
      api_get("sobjects/#{sobject}/describe/layouts/#{CGI.escape(layout_id)}").body
    else
      api_get("sobjects/#{sobject}/describe/layouts").body
    end
  end
end
destroy(*args) click to toggle source

Public: Delete a record.

sobject - String name of the sobject. id - The Salesforce ID of the record.

Examples

# Delete the Account with Id '0016000000MRatd'
client.destroy('Account', '0016000000MRatd')

Returns true if the sobject was successfully deleted. Returns false if an error is returned from Salesforce.

# File lib/restforce/concerns/api.rb, line 401
def destroy(*args)
  destroy!(*args)
rescue *exceptions
  false
end
destroy!(sobject, id) click to toggle source

Public: Delete a record.

sobject - String name of the sobject. id - The Salesforce ID of the record.

Examples

# Delete the Account with Id '0016000000MRatd'
client.destroy('Account', '0016000000MRatd')

Returns true of the sobject was successfully deleted. Raises an exception if an error is returned from Salesforce.

# File lib/restforce/concerns/api.rb, line 419
def destroy!(sobject, id)
  api_delete "sobjects/#{sobject}/#{ERB::Util.url_encode(id)}"
  true
end
explain(soql) click to toggle source

Public: Explain a SOQL query execution plan.

Only available in version 30.0 and later of the Salesforce API.

soql - A SOQL expression.

Examples

# Find the names of all Accounts
client.explain('select Name from Account')

Returns a Hash in the form {:plans => [Array of plan data]} See: www.salesforce.com/us/developer/docs/api_rest/Content/dome_query_expl

ain.htm
# File lib/restforce/concerns/api.rb, line 204
def explain(soql)
  version_guard(30.0) { api_get("query", explain: soql).body }
end
find(sobject, id, field = nil) click to toggle source

Public: Finds a single record and returns all fields.

sobject - The String name of the sobject. id - The id of the record. If field is specified, id should be the id

of the external field.

field - External ID field to use (default: nil).

Returns the Restforce::SObject sobject record. Raises NotFoundError if nothing is found.

# File lib/restforce/concerns/api.rb, line 433
def find(sobject, id, field = nil)
  url = if field
          "sobjects/#{sobject}/#{field}/#{ERB::Util.url_encode(id)}"
        else
          "sobjects/#{sobject}/#{ERB::Util.url_encode(id)}"
        end
  api_get(url).body
end
get_deleted(sobject, start_time, end_time) click to toggle source

Public: Gets the IDs of sobjects of type [sobject] which have been deleted between startDateTime and endDateTime.

Examples

# get deleted sobject Whizbangs between yesterday and today
startDate = Time.new(2002, 10, 31, 2, 2, 2, "+02:00")
endDate = Time.new(2002, 11, 1, 2, 2, 2, "+02:00")
client.get_deleted('Whizbang', startDate, endDate)

Returns a Restforce::Collection if Restforce.configuration.mashify is true. Returns an Array of Hash for each record in the result if Restforce.configuration.mashify is false.

# File lib/restforce/concerns/api.rb, line 104
def get_deleted(sobject, start_time, end_time)
  start_time = start_time.utc.iso8601
  end_time = end_time.utc.iso8601
  url = "sobjects/#{sobject}/deleted/?start=#{start_time}&end=#{end_time}"
  api_get(url).body
end
get_updated(sobject, start_time, end_time) click to toggle source

Public: Gets the IDs of sobjects of type [sobject] which have changed between startDateTime and endDateTime.

Examples

# get changes for sobject Whizbang between yesterday and today
startDate = Time.new(2002, 10, 31, 2, 2, 2, "+02:00")
endDate = Time.new(2002, 11, 1, 2, 2, 2, "+02:00")
client.get_updated('Whizbang', startDate, endDate)

Returns a Restforce::Collection if Restforce.configuration.mashify is true. Returns an Array of Hash for each record in the result if Restforce.configuration.mashify is false.

# File lib/restforce/concerns/api.rb, line 84
def get_updated(sobject, start_time, end_time)
  start_time = start_time.utc.iso8601
  end_time = end_time.utc.iso8601
  url = "sobjects/#{sobject}/updated/?start=#{start_time}&end=#{end_time}"
  api_get(url).body
end
insert(*args)
Alias for: create
insert!(sobject, attrs)
Alias for: create!
limits() click to toggle source

Public: Get info about limits in the connected organization

Only available in version 29.0 and later of the Salesforce API.

Returns an Array of String names for each SObject.

# File lib/restforce/concerns/api.rb, line 67
def limits
  version_guard(29.0) { api_get("limits").body }
end
list_sobjects() click to toggle source

Public: Get the names of all sobjects on the org.

Examples

# get the names of all sobjects on the org
client.list_sobjects
# => ['Account', 'Lead', ... ]

Returns an Array of String names for each SObject.

# File lib/restforce/concerns/api.rb, line 58
def list_sobjects
  describe.collect { |sobject| sobject['name'] }
end
org_id() click to toggle source

Public: Get the current organization’s Id.

Examples

client.org_id
# => '00Dx0000000BV7z'

Returns the String organization Id

# File lib/restforce/concerns/api.rb, line 168
def org_id
  query('select id from Organization').first['Id']
end
query(soql) click to toggle source

Public: Executs a SOQL query and returns the result.

soql - A SOQL expression.

Examples

# Find the names of all Accounts
client.query('select Name from Account').map(&:Name)
# => ['Foo Bar Inc.', 'Whizbang Corp']

Returns a Restforce::Collection if Restforce.configuration.mashify is true. Returns an Array of Hash for each record in the result if Restforce.configuration.mashify is false.

# File lib/restforce/concerns/api.rb, line 185
def query(soql)
  response = api_get 'query', q: soql
  mashify? ? response.body : response.body['records']
end
query_all(soql) click to toggle source

Public: Executes a SOQL query and returns the result. Unlike the Query resource, QueryAll will return records that have been deleted because of a merge or delete. QueryAll will also return information about archived Task and Event records.

Only available in version 29.0 and later of the Salesforce API.

soql - A SOQL expression.

Examples

# Find the names of all Accounts
client.query_all('select Name from Account').map(&:Name)
# => ['Foo Bar Inc.', 'Whizbang Corp']

Returns a Restforce::Collection if Restforce.configuration.mashify is true. Returns an Array of Hash for each record in the result if Restforce.configuration.mashify is false.

# File lib/restforce/concerns/api.rb, line 225
def query_all(soql)
  version_guard(29.0) do
    response = api_get 'queryAll', q: soql
    mashify? ? response.body : response.body['records']
  end
end
recent(limit = nil) click to toggle source

Public: Finds recently viewed items for the logged-in user.

limit - An optional limit that specifies the maximum number of records to be

returned.
If this parameter is not specified, the default maximum number of records
returned is the maximum number of entries in RecentlyViewed, which is 200
records per object.

Returns an array of the recently viewed Restforce::SObject records.

# File lib/restforce/concerns/api.rb, line 472
def recent(limit = nil)
  path = limit ? "recent?limit=#{limit}" : "recent"

  api_get(path).body
end
select(sobject, id, select, field = nil) click to toggle source

Public: Finds a single record and returns select fields.

sobject - The String name of the sobject. id - The id of the record. If field is specified, id should be the id

of the external field.

select - A String array denoting the fields to select. If nil or empty array

is passed, all fields are selected.

field - External ID field to use (default: nil).

# File lib/restforce/concerns/api.rb, line 451
def select(sobject, id, select, field = nil)
  path = if field
           "sobjects/#{sobject}/#{field}/#{ERB::Util.url_encode(id)}"
         else
           "sobjects/#{sobject}/#{ERB::Util.url_encode(id)}"
         end

  path = "#{path}?fields=#{select.join(',')}" if select&.any?

  api_get(path).body
end
update(*args) click to toggle source

Public: Update a record.

sobject - String name of the sobject. attrs - Hash of attributes to set on the record.

Examples

# Update the Account with Id '0016000000MRatd'
client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')

Returns true if the sobject was successfully updated. Returns false if there was an error.

# File lib/restforce/concerns/api.rb, line 303
def update(*args)
  update!(*args)
rescue *exceptions
  false
end
update!(sobject, attrs) click to toggle source

Public: Update a record.

sobject - String name of the sobject. attrs - Hash of attributes to set on the record.

Examples

# Update the Account with Id '0016000000MRatd'
client.update!('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')

Returns true if the sobject was successfully updated. Raises an exception if an error is returned from Salesforce.

# File lib/restforce/concerns/api.rb, line 321
def update!(sobject, attrs)
  id = attrs.fetch(attrs.keys.find { |k, v| k.to_s.casecmp('id').zero? }, nil)
  raise ArgumentError, 'ID field missing from provided attributes' unless id

  attrs_without_id = attrs.reject { |k, v| k.to_s.casecmp("id").zero? }
  api_patch "sobjects/#{sobject}/#{CGI.escape(id)}", attrs_without_id
  true
end
upsert(*args) click to toggle source

Public: Update or create a record based on an external ID

sobject - The name of the sobject to created. field - The name of the external Id field to match against. attrs - Hash of attributes for the record.

Examples

# Update the record with external ID of 12
client.upsert('Account', 'External__c', External__c: 12, Name: 'Foobar')

Returns true if the record was found and updated. Returns the Id of the newly created record if the record was created. Returns false if something bad happens (for example if the external ID matches multiple resources).

# File lib/restforce/concerns/api.rb, line 345
def upsert(*args)
  upsert!(*args)
rescue *exceptions
  false
end
upsert!(sobject, field, attrs) click to toggle source

Public: Update or create a record based on an external ID

sobject - The name of the sobject to created. field - The name of the external Id field to match against. attrs - Hash of attributes for the record.

Examples

# Update the record with external ID of 12
client.upsert!('Account', 'External__c', External__c: 12, Name: 'Foobar')

Returns true if the record was found and updated. Returns the Id of the newly created record if the record was created. Raises an exception if an error is returned from Salesforce, including the 300 error returned if the external ID provided matches multiple records (in which case the conflicting IDs can be found by looking at the response on the error)

# File lib/restforce/concerns/api.rb, line 367
def upsert!(sobject, field, attrs)
  attrs = attrs.dup
  external_id =
    extract_case_insensitive_string_or_symbol_key_from_hash!(attrs, field).to_s
  if field.to_s != "Id" && (external_id.nil? || external_id.strip.empty?)
    raise ArgumentError, 'Specified external ID field missing from provided ' \
                         'attributes'
  end

  response =
    if field.to_s == "Id" && (external_id.nil? || external_id.strip.empty?)
      version_guard(37.0) do
        api_post "sobjects/#{sobject}/#{field}", attrs
      end
    else
      api_patch "sobjects/#{sobject}/#{field}/" \
                "#{ERB::Util.url_encode(external_id)}", attrs
    end

  response.body.respond_to?(:fetch) ? response.body.fetch('id', true) : true
end
user_info() click to toggle source

Public: Get info about the logged-in user.

Examples

# get the email of the logged-in user
client.user_info.email
# => user@example.com

Returns an Array of String names for each SObject.

# File lib/restforce/concerns/api.rb, line 45
def user_info
  get(api_get.body.identity).body
end

Private Instance Methods

api_path(path) click to toggle source

Internal: Returns a path to an api endpoint

Examples

api_path('sobjects')
# => '/services/data/v24.0/sobjects'
# File lib/restforce/concerns/api.rb, line 486
def api_path(path)
  "/services/data/v#{options[:api_version]}/#{path}"
end
exceptions() click to toggle source

Internal: Errors that should be rescued from in non-bang methods

# File lib/restforce/concerns/api.rb, line 513
def exceptions
  [Faraday::Error]
end
extract_case_insensitive_string_or_symbol_key_from_hash!(hash, key) click to toggle source
# File lib/restforce/concerns/api.rb, line 504
def extract_case_insensitive_string_or_symbol_key_from_hash!(hash, key)
  value = hash.delete(key.to_sym)
  value ||= hash.delete(key.to_s)
  value ||= hash.delete(key.to_s.downcase)
  value ||= hash.delete(key.to_s.downcase.to_sym)
  value
end
version_guard(version) { || ... } click to toggle source

Internal: Ensures that the ‘api_version` set for the Restforce client is at least the provided version before performing a particular action

# File lib/restforce/concerns/api.rb, line 492
def version_guard(version)
  if version.to_f <= options[:api_version].to_f
    yield
  else
    raise APIVersionError, "You must set an `api_version` of at least #{version} " \
                           "to use this feature in the Salesforce API. Set the " \
                           "`api_version` option when configuring the client - " \
                           "see https://github.com/ejholmes/restforce/blob/master" \
                           "/README.md#api-versions"
  end
end