Skip to main content
Version: 5.1

Receive IDocs over HTTP from SAP S/4HANA Private Cloud

Time: About 45 minutes | What you'll build: An HTTP service that receives the MATMAS IDocs SAP sends whenever a material is distributed, converts the IDoc XML into typed records, maps it to a simple material record with the Data Mapper, logs it, and acknowledges the IDoc to SAP.

SAP usually sends IDocs to an external system over transactional RFC, which needs the SAP JCo libraries on the receiving side, as shown in Call RFC Function Modules and Receive IDocs with SAP S/4HANA Private Cloud. SAP can also send IDocs as XML documents over plain HTTP, through an XML HTTP port. The integration is then an ordinary HTTP service: there are no SAP libraries to download, no SAP gateway to register with, and the same service works behind any load balancer or API gateway.

How it works​

Architecture diagram: SAP S/4HANA Private Cloud sends a MATMAS IDoc as XML through an XML HTTP port and an SM59 destination to the WSO2 Integrator HTTP service POST /sap/idocs, which returns 201 Created; the Data Mapper turns the IDoc XML into JSON, ready to send on to a target system such as an ERP, database or message brokerArchitecture diagram: SAP S/4HANA Private Cloud sends a MATMAS IDoc as XML through an XML HTTP port and an SM59 destination to the WSO2 Integrator HTTP service POST /sap/idocs, which returns 201 Created; the Data Mapper turns the IDoc XML into JSON, ready to send on to a target system such as an ERP, database or message broker
  1. A material is distributed in SAP, for example with transaction BD10, or automatically through change pointers.
  2. ALE builds a MATMAS05 IDoc for the receiving partner and hands it to the partner's XML HTTP port.
  3. The port turns the IDoc into IDoc XML and sends it with an HTTP POST to the URL defined in an SM59 HTTP connection to an external server.
  4. The integration's POST /sap/idocs resource receives the XML, converts it into a MATMAS05 record, maps it to a MaterialEvent record with the Data Mapper, logs it, and returns 201 Created.
  5. Because the HTTP call returned a 2xx status, SAP sets the IDoc to status 03 (data passed to port OK). Any other status, or no response, leaves the IDoc in an error status, from where it can be sent again.

Before you begin​

Prerequisites
  • A URL for the integration that the SAP system can reach over the network, for example through your API gateway or load balancer.
  • Access to the SAP GUI transactions SM59, WE21, BD54, WE20, BD64 and BD10, or a colleague from your SAP Basis team who can run them for you.
  • A material that exists in your SAP client. The examples in this guide use material FG233 in client 100.

Build the integration​

Build the service first, so that it is running when you test the connection from SAP.

Step 1: Create the integration and the HTTP service​

  1. Create a new integration named SapIdocReceiver in a project named SapIdocReceiver.

    Create a Project form with the project name and the integration name both set to SapIdocReceiverCreate a Project form with the project name and the integration name both set to SapIdocReceiver
  2. On the integration overview, select Add Artifact manually. On the Artifacts page, select HTTP Service under Integration as API.

    Artifacts page with the HTTP Service card selected under Integration as APIArtifacts page with the HTTP Service card selected under Integration as API
  3. Keep Design From Scratch, set Service Base Path to /sap, and select Create.

    Create HTTP Service form with Design From Scratch selected and the service base path set to /sapCreate HTTP Service form with Design From Scratch selected and the service base path set to /sap

Step 2: Add the IDoc resource​

SAP posts each IDoc as an XML document, so the resource takes an xml payload.

  1. Select Add Resource, then POST, and set Resource Path to idocs.

  2. Select Define Payload, open Browse Existing Types, search for xml, select xml, and select Save.

    Define Payload dialog on the Browse Existing Types tab with the xml data type selectedDefine Payload dialog on the Browse Existing Types tab with the xml data type selected
  3. Select the edit icon on the payload, change Name to idoc, and select Save. Keep the default responses (201 with json, 500 with error) and select Save.

    New Resource Configuration panel with the POST method, the resource path idocs, an xml payload named idoc, and 201 json and 500 error responsesNew Resource Configuration panel with the POST method, the resource path idocs, an xml payload named idoc, and 201 json and 500 error responses

Step 3: Create the IDoc types​

The XML that SAP sends has the IDoc type as its root element, for example <MATMAS05>, with one <IDOC> element. Inside it, EDI_DC40 is the control record and every other element is a segment. Creating record types for this structure lets the Data Mapper show the IDoc fields.

  1. In the project explorer, select + next to Types, then select Add Type. In the New Type panel, open the Import tab and set Format to XML.

  2. Paste a sample MATMAS05 IDoc and select Import. Include only the segments and fields you need; the import creates one record type per element, and segments and fields that are not in a type are ignored when an IDoc is converted:

    <MATMAS05>
    <IDOC BEGIN="1">
    <EDI_DC40 SEGMENT="1">
    <DOCNUM>0000000000057020</DOCNUM>
    <MESTYP>MATMAS</MESTYP>
    <IDOCTYP>MATMAS05</IDOCTYP>
    <SNDPRN>S4HCLNT100</SNDPRN>
    <RCVPRN>WSO2HTTP</RCVPRN>
    </EDI_DC40>
    <E1MARAM SEGMENT="1">
    <MATNR>FG233</MATNR>
    <MTART>FERT</MTART>
    <MATKL>L004</MATKL>
    <MEINS>ST</MEINS>
    </E1MARAM>
    </IDOC>
    </MATMAS05>
    New Type panel on the Import tab with format XML and a sample MATMAS05 IDoc pasted inNew Type panel on the Import tab with format XML and a sample MATMAS05 IDoc pasted in
  3. The import infers DOCNUM as int, which would drop the leading zeros of the IDoc number. In the type diagram, open the ⋮ menu on the EDI_DC40 card and select Edit. Change the type of DOCNUM to string, and select Save.

    Edit Type panel for EDI_DC40 with DOCNUM changed to string, next to the type diagram of IDOC, EDI_DC40 and E1MARAMEdit Type panel for EDI_DC40 with DOCNUM changed to string, next to the type diagram of IDOC, EDI_DC40 and E1MARAM
  4. Create the output type. Select Add Type, keep Create from scratch, name it MaterialEvent, and add five string fields: idocNumber, materialNumber, materialType, materialGroup and baseUnit. Select Save.

    New Type panel for the MaterialEvent record with five string fields: idocNumber, materialNumber, materialType, materialGroup and baseUnitNew Type panel for the MaterialEvent record with five string fields: idocNumber, materialNumber, materialType, materialGroup and baseUnit

Step 4: Convert the payload to the IDoc type​

  1. Open the idocs resource. Select the + below Start, then Declare Variable. Name it matmas and set Type to MATMAS05.

  2. In Expression, open the helper pane, select Functions, search for parseAsType, and select parseAsType() under data.xmldata. This adds the ballerina/data.xmldata import. Then set the expression to:

    check xmldata:parseAsType(idoc, {}, MATMAS05)

    parseAsType converts the XML payload into a MATMAS05 record. If the XML does not match the type, the step fails, the Error Handler returns 500, and SAP keeps the IDoc in an error status.

    Declare Variable form for matmas of type MATMAS05 with the expression check xmldata:parseAsType(idoc, {}, MATMAS05)Declare Variable form for matmas of type MATMAS05 with the expression check xmldata:parseAsType(idoc, {}, MATMAS05)
  3. Select Save.

Step 5: Map the IDoc with the Data Mapper​

  1. Select the + after the conversion step, then Map Data. Expand Within Project and select Create Data Mapper.

  2. Name the data mapper toMaterialEvent. Under Inputs, select Add Argument, enter matmas, and select Add. Set Output to MaterialEvent and Result to materialEvent, then select Open in Data Mapper.

    Data Mapper Creation form with the name toMaterialEvent, the input matmas of type MATMAS05, the output type MaterialEvent and the result materialEventData Mapper Creation form with the name toMaterialEvent, the input matmas of type MATMAS05, the output type MaterialEvent and the result materialEvent
  3. Draw a line from each input field to its output field:

    Input (matmas)Output (MaterialEvent)
    IDOC.EDI_DC40.DOCNUMidocNumber
    IDOC.E1MARAM.MATNRmaterialNumber
    IDOC.E1MARAM.MTARTmaterialType
    IDOC.E1MARAM.MATKLmaterialGroup
    IDOC.E1MARAM.MEINSbaseUnit
    Data Mapper toMaterialEvent with DOCNUM, MATNR, MTART, MATKL and MEINS mapped to idocNumber, materialNumber, materialType, materialGroup and baseUnitData Mapper toMaterialEvent with DOCNUM, MATNR, MTART, MATKL and MEINS mapped to idocNumber, materialNumber, materialType, materialGroup and baseUnit
  4. Go back to the resource. The flow now has a Map Data step that produces materialEvent.

Step 6: Log and acknowledge the IDoc​

SAP treats any 2xx response as a successful delivery.

  1. Add a Log Info step after Map Data, switch Msg to Expression, and enter:

    string `IDoc ${materialEvent.idocNumber} received over HTTP for material ${materialEvent.materialNumber}`
    log printInfo form with a string template that uses materialEvent.idocNumber and materialEvent.materialNumberlog printInfo form with a string template that uses materialEvent.idocNumber and materialEvent.materialNumber
  2. Add a Return step and enter materialEvent, then select Save. The resource returns 201 Created with the mapped material.

    Return form with the expression materialEventReturn form with the expression materialEvent

The completed resource converts the IDoc, maps it, logs it and acknowledges it. In a real integration, this is where you would send materialEvent on to the target system before returning.

Completed resource flow for POST idocs: Start, xmldata parseAsType into matmas, Map Data into materialEvent, log printInfo, Return materialEvent, and the Error HandlerCompleted resource flow for POST idocs: Start, xmldata parseAsType into matmas, Map Data into materialEvent, log printInfo, Return materialEvent, and the Error Handler

Select Run. The service starts on port 9090, so the IDoc endpoint is http://<integration-host>:9090/sap/idocs.

WSO2 Integrator terminal showing bal run compiling sapidocreceiver and running the executableWSO2 Integrator terminal showing bal run compiling sapidocreceiver and running the executable

Set up SAP​

SAP needs three things: an HTTP destination that points at the integration, an XML HTTP port that uses it, and a partner profile and distribution model that route MATMAS IDocs to the port.

Create the HTTP destination​

  1. Start transaction SM59, select HTTP Connections to External Server, and select Create. Enter WSO2_IDOC_HTTP as the Destination, keep connection type G, and confirm.

  2. Enter a description. On Technical Settings, set Host to the integration host, Port to the port SAP should connect to, and Path Prefix to /sap/idocs.

    RFC destination WSO2_IDOC_HTTP of connection type G in transaction SM59, with host idoc-receiver.example.com, port 80 and path prefix /sap/idocsRFC destination WSO2_IDOC_HTTP of connection type G in transaction SM59, with host idoc-receiver.example.com, port 80 and path prefix /sap/idocs
  3. On Logon & Security, keep Do Not Use a User if the endpoint does not check credentials, or select Basic Authentication with the user and password your API gateway or service expects. For HTTPS, select SSL Active under Security Options with an SSL client PSE, and set Port to 443.

    Security Options on the Logon and Security tab of the RFC destination, with SSL Active and the DFAULT SSL Client (Standard) PSESecurity Options on the Logon and Security tab of the RFC destination, with SSL Active and the DFAULT SSL Client (Standard) PSE
    Trust the integration's certificate

    With SSL Active, SAP checks the integration's certificate against the SSL client PSE. If the root certificate authority of that certificate is not in the PSE, the connection test fails with SSSLERR_PEER_CERT_UNTRUSTED. Import the root certificate into the PSE with transaction STRUST, or ask your SAP Basis team to do it.

  4. Select Save, then Connection Test. The test sends an HTTP GET, and the service only accepts POST, so a 405 Method Not Allowed response means SAP reached the integration.

    Connection test for HTTP destination WSO2_IDOC_HTTP with HTTP response status 405 Method Not Allowed returned by the integrationConnection test for HTTP destination WSO2_IDOC_HTTP with HTTP response status 405 Method Not Allowed returned by the integration

Create the XML HTTP port​

  1. Start transaction WE21, select XML HTTP, and select Create.

  2. Enter a port name, for example WSO2_HTTP, a description, and set RFC destination to WSO2_IDOC_HTTP. Keep the content type Text/XML, then Save.

    XML HTTP port WSO2_HTTP in transaction WE21 with the RFC destination WSO2_IDOC_HTTP and content type Text/XML, and the message Data was savedXML HTTP port WSO2_HTTP in transaction WE21 with the RFC destination WSO2_IDOC_HTTP and content type Text/XML, and the message Data was saved

Create the logical system and partner profile​

  1. Start transaction BD54, select New Entries, add a logical system for the integration, for example WSO2HTTP, and Save. Logical systems are cross-client, so SAP asks for a workbench request.

    New logical system WSO2HTTP in transaction BD54, and the message Data was savedNew logical system WSO2HTTP in transaction BD54, and the message Data was saved
  2. Start transaction WE20, select Partner Type LS, and create a partner profile for WSO2HTTP. Under Outbound, add message type MATMAS with the XML HTTP port as Receiver port, output mode Pass IDoc Immediately, and basic type MATMAS05, then Save.

    Partner profile WSO2HTTP of partner type LS in transaction WE20 with an outbound parameter for message type MATMAS, receiver port WSO2_HTTP and basic type MATMAS05Partner profile WSO2HTTP of partner type LS in transaction WE20 with an outbound parameter for message type MATMAS, receiver port WSO2_HTTP and basic type MATMAS05

Add MATMAS to the distribution model​

  1. Start transaction BD64, switch to change mode, and select Create Model View.

  2. Select the new model view, then Add Message Type, with the logical system of your SAP client as Sender, WSO2HTTP as Receiver, and MATMAS as Message Type, then Save.

    Distribution model in transaction BD64 with the model view WSO2 Integrator IDoc over HTTP, sending MATMAS from client 100 S/4HANA (S4HCLNT100) to WSO2HTTP, and the message Distribution model has been savedDistribution model in transaction BD64 with the model view WSO2 Integrator IDoc over HTTP, sending MATMAS from client 100 S/4HANA (S4HCLNT100) to WSO2HTTP, and the message Distribution model has been saved

Run and verify​

  1. With the integration running, start transaction BD10 in SAP, enter material FG233, message type MATMAS and logical system WSO2HTTP, and select Execute.

    Send Material screen in transaction BD10 with material FG233, message type MATMAS and logical system WSO2HTTPSend Material screen in transaction BD10 with material FG233, message type MATMAS and logical system WSO2HTTP

    SAP confirms that it generated one communication IDoc.

    Information dialog in BD10 stating 1 communication IDoc(s) generated for message type MATMASInformation dialog in BD10 stating 1 communication IDoc(s) generated for message type MATMAS
  2. The integration logs the IDoc and returns the mapped material to SAP. To see the response yourself, post a saved IDoc XML file to the service, for example with curl -X POST -H "Content-Type: text/xml" --data-binary @matmas05.xml http://localhost:9090/sap/idocs:

    WSO2 Integrator terminal with the log line IDoc 0000000000057020 received over HTTP for material FG233, and the JSON response with idocNumber, materialNumber FG233, materialType FERT, materialGroup L004 and baseUnit STWSO2 Integrator terminal with the log line IDoc 0000000000057020 received over HTTP for material FG233, and the JSON response with idocNumber, materialNumber FG233, materialType FERT, materialGroup L004 and baseUnit ST
    {
    "idocNumber": "0000000000057020",
    "materialNumber": "FG233",
    "materialType": "FERT",
    "materialGroup": "L004",
    "baseUnit": "ST"
    }
  3. In transaction WE02, filter on partner number WSO2HTTP. The IDoc has status 03, and its status text reads IDoc sent by HTTP in XML format.

    IDoc list in transaction WE02 with two MATMAS05 IDocs for partner WSO2HTTP on port WSO2_HTTP in status 03, and the status text IDoc sent by HTTP in XML formatIDoc list in transaction WE02 with two MATMAS05 IDocs for partner WSO2HTTP on port WSO2_HTTP in status 03, and the status text IDoc sent by HTTP in XML format

Troubleshooting​

SymptomCause and fix
The SM59 connection test fails with SSSLERR_PEER_CERT_UNTRUSTEDThe SSL client PSE does not trust the integration's certificate. Import its root certificate authority with transaction STRUST.
The SM59 connection test fails with a timeout or ICM_HTTP_CONNECTION_FAILEDSAP cannot reach the integration host and port. Check the host, port and firewall from the SAP network, and that the integration is running.
The IDoc status is 02 (error passing data to port)The service did not return a 2xx status. Check the integration log for the error, fix the cause, and resend the IDoc with transaction BD87.
BD10 reports 0 communication IDoc(s) generatedThe distribution model has no MATMAS entry for the receiver. Add it in Add MATMAS to the distribution model.
400 Bad Request in the integration logThe request body is not well-formed XML. Check that the port's content type is Text/XML.
500 Internal Server Error and a conversion error in the logThe IDoc does not match the record types, for example a required field is missing or a segment the types expect once appears more than once. Edit the record types to match the IDoc, for example by making a field optional or changing a segment to an array.

What's next​

  • Secure the endpoint. Put the service behind your API gateway, or add basic authentication to the HTTP service, and set the matching credentials in the SM59 destination.
  • Deploy it. Ship it to WSO2 Cloud, a Docker container, Kubernetes, or a virtual machine.
  • Receive other IDocs. Add outbound parameters for more message types in WE20, such as DEBMAS for customers or ORDERS for purchase orders, and route on the MESTYP field of EDI_DC40.
  • Use the RFC route instead. To also call BAPIs or answer RFC calls from SAP, use the SAP JCo connector, as shown in Call RFC Function Modules and Receive IDocs with SAP S/4HANA Private Cloud.