| Qore SalesforceRestClient Module Reference 2.0.1

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
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
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
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
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
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
| checkClientOptions (hash< auto > opts)
| verifies that the options passed match the configured options
| constructor (*hash< auto > opts, *softbool do_not_connect)
| creates the object with the given options
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
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
*string | getApi ()
| returns the Salesforce.com REST API version currently in use
*hash< string, hash< auto > > | getApis ()
| Return available APIs as a hash.
hash< auto > | getOAuth2Options ()
| Return OAuth2 options.
bool | isAuthTokenError (int status_code, hash< auto > headers, bool body_deserialized, *string body_content_type, auto body)
| Returns True if the response was related to an authorization token error.
| login (*reference< hash< auto > > info)
| logs in to Salesforce.com with the credentials provided in the constructor()
| logout (*reference< hash< auto > > info)
| logs out of Salesforce.com by revoking the access token
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
| processApis (*list< auto > apis)
| Process the API response from Salesforce and set / verify the client's API level.
| setVerifyApi ()
| Sets / verifies the api level and sets the application URL accordingly.

## Static Public Member Functions
static string | getBulkDate (date d)
| returns a date string for use with Salesforce.com Bulk REST API requests
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
| checkLogin (*reference< hash< auto > > info)
| Checks if a login is necessary; if so, then the login is performed.
*hash< auto > | getOAuth2AuthHeaders ()
| Returns headers to use with OAuth2 authorization / token requests.
*hash< auto > | getUpdateOptionsAfterLogin (hash< auto > h)
| Returns options to update after an OAuth2 login.
hash< auto > | loginIntern (*reference< hash > info)
| performs authentication and authorization with Salesforce.com using the OAuth2 authorization URL
Mutex | m ()
| Mutex for token acquisition.
| setApi ()
| Checks the API and sets the final URL.
| setHeaders ()
| Set headers for Salesforce REST communications.
| setOAuth2LoginInfo (hash< auto > h)
| Sets options from the OAuth2 login response on the local object.

## 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< string, 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 | id_service_url
| The identity service URL.
string | instance_url
| The instance URL.
string | oauth2_logout_url
| Salesforce.com OAuth2 Revoke Token URL.

## 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:

- `oauth2_client_id:` the Salesforce.com "consumer key"
- `oauth2_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
- `oauth2_auth_url:` default value `"https://login.salesforce.com/services/oauth2/authorize"`
- `oauth2_token_url:` default value `"https://login.salesforce.com/services/oauth2/token"` (used for logging in to Salesforce.com)
- `oauth2_logout_url:` 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<auto> 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<auto> jh = sfrest.bulkJobCreate(BulkJobInsert, "Account", BulkJobCsv).jobInfo;
  printf("job ID created: %y\n", jh.id);
  hash<auto> h = sfrest.bulkJobAddBatch(jh.id, csv_string, BulkJobCsv).body;
  printf("batch ID: %y batch state: %y\n", h.id, h.state);

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<auto> 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<auto> 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

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 `oauth2_client_id:` (required) the Salesforce.com "consumer key" for the Connected App `oauth2_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:` 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:` 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

The following are mandatory options for Salesforce.com authentication: `oauth2_client_id`, `oauth2_client_secret`, other options may be required depending on the OAuth2 grant type used

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<auto> 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<auto> 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

## ◆ getOAuth2AuthHeaders()

*hash< auto > SalesforceRestClient::SalesforceRestClient::getOAuth2AuthHeaders | ( |  | ) |
| protected

Returns headers to use with OAuth2 authorization / token requests.

Since
  RestClient 2.0

## ◆ getOAuth2Options()

hash< auto > SalesforceRestClient::SalesforceRestClient::getOAuth2Options | ( |  | ) |

Return OAuth2 options.

Returns
  a hash of OAuth2 options

## ◆ getUpdateOptionsAfterLogin()

*hash< auto > SalesforceRestClient::SalesforceRestClient::getUpdateOptionsAfterLogin | ( | hash< auto > | h | ) |
| protected

Returns options to update after an OAuth2 login.

Since
  SalesforceRestClient 2.0

## ◆ isAuthTokenError()

bool SalesforceRestClient::SalesforceRestClient::isAuthTokenError | ( | int | status_code,
|  | hash< auto > | headers,
|  | bool | body_deserialized,
|  | *string | body_content_type,
|  | auto | body )

Returns True if the response was related to an authorization token error.

Returns
  True if the response was related to an authorization token error

## ◆ 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

## ◆ 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<auto> 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()

## ◆ setApi()

SalesforceRestClient::SalesforceRestClient::setApi | ( |  | ) |
| protected

Checks the API and sets the final URL.

Since
  SalesforceRestClient 2.0

## ◆ setOAuth2LoginInfo()

SalesforceRestClient::SalesforceRestClient::setOAuth2LoginInfo | ( | hash< auto > | h | ) |
| protected

Sets options from the OAuth2 login response on the local object.

Since
  SalesforceRestClient 2.0