Customers integrating with SAP Business Network for Logistics (BNL) : Global Track and Trace option (GTT) from their SAP ERP system or Carrier network can face common issues integrating messages in and out of GTT. This blog captures the various integration flows, tools available within the application, and the common connectivity errors that a customer can face when integrating with BNL GTT. This blog is written primarily from the point of view of an IT Admin, Super User, internal technical support, or consulting partner, although it can be helpful for a functional end user.

There are two core data types within GTT that you will see integration activity for

Tracked Process

This is the core business record that you, as a shipper, seek to track and gain insights into what take place in real-time. This is the core data object within GTT and can be any number of the following transaction types from your SAP ERP

• • Shipment
  • Outbound Delivery
  • Inbound Delivery
  • Sales Order
  • Purchase Order
  • Stock Transfer

These integrations often originate from your SAP ERP system and are sent inbound to GTT. Once integrated into GTT, the shipment data is pushed outbound to a Visibility Provider or Carrier via the BNL PutOrderForTracking API

Event

This is the real-world event business data that feeds into your tracked process objects. GTT uses this integration data to deduce what is happening in real-time with the various Tracked Processes linked to the event. These events are often reported directly to a shipment tracked process object, which is then linked upstream to any deliveries or orders within your ERP.

These integrations often originate from a Visibility Provider, such as Project44, or directly from a Carrier’s backend system integrating to the BNL OrderEvents API

To help illustrate the integration flow and how GTT manages Tracked Processes and Events, please refer to the following illustration.

Idoc XML messages are integrated from your SAP ERP into GTT. These are then split out and read into the GTT engine/DB. GTT will then push out a PutOrderForTracking API call to your Visibility Provider or Carrier for that shipment. Then, throughout the life of that shipment, the Visibility Provider or Carrier will integrate OrderEvents via API back into GTT. GTT will then read those events and link them up with the relevant Tracked Processes linked to that shipment.

Tracked Process integration : Common Errors

• Duplicate alternative keys
• Requested route … does not exist.
• String does not match pattern
• Invalid date and time format
• 503 Service Unavailable
• 502 Bad Gateway
• Failed to obtain JDBC Connection

Event Integration : Common Errors

• Alternative Key must match the LBN ID of the current user
• Duplicate Primary Keys

P44 shipment Initialization : Common Errors

• Shipment does not exist for track id
• Origin stop start time must occur before destination stop start
• There is no primary capacity provider for identifier
• Appointment window date time must not be null
• Carrier scac must be provided
• A phone number cannot be less than ten digits
• Shipment destination appointment window must end 9 months into the future
• Location address state should be one of the following
• Invalid identifier alue for AIR_WAYBILL
• No shipment identifier was provided that is support by the capacity provider

• Just getting started, I want to setup basic shipment integration from my SAP ERP to GTT
• Making the climb, I want to expand my use of the application and integrate more advanced integration flows using the standard application code sets
• Reaching the peak, I want to build my own custom application with my own custom integration
• Expanding my visibility, I want to forward GTT data back to my SAP ERP or to other systems
• Expanding my visibility, I want to integrate my GTT tenant with the Ariba Business Network
• Guide for Message Log Administrators, I want to learn more about what tools are available to me as a shipper to analyze errors within my tenant
• Interface Reference Guide, I want to learn more about the specific backend technical details of GTT including Idoc formatting, response code formatting, field properties/metadata, and internal JSON formatting
• Project44 configuration guide, I would like to utilize the SAP partnership with Project44 so that I can integrate event data from P44 into my GTT solution

The GTT application is prebuilt with many tiles/pages/tools available to you that allow you to easily see error messages. You can use these tools to track down a specific ID and see where exactly it might have failed in the process and for what reason.

Check Process and Events Tile

This tile allows you the ability to see the complete technical set of data available for a given tracked process record. You can use this tile to see the full history for any tracked process (be it a shipment, delivery, purchase order, etc..). here, you can see the following relevant information for a given ID.

• Last update user & timestamp
• Carrier mode, identifier data, and VP tracking ID data
• Stops and location data
• Other linked tracked process
• Complete set of Planned and Unplanned event data that have been reported to that Tracked Process (with the ability to drill down into the event itself to see the complete event data set)

View Logs tile

This tile is your primary tool to analyze and view the integration-related activity in and out of the system and where you can see what the system is doing internally when it is processing the Tracked Processes and Events for consumption. You will also see reports/metrics here that outline a summary of how many of your records have failed, how many have been successful, and how many are pending consumption within a given timeframe. You can also utilize the Tracking Error Report for a given timeframe to see an aggregate analysis of common errors that are logged within your own tenant.

Manage Message Logs (MML)

This is the primary integration monitoring tool that is used to analyze the complete set of integration activity within GTT for your tenant. Here, you can see both Tracked Process integrations from your SAP ERP as well as Event integrations from a Visibility Provider or Carrier.

Manage Event Logs (MEL)

This tool, like the MML tool, can be used to see the event-specific integration processing records. This is specific to events only from a Visibility Provider or Carrier.

• Drilling into any record shown here will take you directly to the same Correlation Details page as the MML app (see above)

Manage Integration Logs (MIL)

This app is used to analyze/view the inbound and outbound API traffic between GTT and your Visibility Provider or Carrier.

*For additional information on the tools available to you within the app, please visit the Guide for Message Log Administrators to learn more

Tracked Process Common Errors

Duplicate alternative keys xri://sap.com/id:LBN#11111111:xx1234:FT1_SHIPMENT:1234567 are not allowed. Change the message payload to remove the duplication or contact your Model Administrator.

• This error is thrown when your SAP ERP system is integrating a soap XML file inbound to GTT that contains duplicated tracking reference fields that link that tracked process to another tracked process. The inbound soap XML gets converted into a GTT JSON file for processing, which is read into the GTT engine, throwing this error
• For example, if you integrate an OutboundDelivery from your SAP ERP to BNL GTT that contains duplicated /Envelope/Body/GTTMSG01/IDOC/E1EHPAO/E1EHPTID/TRXCOD (FT1_SHIPMENT) segments with the same shipment tracking ID. You cannot link the same TP to the same Shipment ID twice. You will need to adjust the incoming soap XML from your SAP ERP to not send this duplicate message

404 Not Found: "404 Not Found: Requested route ('lbnplatform-bprepo.cfapps.eu10.hana.ondemand.com') does not exist.<EOL>"

• This generic error could imply platform-level issues within the GTT application. If you see this, please log a customer support case referencing the ID of this error and the error details

Swagger validation failed. #/trackedObjects/1/value: string [/XX12345] does not match pattern ^[^;%\/\\]*$. Correct the message payload or contact your Model Administrator.

• This error is thrown when a special character is integrated inbound from your SAP ERP system in the Soap XML file for this record. In this example, the “/” at the beginning of “/XX12345” throws the error. You can open the JSON payload file for this integration record in GTT and do a CTRL+F for the value called out in the error. Then, you can also do the same in your inbound soap XML payload in GTT to see where this is coming from in your ERP. The first portion of the error will also tell you which data type is having the issue (in this case, the TrackedObjects segment of the JSON file). You will need to remove the special character and resend the transaction.

Invalid date and time format 000000011111111 in field(s) EVT_EXP_DATETIME for tracked process/event (TRXID:1234567). Check the message payload.

• This error is thrown when a date/time value sent in the Soap XML from your ERP contains an improperly formatted date/time string. You can look up the value provided in the app under the payload Tab to see which field from your ERP is sending in the wrong format (in this example, the planned delivery time EVT_EXP_DATETIME). You will need to correct the date/time data in your SAP ERP and resend the transaction.
• Example formatting : 020230920070000

503 Service Unavailable: "503 Service Unavailable: Requested route ('lbnplatform-bprepo.cfapps.eu10.hana.ondemand.com') has no available endpoints.<EOL>"

• This generic error could imply platform-level issues within the GTT application. If you see this, please log a customer support case referencing the ID of this error and the error details

503 Service Unavailable: "{"timestamp":1690669205454,"status":503,"error":"Service Unavailable","path":"/bpr/BusinessPartners"}"

• This generic error could imply platform-level issues within the GTT application. If you see this, please log a customer support case referencing the ID of this error and the error details

502 Bad Gateway: "502 Bad Gateway: Registered endpoint failed to handle the request.<EOL>"

• This generic error could imply platform-level issues within the GTT application. If you see this, please log a customer support case referencing the ID of this error and the error details

Failed to obtain JDBC Connection; nested exception is java.sql.SQLTransientConnectionException: HikariPool-3 - Connection is not available, request timed out after 30000ms.

• This generic error could imply platform-level issues within the GTT application. If you see this, please log a customer support case referencing the ID of this error and the error details

Event Integration Common Errors

For process event, LBN ID LBN#11111111 in Alternative Key must match the LBN ID LBN#2222222 of the current user. Change the message payload to use the correct LBN ID.

• This error is thrown when the JSON.altKey entry in the JSON event file contains an LBN ID that does not match your tenant’s LBN ID. This is often thrown when an event comes in with your test account LBN ID to your Prod LBN Account (with a different LBN ID) and visa versa.
• Example format of the JSON.altKey : xri://sap.com/id:LBN#11111111:xx1234:FT1_SHIPMENT:1234567

Duplicate primary keys {"Time":"2023-08-17T07:00:00Z"} are not allowed. Change the message payload to remove the duplication or contact your Model Administrator.

• This error is thrown when an event is integrated inbound (it can also be thrown if an inbound soap XML for a shipment contains duplicated DocIDs or other reference data) to GTT that has duplicated primary key values. In this example, the Time value of “2023-08-17T07:00:00Z” was sent twice within the same payload for different events. Those two separate events cannot have the same exact timestamp
• This can also be thrown for other primary keys as well
  • DocID : Duplicated /Envelope/Body/GTTMSG01/IDOC/E1EHPAO/E1EHPCP/PARAMNAME (YN_SHP_SHIPPER_REF_VALUE) entries from an inbound Soap XML file (mapped to the shipperRefDocuments.docID JSON entry in GTT)
  • Event_type : duplicated event types integrated in one payload for a shipment. For example, if a payload for an event is sent in with duplicated shipment.Departure event tags. This will be thrown for ETA as well as actual events.

Project 44 shipment initialization common errors

HTTP operation failed invoking https://sap-lbn-connector.na.project44.com/sap-lbn/inbound/order-for-tracking with statusCode: 400 'ERROR | An error occurred while processing a request: error\u003d An error occurred while handling a request: error\u003d UPDATE failed: Shipment does not exist for track id: VVVVVVVVV and technical id: xri://sap.com/id:LBN#11111111:xx1234:FT1_SHIPMENT:1234567:GTT'

• This error is thrown when the ID values provided in your Soap XML messages to LBN GTT are not valid shipment tracking IDs within P44. This will commonly occur if you integrate more than one message into GTT within a short amount of time. LBN will push the first message over to P44, and then if a short while later another message gets pushed over, P44 could still be processing the initial transmission, throwing this error. Please investigate your inbound XML data from your ERP in this instance to check the shipment IDs and the timing of your transmissions.

HTTP operation failed invoking https://na12.api.project44.com/api/v4/ltl/trackedshipments with statusCode: 400 {'httpStatusCode':400,'httpMessage':'Bad Request','errors':[{'severity':'ERROR','message':'Origin stop start time must occur before destination stop start time.','source':'SYSTEM'}],

• This error is thrown when the integrated message from your SAP ERP contains a start date at the Origin location that is after the destination start time provided in that same message. Please adjust the dates in your ERP so that the pickup date/time is before the drop-off date/time

HTTP operation failed invoking https://na12.api.project44.com/api/v4/tl/shipments with statusCode: 400 {'httpStatusCode':400,'httpMessage':'Bad Request','errors':[{'severity':'ERROR','message':'There is no Primary Capacity Provider for identifier P44_EU:VVVVVVVV', }

• This error is thrown when the Capacity Provider information is not valid in P44 and/or not provided when required. This is often thrown in the LTL scenario. Please validate your internal P44 configurations to ensure that you have the carrier configured within P44 and have the Capacity Provider information maintained within your CPC (configure partner connections) tile in BNL

HTTP operation failed invoking https://na12.api.project44.com/api/v4/ltl/trackedshipments with statusCode: 400 {'httpStatusCode':400,'httpMessage':'Bad Request','errors':[{'severity':'ERROR','message':'shipmentStops[1].appointmentWindow.startDateTime, must not be null','diagnostic':'shipmentStops[1].appointmentWindow.startDateTime','source':'SYSTEM'},{'severity':'ERROR','message':'shipmentStops[1].appointmentWindow.endDateTime, must not be null','diagnostic':'shipmentStops[1].appointmentWindow.endDateTime','source':'SYSTEM'}]

• This error is thrown when the integrated message from your SAP ERP does not contains an appointment start or end date time for any of the stops provided in the shipment. You will need to update the shipment in your ERP to ensure that dates are maintained for each stop in the shipment to fix this error.

HTTP operation failed invoking https://sap-lbn-connector.na.project44.com/sap-lbn/inbound/order-for-tracking with statusCode: 400 'ERROR | An error occurred while processing a request: error\u003d An error occurred while handling a request: error\u003d Carrier scac must be provided'

• When initiating a shipment to p44 using SCAC tracking, a SCAC code must be provided in the call to P44. If it is not, this error will be thrown. Please ensure that you are integrating a SCAC code or SAP BNL carrier ID from your SAP ERP in the business partner settings for the carrier. You can then configure your partner connections in SAP BNL accordingly with the same SCAC carrier data to have it integrated over to P44.

HTTP operation failed invoking https://na12.api.project44.com/api/v4/ltl/trackedshipments with statusCode: 400 {'httpStatusCode':400,'httpMessage':'Bad Request','errors':[{'severity':'ERROR','message':'shipmentStops[1].location.contact.phoneNumber, A phone number, including an optional country code for North America but not including the optional extension, cannot be less than ten digits.','diagnostic':'shipmentStops[1].location.contact.phoneNumber','source':'SYSTEM'}],

• This error is thrown when the phone number provided does not match the phone number standards for the country code provided. Please review the contact information in your SAP ERP for the shipment and update any faulty phone numbers to match the standards for that country.

HTTP operation failed invoking https://na12.api.project44.com/api/v4/tl/shipments with statusCode: 400 {'httpStatusCode':400,'httpMessage':'Bad Request','errorMessage':'Error creating truckload shipment.','errors':[{'severity':'ERROR','message':'Shipment destination appointment window must end 9 Months into the future.','source':'SYSTEM'}],

• This error is thrown when you attempt to integrate a shipment to P44 that either starts or ends 9+ months out into the future. P44 is unable to track shipments and/or initiate tracking for shipments until they are within the 9-month window from the current date/time

HTTP operation failed invoking https://na12.api.project44.com/api/v4/ltl/trackedshipments with statusCode: 400 {'httpStatusCode':400,'httpMessage':'Bad Request','errors':[{'severity':'ERROR','message':'shipmentStops[1].location.address, State should be one of: [DIF, AGU, BCN, BCS, CAM, COA, COL, CHP, CHH, DUR, GUA, GRO, HID, JAL, MEX, MIC, MOR, NAY, NLE, OAX, PUE, QUE, ROO, SLP, SIN, SON, TAB, TAM, TLA, VER, YUC, ZAC, AG, BC, BS, CM, CO, CL, CS, CH, DG, GT, GR, HG, JA, EM, MI, MO, NA, NL, OA, PU, QT, QR, SL, SI, SO, TB, TM, TL, VE, YU, ZA]','diagnostic':'shipmentStops[1].location.address','source':'SYSTEM'}],

• This error is thrown when the state / region code sent to P44 is not a valid option based on the country data that was provided alongside it. Please check your SAP ERP to validate the stop location master data and update the State/Region value to be a valid option from the list provided in the error message details.

HTTP operation failed invoking https://sap-lbn-connector.na.project44.com/sap-lbn/inbound/order-for-tracking with statusCode: 500 'ERROR | 400 : \'{\'httpStatusCode\':400,\'httpMessage\':\'Bad Request\',\'errors\':[{\'severity\':\'ERROR\',\'message\':\'Invalid identifier value ABCD12345678 for AIR_WAYBILL\',\'source\':\'SYSTEM\'},{\'severity\':\'ERROR\'

• This error is thrown when p44 is validating the carrier reference data for tracking. This means that the tracking ID provided, as called out in the ABCD… value of the error message, is not a valid tracking ID. Please work with your carrier and/or forwarder to ensure that you have the correct carrier tracking ID populated in your SAP ERP for the shipment.

HTTP operation failed invoking https://na12.api.project44.com/api/v4/ltl/trackedshipments/123454 with statusCode: 400 {'httpStatusCode':400,'httpMessage':'Bad Request','errorMessage':'Could not create shipment for specified capacity provider.','errors':[{'severity':'ERROR','message':'No shipment identifier was provided that is supported by the capacity','source':'SYSTEM'}],

• This error is thrown when the value type that is sent to P44 for tracking with the carrier is not valid and/or not supported by that carrier. For example, if a carrier only supports License Plate tracking and you attempt to send over a container ID, this error can be thrown. Please work with your carrier/forward to ensure that you are aware of their tracking methods and that you have the correct tracking reference data provided for that shipment.

HTTP operation failed invoking https://na12.api.project44.com/api/v4/tl/shipments with statusCode: 400 {'httpStatusCode':400,'httpMessage':'Bad Request','errors':[{'severity':'ERROR','message':'shipmentStops[0], City must be provided for each shipment stop, when providing a complete address.','diagnostic':'shipmentStops[0]','source':'SYSTEM'},{'severity':'ERROR','message':'shipmentStops[0], A company name must be provided for each shipment stop, when providing an address or geoCoordinates.','diagnostic':'shipmentStops[0]','source':'SYSTEM'},{'severity':'ERROR','message':'shipmentStops[0], State must be provided for each shipment stop, when providing a complete address.','diagnostic':'shipmentStops[0]','source':'SYSTEM'},{'severity':'ERROR','message':'shipmentStops[0].location.address.postalCode, may not be empty','diagnostic':'shipmentStops[0].location.address.postalCode','source':'SYSTEM'}],

• This error is thrown when validating the stop address data provided to P44 for your shipment. If you are integrating an address set the full set of data needs to be provided in order for P44 to link up that shipment with a real physical location for tracking. The error will call out the missing fields that you will need to have updated in your SAP ERP on the shipment itself or BP master data.

By now, you should be familiar and comfortable with the tools available to you as an IT Admin, Partner, or end user that helps guide you down a path to analyze and support any integration errors faced within your BNL GTT tenant. You can reference this blog as a resource to reference common errors should you see them.

For additional documentation for SAP BNL GTT, please click here

We look forward to enhancing this knowledge base over time, so please feel free to comment below with any additional errors or suggestions should you see these in your day-to-day work on the GTT application. We will update this blog over time as additional topics and functionalities are released to the application.