Class: Restforce::Client

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

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

Public: Creates a new client instance

options - 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')

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={ ... }>



51
52
53
54
55
56
57
58
59
60
 
# File 'lib/restforce/client.rb', line 51

def initialize(options = {})
  raise 'Please specify a hash of options' unless options.is_a?(Hash)
  @options = {}.tap do |options|
    [:username, :password, :security_token, :client_id, :client_secret, :host,
     :api_version, :oauth_token, :refresh_token, :instance_url, :cache].each do |option|
      options[option] = Restforce.configuration.send option
    end
  end
  @options.merge!(options)
end

Instance Method Details

#authenticate! ⇒ Object

Public: Force an authentication



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

def authenticate!
  connection.headers['X-ForceAuthenticate'] = true
  get nil
ensure
  connection.headers.delete('X-ForceAuthenticate')
end

#create(sobject, attrs) ⇒ Object

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



159
160
161
162
163
 
# File 'lib/restforce/client.rb', line 159

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

#create!(sobject, attrs) ⇒ Object

See .create

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



169
170
171
172
 
# File 'lib/restforce/client.rb', line 169

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

#describe(sobject) ⇒ Object

Public: Returns a detailed describe result for the specified sobject

sobject - Stringish name of the sobject (default: nil).

Examples

# get the describe for the Account object
client.describe('Account')
# => { ... }

Returns the Hash representation of the describe call.



94
95
96
97
 
# File 'lib/restforce/client.rb', line 94

def describe(sobject)
  response = api_get "sobjects/#{sobject.to_s}/describe"
  response.body
end

#describe_sobjects ⇒ Object

Public: Get the global describe for all sobjects.

Returns the Hash representation of the describe call.



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

def describe_sobjects
  response = api_get 'sobjects'
  response.body['sobjects']
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.



237
238
239
240
241
 
# File 'lib/restforce/client.rb', line 237

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.



247
248
249
250
 
# File 'lib/restforce/client.rb', line 247

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.



79
80
81
 
# File 'lib/restforce/client.rb', line 79

def list_sobjects
  describe_sobjects.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



107
108
109
 
# File 'lib/restforce/client.rb', line 107

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.



123
124
125
126
 
# File 'lib/restforce/client.rb', line 123

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.



144
145
146
147
 
# File 'lib/restforce/client.rb', line 144

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



258
259
260
 
# File 'lib/restforce/client.rb', line 258

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.



182
183
184
185
186
 
# File 'lib/restforce/client.rb', line 182

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.



192
193
194
195
196
 
# File 'lib/restforce/client.rb', line 192

def update!(sobject, attrs)
  id = attrs.has_key?(:Id) ? attrs.delete(:Id) : attrs.delete('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.



212
213
214
215
216
 
# File 'lib/restforce/client.rb', line 212

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.



223
224
225
226
227
 
# File 'lib/restforce/client.rb', line 223

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