SAP IDoc

Requires the SAP NW RFC SDK installed on the server — see SAP SDK.

The asynchronous path, and the only one where SAP calls the CMS. The cms-idoc-connector microservice registers an RFC Server (node-rfc, Server class) with the SAP gateway and receives the IDocs sent to it. See SAP for the overview.

How it works

The connector is a separate process from cms-sap-connector because an RFC Server is a long-lived listener registered with the gateway, not a request/response call — a failure or restart of the listener must not affect the RFC client or the API.

Like any passive receipt, it is event-driven: there is no schedule, no cron. The IDoc arrives when SAP sends it.

Listeners

cms-api sends the full list of desired listeners (POST /idoc/listeners/sync) — one entry per SAP IDoc External Connection that has an active Collection using it.
The connector reconciles (starts, stops, restarts registrations) and returns the status of each.
GET /idoc/listeners/status reads the current state without waiting for the next sync.

A single Program ID is kept per External Connection. Several Collections — different IDoc types — share the same listener; it is cms-api that decides which ones each received IDoc goes to.

Configuring the connection

On the SAP External Connection, the IDoc block asks for two things of different natures:

Block	Fields	What for
Gateway registration	Gateway host, gateway service, Program ID, SAProuter, trace	This is what SAP will look for
Client logon	Client, user, password, language, host/instance or message server	Resolving the function module’s metadata

The client logon looks redundant — registration itself asks for no user or password. But node-rfc’s Server will not register anything with the gateway without first opening that connection, which it uses to resolve the IDOC_INBOUND_ASYNCHRONOUS interface. Without it, the listener does not come up.

The two test buttons

Button	What it does	Cost
Test Login	Opens and closes the logon connection. Registers nothing with the gateway	Cheap, and never leaves a stuck connection in SMGW
Test Gateway Registration	A short-lived registration: starts and stops immediately	Requires SM59/WE21/ACL already configured on the SAP side

Use the first to validate credentials and network reach; the second only after Basis has done their part.

What has to exist on the SAP side

This is the part that usually stalls a deployment, and it is not done in the CMS. Take this list to Basis:

RFC destination of type T (Registered) in SM59, with the chosen Program ID.
WE21 port (Transactional RFC) pointing at that destination.
WE20 partner profile (inbound) for the message type, with a process code linked to IDOC_INBOUND_ASYNCHRONOUS.
Gateway registration allowance: gw/reg_no_conn_info and the secinfo / reginfo ACLs for the Program ID and this service’s host.
Confirmation of the interface structure (EDI_DC40 / EDI_DD40), which differs between ECC and S/4HANA.

Item 4 is the one most often forgotten. Without the gateway ACL, registration fails with a security error that mentions no ACL at all — and time gets lost looking in the wrong place.

Collection — `SAP_IDOC`

In the Collection you define which IDocs on this connection this interface serves. The filters are applied to the control record (EDIDC):

Filter	Matches against	Empty means
IDoc type	`IDOCTYP` (e.g. `ORDERS05`)	Any type
Message type	`MESTYP` (e.g. `ORDERS`)	Any message
Partner	The sending partner	Any partner

Several Collections can share the same connection, each with its own slice. An IDoc matching more than one filter is forwarded to all the Collections that accept it — which allows, for instance, one Collection specific to a partner and another generic one for auditing.

The message format

Each IDoc arrives grouped by DOCNUM, with the control record (EDIDC) and the data segments (EDIDD). The Collection’s Transformer receives that whole set and decides what becomes a message — typically flattening the segments that matter.

Development mode

Without SAP_IDOC_CLIENT=real, the connector starts with a fake server: it never registers anything with the gateway and accepts POST /idoc/simulate to inject a test IDoc down the same path a real IDoc would take. That is how the Collection configuration, the Transformer and the forwarding are tested without access to a SAP system.

Installing the SDK is the same as for the RFC client, with SAP_IDOC_CLIENT=real instead of SAP_RFC_CLIENT.

Monitoring

Configure the Connection Lost alert for IDoc Collections. Because receipt is passive, a dead listener is silent: it raises no error, IDocs simply stop arriving. Without the alert, the stoppage only surfaces when someone misses the data. See Alerts.

The listener state also shows up on the Applications Panel, when the Application uses an SAP IDoc keep-alive.