web-services/sync-vs-async.md

metadata

title: Synchronous or Asynchronous | Sage Intacct Developer
url: https://developer.intacct.com/web-services/sync-vs-async/

Synchronous or Asynchronous | Sage Intacct Developer

Overview

Your First XML API Calls

XML Requests

XML Responses

XML Functions

Queries

Error Handling

Code and Usage Examples

Synchronous or Asynchronous

Parameter Formats

• Synchronous responses
• Asynchronous responses
  • Setting up asynchronous processing
  • Using asynchronous processing
  • Asynchronous processing for original custom reports
  • Best practices and tips

---

The Intacct XML API supports both synchronous and asynchronous responses to incoming requests.

A synchronous response returns to the client in the same HTTP connection as the request. Asynchronous responses are returned to the client in subsequent connections, freeing the client to send other requests instead of blocking while waiting for the response.

By default, responses from the gateway are synchronous. If you want asynchronous responses, some additional steps are required.

Note: The use of asynchronous 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

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 by limiting your calls based on our set of recommendations.

---

Asynchronous responses

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.

Note: The maximum asynchronous request size is 500K characters.

Setting up asynchronous processing

You must open a support case for help establishing an asynchronous transport policy. Be prepared to provide the following information:

Attribute	Required	Type	Description
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: false

An example transport policy setup is as follows:

• Policy ID: hello-world
• Response URL: https://www.example.com/test/intacct-async.php
• HTTP User ID: intacct
• HTTP Password: test123
• Serialize: false

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 controlid in the request’s control block. This will allow you to match up asynchronous responses in your system.
• Specify unique values for the controlid attribute of each function. This will allow you to match up the individual functions in your system.
• If specifying unique values for the controlid attribute of each function, set the uniqueid element to true in the request’s control block. This will tell the system to fail any function where the controlid value was previously successful.
• Ensure that your asynchronous request does not exceed the maximum request size of 500K characters or the request will not execute.
• 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 each.
• Avoid large multi-function operations when the operation’s transaction attribute 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.

Provide feedback