Module: Sfdc::Concerns::API

Extended by:
Verbs
Included in:
AbstractClient
Defined in:
lib/sfdc/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.



159
160
161
162
163
 
# File 'lib/sfdc/concerns/api.rb', line 159

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.



179
180
181
 
# File 'lib/sfdc/concerns/api.rb', line 179

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.



60
61
62
63
64
65
66
 
# File 'lib/sfdc/concerns/api.rb', line 60

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



84
85
86
87
88
89
90
 
# File 'lib/sfdc/concerns/api.rb', line 84

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.



273
274
275
276
277
 
# File 'lib/sfdc/concerns/api.rb', line 273

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.



291
292
293
294
 
# File 'lib/sfdc/concerns/api.rb', line 291

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 Sfdc::SObject sobject record.



304
305
306
 
# File 'lib/sfdc/concerns/api.rb', line 304

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.



41
42
43
 
# File 'lib/sfdc/concerns/api.rb', line 41

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



100
101
102
 
# File 'lib/sfdc/concerns/api.rb', line 100

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

#post_chatter(text, url = nil) ⇒ Object

Chatter ##################### client.post_chatter(“text”, “url”)



310
311
312
313
314
 
# File 'lib/sfdc/concerns/api.rb', line 310

def post_chatter(text, url=nil)
  base_url = "chatter/feeds/news/me/feed-items?"
  base_url += ((url == nil) ? "text=#{text}" : "text=#{text}&url=#{url}")
  api_post(base_url)
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 Sfdc::Collection if Sfdc.configuration.mashify is true. Returns an Array of Hash for each record in the result if Sfdc.configuration.mashify is false.



116
117
118
119
 
# File 'lib/sfdc/concerns/api.rb', line 116

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

#recent(num) ⇒ Object

get a list of recently viewed records.



142
143
144
 
# File 'lib/sfdc/concerns/api.rb', line 142

def recent(num)
  api_get('recent', :q => num).body
end

#search(sosl) ⇒ Object

Public: Perform a SOSL search

sosl - A SOSL expression.

Examples

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

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

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



137
138
139
 
# File 'lib/sfdc/concerns/api.rb', line 137

def search(sosl)
  api_get('search', :q => sosl).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.



196
197
198
199
200
 
# File 'lib/sfdc/concerns/api.rb', line 196

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) 


214
215
216
217
218
219
 
# File 'lib/sfdc/concerns/api.rb', line 214

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.



235
236
237
238
239
 
# File 'lib/sfdc/concerns/api.rb', line 235

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.



255
256
257
258
259
 
# File 'lib/sfdc/concerns/api.rb', line 255

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