Module: Restforce::Client::API

Included in:
Restforce::Client
Defined in:
lib/restforce/client/api.rb

Instance Method Summary collapse

Instance Method Details

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

Public: Insert a 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



100
101
102
103
104
 
# File 'lib/restforce/client/api.rb', line 100

def create(sobject, attrs)
  create!(sobject, attrs)
rescue *exceptions
  false
end

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

See .create

Returns the String Id of the newly created sobject. Raises an error if something bad happens.



111
112
113
 
# File 'lib/restforce/client/api.rb', line 111

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.



33
34
35
36
37
38
39
 
# File 'lib/restforce/client/api.rb', line 33

def describe(sobject=nil)
  if sobject
    api_get("sobjects/#{sobject.to_s}/describe").body
  else
    api_get('sobjects').body['sobjects']
  end
end

#destroy(sobject, id) ⇒ Object

Public: Delete a record.

Examples

# Delete the Account with Id '0016000000MRatd'
client.delete('Account', '0016000000MRatd')

Returns true if the sobject was successfully deleted, false otherwise.



180
181
182
183
184
 
# File 'lib/restforce/client/api.rb', line 180

def destroy(sobject, id)
  destroy!(sobject, id)
rescue *exceptions
  false
end

#destroy!(sobject, id) ⇒ Object

See .destroy

Returns true of the sobject was successfully deleted, raises an error otherwise.



190
191
192
193
 
# File 'lib/restforce/client/api.rb', line 190

def destroy!(sobject, id)
  api_delete "sobjects/#{sobject}/#{id}"
  true
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.



14
15
16
 
# File 'lib/restforce/client/api.rb', line 14

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



49
50
51
 
# File 'lib/restforce/client/api.rb', line 49

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.



65
66
67
68
 
# File 'lib/restforce/client/api.rb', line 65

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.



86
87
88
 
# File 'lib/restforce/client/api.rb', line 86

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

#update(sobject, attrs) ⇒ Object

Public: Update a record.

Examples

# Update the Account with Id '0016000000MRatd'
client.update('Account', Id: '0016000000MRatd', Name: 'Whizbang Corp')

Returns true if the sobject was successfully updated, false otherwise.



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

def update(sobject, attrs)
  update!(sobject, attrs)
rescue *exceptions
  false
end

#update!(sobject, attrs) ⇒ Object

See .update

Returns true if the sobject was successfully updated, raises an error otherwise.



134
135
136
137
138
139
 
# File 'lib/restforce/client/api.rb', line 134

def update!(sobject, attrs)
  id = attrs.has_key?(:Id) ? attrs.delete(:Id) : attrs.delete('Id')
  raise 'Id field missing.' unless id
  api_patch "sobjects/#{sobject}/#{id}", attrs
  true
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. Returns false if something bad happens.



155
156
157
158
159
 
# File 'lib/restforce/client/api.rb', line 155

def upsert(sobject, field, attrs)
  upsert!(sobject, field, attrs)
rescue *exceptions
  false
end

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

See .upsert

Returns true if the record was found and updated. Returns the Id of the newly created record if the record was created. Raises an error if something bad happens.



166
167
168
169
170
 
# File 'lib/restforce/client/api.rb', line 166

def upsert!(sobject, field, attrs)
  external_id = attrs.has_key?(field.to_sym) ? attrs.delete(field.to_sym) : attrs.delete(field.to_s)
  response = api_patch "sobjects/#{sobject}/#{field.to_s}/#{external_id}", attrs
  (response.body && response.body['id']) ? response.body['id'] : true
end