Implementing S/4HANA Cloud APIs with APIM

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/523efe6d0a9d43beb5d62ad07937578f.html -->
<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 Arvin Wu, 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/523efe6d0a9d43beb5d62ad07937578f.html
-->
<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-call-integration-flow/-->  
    <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

__________

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

Additional resources

How to find an API on SAP S/4HANA OP (EN) | SAP Blogs