Synchronous or Asynchronous Response Types
- Synchronous responses
- Asynchronous responses
The gateway supports both synchronous and asynchronous responses to incoming requests.
A synchronous response returns to the client in the same HTTP connection as the request. With asynchronous responses, a client can send multiple requests and receive the responses in subsequent connections.
By default, responses from the gateway are synchronous. If you want asynchronous responses, some additional steps are required.
Note: The use of synchronous responses is similar to using the Process offline option for CSV imports and Process and store for reports in the Sage Intacct UI.
Synchronous responses are typically used when the client must wait to receive the response before processing continues on the client side. A request is processed in real time, and the gateway returns the response via the HTTP connection created by the client. If a validation error occurs, the error is returned synchronously.
Note: Sending a large request can cause the sender process to time out (after 15 minutes) even though the request is still being processed by the Sage Intacct system. You can avoid timeouts using by limiting your calls to a given set of recommendations.
You can work with Sage Intacct to configure asynchronous processing if you do not want your client to wait for responses in the same HTTP connection. Asynchronous responses can be very useful when posting large requests that require significant processing time or when a response is not needed in the same HTTP connection.
Setting up asynchronous processing
You must open a support case for help establishing an asynchronous transport policy. Be prepared to provide the following information:
|Policy ID||Required||string(40)||Unique policy ID you want to use|
|Response URL||Required||string(256)||Callback URL for posting XML responses. HTTPS is the only supported protocol.|
|HTTP User ID||Optional||string(40)||User ID for basic server authentication|
|HTTP Password||Optional||string(40)||Password for basic server authentication|
|Serialize||Optional||boolean||Serialize async requests one at a time. Default:
An example transport policy setup is as follows:
- Policy ID:
- Response URL:
- HTTP User ID:
- HTTP Password:
Using asynchronous processing
Once you have a transport policy in place, you provide the transport policy ID in the
<control> block of your requests, as shown:
<request> <control> <senderid>test_sender</senderid> <password>test_password</password> <controlid>446ca3a4-28b3-4379-8760-a12812c8b02c</controlid> <uniqueid>false</uniqueid> <dtdversion>3.0</dtdversion> <policyid>hello-world</policyid> <!-- this your unique transport policy ID --> <includewhitespace>false</includewhitespace> </control> <operation> <!-- ... --> </operation> </request>
The above request will result in the following acknowledgement response, and the connection is closed:
<response> <acknowledgement> <status>success</status> </acknowledgement> <control> <status>success</status> <senderid>test_sender</senderid> <controlid>446ca3a4-28b3-4379-8760-a12812c8b02c</controlid> <uniqueid>false</uniqueid> <dtdversion>3.0</dtdversion> </control> </response>
When the request is processed out of the queue, a response is posted back in a new connection using the callback URL and any other parameters set up in the transport policy:
POST /test/intacct-async.php HTTP/1.1 Host: www.example.com Content-Type: application/xml Authorization: Basic abc123 <?xml version="1.0" encoding="UTF-8"?> <response> <control> <status>success</status> <senderid>test_sender</senderid> <controlid>446ca3a4-28b3-4379-8760-a12812c8b02c</controlid> <uniqueid>false</uniqueid> <dtdversion>3.0</dtdversion> </control> <operation> <!-- ... --> </operation> </response>
Asynchronous processing for original custom reports
When running original custom reports (using
readReport), some additional features for handling asynchronous results are available.
Best practices and tips
Asynchronous requests require more infrastructure on your end, compared to simply sending a request and waiting for a response. Consider the following best practices and tips when preparing to use asynchronous processing:
- Specify a unique
controlidin the request’s control block. This will allow you to match up asynchronous responses in your system.
- Specify unique values for the
controlidattribute of each function. This will allow you to match up the individual functions in your system.
- If specifying unique values for the
controlidattribute of each function, set the
truein the request’s control block. This will tell the system to fail any function where the
controlidvalue was previously successful.
- Sending multiple functions in one request’s operation can increase throughput, but this depends on the function, the tenant configuration, and the data being manipulated/processed. For example, you may find that sending 1 request operation to create 20 vendors is quicker than sending 20 request operations to create 1 vendor.
- Avoid large multi-function operations when the operation’s
transactionattribute is set to
true. Rolling back large multi-function operations adds significant overhead to your request.
- Multiple queue workers take jobs as slots open up, so FIFO processing of your requests is not guaranteed. If you need one-at-a-time processing, open a support case and ask that your company’s asynchronous requests be serialized.