Integration Patterns and Runtime Flow for Side-by-Side Extensions

Explanation

Once an architect decides on a side-by-side extension, the next critical design work is defining how it integrates with the digital core at runtime. There are two broad integration styles: synchronous request-response and asynchronous event-driven, and most non-trivial extensions use a combination of both. Synchronous integration typically uses OData services or REST APIs exposed by S/4HANA (either standard released APIs from the SAP API Business Hub catalog, or custom APIs built via RAP - the ABAP RESTful Application Programming Model - in the core for private cloud/on-premise systems). The side-by-side application, often built with CAP on BTP, calls these APIs directly for read or write operations. This pattern suits scenarios where the extension needs an immediate response, such as validating stock availability before confirming a custom quote. The main runtime risks here are latency (every synchronous call adds network round-trip time to the user's perceived response), availability coupling (if the core API is down or slow, the extension's functionality degrades or fails), and authentication complexity, since calls must be authenticated and authorized end-to-end, typically via OAuth 2.0 client credentials or principal propagation through SAP Cloud Connector for on-premise systems, or direct OAuth trust for cloud-to-cloud calls. Asynchronous integration uses event-driven patterns: S/4HANA can emit business events (such as a sales order being created or changed) via a broker, and the side-by-side extension subscribes to these events through an event mesh or messaging service on BTP. This decouples the extension from the core's real-time availability - if the extension is down, events can be queued or replayed rather than lost, provided the eventing infrastructure supports durable delivery. This pattern suits scenarios like triggering a downstream compliance check or updating an external system after a business document is finalized, where immediate synchronous response is not required. SAP Cloud Connector is a key component when the core system is on-premise or in a private network: it establishes a secure reverse-invoke tunnel from BTP into the customer's network, allowing side-by-side apps to reach on-premise APIs without opening inbound firewall ports directly to the internet. Understanding its role, and that it is a potential single point of failure and a performance chokepoint if undersized, is important for production readiness discussions. Authentication and authorization deserve special attention. Principal propagation (passing the identity of the actual business user through to the backend) is preferred where fine-grained authorization in the core must be respected, but it adds complexity in trust configuration (SAML bearer assertion, or OAuth token exchange) compared to technical/service users with broad authorizations, which are simpler but weaker from a security and audit perspective. Troubleshooting side-by-side integration issues requires correlating logs across two or more systems: the BTP application logs (via a logging service), the integration/API gateway logs, and the core system's own trace tools. A common production issue is intermittent timeouts under load that only manifest when both the core and the extension are under peak transaction volume simultaneously - this requires load testing the combined flow, not just each side in isolation. Idempotency is another frequent gap: if an asynchronous event is redelivered (which most at-least-once delivery guarantees permit), the extension's event handler must be designed to safely process the same event twice without duplicating business effects, such as creating a document twice.

Code example

// Simplified CAP (Node.js/CDS) event handler illustrating idempotent processing// of an inbound 'SalesOrder.Created' event from S/4HANA via an event mesh subscriptionmodule.exports = function (srv) {  srv.on('SalesOrderCreated', async (msg) => {    const { orderId, eventId } = msg.data;     // Idempotency check: has this eventId already been processed?    const processed = await SELECT.one.from('ProcessedEvents').where({ eventId });    if (processed) {      console.log(`Event ${eventId} already processed, skipping.`);      return;    }     try {      // Call downstream logic, e.g. custom compliance check      await performComplianceCheck(orderId);       // Record event as processed only after successful handling      await INSERT.into('ProcessedEvents').entries({ eventId, processedAt: new Date() });    } catch (err) {      // Do not mark as processed; allow retry/redelivery to reprocess safely      console.error(`Failed processing event ${eventId}:`, err);      throw err;    }  });};

Real project scenario

A logistics company's side-by-side extension on BTP subscribes to goods-issue events from an S/4HANA private cloud system to trigger a customs documentation workflow. During a peak shipping period, duplicate events were redelivered by the event mesh due to a transient network blip, and the extension briefly generated duplicate customs filings until the team added an idempotency table keyed on event ID, after which redelivered events were safely ignored.

Common mistakes

• Assuming event delivery is exactly-once when most eventing infrastructure only guarantees at-least-once delivery • Using a single broad technical user for all API calls instead of scoping authorizations per integration use case • Not load testing the combined core-plus-extension flow, only testing each side independently • Undersizing or single-instancing SAP Cloud Connector, creating an availability bottleneck for on-premise integration • Failing to correlate logs across BTP, integration middleware, and the core system, making production incidents hard to diagnose

Best practices

• Choose synchronous integration only when immediate response is functionally required; prefer asynchronous events elsewhere for resilience • Design all event handlers to be idempotent using a durable processed-event record or natural business keys • Use principal propagation where fine-grained backend authorization matters, accepting the added trust configuration complexity • Size and monitor SAP Cloud Connector capacity as a production-critical component, not an afterthought • Establish correlation IDs that flow across BTP, middleware, and core logs to enable end-to-end troubleshooting

Interview angle

Candidates are often asked to describe how a BTP extension securely reaches an on-premise S/4HANA system and how they would handle duplicate event delivery; strong answers mention Cloud Connector, OAuth/principal propagation trade-offs, and concrete idempotency design rather than vague references to 'API integration.'