Module: Restforce::Concerns::API

Extended by:
Verbs
Included in:
AbstractClient
Defined in:
lib/restforce/concerns/api.rb

Instance Method Summary collapse

Methods included from Verbs

define_api_verb, define_verb, define_verbs

Instance Method Details

#create(*args) ⇒ Object Also known as: insert

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.



263
264
265
266
267
# File 'lib/restforce/concerns/api.rb', line 263

def create(*args)
  create!(*args)
rescue *exceptions
  false
end

#create!(sobject, attrs) ⇒ Object Also known as: insert!

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.



283
284
285
# File 'lib/restforce/concerns/api.rb', line 283

def create!(sobject, attrs)
  api_post("sobjects/#{sobject}", attrs).body['id']
end

#describe(sobject = nil) ⇒ Object

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.



123
124
125
126
127
128
129
# File 'lib/restforce/concerns/api.rb', line 123

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) ⇒ Object

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



147
148
149
150
151
152
153
154
155
# File 'lib/restforce/concerns/api.rb', line 147

def describe_layouts(sobject, layout_id = nil)
  version_guard(28.0) do
    if layout_id
      api_get("sobjects/#{sobject}/describe/layouts/#{layout_id}").body
    else
      api_get("sobjects/#{sobject}/describe/layouts").body
    end
  end
end

#destroy(*args) ⇒ Object

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.



386
387
388
389
390
# File 'lib/restforce/concerns/api.rb', line 386

def destroy(*args)
  destroy!(*args)
rescue *exceptions
  false
end

#destroy!(sobject, id) ⇒ Object

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.



404
405
406
407
# File 'lib/restforce/concerns/api.rb', line 404

def destroy!(sobject, id)
  api_delete "sobjects/#{sobject}/#{id}"
  true
end

#explain(soql) ⇒ Object

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 => [Array of plan data] See: www.salesforce.com/us/developer/docs/api_rest/Content/dome_query_expl

ain.htm


201
202
203
# File 'lib/restforce/concerns/api.rb', line 201

def explain(soql)
  version_guard(30.0) { api_get("query", explain: soql).body }
end

#find(sobject, id, field = nil) ⇒ Object

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.



417
418
419
420
421
422
423
424
# File 'lib/restforce/concerns/api.rb', line 417

def find(sobject, id, field = nil)
  if field
    url = "sobjects/#{sobject}/#{field}/#{URI.encode(id)}"
  else
    url = "sobjects/#{sobject}/#{id}"
  end
  api_get(url).body
end

#get_deleted(sobject, start_time, end_time) ⇒ Object

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.



101
102
103
104
105
106
# File 'lib/restforce/concerns/api.rb', line 101

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) ⇒ Object

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.



81
82
83
84
85
86
# File 'lib/restforce/concerns/api.rb', line 81

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

#limitsObject

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.



64
65
66
# File 'lib/restforce/concerns/api.rb', line 64

def limits
  version_guard(29.0) { api_get("limits").body }
end

#list_sobjectsObject

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.



55
56
57
# File 'lib/restforce/concerns/api.rb', line 55

def list_sobjects
  describe.collect { |sobject| sobject['name'] }
end

#org_idObject

Public: Get the current organization’s Id.

Examples

client.org_id
# => '00Dx0000000BV7z'

Returns the String organization Id



165
166
167
# File 'lib/restforce/concerns/api.rb', line 165

def org_id
  query('select id from Organization').first['Id']
end

#query(soql) ⇒ Object

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.



182
183
184
185
# File 'lib/restforce/concerns/api.rb', line 182

def query(soql)
  response = api_get 'query', q: soql
  mashify? ? response.body : response.body['records']
end

#query_all(soql) ⇒ Object

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.



222
223
224
225
226
227
# File 'lib/restforce/concerns/api.rb', line 222

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) ⇒ Object

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.



455
456
457
458
459
# File 'lib/restforce/concerns/api.rb', line 455

def recent(limit = nil)
  path = limit ? "recent?limit=#{limit}" : "recent"

  api_get(path).body
end

#search(sosl) ⇒ Object

Public: Perform a SOSL search

sosl - A SOSL expression.

Examples

# Find all occurrences of 'bar'
client.search('FIND {bar}')
# => #<Restforce::Collection >

# Find accounts match the term 'genepoint' and return the Name field
client.search('FIND {genepoint} RETURNING Account (Name)').map(&:Name)
# => ['GenePoint']

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.



246
247
248
# File 'lib/restforce/concerns/api.rb', line 246

def search(sosl)
  api_get('search', q: sosl).body
end

#select(sobject, id, select, field = nil) ⇒ Object

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).



435
436
437
438
439
440
441
442
443
444
# File 'lib/restforce/concerns/api.rb', line 435

def select(sobject, id, select, field = nil)
  if field
    path = "sobjects/#{sobject}/#{field}/#{URI.encode(id)}"
  else
    path = "sobjects/#{sobject}/#{id}"
  end
  path << "?fields=#{select.join(',')}" if select && select.any?

  api_get(path).body
end

#update(*args) ⇒ Object

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.



300
301
302
303
304
# File 'lib/restforce/concerns/api.rb', line 300

def update(*args)
  update!(*args)
rescue *exceptions
  false
end

#update!(sobject, attrs) ⇒ Object

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.

Raises:

  • (ArgumentError)


318
319
320
321
322
323
324
# File 'lib/restforce/concerns/api.rb', line 318

def update!(sobject, attrs)
  id = attrs.fetch(attrs.keys.find { |k, v| k.to_s.downcase == 'id' }, nil)
  raise ArgumentError, 'Id field missing from attrs.' unless id
  attrs_without_id = attrs.reject { |k, v| k.to_s.downcase == "id" }
  api_patch "sobjects/#{sobject}/#{id}", attrs_without_id
  true
end

#upsert(*args) ⇒ Object

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).



341
342
343
344
345
# File 'lib/restforce/concerns/api.rb', line 341

def upsert(*args)
  upsert!(*args)
rescue *exceptions
  false
end

#upsert!(sobject, field, attrs) ⇒ Object

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)



363
364
365
366
367
368
369
370
371
372
# File 'lib/restforce/concerns/api.rb', line 363

def upsert!(sobject, field, attrs)
  external_id = attrs.
    fetch(attrs.keys.find { |k, v| k.to_s.downcase == field.to_s.downcase }, nil)
  attrs_without_field = attrs.
    reject { |k, v| k.to_s.downcase == field.to_s.downcase }
  response = api_patch "sobjects/#{sobject}/#{field}/#{URI.encode(external_id)}",
                       attrs_without_field

  (response.body && response.body['id']) ? response.body['id'] : true
end

#user_infoObject

Public: Get info about the logged-in user.

Examples

# get the email of the logged-in user
client..email
# => [email protected]

Returns an Array of String names for each SObject.



42
43
44
# File 'lib/restforce/concerns/api.rb', line 42

def 
  get(api_get.body.identity).body
end