1. Integration Guide
  2. ShipmentStatus Interface (INE)

ShipmentStatus Interface (INE)

You can also send received ship unit quantities with this interface using the SStatusShipUnit element.

Insert New Shipment Status into Transportation and Global Trade Management Cloud

Required Data

Before you can send ShipmentStatus transmissions to Transportation and Global Trade Management Cloud, you must set up the following:

  • User accounts for service providers in Transportation and Global Trade Management Cloud
  • Shipment Status Codes
  • Shipment Status Reason Codes
  • Shipment Event Groups
  • Shipment Reason Groups
  • Corporations for service providers

What Data Goes into the Transmission?

  1. To ensure that Transportation and Global Trade Management Cloud processes multiple ShipmentStatus transactions in the order you intend, set IsProcessInSequence to Y in the TransmissionHeader.
  2. Identify which object (shipment, shipment group etc.) the status applies to. Set StatusLevel, ShipmentStatusType, ServiceProviderAlias, and ShipmentRefnum or IntSavedQuery.
  3. ShipmentStatusType must be set to one of Shipment or ShipmentGroup. Note that it is case sensitive. The integration logic assumes that it is a ShipmentGroup if the value is not matched to Shipment.
  4. Optionally, identify which equipment the shipment status refers to with SStatusSEquipment element.
  5. Include the time when the event occurred. To be sure that Transportation and Global Trade Management Cloud can interpret the time correctly, include the TimeZoneGID element. Alternatives to doing this is:
    • If you cannot include the TimeZoneGID, Transportation and Global Trade Management Cloud can set the time zone to the time zone of the Location where the event occurred.
    • If you cannot do this either, set the TimeZoneGID to Local. In this case, Transportation and Global Trade Management Cloud saves and displays the event date as entered, ignoring user preferences.
  6. Enter your status information. In some cases, shipments can only have events added to them if they are of a certain status.
  7. Identify at what SSStop (number or location name) the event (shipment status) occurred. The LocationID = Location Reference Number and the LocationRefnumQualifierGID = Location Reference Qualifier in the Location Manager.
  8. If you have a Shipment Agent Type with the Recalculate Estimated Stop Times action, then you must include a RATE_GEO element for Transportation and Global Trade Management Cloud to be able to recalculate your estimated stop times and/or re-drive your shipment. If you omit the RATE_GEO element, Transportation and Global Trade Management Cloud only resets the stop times you provide.
  9. See the ShipmentStatus Diagram in the XML schema to learn which elements are required. To view the diagrams use an XML application like XML Spy.

Send Shipment Status from Transportation and Global Trade Management Cloud

You can forward a received ShipmentStatus transmission to an external system with an agent. See the agent action called SEND SHIPMENT STATUS XML.

Match Events to an Object

You can use one of these methods:

  • If you need the object (shipment or shipment group) to match many reference numbers, use IntSavedQuery.
  • If you need the object to only match one out of a set of reference numbers, use ShipmentRefnums, or ShipmentGroupRefnums.

IntSavedQuery

If you specify the IntSavedQuery element, only that query is applied. You can define a query to search for shipments or shipment groups that shipment status applies to. To do this, set:

  • IntSavedQueryGID to specify which query you want to use. If the query you specify here does not return any results, Transportation and Global Trade Management Cloud generates an error message. No other queries are applied. You must have created this query in Power Data beforehand.
  • IntSavedQueryArg to arguments that can be referred to in the queries. For example, BM=YELLOW-0000007. If you omit this element, your IntSavedQueryGID must point to a query that uses XPath instead.
  • IsMultiMatch to N to forbid multiple records to be returned from the query. If your query happens to return multiple records, Transportation and Global Trade Management Cloud generates an error message.

Refnums

If you omit the IntSavedQuery element, Transportation and Global Trade Management Cloud tries to match your shipment status with:

  • The ShipmentRefnum elements to the shipment_refnum table in the database.
  • The SSEquipment/ EquipmentIdentificationNum element to the S_Equipment.Equipment_Number field in the database
  • The standard integration saved query INT_SHIPMENT_STATUS_GID_1
  • The standard integration saved query INT_SHIPMENT_STATUS_GID_2

You can optionally enforce a rule that a give shipment may have only one shipment reference number with a given qualifier. The update_flag column in the shipment_refnum_qual table indicates if the rule is in effect or not. The valid values for the update_flag are:

  • UPDATE_OK: Only one value is allowed for a give qualifier, the value of which can be modified.
  • UPDATE_NOT_OK: Only one value is allowed for a give qualifier, the value of which cannot be modified.
  • MANY: a given shipment can have multiple values for the same qualifier.

Match Events to a Shipment Stop

For Transportation and Global Trade Management Cloud to match an event to a stop on a shipment, you must include the SSStopSequenceNum element.

Another way of matching event to shipment stop is to include the LocationID where the event occurred and the LocationRefnumQualifierGID in SSStop/SSLocation. This only works if you have enabled this feature in your glog.properties file. As long as Transportation and Global Trade Management Cloud can match your LocationID to a stop number, your shipment status saves as if you had supplied a stop number.

Note: If Transportation and Global Trade Management Cloud cannot match the event to a location, Transportation and Global Trade Management Cloud still saves the information but not for a specific stop and only as informational. You can also have Transportation and Global Trade Management Cloud send you a TransmissionReport if the LocationID is missing altogether (controlled by glog.properties). Transportation and Global Trade Management Cloud also set the time zone for the event to local.

Correspondingly, if the event is not related to a shipment stop to begin with, Transportation and Global Trade Management Cloud saves the event as informational with a local time zone.

A single stop related shipment event can be applied to multiple shipments, regardless of whether their stop numbers or location IDs are the same. This will allow for situations where you want to apply a single shipment stop event to stop 2, but stop 2 of shipment 1 and stop 1 of shipment 2 are both Philadelphia. Stop related events are applied to all the shipments specified in the ShipmentStatus interface. To work successfully, the ShipmentStatus XML must include an IntSavedQuery element that will return two shipments. Logically, this is similar to having specified the ShipmentStatus message multiple times in the Transmission XML.