SalesforceRestClient::SalesforceRestClient Class Reference

this class provides the REST client API for communication with Salesforce.com More...

Inheritance diagram for SalesforceRestClient::SalesforceRestClient:
[legend]

## Public Member Functions

hash< auto > | bulkGet (string path, auto body, *reference< hash< auto >> info, *hash< auto > hdr)
| sends an HTTP `GET` request to the REST server using the Salesforce.com Bulk REST API and returns the response More...
hash< auto > | bulkJobAddBatch (string jobid, data batch_data, string job_content_type, *reference< hash< auto >> info, *hash< auto > hdr)
| add a batch to a job using the Bulk REST API More...
hash< auto > | bulkJobClose (string jobid, *reference< hash< auto >> info, *hash< auto > hdr)
| sends a Bulk REST API job close `POST` request to the server and returns the deserialized result message body More...
hash< auto > | bulkJobCreate (string operation, string object, string job_content_type, *reference< hash< auto >> info, *hash< auto > hdr)
| creates a Salesforce.com batch job and returns the job information as a hash More...
hash< auto > | bulkPost (string path, auto body, *reference< hash< auto >> info, *hash< auto > hdr)
| sends an HTTP `POST` request to the REST server using the Salesforce.com Bulk REST API and returns the response More...
| checkClientOptions (hash< auto > opts)
| verifies that the options passed match the configured options More...
| constructor (*hash< auto > opts, *softbool do_not_connect)
| creates the object with the given options (which include the following mandatory options for Salesforce.com authentication: `client_id`, `client_secret`, `username`, `password`) More...
hash< auto > | doBulkRequest (string m, string path, auto body, *reference< hash< auto >> info, softbool decode_errors=True, *hash< auto > hdr)
| sends a Bulk API REST request to the Salesforce.com server using `"rawxml"` serialization and returns the response; performs an implicit login to Salesforce.com if necessary More...
hash< auto > | doRequest (string m, string path, auto body, *reference< hash< auto >> info, softbool decode_errors=True, *hash< auto > hdr)
| sends an HTTP request to the REST server and returns the response; performs an implicit login to Salesforce.com if necessary More...
string | getApi ()
| returns the Salesforce.com REST API version currently in use
*string | getToken ()
| returns the access token
| login (*reference< hash< auto >> info)
| logs in to Salesforce.com with the credentials provided in the constructor() More...
| logout (*reference< hash< auto >> info)
| logs out of Salesforce.com by revoking the access token More...
hash< auto > | patch (string path, auto body, *reference< hash< auto >> info, *hash< auto > hdr)
| sends an HTTP `PATCH` request to the Salesforce.com REST server and returns the response; performs an implicit login to Salesforce.com if necessary More...

## Static Public Member Functions

static string | getBulkDate (date d)
| returns a date string for use with Salesforce.com Bulk REST API requests More...
static string | getGmtDate (date d)
| returns a date string in GMT for use in Salesforce.com requests

## Public Attributes

const | AsyncDataloadNs = "http://www.force.com/2009/06/asyncapi/dataload"
| Salesforce.com async dataload namespace.
const | Defaults = ...
| defaults for direct member values
const | DefaultSendEncoding = "gzip"
| default send encoding
const | JobInfoAttributes = ...
| Salesforce.com XML jobInfo attributes.
const | RequiredOptions = ...
| required options

## Protected Member Functions

| loginIntern (*reference< hash > info)
| performs authentication and authorization with Salesforce.com using the OAuth2 authorization URL More...
Mutex | m ()
| Mutex for token acquisition.

## Static Protected Member Functions

static hash | getOptions (*hash< auto > opts)
| returns options for the RestClient::constructor()

## Protected Attributes

string | api
| Salesforce.com REST API version to be used (`"auto"` = latest version)
hash< auto > | api_hash
| hash of APIs retrieved from GET /services/data; keyed by API version string; values: `"label"`, `"url"`
string | api_used
| Salesforce.com REST API version currently in use.
string | client_id
| Salesforce.com "consumer key".
string | client_secret
| Salesforce.com "consumer secret".
string | oauth_url_auth
| Salesforce.com OAuth2 Authorization URL.
string | oauth_url_revoke
| Salesforce.com OAuth2 Revoke Token URL.
string | oauth_url_token
| Salesforce.com OAuth2 Get Token URL.
string | password
| Salesforce.com password.
string | token
| Salesforce.com token.
string | username
| Salesforce.com username.

## Detailed Description

this class provides the REST client API for communication with Salesforce.com

This class requires the following options for Salesforce.com authentication and authorization to the target Connected App:

- `client_id:` the Salesforce.com "consumer key"
- `client_secret:` the Salesforce.com "consumer secret"
- `username:` the Salesforce.com account username
- `password:` the Salesforce.com account password

The following options can be overridden; default values are provided as follows:

- `api:` default value `"auto"` for the Salesforce.com REST API version; `"auto"` means use the latest version available
- `oauth_url_auth:` default value `"https://login.salesforce.com/services/oauth2/authorize"`
- `oauth_url_token:` default value `"https://login.salesforce.com/services/oauth2/token"` (used for logging in to Salesforce.com)
- `oauth_url_revoke:` default value `"https://login.salesforce.com/services/oauth2/revoke"`

This class also automatically adds support for the `"PATCH"` HTTP method used by Salesforce.com for updates to existing objects, as well as the SalesforceRestClient::patch() method

The SalesforceRestClient::patchdoRequest() method is overridden in this class to provide transparent authentication and authorization to Salesforce.com. With every REST request, if no token has been acquired, first a login token will be acquired, the internal URL set to the target URL provided by the token call, and then the requested REST call will be made.

When logging in to Salesforce.com (see SalesforceRestClient::login()), the `Authorization` header is set by default to be included with any future calls made through this object (or with RestClient methods in the parent class).

When sending headers to Salesforce.com, any headers with date values are converted to GMT format; for example, the `"If-Modified-Since"` and `"If-Unmodified-Since"` headers can be set to date/time values, and this object will convert them to date strings in GMT format; ex:

SalesforceRestClient rest(opts);
hash ans = rest.get("sobjects", NOTHING, NOTHING, ("If-Modified-Since": 2016-11-25));

In a request sent from the call above in the `Europe/Prague` time zone, the `"If-Modified-Since"` header would be sent as:

    If-Modified-Since: Thu, 24 Nov 2016 23:00:00 GMT

The following methods support communication with the Salesforce.com Bulk REST API:

- doBulkRequest()
- bulkGet()
- bulkPost()
- bulkJobCreate()
- bulkJobAddBatch()
- bulkJobClose()

## Member Function Documentation

## bulkGet()

hash<auto> SalesforceRestClient::SalesforceRestClient::bulkGet | ( | string | path,
|  | auto | body,
|  | *reference< hash< auto >> | info,
|  | *hash< auto > | hdr
| ) |  |

sends an HTTP `GET` request to the REST server using the Salesforce.com Bulk REST API and returns the response

Example:
  hash ans = rest.bulkGet("/orders/1?info=verbose");

Parameters

  path | the URI path to add (will be appended to any root path given in the constructor)
  body | an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor()

  info

  an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
  - `headers:` a hash of outgoing HTTP request headers
  - `request-uri`: the request URI string sent (ex: `"GET /services/async/38.0/job HTTP/1.1"`)
  - `body-content-type`: the outgoing message body Mime `Content-Type` value
  - `response-headers`: a hash of processed incoming HTTP headers in the response with keys converted to lower case and additional information added
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `chunked:` set to True if the response was received with chunked transfer encoding
  - `response-code`: the HTTP response code
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-serialization`: the type of message serialization in the response; see DataSerializationOptions for possible values
  - `request-body`: the raw message body in the request (before any content encoding)
  - `request-serialization`: the type of message serialization in the request; see DataSerializationOptions for possible values

  hdr | any headers to be sent with the request; headers here will override default headers for the object as well

Returns
  A hash of headers received from the HTTP server with all key names converted to lower-case; if any message body is included in the response, it will be deserialized to Qore data and assigned to the value of the `"body"` key

Exceptions

  DESERIALIZATION-ERROR | the response body could not be deserialized (unknown `Content-Type` or invalid serialization)

  REST-RESPONSE-ERROR

  if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
  - `"response-code"`: the HTTP response code given
  - `"response-headers"`: a hash of processed response headers
  - `"response-headers-raw"`: a hash of raw unprocessed response headers
  - `"response-body"`: the decoded response body

Note that this exception is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True

Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.

Note
  authentication and authorization is done transparently as with the standard OAuth2 mechanism used with the non-bulk REST API

See also
  - RestClient::getSerialization()
  - RestClient::setSerialization()

## bulkJobAddBatch()

hash<auto> SalesforceRestClient::SalesforceRestClient::bulkJobAddBatch | ( | string | jobid,
|  | data | batch_data,
|  | string | job_content_type,
|  | *reference< hash< auto >> | info,
|  | *hash< auto > | hdr
| ) |  |

add a batch to a job using the Bulk REST API

Example:
  hash jh = sfrest.bulkJobCreate(BulkJobInsert, "Account", BulkJobCsv).jobInfo;
  printf("job ID created: %y\n", jh.id);
  hash h = sfrest.bulkJobAddBatch(jh.id, csv_string, BulkJobCsv).body;
  printf("batch ID: %y batch state: %y\n", h.id, h.state);
  printf
  string printf(string fmt,...)

Parameters

  jobid | the job ID to add the batch to
  batch_data | the data for the job; this data is not serialized but rather sent as-is using the MIME `Content-Type` associated with the job content type value
  job_content_type | the content type of the job; see Salesforce.com Bulk REST API Job Content Types for valid values

  info

  an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
  - `headers:` a hash of outgoing HTTP request headers
  - `request-uri`: the request URI string sent (ex: `"POST /services/async/38.0/job HTTP/1.1"`)
  - `body-content-type`: the outgoing message body Mime `Content-Type` value
  - `response-headers`: a hash of processed incoming HTTP headers in the response with keys converted to lower case and additional information added
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `chunked:` set to True if the response was received with chunked transfer encoding
  - `response-code`: the HTTP response code
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-serialization`: the type of message serialization in the response; see DataSerializationOptions for possible values
  - `request-body`: the raw message body in the request (before any content encoding)

  hdr | any headers to be sent with the request; headers here will override default headers for the object as well

Returns
  the deserialized message body returned by Salesforce.com

Exceptions

  INVALID-CONTENT-TYPE | invalid job content type passed; see BulkJobContentTypes for valid values

Note
  authentication and authorization is done transparently as with the standard OAuth2 mechanism used with the non-bulk REST API

## bulkJobClose()

hash<auto> SalesforceRestClient::SalesforceRestClient::bulkJobClose | ( | string | jobid,
|  | *reference< hash< auto >> | info,
|  | *hash< auto > | hdr
| ) |  |

sends a Bulk REST API job close `POST` request to the server and returns the deserialized result message body

Example:
  sfrest.bulkJobClose(jh.id);

Parameters

  jobid | the job ID to close

  info

  an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
  - `headers:` a hash of outgoing HTTP request headers
  - `request-uri`: the request URI string sent (ex: `"POST /services/async/38.0/job HTTP/1.1"`)
  - `body-content-type`: the outgoing message body Mime `Content-Type` value
  - `response-headers`: a hash of processed incoming HTTP headers in the response with keys converted to lower case and additional information added
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `chunked:` set to True if the response was received with chunked transfer encoding
  - `response-code`: the HTTP response code
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-serialization`: the type of message serialization in the response; see DataSerializationOptions for possible values
  - `request-body`: the raw message body in the request (before any content encoding)
  - `request-serialization`: the type of message serialization in the request; see DataSerializationOptions for possible values

  hdr | any headers to be sent with the request; headers here will override default headers for the object as well

Returns
  the deserialized message body returned by Salesforce.com

Note
  authentication and authorization is done transparently as with the standard OAuth2 mechanism used with the non-bulk REST API

## bulkJobCreate()

hash<auto> SalesforceRestClient::SalesforceRestClient::bulkJobCreate | ( | string | operation,
|  | string | object,
|  | string | job_content_type,
|  | *reference< hash< auto >> | info,
|  | *hash< auto > | hdr
| ) |  |

creates a Salesforce.com batch job and returns the job information as a hash

Example
  hash h = sfrest.bulkJobCreate(BulkJobInsert, "Account", BulkJobJson);
  printf("job ID created: %y\n", h.jobInfo.id);

Parameters

  operation | the operation to create; see Salesforce.com Bulk REST API Job Operations for valid values
  object | the API object to operate on
  job_content_type | the content type of the job; see Salesforce.com Bulk REST API Job Content Types for valid values

  info

  an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
  - `headers:` a hash of outgoing HTTP request headers
  - `request-uri`: the request URI string sent (ex: `"POST /services/async/38.0/job HTTP/1.1"`)
  - `body-content-type`: the outgoing message body Mime `Content-Type` value
  - `response-headers`: a hash of processed incoming HTTP headers in the response with keys converted to lower case and additional information added
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `chunked:` set to True if the response was received with chunked transfer encoding
  - `response-code`: the HTTP response code
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-serialization`: the type of message serialization in the response; see DataSerializationOptions for possible values
  - `request-body`: the raw message body in the request (before any content encoding)
  - `request-serialization`: the type of message serialization in the request; see DataSerializationOptions for possible values

  hdr | any headers to be sent with the request; headers here will override default headers for the object as well

Returns
  the deserialized message body returned by Salesforce.com

Exceptions

  INVALID-OPERATION | invalid operation passed; see BulkJobContentTypes for valid values
  INVALID-CONTENT-TYPE | invalid job content type passed; see BulkJobContentTypes for valid values

Note
  authentication and authorization is done transparently as with the standard OAuth2 mechanism used with the non-bulk REST API

## bulkPost()

hash<auto> SalesforceRestClient::SalesforceRestClient::bulkPost | ( | string | path,
|  | auto | body,
|  | *reference< hash< auto >> | info,
|  | *hash< auto > | hdr
| ) |  |

sends an HTTP `POST` request to the REST server using the Salesforce.com Bulk REST API and returns the response

Example:
  hash ans = rest.bulkPost("/orders", ("product": "xyz123", "options": 500));

Parameters

  path | the URI path to add (will be appended to any root path given in the constructor)
  body | an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor()

  info

  an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
  - `headers:` a hash of outgoing HTTP request headers
  - `request-uri`: the request URI string sent (ex: `"POST /services/async/38.0/job HTTP/1.1"`)
  - `body-content-type`: the outgoing message body Mime `Content-Type` value
  - `response-headers`: a hash of processed incoming HTTP headers in the response with keys converted to lower case and additional information added
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `chunked:` set to True if the response was received with chunked transfer encoding
  - `response-code`: the HTTP response code
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-serialization`: the type of message serialization in the response; see DataSerializationOptions for possible values
  - `request-body`: the raw message body in the request (before any content encoding)
  - `request-serialization`: the type of message serialization in the request; see DataSerializationOptions for possible values

  hdr | any headers to be sent with the request; headers here will override default headers for the object as well

Returns
  A hash of headers received from the HTTP server with all key names converted to lower-case; if any message body is included in the response, it will be deserialized to Qore data and assigned to the value of the `"body"` key

Exceptions

  DESERIALIZATION-ERROR | the response body could not be deserialized (unknown `Content-Type` or invalid serialization)

  REST-RESPONSE-ERROR

  if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
  - `"response-code"`: the HTTP response code given
  - `"response-headers"`: a hash of processed response headers
  - `"response-headers-raw"`: a hash of raw unprocessed response headers
  - `"response-body"`: the decoded response body

Note that this exception is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True

Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.

Note
  authentication and authorization is done transparently as with the standard OAuth2 mechanism used with the non-bulk REST API

See also
  - RestClient::getSerialization()
  - RestClient::setSerialization()

## checkClientOptions()

SalesforceRestClient::SalesforceRestClient::checkClientOptions | ( | hash< auto > | opts | ) |

verifies that the options passed match the configured options

Exceptions

  SALESFORCE-REST-OPTION-ERROR | one or more options does not match

## constructor()

SalesforceRestClient::SalesforceRestClient::constructor | ( | *hash< auto > | opts,
|  | *softbool | do_not_connect
| ) |  |

creates the object with the given options (which include the following mandatory options for Salesforce.com authentication: `client_id`, `client_secret`, `username`, `password`)

Example:
  SalesforceRestClient rest({"url": "http://localhost:8001/rest"});

Parameters

  opts

  valid options are:
  - `additional_methods:` Optional hash with more but not-HTTP-standardized methods to handle. It allows to create various HTTP extensions like e.g. WebDAV. The hash takes the method name as a key, and the value is a boolean True or False: indicating if the method can accept a message body as well. Example:
    # add new HTTP methods for WebDAV. Both of them require body posting to the server
    ("additional_methods": ("PROPFIND": True, "MKCOL": True ));
  - `api:` the Salesforce.com API to use; use `"auto"` (the default) to use the latest API version
  - `client_id:` (required) the Salesforce.com "consumer key" for the Connected App
  - `client_secret:` (required) the Salesforce.com "consumer secret" for the Connected App
  - `connect_timeout:` The timeout value in milliseconds for establishing a new socket connection (also can be a relative date-time value for clarity, ex: `20s`)
  - `content_encoding:` for possible values, see EncodingSupport; this sets the send encoding (if the `"send_encoding"` option is not set) and the requested response encoding (note that the RestClient class will only compress outgoing message bodies over CompressionThreshold bytes in size); additionally please note that Salesforce.com does not support `"bzip2"` compression
  - `data:` a data serialization option; if not present defaults to `"json"`
  - `default_path:` The default path to use for new connections if a path is not otherwise specified in the connection URL
  - `default_port:` The default port number to connect to if none is given in the URL
  - `error_passthru:` if True then HTTP status codes indicating errors will not cause a `REST-RESPONSE-ERROR` exception to be raised, rather such responses will be passed through to the caller like any other response
  - `headers:` an optional hash of headers to send with every request, these can also be overridden in request method calls
  - `http_version:` Either '1.0' or '1.1' for the claimed HTTP protocol version compliancy in outgoing message headers
  - `max_redirects:` The maximum number of redirects before throwing an exception (the default is 5)
  - `password:` (required) the Salesforce.com account password for the Connected App
  - `proxy:` The proxy URL for connecting through a proxy
  - `redirect_passthru:` if True then redirect responses will be passed to the caller instead of processed
  - `send_encoding:` a send data encoding option or the value `"auto"` which means to use automatic encoding; if not present defaults to `"gzip"` content encoding on sent message bodies (note that the RestClient class will only compress outgoing message bodies over CompressionThreshold bytes in size); additionally please note that Salesforce.com does not support `"bzip2"` compression
  - `timeout:` The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: `30s`)
  - `username:` (required) the Salesforce.com account username for the Connected App

  do_not_connect | if `False` (the default), then a connection will be immediately established to the remote server and a token will be received

Exceptions

  RESTCLIENT-ERROR | invalid option passed to constructor, unsupported data serialization, etc
  SALESFORCERESTCLIENT-ERROR | missing or invalid connection option

## doBulkRequest()

hash<auto> SalesforceRestClient::SalesforceRestClient::doBulkRequest | ( | string | m,
|  | string | path,
|  | auto | body,
|  | *reference< hash< auto >> | info,
|  | softbool | decode_errors = `True`,
|  | *hash< auto > | hdr
| ) |  |

sends a Bulk API REST request to the Salesforce.com server using `"rawxml"` serialization and returns the response; performs an implicit login to Salesforce.com if necessary

Example:
  hash ans = rest.doBulkRequest("POST", "job", job);

Parameters

  m | the HTTP method to be used; case is ignored (if not a valid method an `HTTP-CLIENT-METHOD-ERROR` exception is raised)
  path | the URI path to add (will be appended to any root path given in the constructor)
  body | an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor()

  info

  an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
  - `headers:` a hash of outgoing HTTP request headers
  - `request-uri`: the request URI string sent (ex: `"POST /services/async/38.0/job HTTP/1.1"`)
  - `body-content-type`: the outgoing message body Mime `Content-Type` value
  - `response-headers`: a hash of processed incoming HTTP headers in the response with keys converted to lower case and additional information added
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `chunked:` set to True if the response was received with chunked transfer encoding
  - `response-code`: the HTTP response code
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-serialization`: the type of message serialization in the response; see DataSerializationOptions for possible values
  - `request-body`: the raw message body in the request (before any content encoding)
  - `request-serialization`: the type of message serialization in the request; see DataSerializationOptions for possible values

  decode_errors | decode the message body with HTTP error responses and throw an exception based on the message body
  hdr | any headers to be sent with the request; headers here will override default headers for the object as well

Returns
  A hash of headers received from the HTTP server with all key names converted to lower-case; if any message body is included in the response, it will be deserialized to Qore data and assigned to the value of the `"body"` key

Exceptions

  DESERIALIZATION-ERROR | the response body could not be deserialized (unknown `Content-Type` or invalid serialization)
  HTTP-CLIENT-METHOD-ERROR | invalid HTTP method argument passed

  REST-RESPONSE-ERROR

  if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
  - `"response-code"`: the HTTP response code given
  - `"response-headers"`: a hash of processed response headers
  - `"response-headers-raw"`: a hash of raw unprocessed response headers
  - `"response-body"`: the decoded response body

Note that this exception is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True

Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.

Note
  authentication and authorization is done transparently as with the standard OAuth2 mechanism used with the non-bulk REST API

See also
  - RestClient::getSerialization()
  - RestClient::setSerialization()

## doRequest()

hash<auto> SalesforceRestClient::SalesforceRestClient::doRequest | ( | string | m,
|  | string | path,
|  | auto | body,
|  | *reference< hash< auto >> | info,
|  | softbool | decode_errors = `True`,
|  | *hash< auto > | hdr
| ) |  |

sends an HTTP request to the REST server and returns the response; performs an implicit login to Salesforce.com if necessary

Example:
  hash ans = rest.doRequest("GET", "sobjects");

Parameters

  m | the HTTP method to be used; case is ignored (if not a valid method an `HTTP-CLIENT-METHOD-ERROR` exception is raised)
  path | the URI path to add (will be appended to any root path given in the constructor)
  body | an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor()

  info

  an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
  - `headers:` a hash of outgoing HTTP request headers
  - `request-uri`: the request URI string sent (ex: `"POST /services/async/38.0/job HTTP/1.1"`)
  - `body-content-type`: the outgoing message body Mime `Content-Type` value
  - `response-headers`: a hash of processed incoming HTTP headers in the response with keys converted to lower case and additional information added
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `chunked:` set to True if the response was received with chunked transfer encoding
  - `response-code`: the HTTP response code
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-serialization`: the type of message serialization in the response; see DataSerializationOptions for possible values
  - `request-body`: the raw message body in the request (before any content encoding)
  - `request-serialization`: the type of message serialization in the request; see DataSerializationOptions for possible values

  decode_errors | decode the message body with HTTP error responses and throw an exception based on the message body
  hdr | any headers to be sent with the request; headers here will override default headers for the object as well

Returns
  A hash of headers received from the HTTP server with all key names converted to lower-case; if any message body is included in the response, it will be deserialized to Qore data and assigned to the value of the `"body"` key

Exceptions

  DESERIALIZATION-ERROR | the response body could not be deserialized (unknown `Content-Type` or invalid serialization)
  HTTP-CLIENT-METHOD-ERROR | invalid HTTP method argument passed

  REST-RESPONSE-ERROR

  if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
  - `"response-code"`: the HTTP response code given
  - `"response-headers"`: a hash of processed response headers
  - `"response-headers-raw"`: a hash of raw unprocessed response headers
  - `"response-body"`: the decoded response body

Note that this exception is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True

Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.

See also
  - RestClient::getSerialization()
  - RestClient::setSerialization()

## getBulkDate()

static string SalesforceRestClient::SalesforceRestClient::getBulkDate | ( | date | d | ) |

static

returns a date string for use with Salesforce.com Bulk REST API requests

Parameters

  d | the date to return as a formatted string using `"YYYY-MM-DDTHH:mm:SSZ"`

Returns
  the string corresponding to the date

See also
  Date Formatting Strings

## login()

SalesforceRestClient::SalesforceRestClient::login | ( | *reference< hash< auto >> | info | ) |

logs in to Salesforce.com with the credentials provided in the constructor()

Parameters

  info

  an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
  - `headers:` a hash of outgoing HTTP request headers
  - `request-uri`: the request URI string sent (ex: `"POST /services/async/38.0/job HTTP/1.1"`)
  - `body-content-type`: the outgoing message body Mime `Content-Type` value
  - `response-headers`: a hash of processed incoming HTTP headers in the response with keys converted to lower case and additional information added
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `chunked:` set to True if the response was received with chunked transfer encoding
  - `response-code`: the HTTP response code
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-serialization`: the type of message serialization in the response; see DataSerializationOptions for possible values
  - `request-body`: the raw message body in the request (before any content encoding)
  - `request-serialization`: the type of message serialization in the request; see DataSerializationOptions for possible values

Note
  this call is made implicitly before each REST call and should not need to be called manually

## loginIntern()

SalesforceRestClient::SalesforceRestClient::loginIntern | ( | *reference< hash > | info | ) |

protected

performs authentication and authorization with Salesforce.com using the OAuth2 authorization URL

called with the Mutex held

## logout()

SalesforceRestClient::SalesforceRestClient::logout | ( | *reference< hash< auto >> | info | ) |

logs out of Salesforce.com by revoking the access token

Example:
  sfrest.logout();

if not logged in then this method returns immediately

Parameters

  info

  an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
  - `headers:` a hash of outgoing HTTP request headers
  - `request-uri`: the request URI string sent (ex: `"POST /services/async/38.0/job HTTP/1.1"`)
  - `body-content-type`: the outgoing message body Mime `Content-Type` value
  - `response-headers`: a hash of processed incoming HTTP headers in the response with keys converted to lower case and additional information added
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `chunked:` set to True if the response was received with chunked transfer encoding
  - `response-code`: the HTTP response code
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-serialization`: the type of message serialization in the response; see DataSerializationOptions for possible values
  - `request-body`: the raw message body in the request (before any content encoding)
  - `request-serialization`: the type of message serialization in the request; see DataSerializationOptions for possible values (for this method, always `"url"`)

## patch()

hash<auto> SalesforceRestClient::SalesforceRestClient::patch | ( | string | path,
|  | auto | body,
|  | *reference< hash< auto >> | info,
|  | *hash< auto > | hdr
| ) |  |

sends an HTTP `PATCH` request to the Salesforce.com REST server and returns the response; performs an implicit login to Salesforce.com if necessary

Example:
  hash ans = rest.patch("/orders/1", ("action": "cancel"));

Parameters

  path | the URI path to add (will be appended to any root path given in the constructor)
  body | an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized according to the serialization rules set in RestClient::constructor()

  info

  an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys:
  - `headers:` a hash of outgoing HTTP request headers
  - `request-uri`: the request URI string sent (ex: `"PATCH /services/async/38.0/job HTTP/1.1"`)
  - `body-content-type`: the outgoing message body Mime `Content-Type` value
  - `response-headers`: a hash of processed incoming HTTP headers in the response with keys converted to lower case and additional information added
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `chunked:` set to True if the response was received with chunked transfer encoding
  - `response-code`: the HTTP response code
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-serialization`: the type of message serialization in the response; see DataSerializationOptions for possible values
  - `request-body`: the raw message body in the request (before any content encoding)
  - `request-serialization`: the type of message serialization in the request; see DataSerializationOptions for possible values

  hdr | any headers to be sent with the request; headers here will override default headers for the object as well

Returns
  A hash of headers received from the HTTP server with all key names converted to lower-case; if any message body is included in the response, it will be deserialized to Qore data and assigned to the value of the `"body"` key

Exceptions

  DESERIALIZATION-ERROR | the response body could not be deserialized (unknown `Content-Type` or invalid serialization)

  REST-RESPONSE-ERROR

  if this exception is thrown by the Qore::HTTPClient::send() call in case of an HTTP response code < 100 or >= 300, the message body is still deserialized if possible and the response information can be retrieved in the info hash output keys as follows:
  - `"response-code"`: the HTTP response code given
  - `"response-headers"`: a hash of processed response headers
  - `"response-headers-raw"`: a hash of raw unprocessed response headers
  - `"response-body"`: the decoded response body

Note that this exception is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True

Other exceptions can be thrown by the Qore::HTTPClient::send() call used to make the HTTP request.

See also
  - RestClient::getSerialization()
  - RestClient::setSerialization()