S/4HANA – Interfacing to Descartes – Carrier Shipping Label
This blog contains the overview section of the document entitled “S4HANA – Interfacing to Descartes – Carrier Shipping Label.pdS4HANA – Approve Time Events.pdf“. The document describes a detailed solution for interfacing S/4HANA’s Inventory Management (IM) module to Descartes’ Parcel Solution Provider. The purpose of this document is to reduce the effort to build similar interfaces between IM and Descartes. Please download the document to get a detailed description of this interface’s development components.
The Descartes System Group portfolio includes platforms that specialize in logistics and transportation management. The parcel capabilities, of Descartes’ transportation management suite, include the functionality to generate compliant shipping labels and documents. This document describes a detailed solution for interfacing S/4HANA’s Inventory Management (IM) module to Descartes’ Parcel Solution Provider. In IM, the interface is triggered when a handling unit (HU) is packaged in an outbound delivery. This custom interface solution provides the following functionality:
- Generating a carrier shipping label, both domestic & international
- Printing a carrier shipping label
- Updating the HU, in S/4HANA, with the tracking number
- Extensive application logging
- Data validation
The systems involved in this interface are
- S/4HANA ON PREMISE 1709
- SAP Global Trade Services (GTS)
- SAP Process Integration (PI)
- A Middleware Layer
- Descartes’ Parcel Solution Provider
This interface was implemented for a specific set of requirements. Any subsequent implementation will require adaptation. The purpose of this document is to reduce the effort to build similar interfaces between S/4HANA IM and Descartes.
The focus of this document is the S/4HANA ABAP components, required for the interface. These components are:
- Application logging configuration
- Custom mapping tables
- CDS Views
- An output driver program to initiate the interface.
- A custom class to handle:
- Gathering the required data
- Mapping the data
- Calling the proxy class
- Printing the returned label
- Updating S/4HANA with the returned tracking number
The components that are not within the scope of this document include:
- PI, Middleware, and Descartes development
- Configuration of output determination (NACE)
- PI proxy class generation
- GTS development to provide international data
- Zebra printer configuration
This section highlights the main components and flow of the solution, which is a bidirectional, synchronous interface. Data is exchanged between S/4HANA and Descartes in the form of XML messages. SAP PI and the middleware layer are simply “pass through”. This means they handle sending and receiving the messages, but do not impact the message content. The data flow and the systems are described below in Figures 1 and 2.
Figure 1 – Data Flow Diagram
Figure 2 – Data Flow Description
As stated earlier, this interface is triggered from the S/4HANA system, when a handling unit is packaged in an outbound delivery. The trigger mechanism is a custom output type (ZDCR), configured on the handling unit. Figure 3 shows the configuration of the processing routine, for output type ZDCR.
Figure 3 – Processing Routine of Output Type ZDCR
The driver program is a report named “ZFTSI_CARRIER_LABEL_DRIVER”. The main purpose of the driver program is to call the “execute” method of the handler class. When this report is triggered, from output type ZDCR, it is executed in the background. It can also be executed manually using transaction SE38.
Manual execution provides a test feature to validate the gathered request data. The request data is not actually sent to Descartes, when the program is executed in “Test” mode. The request data is just selected and mapped to the output structure. Any errors that occur will be displayed when execution is complete. The data to be sent to Descartes is also displayed. The displayed “Execution Log” is identical to the entries written to the application log. An example of the driver program’s output is shown in Figure 4.
Figure 4 – Driver Program Output (Foreground Processing/Test Mode)
The custom “handler” class, named “ZCL_FTS_CARRIER_LABEL_HANDLER”, is the main component of the interface. It performs the following tasks:
- Selects and maps the request data
- Sends the Descartes request to the PI proxy class
- Receives the Descartes response from the PI proxy class
- Validates the Descartes response
- Extracts and prints the label data
- Updates the HU, in S/4HANA, with the tracking number
- An execution log is written to application log
Descartes requires a substantial amount of data to print a shipping label. To gather the request data, several IM documents and the SAP GTS system were required. Appendix A describes the entire, deep, format of the Descartes request. The included diagrams indicate which fields could be populated and also the field’s source. The following IM document objects were required to construct the request data:
- Handling Unit (HU)
- Purchase Order or Sales Order
When the request data couldn’t be selected from GTS data or standard IM documents, custom tables were used. These tables will be covered in section 2 of this document.
The response, returned from Descartes, contains the shipping label data, the tracking number, and any errors that were encountered. Appendix B describes the entire, deep, format of the Descartes response.
Excellent blog, Jim! Very useful. Thanks for sharing.