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.
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.
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:
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 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:
controlidin the request’s control block. This will allow you to match up asynchronous responses in your system.
controlidattribute of each function. This will allow you to match up the individual functions in your system.
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.
transactionattribute is set to
true. Rolling back large multi-function operations adds significant overhead to your request.