CAP database rollback and remote calls: Use the right transaction boundary
A manufacturer's custom service saves a local request and also contacts another system to reserve components.
START HERE · NO PRIOR TOPIC KNOWLEDGE NEEDED
What it is. Why it matters.
A database transaction groups changes that succeed or fail together. An external HTTP call is a separate action; an outbox can coordinate reliable follow-up after local changes.
Completely new to SAP?
Manufacturers use SAP to connect work such as buying components, recording inventory, planning production, shipping equipment and accounting for costs. SAP S/4HANA is an enterprise resource planning system: it connects these activities through shared business data.
ABAP is SAP’s programming language for business applications. A program reads data, applies rules and produces a result. Start with the objects involved before investigating code.
A transaction code, or t-code, is a shortcut to a task in classic SAP GUI. Fiori apps provide another way to work. Names and screens depend on the product and release; you do not need a live system to learn the concepts in this guide.

Scope and source-review notes
Scope and evidence
Source review by FAST SAP SOLUTIONS® editorial. This badge describes our editorial review; it does not represent SAP certification or independent endorsement.
CAP Node.js local transactions and current queue/outbox concepts; API names, persistence and retry settings vary by installed runtime, and Java differs.
Primary documentation reviewed on 14 November 2026 using readable full text and official indexed excerpts. Relevant full-text event-queue sections and indexed transaction/runtime reference text reviewed. Queue configuration, restart survival, remote contracts and the snippet were not executed; application state names are illustrative.
A MANUFACTURING EXAMPLE
Avoid an inconsistent component reservation handoff
Two systems, two outcomes
Read the example values
- Local transaction
- Save order
- External operation
- Notify receiver
- Outbox record
- Track intended follow-up
- Failure case
- One operation can fail
Words you’ll meet in this guide
- Program
- A set of instructions executed by a computer.
- Class
- A reusable unit that groups data with operations called methods.
- Database
- Organized information kept beyond one program execution.
- Internal table
- A list of rows held temporarily in an ABAP program’s memory.
- Key
- One or more fields used to identify or find a record.
- CDS
- Core Data Services: reusable definitions of business data and relationships.
- API
- A defined interface through which programs exchange data or request actions.
- HTTP
- The request-and-response protocol used by web applications and APIs.
Preview the practical steps
SEE THE CONNECTION
See it in a simple example.
A small example to make the idea concrete.
Avoid an inconsistent component reservation handoff
A manufacturer's custom service saves a local request and also contacts another system to reserve components.
A local rollback cannot undo a remote business effect
A CAP request can write local data and call another system, but those actions do not automatically form one distributed ACID transaction.
Scope and prerequisites
The example uses current CAP Node.js queue concepts, including the documented cds.queued wrapper.
Worked case: local order O100 and reservation R700
A fictional request creates local order O100 for 3 units of material M10, calls a warehouse reservation service and then performs another validation.
Avoid an inconsistent component reservation handoff
A manufacturer's custom service saves a local request and also contacts another system to reserve components.
Separate local transaction evidence from the external effect and use the documented delivery design before promising all-or-nothing cross-system behavior.
| Reader | Business question | Evidence to carry forward |
|---|---|---|
| SAP developers and application teams supporting manufacturers | Avoid an inconsistent component reservation handoff | Separate local transaction evidence from the external effect and use the documented delivery design before promising all-or-nothing cross-system behavior. |
01 A local rollback cannot undo a remote business effect
A CAP request can write local data and call another system, but those actions do not automatically form one distributed ACID transaction. If a remote reservation succeeds and the local request later fails, the local database can roll back while the reservation remains. Draw the actual boundaries before adding another try/catch or rollback call. [1] [2]
When the remote work can occur after local commit, a supported transactional event queue/outbox can persist the intended follow-up with the business data and dispatch it later. That changes the response contract: local acceptance is no longer remote completion. This tutorial develops an order/reservation case with retry, uncertainty and reconciliation states.
02 Scope and prerequisites
The example uses current CAP Node.js queue concepts, including the documented cds.queued wrapper. Older CAP releases used different outbox configuration patterns; CAP Java has its own OutboxService APIs. Record installed packages, database adapter, deployment topology and the persistence/retry configuration actually enabled in your project.
You should understand a managed request transaction and a remote service call. Use test receivers and disposable orders for failure exercises. The snippets below illustrate integration boundaries, not a deployed end-to-end reservation implementation. No remote reservation or database rollback was executed for this article, and no universal queue default or exactly-once delivery guarantee is claimed.
03 Worked case: local order O100 and reservation R700
A fictional request creates local order O100 for 3 units of material M10, calls a warehouse reservation service and then performs another validation. The warehouse accepts reservation R700. The later local validation fails, so O100 rolls back. The warehouse still holds 3 units because its transaction completed independently.
This leaves an orphan reservation relative to the local order. Retrying the original request can create another reservation unless the receiver recognizes the same business request. A local exception handler cannot reverse R700 merely by throwing again. The design needs either a synchronous compensation/reconciliation policy or a deferred follow-up whose intent is committed with the order.
| Time | Local system | Warehouse system |
|---|---|---|
| T1 | Begin order O100 transaction | No reservation |
| T2 | Call remote reservation | Create R700 for 3 units |
| T3 | Later validation fails | R700 already accepted |
| T4 | Roll back O100 | R700 remains |
| T5 retry | May submit another request | Duplicate effect possible |
04 Choose synchronous confirmation or deferred follow-up deliberately
Use a synchronous call when the current business response truly requires the remote answer, then design timeout and partial-outcome handling. You may need a documented cancellation operation, a reservation expiry policy or a remote lookup by stable request reference. Keep those capabilities explicit; do not invent a compensation endpoint that the receiver does not provide.
Use deferred work when local creation can return a pending state and remote completion can be shown later. An outbox is suitable for notifications or remote writes whose results are not needed in the current execution context. It cannot transparently replace a synchronous price quotation or availability decision if the user must see that answer before accepting the operation. [2]
05 What the transactional queue changes
With the supported persistent queue setup, the local business change and queued intent are stored within the current transaction. If that transaction fails, the queued intent should not survive as committed work. If it commits, the dispatcher can send the follow-up after commit and retry according to configuration. [2]
This addresses a specific gap: an application can no longer commit an order and forget to record that a notification was required because the process crashed between two independent steps. It does not make the warehouse transaction part of the local commit. Receiver acceptance and the local acknowledgment of that acceptance still form another failure boundary.
06 Illustrative CAP Node.js integration shape
The sketch wraps a configured remote service and queues a request from the order-create flow. The requestId is a stable business correlation value that the receiver must support for duplicate handling. Inspect your installed queue documentation for persistent storage, retry and operational settings before relying on restart survival.
The awaited queued send records the intended work according to the queue contract; it does not mean the warehouse has already created a reservation. Return a local pending state from the order operation and implement a separate supported confirmation/reconciliation path. Do not fabricate a remote reservation number in the original response.
const cds = require('@sap/cds')
module.exports = class OrderService extends cds.ApplicationService {
async init() {
const warehouse = await cds.connect.to('Warehouse')
const queuedWarehouse = cds.queued(warehouse)
this.after('CREATE', 'Orders', async (order) => {
await queuedWarehouse.send('POST', 'Reservations', {
requestId: `reserve:${order.ID}:v1`,
orderId: order.ID,
material: order.material,
quantity: order.quantity
})
})
return super.init()
}
}07 Define observable business states independently of queue internals
For O100, use a business state such as RESERVATION_PENDING after the local commit, CONFIRMED after supported remote confirmation and NEEDS_REVIEW when automatic processing cannot resolve the outcome. These are illustrative application states, not CAP-delivered status values. They let users distinguish saved order data from warehouse completion.
Queue records are operational evidence, not necessarily the best public UI model. A task being dispatched or removed does not by itself explain every business outcome. Correlate the stable request ID with receiver evidence and maintain the order's state through a controlled workflow. If the receiver declines reservation because stock is insufficient, represent that business outcome rather than retrying forever as though every rejection were a network outage.
| State | What is established | User-visible implication |
|---|---|---|
| RESERVATION_PENDING | Local order and follow-up intent committed | Do not promise warehouse stock yet |
| CONFIRMED | Receiver reservation correlated and accepted | Show verified reservation reference |
| NEEDS_REVIEW | Retry/reconciliation cannot determine outcome | Provide an owned resolution path |
| REJECTED_BY_WAREHOUSE | Known business rejection | Explain next business choice |
08 Retries require receiver-side duplicate handling
A timeout can occur after the warehouse accepts the request but before CAP receives the response. Retrying then sends the same intent again. Use a stable idempotency/business key and a receiver contract that returns or recognizes the existing result for that key. Generating a new random request ID for every retry defeats this protection.
The receiver should define what happens if the same key arrives with a different material or quantity. Rejecting that mismatch or returning a controlled conflict is safer than silently treating changed content as the same request. An outbox improves reliable follow-up; it does not independently guarantee one business effect across an arbitrary remote API.
09 Troubleshooting local and remote divergence
Collect both systems' evidence before deciding whether to retry, compensate or correct data. A local queue failure and a remote business rejection are different states.
| Observation | Question | Next action |
|---|---|---|
| Remote reservation; no local order | Was direct call sent before local failure? | Reconcile and use supported cancellation if required |
| Order pending; no remote call | Did queued intent commit and dispatcher run? | Inspect configured queue and correlated task |
| Receiver accepted twice | Stable key and receiver deduplication? | Repair idempotency contract |
| Repeated business rejection | Is error retryable? | Route to business resolution |
| Timeout after remote acceptance | Outcome uncertain? | Query receiver by stable reference |
| Works until process restart | Was persistence actually configured? | Inspect deployed queue storage and settings |
| Local response says confirmed immediately | Confusing enqueue with remote completion? | Correct response/state contract |
10 Test failures before and after the commit boundary
First test local validation failure before commit: neither the order nor committed follow-up intent should remain under the chosen design. Next commit O100 while the receiver is unavailable and verify a pending order plus recoverable queued work. Restart the test process where the configured persistent queue supports it and confirm the intended survival behavior.
Then simulate a receiver that accepts but loses its response. Retry with the same stable reference and verify one reservation effect. Test a permanent business rejection and a malformed payload separately from transient unavailability. Inspect local and remote state after each test. These are proposed acceptance checks and require a controlled test receiver; the article has not executed them.
11 Operations and evolving event contracts
Assign an owner for exhausted retries and uncertain reservations. Keep correlation identifiers, failure classification and a supported manual reconciliation procedure available. Avoid automatic loops that create a fresh order whenever a queue task fails. Repairing one side must preserve the authoritative business reference and recorded history.
Queued payloads can survive deployments. If a later release changes the event shape, account for already persisted work and receiver compatibility. Include a version or stable contract where useful, and avoid removing a handler while old tasks still require it. Monitor pending age and resolution outcomes according to business needs rather than assuming queue depth alone tells users whether orders are fulfilled.
12 Frequently asked questions
Does cds.tx make remote calls atomic? No. CAP documents that nested transaction coordination is not a distributed atomic transaction across independent services. [1]
Can an outbox return the remote result immediately? Its purpose is deferred reliable work; design a separate confirmation/read path when the result arrives later.
Does retry mean exactly once? Not across an arbitrary receiver. Stable keys and receiver-side duplicate handling are necessary for one intended business effect.
What should the design review contain? A timeline, local/remote commit owners, pending-state contract, stable request key, retry classification, receiver lookup/compensation capabilities and failure tests. That explains how the systems converge when the happy path breaks.
Related services and next steps
Primary sources
Found this useful?
Share this guide with your network, or leave a like.
Your like is saved in this browser.