DRE — DRFOUT Master Data Integration Guide

This guide is for SAP S/4HANA Basis administrators configuring a DRFOUT master-data replication from S/4HANA to DRE via SOAMANAGER. DRE accepts the S/4HANA DRFOUT SOAP envelope directly — there is no SAP Cloud Platform Integration (CPI) intermediary. S/4HANA's logical port points straight at DRE's SOAP endpoint.

DRE exposes the DRFOUT master-data interface over two transports in Phase 1:

SOAP (S/4HANA DRFOUT, via SOAMANAGER):
  POST https://<dre-srv-host>/api/v1/master-data/soap
  Content-Type: text/xml            (SOAP 1.1; application/soap+xml also accepted)

REST/JSON (integrators, tooling, tests):
  POST https://<dre-srv-host>/api/v1/master-data/ProductMerchandiseViewReplicationBulkRequest
  Content-Type: application/json

Both transports feed the same asynchronous pipeline (raw-payload retention, idempotency, BullMQ worker, converter, optional webhook). S/4HANA uses the SOAP endpoint; the REST endpoint stays available for non-S/4 integrators and tooling.

Endpoint URL note. S/4HANA connects to the srv module URL directly (the BTP service-binding URL), not the approuter URL. DRFOUT traffic is authenticated by mTLS, not by an XSUAA JWT; routing through the approuter would strip the client-certificate header and break authentication. No approuter route is required for the SOAP path.

1. S/4HANA SOAMANAGER setup

Configure an outbound logical port in S/4HANA so DRFOUT posts the SOAP envelope to DRE.

1.1 Steps

Step	S/4HANA action	Purpose
1	Import the WSDL into SOAMANAGER	Defines the `ProductMerchandiseViewReplicationBulkRequest_Out` service consumer
2	Create a logical port (manual configuration)	Binds the consumer proxy to DRE's endpoint
3	Set the endpoint (target) URL	Points at DRE's SOAP route
4	Configure the transport security (mTLS client certificate)	Authenticates S/4 to DRE
5	Activate DRFOUT replication for the merchandise-view object	Triggers the outbound POSTs

1.2 WSDL import (Step 1)

Use your S/4 system's own SOAMANAGER WSDL export for the merchandise-view replication outbound service as the contract for the logical-port configuration. It is SAP-standard, matched to your release and any active extensions.

targetNamespace: http://sap.com/xi/EA-RETAIL/Global2
The operation is one-way: a single wsdl:input (ProductMerchandiseViewReplicationBulkRequest) and no wsdl:output. There is no application-level confirmation message in the contract (see § 5 Response behaviour).

1.3 Endpoint URL (Step 3)

Set the logical-port endpoint (target) URL to DRE's SOAP route on the srv module host:

https://<dre-srv-host>/api/v1/master-data/soap

(Replace <dre-srv-host> with the srv module's BTP URL — not the approuter URL.)

1.4 Transport / messaging settings (Steps 2 & 4)

Setting	Value
Configuration type	Manual
Transport binding	SOAP 1.1 (`text/xml`); SOAP 1.2 (`application/soap+xml`) also accepted
Reliable Messaging (WS-RM)	Off — DRE does not implement WS-RM (see § 6)
Authentication	X.509 client certificate (mTLS)
Client certificate (STRUST)	Your DRFOUT client cert; its CN must be allow-listed in DRE (see § 4)

1.5 Idempotency (no extra step)

DRE derives the idempotency key from the SOAP body — specifically the message identifier in MessageHeader (the ID/UUID element). You do not set any Idempotency-Key HTTP header for the SOAP transport (that header is only used by the REST endpoint). DRFOUT re-deliveries carry the same message identifier, and DRE de-duplicates server-side (see § 3).

2. ActionCode pragma — only `04` is processed

DRE applies the following action-code pragma:

Only items with ActionCode = '04' (Insert/Update upsert) are projected onto Articles. Items with other action codes (01 delete, 02, 03, 05, 06) are silently dropped (counted as rowsSkipped).

This is protocol-agnostic — the SOAP and REST transports feed the same converter. Rationale: tenants that delete master data in DRE do so deliberately, not as a side effect of S/4 archiving. A row deleted in S/4 is not removed from DRE automatically.

DRFOUT forwards all items unchanged; DRE applies the filter server-side. Every received item is retained losslessly in the raw-payload store regardless of action code (audit-trail symmetry with the source DRFOUT log); only 04 items are upserted into Articles by the worker.

3. Replay / idempotency

The DRFOUT framework retries failed messages. DRE is tolerant.

The idempotency key is the MessageHeader message identifier (ID/UUID) extracted from the SOAP body — not an HTTP header.

Scenario	DRE behaviour	S/4 outcome
First delivery	`202` + empty SOAP body	DRFOUT call succeeds (transport ACK)
Retry, same message ID, same payload	`200` (replay) + empty SOAP body	succeeds (de-duplicated, no duplicate job)
Retry, same message ID, different payload	`409` + SOAP Fault	DRFOUT logs the fault — operator action required
Network blip — no response	S/4 retries	the message identifier catches the 2nd call
DRE `5xx`	SOAP Fault	S/4 retries on its DRFOUT cadence

DRE retains idempotency keys for 24 h. Within that window retries are absorbed; after 24 h the same key is treated as a fresh request — DRFOUT's retry window is far shorter, so this never matters in practice.

4. Cert pinning + rotation (mTLS via STRUST/SOAMANAGER)

DRE enforces mTLS on the SOAP endpoint. The CN → tenant mapping lives in the mTLS configuration store with namespaced keys:

mtls.cn.master-data.<cn>  ->  <tenantId>

The CN source is now the S/4HANA DRFOUT client certificate (configured in STRUST and bound to the logical port in SOAMANAGER), not a CPI-issued certificate. The CN-mapping mechanism in DRE is unchanged.

4.1 Onboarding a new S/4 tenant

S/4 Basis generates (or imports) a client certificate in STRUST (CN per your convention, e.g. <tenantId>.drfout.<company>).
S/4 Basis exports the public certificate and submits it to DRE ops.
DRE ops imports the cert into the trust store and writes the CN -> tenant mapping row.
S/4 Basis binds the certificate to the logical port in SOAMANAGER.
End-to-end smoke test against DRE staging.

4.2 Rotation cadence

Default cert lifetime: 365 days.
Renewal window: 30 days before expiry.
Hot-swap: import the new cert in STRUST as a secondary identity, switch the logical port to it on a maintenance window, retire the old cert.
DRE accepts both certs simultaneously during the swap (overlapping CN mappings allowed for <= 7 days).

4.3 Revocation

DRE consults the trust store on each request (not cached) — revocation propagates within seconds of a trust-store update. CRL polling cadence: 5 min on the DRE side.

5. Response behaviour — one-way fire-and-forget

The canonical WSDL declares a one-way operation (a single wsdl:input, no wsdl:output). DRE therefore returns a transport-level acknowledgement only:

DRE outcome	HTTP status	SOAP response body
Accepted (async enqueue)	`202`	minimal/empty SOAP envelope (`<soap:Body/>`)
Replay (same message ID, same payload)	`200`	minimal/empty SOAP envelope
Malformed XML / wrong Content-Type / validation	`400` (or `413` over size cap)	SOAP 1.1 Fault
Idempotency conflict (same ID, different body)	`409`	SOAP 1.1 Fault
Authentication failure	`401` / `403`	SOAP 1.1 Fault
Internal error	`500`	SOAP 1.1 Fault

There is no BulkConfirmation envelope and no SeverityCode/LogMessage payload — that type does not exist in the contract. After a 202, DRE has persisted the raw payload, created an ImportJobs row (status=QUEUED), and enqueued the bulk for the worker. Terminal job status is available via:

GET /api/v1/jobs/{jobId} (job-status REST API), or
the optional outbound webhook.

SOAP Faults are intentionally minimal: they carry a faultcode and a short, safe faultstring only. They never expose internal details (stack traces, tenant IDs, or job IDs) in a <detail> element.

The inbound operation returns no application-level payload and delegates to DRE's asynchronous queue/converter pipeline.

6. WS-RM (Reliable Messaging)

DRE does not implement WS-RM. Configure the S/4 logical port for plain SOAP 1.1 (no Reliable Messaging). Although the canonical WSDL policy may declare enableWSRM=true, DRE operates plain SOAP 1.1 one-way and ignores it at runtime. If a specific customer's logical port mandates WS-RM, that is a separate engineering spike — out of scope for Phase 1.

7. Operational metrics

DRE emits Prometheus counters:

Metric	Labels	Meaning
`dre_drfout_inbound_total`	`tenant`, `interface`, `protocol={soap,rest}`, `outcome={accepted,rejected,replay}`	Inbound message count, split by transport
`dre_drfout_items_total`	`tenant`, `interface`, `action_code`	Per-item accounting (incl. dropped non-`04`s)
`dre_drfout_job_duration_seconds`	`tenant`, `interface`	Histogram of inbound->processed time

The protocol label distinguishes SOAP (S/4 DRFOUT) from REST (integrators).

8. Reference

SOAP endpoint: POST /api/v1/master-data/soap
REST endpoint: POST /api/v1/master-data/ProductMerchandiseViewReplicationBulkRequest
Article Import API — REST and bulk-import alternatives to DRFOUT

9. Phase 2 outlook

Phase 2 candidates — only landed if a customer requests them:

BusinessPartner (customer + supplier master)
MerchandiseCategoryHierarchy (category tree)
PriceList (RPR/sales prices)
Site (store master, store-cluster mapping)
Article manual-price-entry projection (currently deferred)

Each lands as an additional SOAP/REST interface under the same /api/v1/master-data path family and the same async pipeline documented above.

1. S/4HANA SOAMANAGER setup​

1.1 Steps​

1.2 WSDL import (Step 1)​

1.3 Endpoint URL (Step 3)​

1.4 Transport / messaging settings (Steps 2 & 4)​

1.5 Idempotency (no extra step)​

2. ActionCode pragma — only 04 is processed​

3. Replay / idempotency​

4. Cert pinning + rotation (mTLS via STRUST/SOAMANAGER)​

4.1 Onboarding a new S/4 tenant​

4.2 Rotation cadence​

4.3 Revocation​

5. Response behaviour — one-way fire-and-forget​

6. WS-RM (Reliable Messaging)​

7. Operational metrics​

8. Reference​

9. Phase 2 outlook​