SalesforceSoapClient::SalesforceSoapClient Class Reference

class provising SOAP API access to Salesforce.com More...

Inheritance diagram for SalesforceSoapClient::SalesforceSoapClient:
[legend]

## Public Member Functions

| constructor (hash opts)
| creates the object with the given options More...
| destructor ()
| destroys the object More...
| login ()
| performs a manual login to Salesforce.com
| logout ()
| performs a manual logout to Salesforce.com
| disconnect ()
| disconnects from Salesforce.com; if the `force_logout` option was given in the constructor(), then a logout is performed before disconnecting
any | callOperation (string operation, any args, *hash opts, *reference info)
| makes a server call with the given operation, arguments, options, and optional info hash reference and returns the result More...
any | call (string operation, any args, *hash header)
| makes a server call with the given operation and arguments and returns the deserialized result More...
any | call (string operation, any args, reference info)
| makes a server call with the given operation and arguments and returns the deserialized result More...
any | call (reference info, string operation, any args, *hash header)
| makes a server call with the given operation and arguments and returns the deserialized result with an output argument giving technical information about the call More...
any | methodGate (string op, any arg)
| uses call() to transparently serialize the argument and make a call to the given operation and return the deserialized results More...

## Public Attributes

const | AuthorizationHash
| authorization key required for logging in to Salesforce.com
const | AuthorizationOpts = AuthorizationHash.keys()
| list of authorization keys
const | RequiredOpts
| required options

## Private Member Functions

| processOpts (hash opts)
| processes options given in the constructor()
any | callIntern (string operation, any args, *hash opts, *reference info)
| makes the internal call and returns the deserialized response More...

## Private Attributes

bool | force_logout = False

## Detailed Description

class provising SOAP API access to Salesforce.com

This class inherits SoapClient to perform SOAP communication with Salesforce.com.

Note
  By default this class does not log out of Salesforce.com in the destructor in order to keep the API session alive. To force a logout of the session in the destructor, use the `force_logout` option in the constructor().

## Member Function Documentation

## call() [1/3]

any SalesforceSoapClient::SalesforceSoapClient::call | ( | string | operation,
|  | any | args,
|  | *hash | header
| ) |  |

makes a server call with the given operation and arguments and returns the deserialized result

Parameters

  operation | the operation name for the SOAP call
  args | the operation parameter(s)
  header | optional soap headers (if required by the operation)

Returns
  the deserialized result of the SOAP call to the SOAP server

## call() [2/3]

any SalesforceSoapClient::SalesforceSoapClient::call | ( | string | operation,
|  | any | args,
|  | reference | info
| ) |  |

makes a server call with the given operation and arguments and returns the deserialized result

Parameters

  operation | the operation name for the SOAP call
  args | the arguments to the SOAP operation

  info

  an optional reference to return a hash of technical information about the SOAP call (raw message info and headers); the following keys are present in this hash:
  - `"headers"`: a hash of HTTP request headers
  - `"request-uri"`: the request URI string (ex: `"POST /services/Soap/c/29.0 HTTP/1.1"`)
  - `"response-uri"`: the response URI string (ex: `"HTTP/1.1 200 OK"`)
  - `"charset"`: the character encoding string (ex: `"UTF-8"`)
  - `"body-content-type"`: the `Content-Type` of the response without any `charset` declaration
  - `"accept-charset"`: the valus of any `Accept-Charset` header in the response
  - `"response-headers"`: a hash of HTTP response headers
  - `"response-body"`: the raw XML response body (in case content encoding is used, this is the decoded value)
  - `"request-body"`: the raw XML request body
  - `"request-soap-headers"`: an optional hash of SOAP headers used in the request (if applicable)

Returns
  the deserialized result of the SOAP call to the SOAP server

## call() [3/3]

any SalesforceSoapClient::SalesforceSoapClient::call | ( | reference | info,
|  | string | operation,
|  | any | args,
|  | *hash | header
| ) |  |

makes a server call with the given operation and arguments and returns the deserialized result with an output argument giving technical information about the call

Parameters

  info

  an optional reference to return a hash of technical information about the SOAP call (raw message info and headers); the following keys are present in this hash:
  - `"headers"`: a hash of HTTP request headers
  - `"request-uri"`: the request URI string (ex: `"POST /services/Soap/c/29.0 HTTP/1.1"`)
  - `"response-uri"`: the response URI string (ex: `"HTTP/1.1 200 OK"`)
  - `"charset"`: the character encoding string (ex: `"UTF-8"`)
  - `"body-content-type"`: the `Content-Type` of the response without any `charset` declaration
  - `"accept-charset"`: the valus of any `Accept-Charset` header in the response
  - `"response-headers"`: a hash of HTTP response headers
  - `"response-body"`: the raw XML response body (in case content encoding is used, this is the decoded value)
  - `"request-body"`: the raw XML request body
  - `"request-soap-headers"`: an optional hash of SOAP headers used in the request (if applicable)

  operation | the operation name for the SOAP call
  args | the arguments to the SOAP operation
  header | optional soap headers (if required by the operation)

Returns
  the deserialized result of the SOAP call to the SOAP server

## callIntern()

any SalesforceSoapClient::SalesforceSoapClient::callIntern | ( | string | operation,
|  | any | args,
|  | *hash | opts,
|  | *reference | info
| ) |  |

private

makes the internal call and returns the deserialized response

Parameters

  operation | the SOAP operation to use to serialize the request; if the operation is not known to the underlying WebService class, an exception will be thrown
  args | the arguments to the SOAP operation

  opts

  an optional hash of options for the call as follows:
  - `soap_header:` a hash giving SOAP header information, if required by the message
  - `http_header:` a hash giving HTTP header information to include in the message (does not override automatically-generated SOAP message headers)
  - `xml_opts:` an integer XML generation option code; see XML Generation Constants for possible values; combine multiple codes with binary or (``|)
  - `soapaction:` an optional string that will override the SOAPAction for the request; en empty string here will prevent the SOAPAction from being sent

  info

  an optional reference to return a hash of technical information about the SOAP call (raw message info and headers); the following keys are present in this hash:
  - `"headers"`: a hash of HTTP request headers
  - `"request-uri"`: the request URI string (ex: `"POST /services/Soap/c/29.0 HTTP/1.1"`)
  - `"response-uri"`: the response URI string (ex: `"HTTP/1.1 200 OK"`)
  - `"charset"`: the character encoding string (ex: `"UTF-8"`)
  - `"body-content-type"`: the `Content-Type` of the response without any `charset` declaration
  - `"accept-charset"`: the valus of any `Accept-Charset` header in the response
  - `"response-headers"`: a hash of HTTP response headers
  - `"response-body"`: the raw XML response body (in case content encoding is used, this is the decoded value)
  - `"request-body"`: the raw XML request body
  - `"request-soap-headers"`: an optional hash of SOAP headers used in the request (if applicable)

Returns
  a hash with the following keys:
  - `hdr:` a hash of message headers
  - `body:` the serialized message body

Exceptions

  WSDL-OPERATION-ERROR | the operation is not defined in the WSDL
  HTTP-CLIENT-RECEIVE-ERROR | this exception is thrown when the SOAP server returns an HTTP error code; if a SOAP fault is returned, then it is deserialized and returned in the arg key of the exception hash

Note
  this method can throw any exception that HTTPClient::send() can throw as well as any XML parsing errors thrown by parse_xml()

## callOperation()

any SalesforceSoapClient::SalesforceSoapClient::callOperation | ( | string | operation,
|  | any | args,
|  | *hash | opts,
|  | *reference | info
| ) |  |

makes a server call with the given operation, arguments, options, and optional info hash reference and returns the result

Parameters

  operation | the SOAP operation to use to serialize the request; if the operation is not known to the underlying WebService class, an exception will be thrown
  args | the arguments to the SOAP operation

  opts

  an optional hash of options for the call as follows:
  - `soap_header:` a hash giving SOAP header information, if required by the message
  - `http_header:` a hash giving HTTP header information to include in the message (does not override automatically-generated SOAP message headers)
  - `xml_opts:` an integer XML generation option code; see XML Generation Constants for possible values; combine multiple codes with binary or (``|)
  - `soapaction:` an optional string that will override the SOAPAction for the request; en empty string here will prevent the SOAPAction from being sent

  info

  an optional reference to return a hash of technical information about the SOAP call (raw message info and headers); the following keys are present in this hash:
  - `"headers"`: a hash of HTTP request headers
  - `"request-uri"`: the request URI string (ex: `"POST /services/Soap/c/29.0 HTTP/1.1"`)
  - `"response-uri"`: the response URI string (ex: `"HTTP/1.1 200 OK"`)
  - `"charset"`: the character encoding string (ex: `"UTF-8"`)
  - `"body-content-type"`: the `Content-Type` of the response without any `charset` declaration
  - `"accept-charset"`: the valus of any `Accept-Charset` header in the response
  - `"response-headers"`: a hash of HTTP response headers
  - `"response-body"`: the raw XML response body (in case content encoding is used, this is the decoded value)
  - `"request-body"`: the raw XML request body
  - `"request-soap-headers"`: an optional hash of SOAP headers used in the request (if applicable)

Returns
  a hash with the following keys:
  - `hdr:` a hash of message headers
  - `body:` the serialized message body

Exceptions

  WSDL-OPERATION-ERROR | the operation is not defined in the WSDL
  HTTP-CLIENT-RECEIVE-ERROR | this exception is thrown when the SOAP server returns an HTTP error code; if a SOAP fault is returned, then it is deserialized and returned in the arg key of the exception hash

Note
  this method can throw any exception that HTTPClient::send() can throw as well as any XML parsing errors thrown by parse_xml()

## constructor()

SalesforceSoapClient::SalesforceSoapClient::constructor | ( | hash | opts | ) |

creates the object with the given options

Parameters

  opts

  options for the SOAP connection; see SoapClient::constructor() for option info for the embedded SoapClient, plus the following options:
  - `username:` (required) Salesforce.com username
  - `password:` (required) Salesforce.com password
  - `token:` (required) Salesforce.com user API token
  - `force_logout` (optional) forces a logout when the SalesforceSoapClient object is destroyed; this should normally be False to allow for the session to remain valid

## destructor()

SalesforceSoapClient::SalesforceSoapClient::destructor | ( |  | ) |

destroys the object

Note
  if the `force_logout` option was given in the constructor(), then a logout from the Salesforce.com session is also performed

## methodGate()

any SalesforceSoapClient::SalesforceSoapClient::methodGate | ( | string | op,
|  | any | arg
| ) |  |

uses call() to transparently serialize the argument and make a call to the given operation and return the deserialized results

Parameters

  op | the operation name, which is the method name passed to methodGate()
  arg | a list or arguments or a single argument (or NOTHING) for the operation

Returns
  the deserialized result of the SOAP call to the SOAP server

## Member Data Documentation

## force_logout

bool SalesforceSoapClient::SalesforceSoapClient::force_logout = False

private

logouts should be performed manually to ensure that the user's session remains valid