module Restforce::Concerns::API

def api_path(path)

# => '/services/data/v24.0/sobjects'
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 false if something bad happens.
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)

Raises exceptions if an error is returned from Salesforce.
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)

Returns the Hash representation of the describe call.

# => { ... }
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 destroy(*args)

Returns false if an error is returned from Salesforce.
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)

Raises an exception if an error is returned from Salesforce.
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

Internal: Errors that should be rescued from in non-bang methods 
def exceptions
  [Faraday::Error::ClientError]
end

def find(sobject, id, field=nil)

Returns the Restforce::SObject sobject record.

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

Returns an Array of String names for each SObject.

# => ['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

Returns the String organization 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 an Array of Hash for each record in the result if Restforce.configuration.mashify is false.
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 an Array of Hash for each record in the result if Restforce.configuration.mashify is false.
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 update(*args)

Returns false if there was an error.
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)

Raises an exception if an error is returned from Salesforce.
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 false if something bad happens.
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)

Raises an exception if an error is returned from Salesforce.
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