Implementing S/4HANA Cloud APIs with APIM
The current task is to implement the Warehouse Shipping Advice SOAP API using SAP API Management Why so? That way both the integration flows (CPI) and SOAP API calls (APIM) can be managed within the same SAP integration suite framework. Pre-requisites:
Disclaimer:
Good to know:
|
Putting it all together
Step1. [APIM] Let's take a closer look at the this inbound SOAP API namely: WAREHOUSESHIPPINGADVICE_IN
Good to know:
- SAP API Management is integrated with API Business Hub. Each SOAP web service has its own vignette/ curriculum vitae that you can retrieve directly from the API hub through the APIM discovery option.
- The vignette describes the business explorer scope item and the communication scenario this API belongs to.
Step2. [S4HC] Let's create the communication arrangement for the COMM_0440
If you have a communication system with communication users that cover the available authentication methods this will take only a couple of minutes to get done as depicted below:
Good to know:
- This is a mandatory and one-off operation.
- mTLS Client Certificate authentication implies using the communication (technical) user identity to establish a password-less and encrypted communication between a client application and a S4HC backend.
Step3. [APIM] Create a SOAP API or copy an existing one.
Select the API Provider with the x509 keypair and have it linked to the API proxy. As the API Provider already designates the S/4HANA Cloud tenant host the URL below has to be a relative one.
Congrats. You've just created a SOAP API. Before you can start using it you need to adjust the policy and the API endpoint resources in the policy and resource editors.
Step4. [APIM] Let's append the API endpoint to the proxy path.
Step5. [APIM] Let's fix the APIM policy:
Good to know:
- When calling an inbound SOAP API a unique MessageId must be provided in the soap envelope. This requirement is part of Web Services Addressing (WS-Addressing) a transport-neutral mechanism. You may further refer to the following SAP note 2694433 - Error SRT_CORE141 While Executing WebService in SOAP for additional insight into this requirement.
- Technically speaking a MessageId is a GUID identifier.
- An UUID can be generated natively with APIM using a cryptographically strong pseudo random number generator static function, namely
createUuid().
!-- https://help.sap.com/viewer/66d066d903c2473f81ec33acfe2ccdb4/Cloud/en-US/523efe6d0a9d43beb5d62ad0793... -->
<AssignMessage async="false" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>
<AssignVariable>
<Name>sapapim.uuid</Name>
<Template>{createUuid()}</Template>
</AssignVariable>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<AssignTo createNew="false" type="request">request</AssignTo>
</AssignMessage>- For the sake of convenience, I hard-coded a sample soap envelope payload into the AssignMessage policy.
- I borrowed the soap envelope from a fantastic blog by arvinwu, namely Using Postman call SAP S/4HANA Cloud SOAP API and simulate outbound SOAP call integration flow, that I recommend be read.
- Please note the MessageId uuid is part of the xml payload in the policy below.
- If you decided to remove the payload from the policy that you can either assign the MessageId as a header or alternatively as a query parameter.
<!-- This policy can be used to create or modify the standard HTTP request and response messages
https://help.sap.com/viewer/66d066d903c2473f81ec33acfe2ccdb4/Cloud/en-US/523efe6d0a9d43beb5d62ad0793...
-->
<AssignMessage async="false" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>
<Set>
<Headers>
<!-- https://answers.sap.com/questions/13179004/unsupported-encoding-br-getting-error-message-in-a.html -->
<Header name="Accept-Encoding">gzip,deflate</Header>
<Header name="Content-Type">text/xml</Header>
<Header name="Accept">*/*</Header>
<Header name="Application-Interface-Key">saptest0</Header>
<!-- <Header name="MessageId">{sapapim.uuid}</Header> -->
</Headers>
<!-- <QueryParams>
<QueryParam name="MessageId">{sapapim.uuid}</QueryParam>
</QueryParams>
-->
<Payload contentType="text/xml">
<!-- https://blogs.sap.com/2020/12/23/using-postman-call-sap-s-4hana-cloud-soap-api-and-simulate-outbound...;
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dec="http://sap.com/xi/EDI/DECWMS" xmlns:wsa="http://www.w3.org/2005/08/addressing">
<soap:Header>
<wsa:messageId>urn:uuid:{sapapim.uuid}</wsa:messageId>
</soap:Header>
<soap:Body>
<dec:WarehouseShippingAdvice>
<MessageHeader>
<CreationDateTime>2020-12-02T08:38:03Z</CreationDateTime>
</MessageHeader>
<Delivery>
<DeliveryDocument>80000023</DeliveryDocument>
<Party>
<ActionCode>01</ActionCode>
<PartnerFunction>LF</PartnerFunction>
</Party>
<Deadlines>
<ActualGoodsMovementDateTime timeZoneCode="GMTUK" daylightSavingTimeIndicator="false">2020-12-02T05:00:00Z</ActualGoodsMovementDateTime>
</Deadlines>
<DeliveryItem>
<DeliveryDocumentItem>10</DeliveryDocumentItem>
<Material>TG11</Material>
<ActualDeliveryQuantity unitCode="PCE">1</ActualDeliveryQuantity>
<ActualDeliveredQtyInBaseUnit unitCode="PCE">1</ActualDeliveredQtyInBaseUnit>
<DeliveryToBaseQuantityDnmntr>1</DeliveryToBaseQuantityDnmntr>
<DeliveryToBaseQuantityNmrtr>1</DeliveryToBaseQuantityNmrtr>
</DeliveryItem>
</Delivery>
</dec:WarehouseShippingAdvice>
</soap:Body>
</soap:Envelope>
</Payload>
</Set>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<AssignTo createNew="false" type="request">request</AssignTo>
</AssignMessage>
Step5. Sending the shipping advice back to S/4HANA Cloud.....
Good to know:
- The API proxy can be use in any 3rd party client application without the need to worry about the authentication details at all...
- The SOAP API endpoint in the API proxy can be protected with either OAuth or an apiKey via the APIM built-in Product Publication mechanism.
Conclusion
In a nutshell, SAP API Management (APIM) can be seen as a fast track, low code convenience tool making API prototyping and publishing a relatively straightforward task. The security with cloud native applications is paramount. And precisely SAP APIM allows to encapsulate and obfuscate the underlying security mechanism and protect the public API endpoints. And that's not a bargain... |
__________
Appendix
APIM's API Provider
Quovadis_x509 keystore contains the public (a CA-signed x509 certificate) and private key pair.
Moreover, the CA authority used to sign the x509 certificate must be known to the S/4HANA Cloud tenant.
 |  |
S/4HANA Cloud Communication Arrangement
The public key has been uploaded and assigned to the communication user of the communication system used with our communication arrangement, as depicted below:
 |  |
Good to know:
- You may opt to deactivate the password of a communication user to be used with the mTLS client certificate authentication.
__________
Line-up of Supply chain APIs
| API Description | API Technical name | Related scope items |
| Warehouse - Read (A2X) | API_WAREHOUSE | 3W0 |
| Warehouse Inbound Delivery - Read (A2X) | API_WHSE_INBOUND_DELIVERY | 3BR |
| Warehouse Outbound Delivery Order - Read, Update (A2X) | API_ APIs for Warehouse Management | 3BS, 3W0 |
| Warehouse Storage Bin - Read (A2X) | API_WAREHOUSE_STORAGE_BIN | 3BS, 3W0 |
| Warehouse Shipping Advice - Receive from Warehouse(B2B) | WarehouseShippingAdvice_In
| 1ZQ |
| Attachments | API_CV_ATTACHMENT_SRV | 3BR, 3BS |
| Attachments (A2X) | API_CV_ATTACHMENT_SRV | 3BR, 3BS |
| Outbound Delivery (A2X) | API_OUTBOUND_DELIVERY_SRV_0002 | BD9 |
Additional resources
How to find an API on SAP S/4HANA OP (EN) | SAP Blogs
- SAP Managed Tags:
3 Comments
