Production Architectural Blueprint • Tool #50 Milestone

SAP OData $batch & Atomic ChangeSet Architecture Guide

Integration Domain: High-Integrity Remote Transactions Protocol: OData V2 & V4 OASIS Specification Clean Core Objective: Zero Inconsistent States

1. The Hazard of Sequential Micro-Transactions

When building side-by-side applications on SAP BTP (or external portals) communicating with SAP S/4HANA, developers frequently make sequential HTTP calls:

1. POST /SalesOrder → Header created with ID 10001.
2. POST /SalesOrderItem (Item 10) → Committed successfully.
3. POST /SalesOrderItem (Item 20) → HTTP 500 Network Timeout or Validation Failure!

In this catastrophic failure mode, the sales order header and item 10 remain committed in SAP S/4HANA while item 20 is lost. The database is left in a corrupted, half-posted business state, generating audit anomalies and manual reconciliation overhead.

2. The Solution: OData $batch and Atomic ChangeSets

The OData $batch endpoint allows bundling multiple read queries and mutating operations into a single HTTP POST request. Crucially, mutating operations grouped inside a ChangeSet execute within a single SAP HANA Logical Unit of Work (LUW):

Architectural Vector	Sequential HTTP Calls	Atomic OData ChangeSet ($batch)
Transaction Atomicity	None (Partial commits occur)	100% All-or-Nothing Rollback
Roundtrip Latency	N roundtrips (High WAN/Cloud Connector overhead)	Single TCP / TLS connection roundtrip
Key Resolution	Requires synchronous read before next POST	Dynamic via Content-ID referencing ($1/_Item)
SAP Work Process Consumption	N work process context switches	Single transactional work process execution

3. Content-ID Referencing: Dynamic Key Binding

When creating a parent header and dependent children in the same request, the header's primary key (e.g. Sales Order Number) is generated by a number range sequence and unknown to the client beforehand.

The OData standard resolves this via Content-ID referencing:

--changeset_boundary
Content-Type: application/http
Content-ID: 1

POST SalesOrder HTTP/1.1
Content-Type: application/json

{ "SalesOrderType": "OR", "SalesOrganization": "1010" }

--changeset_boundary
Content-Type: application/http
Content-ID: 2

POST $1/_Item HTTP/1.1
Content-Type: application/json

{ "Material": "MAT-001", "RequestedQuantity": 50 }

4. OData V2 (MIME) vs OData V4 (JSON Batch)

• OData V2: Utilizes standard MIME multipart boundaries (multipart/mixed; boundary=...). Requires strict adherence to CRLF line endings.
• OData V4: Standardizes on a clean JSON request format ({"requests": [...]}) with atomicityGroup properties, eliminating MIME parsing overhead.

5. Clean Core Governance & Anti-Patterns to Avoid

• Anti-Pattern 1: Unbounded Batch Sizes: Sending thousands of operations in a single batch causes gateway memory saturation and gateway work process timeouts. Batch sizes should be capped at 100-250 items per ChangeSet.
• Anti-Pattern 2: Mixing Read Queries inside a ChangeSet: ChangeSets are reserved strictly for mutating operations (POST, PUT, PATCH, DELETE). GET queries must reside outside ChangeSets within the general batch boundary.
• Anti-Pattern 3: Bypassing CSRF Protection: Always execute a pre-flight HEAD request with X-CSRF-Token: Fetch and retain cookies across the session to prevent 403 Forbidden - CSRF token validation failed errors.