Module: Restforce::Concerns::API
Instance Method Summary collapse
-
#create(*args) ⇒ Object
(also: #insert)
Public: Insert a new record.
-
#create!(sobject, attrs) ⇒ Object
(also: #insert!)
Public: Insert a new record.
-
#describe(sobject = nil) ⇒ Object
Public: Returns a detailed describe result for the specified sobject.
-
#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.
-
#destroy(*args) ⇒ Object
Public: Delete a record.
-
#destroy!(sobject, id) ⇒ Object
Public: Delete a record.
-
#explain(soql) ⇒ Object
Public: Explain a SOQL query execution plan.
-
#find(sobject, id, field = nil) ⇒ Object
Public: Finds a single record and returns all fields.
-
#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.
-
#get_updated(sobject, start_time, end_time) ⇒ Object
Public: Gets the IDs of sobjects of type [sobject] which have changed between startDateTime and endDateTime.
-
#limits ⇒ Object
Public: Get info about limits in the connected organization.
-
#list_sobjects ⇒ Object
Public: Get the names of all sobjects on the org.
-
#org_id ⇒ Object
Public: Get the current organization’s Id.
-
#query(soql) ⇒ Object
Public: Executs a SOQL query and returns the result.
-
#query_all(soql) ⇒ Object
Public: Executes a SOQL query and returns the result.
-
#recent(limit = nil) ⇒ Object
Public: Finds recently viewed items for the logged-in user.
-
#search(sosl) ⇒ Object
Public: Perform a SOSL search.
-
#select(sobject, id, select, field = nil) ⇒ Object
Public: Finds a single record and returns select fields.
-
#update(*args) ⇒ Object
Public: Update a record.
-
#update!(sobject, attrs) ⇒ Object
Public: Update a record.
-
#upsert(*args) ⇒ Object
Public: Update or create a record based on an external ID.
-
#upsert!(sobject, field, attrs) ⇒ Object
Public: Update or create a record based on an external ID.
-
#user_info ⇒ Object
Public: Get info about the logged-in user.
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.
262 263 264 265 266 |
# File 'lib/restforce/concerns/api.rb', line 262 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.
282 283 284 |
# File 'lib/restforce/concerns/api.rb', line 282 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.
122 123 124 125 126 127 128 |
# File 'lib/restforce/concerns/api.rb', line 122 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
146 147 148 149 150 151 152 153 154 |
# File 'lib/restforce/concerns/api.rb', line 146 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.
385 386 387 388 389 |
# File 'lib/restforce/concerns/api.rb', line 385 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.
403 404 405 406 |
# File 'lib/restforce/concerns/api.rb', line 403 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
200 201 202 |
# File 'lib/restforce/concerns/api.rb', line 200 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.
416 417 418 419 |
# File 'lib/restforce/concerns/api.rb', line 416 def find(sobject, id, field = nil) url = field ? "sobjects/#{sobject}/#{field}/#{id}" : "sobjects/#{sobject}/#{id}" 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.
100 101 102 103 104 105 |
# File 'lib/restforce/concerns/api.rb', line 100 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.
80 81 82 83 84 85 |
# File 'lib/restforce/concerns/api.rb', line 80 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 |
#limits ⇒ Object
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.
63 64 65 |
# File 'lib/restforce/concerns/api.rb', line 63 def limits version_guard(29.0) { api_get("limits").body } end |
#list_sobjects ⇒ Object
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.
54 55 56 |
# File 'lib/restforce/concerns/api.rb', line 54 def list_sobjects describe.collect { |sobject| sobject['name'] } end |
#org_id ⇒ Object
Public: Get the current organization’s Id.
Examples
client.org_id
# => '00Dx0000000BV7z'
Returns the String organization Id
164 165 166 |
# File 'lib/restforce/concerns/api.rb', line 164 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.
181 182 183 184 |
# File 'lib/restforce/concerns/api.rb', line 181 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.
221 222 223 224 225 226 |
# File 'lib/restforce/concerns/api.rb', line 221 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.
446 447 448 449 450 |
# File 'lib/restforce/concerns/api.rb', line 446 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.
245 246 247 |
# File 'lib/restforce/concerns/api.rb', line 245 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).
430 431 432 433 434 435 |
# File 'lib/restforce/concerns/api.rb', line 430 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 |
#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.
299 300 301 302 303 |
# File 'lib/restforce/concerns/api.rb', line 299 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.
317 318 319 320 321 322 323 |
# File 'lib/restforce/concerns/api.rb', line 317 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).
340 341 342 343 344 |
# File 'lib/restforce/concerns/api.rb', line 340 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)
362 363 364 365 366 367 368 369 370 371 |
# File 'lib/restforce/concerns/api.rb', line 362 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}/#{external_id}", attrs_without_field (response.body && response.body['id']) ? response.body['id'] : true end |
#user_info ⇒ Object
Public: Get info about the logged-in user.
Examples
# get the email of the logged-in user
client.user_info.email
# => [email protected]
Returns an Array of String names for each SObject.
41 42 43 |
# File 'lib/restforce/concerns/api.rb', line 41 def user_info get(api_get.body.identity).body end |