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.
-
#find(sobject, id, field = nil) ⇒ Object
Public: Finds a single record and returns all fields.
-
#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.
-
#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.
167 168 169 170 171 |
# File 'lib/restforce/concerns/api.rb', line 167 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.
187 188 189 |
# File 'lib/restforce/concerns/api.rb', line 187 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.
73 74 75 76 77 78 79 |
# File 'lib/restforce/concerns/api.rb', line 73 def describe(sobject = nil) if sobject api_get("sobjects/#{sobject.to_s}/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.
This resource was introduced in version 28.0.
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
97 98 99 100 101 102 103 |
# File 'lib/restforce/concerns/api.rb', line 97 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 |
#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.
281 282 283 284 285 |
# File 'lib/restforce/concerns/api.rb', line 281 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.
299 300 301 302 |
# File 'lib/restforce/concerns/api.rb', line 299 def destroy!(sobject, id) api_delete "sobjects/#{sobject}/#{id}" true 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.
312 313 314 |
# File 'lib/restforce/concerns/api.rb', line 312 def find(sobject, id, field=nil) api_get(field ? "sobjects/#{sobject}/#{field}/#{id}" : "sobjects/#{sobject}/#{id}").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
113 114 115 |
# File 'lib/restforce/concerns/api.rb', line 113 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.
129 130 131 132 |
# File 'lib/restforce/concerns/api.rb', line 129 def query(soql) response = api_get 'query', :q => soql mashify? ? response.body : response.body['records'] 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.
150 151 152 |
# File 'lib/restforce/concerns/api.rb', line 150 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).
325 326 327 328 329 330 |
# File 'lib/restforce/concerns/api.rb', line 325 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.
204 205 206 207 208 |
# File 'lib/restforce/concerns/api.rb', line 204 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.
222 223 224 225 226 227 |
# File 'lib/restforce/concerns/api.rb', line 222 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 |
#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.
243 244 245 246 247 |
# File 'lib/restforce/concerns/api.rb', line 243 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.
263 264 265 266 267 |
# File 'lib/restforce/concerns/api.rb', line 263 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 |
#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 |