- SAP Managed Tags
Common queries/issues/know-hows in Business Network for Logistics and their resolution/explanation.
1. Technical IDs in APIs for Carrier Integration
Technical ID in Consumer API for Subcontracting
Technical ID in Consumer API for Order Tracking
- The constant at the end, FC, indicates that the shipper is using Freight Collaboration for Tracking process. Carriers have to make sure that they report events with the exact technical ID for successful reporting.
Technical ID in Consumer API for Booking Confirmation
Technical ID in Consumer API for Order Tracking - Freight Booking
- Note that even though it is a Freight Booking, the technicalID uses Freight Order as the constant in the technicalId.
Location ID in Consumer API for Order Tracking
- The Location Object Type constant can have different values depending on how a shipper configures the location master. Carriers should discuss with their shippers on possible values if relying on this field or if planning to report events with locationID.
- The Location code is shipper-specific code as mastered in their TM system.
Technical ID in Consumer API for Order Tracking - Global Track and Trace Shipment
- The constant that indicates Tracking ID type differs for different tracked processes. The one above is commonly used as it is part of standard GTT model for Shipment Tracked process.
- If a customer uses a custom GTT model, this value could differ.
- The constant at the end, GTT, indicates that the shipper is using Global Track & Trace for the tracking process.
2. Exception occurred while creating or updating the location
Sometimes you see this error when a shipper initiates a tracking request. The error is not specific but does indicate a possible problem.
So, if this error is seen, shippers should check the location master.
3. No matching stop found while reporting events
Carrier reports events via Tracking APIs and all the logs in BNL and CPI show it was successful. However, events are not seen reported against the Freight Order - Execution tab in TM.
On checking srt_moni you will notice some error logs:
As the error indicates, the shipper would have configured mandatory stopIDs for one or more events. This configuration is available in:
- Sometimes shippers fail to convey this requirement to carriers that they have mandated stopIDs. BNL accepts events with or without stopID and reports it as planned or unplanned respectively.
- Carriers can choose to send stopIDs, locationID, or UNLOCODE/IATACode. If the carrier sends locationID or UNLOCODE/IATACode, BNL looks up the stopIDs and delegates it to TM. Usually carriers prefer to use UNLOCODE/IATACode as this is an industry-standard code and they do not have to deal with shipper-specific codes.
4. AccessToken fetch error
One of the scenarios where this error is seen is when a Network Partner is involved and is responding to a Freight Booking confirmation via the API. You will notice that the API call itself gives a 200 OK and also gives a JSON response, but the error will be seen in Manage Integration Logs app as below.
Freight booking API has fields, documentRecipientParty, senderParty, and recipientParty. The values in these fields differ in the consumer and provider calls, that the Network Partner makes. The error occurs when there is a mismatch in the value sin those fields resulting in token issues. To understand the usage, refer this blog.
5. Attachments sent via APIs and application behavior.
General Attachments:
- Can be sent by carriers via their confirmation call or even updates to confirmation call. This can be done until the orders go into execution by the carrier (In certain versions of TM or S/4HANA confirmation updates can be sent even while the order is in execution).
- These attachments can be seen by the shipper in the attachment section against the orders in TM.
- Carriers can also see these attachments in FOFC (Freight Order for Confirmation) app in BNL.
- If any updates to confirmation are made while the order is in execution, the attachments are seen by the carrier in BNL, but they will not get processed by the shipper and cannot be seen in TM (only on certain versions of TM).
Event Attachments:
- These are sent by carriers when reporting events via API.
- If attachments are sent against planned events, these are seen by the carrier in FOFC app.
- Shippers can also see these attachments in the TFM (Track Freight Movement) app in BNL and also in TM in the attachment section of each event. (Not in the general attachment section) (egs: DEPARTURE planned event)
- If attachments are sent against unplanned events, these are seen by the shipper in the TFM app in BNL and also in TM in the attachment section of the event.
- The carrier cannot see the attachment sent for unplanned events in FOFC BNL app.
6. Timezones and event reporting
Scenario | UI/API | FC | GTT |
Location has timeZone and event reported without timeZone (API) | API | UTC reported time is converted to location Timezone | UTC reported time converted to users local timezone. |
Location has no timeZone and event reported without timezone (API) | API | Cannot create Locations without Timezone. | UTC reported time converted to users local timezone. |
Location has TimeZone & event reported with a different timeZone (API) | API | UTC reported time is converted to location Timezone | UTC reported time converted to users local timezone. |
Location has no TimeZone & event reported with a different timeZone (API) | API | Cannot create Locations without Timezone. | UTC reported time converted to users local timezone. |
Location has TimeZone & event reported with a different timeZone (UI) | UI | UTC reported time is converted to location Timezone | The time reported is considered to be for the timezone given and the user sees converted local Time |
Location has no TimeZone & event reported with a different timeZone (UI) | UI | Cannot create Locations without Timezone. | The time reported is considered to be for the timezone given and the user sees converted local Time |
Unplanned Events with timeZone | API | Converts it to the time based on the timeZone sent and shows that timezone as well in the UI. | UTC reported time converted to users local timezone. |
7. invalid_client, Bad Credentials error while reporting events via API
Sometimes when a carrier reports events the below error is seen. The credentials used are also correct.
This happens when the shipper is subscribed to FC but the carrier is reporting event with the technicalId suffixed with GTT or vice versa.
egs: "xri://sap.com/id: LBN#10010005000:BS_SAP:FreightBooking:65000000550:GTT".
To resolve this, the carrier has to make sure the right suffix is sent after discussing with the shipper.
8. FreightOrder with altKey does not exist error
While reporting events, carriers sometimes see this error in the MIL app. The call itself to report events will respond with a 200 OK.
This happens when the Order is not set to "Ready for Transportation Execution" by the shipper. To resolve this, ask the shipper to change the status of the Order, following which events can be reported.
9. JSON parse error: Cannot deserialize value of type com.sap.lbn.trackingservice.domain.input.generic.TransportationMode from String "04": not one of the values accepted for Enum class: [01, 03]
This error is seen in MIL(Manage Integration Logs) app when a carrier is trying to report events via API.
This is because the carrier is reporting the event to FC (Freight Collaboration) with transportMode as "04". As the error suggests, FC only supports reporting events for modes 01(Maritime) and 03(Road) only. However, GTT supports more modes in the reporting API.
10. Carrier Document references reported via tracking are not seen in TM
Carriers while reporting events via API might also want to send some document references, however, due to a limitation in the TM interface-TransportationEventBulkNotification_In these document references cannot be mapped and chance cannot be pushed to TM.
So, if a customer has a use case to receive document references while the order is in execution, they can consider sending an update to confirmation and pass the document references, so that it can be updated in TM against the order.
11. Location ID exists already while configuring Cloud Connector details
BNL allows shippers to configure the technical user and the Cloud Connector Location ID in the System Connections app. This configuration can be reused across tenants if it's within the same Global Account. However if the tenants belong to different Global Accounts, BNL recognizes that the configuration already exists with the same location ID or the User and throws this error.
If it's in the same GA, you don't need to add it again, but rather reuse the config. If its in a different GA, then due to the current limitation that the configuration is not seen in the dialog above, you will have to check if there is any tenant that uses this config and either remove it if unused or configure a different locationID.
12. FC and GTT both for Tracking
There are instances where a customer might use both Freight Collaboration and Global Track and Trace for Tracking depending on the capability of the carrier.
The use case could be that a few carriers prefer to manually report events via the Freight Orders for Reporting app in carrier portal and a few carriers integrate to report events via GTT.
When both are active, by default 2 consumer requests go out to the integrating carrier, one from FC and another from GTT (can be differentiated by the suffix to technicalId). To avoid this, the shipper can deactivate, /SCMTMS/CO_CPX_TORGNTRCKPR_OUT SOAP interface to avoid the FC consumer request from going out. However, they have to make sure the trackingRelevanceIndicator is active so that manual reporting in FC works.
13. Instance Authorization Check Failed in GTT while reporting events
This error is seen when a carrier is reporting events. The call itself would be successful, but the error could be seen in logs. This happens when the carrier LBN ID sent by the carrier does not match the serviceAgenLbnId maintained by the solution owner/shipper. In the particular case above, carrier is reporting at FU level and the FU did not have a serviceAgenLbnId maintained.
14. 108 Missing necessary connectivity configurations or CLOUD_CONNECTOR parameter not found in the Partner Directory for the partner ID (LBN ID)
You might be familiar that customers are recommended to move to Multi-Cloud integration platform. However, we also caution not to delete old, Neo configuration in System Connections app. This error is seen, if a document was exchanged while having Neo config and then the Neo Config was deleted and the Multi-Cloud config was retained. This issue will not be seen on Newly created document objects which are exchanged on the same integration platform config.
15. SOAP messages not generated for SAP TM to BNL scenarios
In some cases, after the setup, you may encounter that SOAP messages not are not getting trigerred and no logs are seen in srt_moni. In this case check for 2 customizations:
1. PPF setting for /SCMTMS/TOR - The right action profile should be maintained.
2. Also make sure the right settings for integration and output options are maintained here for the scenarios that are failing.
Note 1: Before applying any of the above suggestions, make sure to perform a test in your non-production environment as each scenario could be different.
Note 2: This blog will be updated regularly with more Tips & Tricks. If you are interested in receiving updates, make sure to subscribe and bookmark the blog.
| User | Count |
|---|---|
| 2 | |
| 2 | |
| 2 | |
| 2 | |
| 2 | |
| 1 | |
| 1 | |
| 1 | |
| 1 | |
| 1 |
