Class: Restforce::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/restforce/client.rb

Constant Summary collapse

OPTIONS = 
[:username, :password, :security_token, :client_id, :client_secret, :host, :compress,
:api_version, :oauth_token, :refresh_token, :instance_url, :cache, :authentication_retries]

Instance Method Summary collapse

Constructor Details

#initialize(opts = {}) ⇒ Client

Public: Creates a new client instance

opts - A hash of options to be passed in (default: {}).

:username               - The String username to use (required for password authentication).
:password               - The String password to use (required for password authentication).
:security_token         - The String security token to use 
                          (required for password authentication).

:oauth_token            - The String oauth access token to authenticate api
                          calls (required unless password
                          authentication is used).
:refresh_token          - The String refresh token to obtain fresh
                          oauth access tokens (required if oauth
                          authentication is used).
:instance_url           - The String base url for all api requests
                          (required if oauth authentication is used).

:client_id              - The oauth client id to use. Needed for both
                          password and oauth authentication
:client_secret          - The oauth client secret to use.

:host                   - The String hostname to use during
                          authentication requests (default: 'login.salesforce.com').

:api_version            - The String REST api version to use (default: '24.0')

:authentication_retries - The number of times that client
                          should attempt to reauthenticate
                          before raising an exception (default: 3).

:compress               - Set to true to have Salesforce compress the
                          response (default: false).

Examples

# Initialize a new client using password authentication:
Restforce::Client.new :username => 'user',
  :password => 'pass',
  :security_token => 'security token',
  :client_id => 'client id',
  :client_secret => 'client secret'
# => #<Restforce::Client:0x007f934aa2dc28 @options={ ... }>

# Initialize a new client using oauth authentication:
Restforce::Client.new :oauth_token => 'access token',
  :refresh_token => 'refresh token',
  :instance_url => 'https://na1.salesforce.com',
  :client_id => 'client id',
  :client_secret => 'client secret'
# => #<Restforce::Client:0x007f934aaaa0e8 @options={ ... }>

# Initialize a new client with using any authentication middleware:
Restforce::Client.new :oauth_token => 'access token',
  :instance_url => 'https://na1.salesforce.com'
# => #<Restforce::Client:0x007f934aab9980 @options={ ... }>



61
62
63
64
65
 
# File 'lib/restforce/client.rb', line 61

def initialize(opts = {})
  raise 'Please specify a hash of options' unless opts.is_a?(Hash)
  @options = Hash[OPTIONS.map { |option| [option, Restforce.configuration.send(option)] }]
  @options.merge! opts
end

Instance Method Details

#authenticate! ⇒ Object

Public: Force an authentication



280
281
282
283
284
 
# File 'lib/restforce/client.rb', line 280

def authenticate!
  raise 'No authentication middleware present' unless authentication_middleware
  middleware = authentication_middleware.new nil, self, @options
  middleware.authenticate!
end

#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



162
163
164
165
166
 
# File 'lib/restforce/client.rb', line 162

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.



173
174
175
 
# File 'lib/restforce/client.rb', line 173

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

#decode_signed_request(message) ⇒ Object

Public: Decodes a signed request received from Force.com Canvas.

message - The POST message containing the signed request from Salesforce.

Returns the Hash context if the message is valid.



291
292
293
294
 
# File 'lib/restforce/client.rb', line 291

def decode_signed_request(message)
  raise 'client_secret not set' unless @options[:client_secret]
  Restforce.decode_signed_request(message, @options[:client_secret])
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.



95
96
97
98
99
100
101
 
# File 'lib/restforce/client.rb', line 95

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.



242
243
244
245
246
 
# File 'lib/restforce/client.rb', line 242

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.



252
253
254
255
 
# File 'lib/restforce/client.rb', line 252

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.



76
77
78
 
# File 'lib/restforce/client.rb', line 76

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

#middleware ⇒ Object

Public: The Faraday::Builder instance used for the middleware stack. This can be used to insert an custom middleware.

Examples

# Add the instrumentation middleware for Rails.
client.middleware.use FaradayMiddleware::Instrumentation

Returns the Faraday::Builder for the Faraday connection.



348
349
350
 
# File 'lib/restforce/client.rb', line 348

def middleware
  connection.builder
end

#org_id ⇒ Object

Public: Get the current organization’s Id.

Examples

client.org_id
# => '00Dx0000000BV7z'

Returns the String organization Id



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

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.



127
128
129
130
 
# File 'lib/restforce/client.rb', line 127

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.



148
149
150
 
# File 'lib/restforce/client.rb', line 148

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

#subscribe(channel, &block) ⇒ Object

Public: Subscribe to a PushTopic

channel - The name of the PushTopic channel to subscribe to. block - A block to run when a new message is received.

Returns a Faye::Subscription



275
276
277
 
# File 'lib/restforce/client.rb', line 275

def subscribe(channel, &block)
  faye.subscribe "/topic/#{channel}", &block
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.



186
187
188
189
190
 
# File 'lib/restforce/client.rb', line 186

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.



196
197
198
199
200
201
 
# File 'lib/restforce/client.rb', line 196

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.



217
218
219
220
221
 
# File 'lib/restforce/client.rb', line 217

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.



228
229
230
231
232
 
# File 'lib/restforce/client.rb', line 228

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

#without_caching(&block) ⇒ Object

Public: Runs the block with caching disabled.

block - A query/describe/etc.

Returns the result of the block



262
263
264
265
266
267
 
# File 'lib/restforce/client.rb', line 262

def without_caching(&block)
  @options[:perform_caching] = false
  block.call
ensure
  @options.delete(:perform_caching)
end