Sync vs async integration in Boomi

A partner wants to send you orders through an API. The obvious design is: receive the order, create it in the ERP, answer with the ERP order number. It works perfectly in testing. Then the ERP is slow on a Monday morning, the partner’s calls start timing out, they retry, and you get duplicate orders. This article explains when synchronous request-reply is the right choice, when it isn’t, and builds the same API both ways in Boomi.

The problem with waiting

In a synchronous design, the caller waits while your integration does all the work:

Partner ──► API ──► mapping ──► ERP create ──► response (5-30 s)

That is fine when the work is quick and the caller needs the result. It becomes a problem when:

• The backend is slow or busy. The ERP takes 20 seconds at month end, and the caller’s HTTP client gives up at 15.
• The backend is down. Maintenance on the ERP means the API returns errors, even though you could simply accept the orders and create them an hour later.
• Volume comes in bursts. A partner sends 2,000 orders at 09:00. Each one holds a connection open while it waits.
• Timeouts cause duplicates. The caller times out, but your side finished the work. The caller retries and the order is created twice.

The pattern: accept now, process later

In an asynchronous design, the API only does the minimum while the caller waits: check that the request is valid, store it safely in a queue, and reply 202 Accepted with a tracking ID. A separate process takes messages from the queue and does the real work at the pace the ERP can handle.

Partner ──► API: validate + enqueue ──► 202 Accepted { "trackingId": "..." }
                         │
                         ▼
                queue ──► worker: mapping ──► ERP create

The caller can check the result later through a status endpoint, or receive a callback.

How to choose

Question	Leans sync	Leans async
Does the caller need the result to continue?	yes (stock, price)	no (order, invoice)
How long does the work take?	under 1-2 seconds	seconds to minutes
Must it work when the backend is down?	no	yes
Can traffic arrive in bursts?	rarely	often

Questions (“what is the stock of SKU-771?”, “what is customer C-1042’s balance?”) are naturally synchronous. Commands (“create this order”) usually work better asynchronously. For a broader comparison of these patterns, see our guide Integration patterns every team should know.

Building it in Boomi

Both versions start from the same building blocks: a process with a Web Services Server start shape (action Listen) and an API Service component that publishes it as a REST endpoint, as described in Exposing your ERP as a REST API with Boomi.

Version 1: synchronous request-reply

1. Start: Web Services Server, Listen, input type a single JSON object (the order), output type a single JSON object (the result).
2. Validate: use a Decision or a Business Rules shape to check required fields. On failure, set the response status code to 400 and return an error body.
3. Map and create: a Map shape to the ERP order profile, then the ERP connector call.
4. Respond: map the ERP result to the response profile (for example { "orderId": "SO-2026-0815" }) and end with Return Documents.

The caller gets the ERP order number in the same call. Keep this version for fast operations, and set the caller’s timeout expectations clearly in your API documentation.

Version 2: asynchronous with a 202 and a queue

Split the work into two processes.

Process A: the receiver (runs while the caller waits)

1. Start: Web Services Server, Listen, same input profile as before.
2. Validate: the same checks as in version 1. Rejecting bad input immediately is still useful, because the caller can fix it right away.
3. Add a tracking ID: generate an ID (for example from the execution ID, or a GUID through a map function) and store it as a document property.
4. Enqueue: send the order to a queue. In Boomi you can use the Atom Queue connector on runtimes that support it, or publish to a topic with the Boomi Event Streams connector. Event Streams is a managed service, so the messages don’t depend on one runtime’s disk.
5. Respond: set the response status code to 202 and return { "trackingId": "..." , "status": "accepted" } with Return Documents.

The receiver does no ERP work, so it answers in a fraction of a second, even if the ERP is down.

Process B: the worker (runs in the background)

1. Start: a listener on the same queue or topic (Atom Queue or Event Streams connector with a Listen operation).
2. Map and create: the same mapping and ERP call as in version 1, wrapped in a Try/Catch shape.
3. Record the result: store the outcome by tracking ID (for example in a database table, with status CREATED and the ERP order number, or FAILED and a reason).
4. Idempotency: before creating, check whether an order with the partner’s order number already exists in the ERP. Queues usually deliver at least once, so the worker must tolerate duplicates.

Optional: a status endpoint

Add a second operation to the API Service, GET /orders/status/{trackingId}, backed by a small process that reads the result table. Partners can poll it, or you can push a callback to a URL they register.

A shortcut to know about

Boomi’s Process Call shape can start a sub-process without waiting for it to finish. It gives a fast response, but the work then lives only inside the runtime’s execution and is not stored durably like a queue message. Use it for non-critical work, and a real queue or topic for anything you can’t afford to lose.

Before you go live

• Document the contract. Tell consumers that 202 means “accepted for processing”, not “created”, and how to get the final result.
• Watch the queue depth. A growing queue is the early warning that the worker can’t keep up or the ERP is down. Alert on it.
• Handle poison messages. A message that always fails must not block the queue. Move it to a dead-letter or review queue after a few attempts (see Dead-letter handling with Boomi Event Streams).
• Test the outage. Stop the ERP connection, send orders, confirm you still get 202, then restore it and check every order is created exactly once.

Summary

Synchronous request-reply is the right choice for quick questions the caller needs answered now. For commands that touch slow or fragile systems, accept the request, queue it and answer 202, then process it in the background. In Boomi, the same Web Services Server and API Service building blocks support both, and a queue or event stream between two processes makes the difference. For the wider picture, see Integration patterns every team should know.