Understanding External Planning APIs in SAP Business Network for Logistics

[Saif]

SAP Business Network Logistics - Freight Collaboration solution connects shippers and their logistics partners on a safe network for optimized collaboration and insights, integrated tightly with core business processes for efficiency resilience.

SAP Business Network Logistics, Freight Collaboration solution supports outsourcing the planning process, where the ordering party on Transportation Management (TM) on SAP S/4HANA can create freight units and outsource the planning of freight units to a forwarder.

This is done through REST APIs and the flow is depicted below. More details on each step is also explained in the product help page.

Outsourced Planning process and API exchange

Pre-requisites

• Outsourced planning relies on the SOAP interface TransportationOrderGenericRequest_Out for outbound and TransportationOrderGenericRequest_In for Inbound. So as a pre-requisite, integration between SAP Transportation Management and SAP Business Network for Logistics needs to be established.
• Processing type TOR_TPNOR_FU in PPF Action /SMCMTMS/TOR for application /SCMTMS/TRANSPORTATION  should be active. This is done in : 
  • Cross-Application Components -> Processes and tools for Enterprise Applications -> Reusable objects and functions for BOPF Environment -> PPF adapter for Output Management -> Maintain PPF settings
• EDI Communication Profile is assigned to carrier Business Partner.
• LBN ID is mapped to the carrier Business Partner.
• Purchasing Orgs for both Carrier and Shipper are assigned.
• The shipper and carrier tenants need to be connected
• The carrier needs to configure a webhook in System Connections application.

Configuration in System Connections application - Carrier

• The shipper needs to configure B2B integration connection to the carrier tenant in Configure Partner Connections application.

Configure Partner Connections config - Shipper

Carrier integration is explained in detail here which will help in establishing the B2B integration configuration in Shipper and Carrier tenants.

In this blog we will explore a few use cases and the payload examples both from the consumer and the provider’s side.

Freight Order Planning

 Things to note:

• Maintain the Forwarding agent on the Sales Order header- partners, to carry forward the receiver information into the FU so that the recipient of the FU is determined.

SO-header-partners: Forwarding Agent

•  Maintain the Purchasing Org on the Freight Unit, so that the Freight Unit replication can be triggered.

Purchasing Org on FU to trigger FU replication

Consumer APIs

Use case 1: Single FU, Single FO - POST

Github consumer example json - POST request

Business partners info

Stage info

Document references

Item and Delivery Info

In the Manage Integration logs, you will see the following that indicates the request originating from S/4HANA and delegated to the carrier's configured webhook(External system) through the Network. 

MIL indicating consumer call

Use case 2: FU cancellation - DELETE

Github consumer example - DELETE request 

Consumer payload - DELETE

MIL example for cancellation

Provider APIs

Use case 1: Single FU, Single FO

Github provider example for single FU, single FO creation.

Business Partners info

Locations

Document Flow in TM

MIL logs for provider call

Use case 2: Multiple FU, Single FO (same source and destination)

Consumer request is the same as described in consumer API section. Multiple FUs will have multiple requests going out. The baseTransactionDocumentReference will be the same indicating the FUs are originating form the same base, Sales Order document. In the example typeCode – 114 for Sales Order.

Github provider example for multiple FU and single FO.

Stage & Items assignment

Item details

Use case 3: Multiple FU, Single FO (same source and different destinations)

Consumer request is the same as described in consumer API section. Multiple FUs will have multiple requests going out. The baseTransactionDocumentReference will be the same indicating the FUs are originating form the same base, Sales Order document. In the example typeCode – 114 for Sales Order.

Github provider example for multiple FU, single FO with multi-stops

Location & Item assignment - Stage 1

Location and item assignment - stage 2

Freight Order and item assignments in TM

Use case 4: FU update and FO update

The consumer call whenever FU is updated in TM, is the same as initial creation. The same POST call conveys the updates to the FU. (Refer to consumer use case)

The key here is to send the same ID in externalDocumentId field as the one used for creation of FO. Freight Booking updates also follow the same paradigm.

Github provider example for FO update

Freight Booking Planning

The consumer call is the same as the booking is based on Freight Units. Refer the consumer use case described above. 

Github provider example for Freight Booking creation

Creation of Booking key fields

Booking creation item details

Subscribe for updates and if you have requests for some use cases, feel free to request it in the comment section.

Glossary

Acronym	Description
BNL	Business Network for Logistics
TM	Transportation Management
FO	Freight Order
FU	Freight Unit
FB	Freight Booking