Class: RForce::Wrapper::Connection

Inherits:
Object
  • Object
show all
Includes:
ApiMethods::CoreMethods, ApiMethods::DescribeMethods, ApiMethods::UtilityMethods
Defined in:
lib/rforce-wrapper/connection.rb

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from ApiMethods::UtilityMethods

#getServerTimestamp, #getUserInfo, #resetPassword, #sendEmail, #setPassword

Methods included from ApiMethods::DescribeMethods

#describeDataCategoryGroupStructures, #describeDataCategoryGroups, #describeGlobal, #describeLayout, #describeSObject, #describeSObjects, #describeSoftphoneLayout, #describeTabs

Methods included from ApiMethods::CoreMethods

#convertLead, #create, #delete, #emptyRecycleBin, #getDeleted, #getUpdated, #invalidateSessions, #logout, #merge, #process, #query, #queryAll, #queryMore, #retrieve, #search, #undelete, #update, #upsert

Constructor Details

- (Connection) initialize(email, pass, options = {})

Creates a new connect to the Salesforce API using the given email and password or password+token combination and connects to the API. Additional options can be specified. If a version of the Salesforce API that is not supported by the gem is passed, a warning is issued.

Parameters:

  • email (String) —

    the email address of the account to log in with

  • pass (String) —

    the password or password+token combo for the account

  • options (Hash) (defaults to: {}) —

    additional options for the connection

Options Hash (options):

  • :environment (:live, :test) —

    the environment, defaults to :live

  • :version (String) —

    the version of the Salesforce API to use, defaults to '21.0'

  • :wrap_results (Boolean) —

    whether or not to wrap single-element results into an array, defaults to true

Raises:

See Also:



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/rforce-wrapper/connection.rb', line 38

def initialize(email, pass, options = {})
  options = {
    :environment  => :live,
    :version      => '21.0',
    :wrap_results => true
  }.merge(options)
  @wrap_results = options[:wrap_results]
  unless SF_API_VERSIONS.include? options[:version]
    message = "Version #{options[:version]} of the Salesforce Web " +
      "Services API is not supported by RForce-wrapper."
    Kernel.warn(message)
  end
  @binding = RForce::Binding.new Connection.url_for_environment(options[:environment], options[:version])
  @binding. email, pass
end

Instance Attribute Details

- (RForce::Binding) binding (readonly)

The underlying RForce::Binding object.

Returns:

  • (RForce::Binding) —

    the underlying RForce::Binding object.



19
20
21
 
# File 'lib/rforce-wrapper/connection.rb', line 19

def binding
  @binding
end

Class Method Details

+ (String) url_for_environment(type, version)

Returns the URL for the given environment type and version.

Parameters:

  • type (:live, :test) —

    the environment type

  • version (String) —

    the version of the Salesforce API to use

Returns:

  • (String) —

    the URL for the given environment and version

Raises:



61
62
63
64
65
66
67
68
69
70
 
# File 'lib/rforce-wrapper/connection.rb', line 61

def self.url_for_environment(type, version)
  case type
  when :test
    "https://test.salesforce.com/services/Soap/u/#{version}"
  when :live
    "https://www.salesforce.com/services/Soap/u/#{version}"
  else
    raise InvalidEnvironmentException.new "Invalid environment type: #{type.to_s}"
  end
end

Instance Method Details

- (Hash, ...) make_api_call(method, params = nil)

Performs a SOAP API call via the underlying RForce::Binding object. Raises an exception if a Fault is detected. Returns the data portion of the result (wrapped in an Array if wrap_results is true; see #initialize).

Parameters:

  • method (Symbol) —

    the API method to call

  • params (Array, Hash, nil) (defaults to: nil) —

    the parameters to pass to the API method. RForce::Binding expects either an Array or Hash to turn into SOAP arguments. Pass nil, [] or {} if the API call takes no parameters.

Returns:

  • (Hash, Array, nil) —

    a hash of the data portion of the result, wrapped in an array if wrap_results is true and the results are not already an array (indicating multiple results); see #initialize. If there is no data in the result, nil is returned.

Raises:



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/rforce-wrapper/connection.rb', line 88

def make_api_call(method, params = nil)
  result = @binding.send method, params

  # Errors will result in result[:Fault] being set
  if result[:Fault]
    raise SalesforceFaultException.new result[:Fault][:faultcode], result[:Fault][:faultstring]
  end

  # If the result was successful, there will be a key: "#{method.to_s}Response".to_sym
  # which will contain the key :result
  result_field_name = method.to_s + "Response"
  if result[result_field_name.to_sym]
    data = result[result_field_name.to_sym][:result]
    @wrap_results ? Utilities.ensure_array(data) : data
  else
    nil
  end
end