Actual Shipments

Actual Shipment Workflow Considerations

Changes to an existing shipment using the Actual Shipment interface can be configured to trigger additional business logic by way of agent workflow. When the shipment contains multiple orders or is one of a 'graph' of multiple shipments for different modes or service providers, this workflow can be quite complex and involve modification of other objects. Consequently, although simple modifications CAN be achieved using the Actual Shipment interface, e.g. addition of a new Shipment Reference Number, these cases should instead make use of the Generic Status Update interface.

Structural Changes to Shipment Ship Units in Release 6.0

Prior to Transportation and Global Trade Management Cloud release 6.0, shipment ship units were shared among different shipments/legs of a multi-leg movement. With the multi-tier execution enhancement in release 6.0, this has been changed to not allow sharing of the shipment ship units across multiple shipments. As a result of this change, updates to Shipment Ship Unit details (quantities or attributes) will not automatically be reflected across all legs when a change is made to a shipment ship unit. There are several options for making the appropriate changes to each of the impacted legs:

Update Each Shipment Manually
- Update each of the shipments impacted with a separate ActualShipment xml. Each ActualShipment xml would update the appropriate ship units on that shipment.
Leverage Integration Saved Query
- Leverage the IntSavedQuery within the Shipment/ShipmentHeader and Shipment/SShipUnit to search for the GIDs of the shipment(s) and ship unit(s).
- This option is beneficial when the shipment and/or ship unit GIDs are not all known in the integration layer.
- This option is limited in that any other fields set in the ActualShipment would be applied to all shipments identified by the query. A similar situation exists for the Ship Units on the shipments.
Use Propagation for Ship Unit Changes
- This is useful to propagate the count and quantity changes to upstream or downstream shipments.
- Initiated by setting the Shipment/ShipmentHeader/IntCommand/IntCommandName = "PropagateShipUnitChanges". The propagation option (upstream, downstream, or both) is specified by the IntCommand/IntArg element. Refer to the GLog XML Schema for the specific values to be used.
- This option has limitations on the types of changes it will handle and propagate. Several are listed as follows:
  - Cannot Add SEquipment From Another Shipment: You cannot add a SEquipment that already exists on another shipment to a shipment with the propagation. The SEquipment addition should be done in a separate ActualShipment without the propagation.
  - Cannot Change SEquipment for Existing Ship Unit: If there are more than one SEquipment on a Shipment, you cannot change the SEquipment for an existing Ship Unit with the propagation.
  - Cannot Add New SEquipment for Existing Ship Unit: You cannot add a new SEquipment and assign to an existing Ship Unit with the propagation. The SEquipment changes should be done in a separate ActualShipment without the propagation.
  - Limited Support to Add New SEquipment and New Ship Unit: You can add a new SEquipment and assign to a new Ship Unit. The logic will determine the new SEquipment and persist it before initiating the propagation logic.
  - Can Add a New Ship Unit: The propagation supports adding a new Ship Unit to the Shipment. The Ship Unit must be assigned to an existing SEquipment on the shipment.
  - Cannot Use DR Transaction Code In Ship Unit: You cannot use the DR transaction code in the Ship Unit to dereference the Ship Unit from the Shipment. Since the Ship Units are no longer shared among shipments, you should consider using the D transaction code to delete the ship unit. If there is a need to use the DR transaction code, it should be done in a separate ActualShipment without the propagation.

Note: When migrating to Transportation and Global Trade Management 6.0 from a previous release, review the implementation of the Actual Shipment integration into Transportation and Global Trade Management to determine the impacts of this change.

Updating Parts of a Shipment

When sending an actual shipment to Transportation and Global Trade Management Cloud you often want to update parts of an existing shipment. Generally, the TransactionCode of the shipment (ShipmentHeader/TransactionCode) provides the guiding rule for the child elements. Here are some examples:

Sample Elements

Element	Description
Shipment/ShipUnit/ShipUnitContent	If TransactionCode=IU, a Line Number that does not exist will be added, otherwise updated. You cannot delete an individual line.
Shipment/ShipmentHeader/ShipmentRefnum	If TransactionCode=IU, a new Qualifier Value pair will be added. You can delete (and replace) using the GenericStatusUpdate interface.
ShipmentHeader/Remark	If TransactionCode is IU and the RemarkSequence does not exist, then Transportation and Global Trade Management Cloud will automatically generate a sequence number and add the remark. If TransactionCode is IU and the RemarkSequence does exist, Transportation and Global Trade Management Cloud updates with a new RemarkQualifier and RemarkText. If you supply neither a RemarkSequence nor a RemarkQualifier, Transportation and Global Trade Management Cloud adds the RemarkText as new Remark. You can delete (and replace) using the GenericStatusUpdate interface.

Element

Description

Shipment/ShipUnit/ShipUnitContent

If TransactionCode=IU, a Line Number that does not exist will be added, otherwise updated. You cannot delete an individual line.

Shipment/ShipmentHeader/ShipmentRefnum

If TransactionCode=IU, a new Qualifier Value pair will be added. You can delete (and replace) using the GenericStatusUpdate interface.

ShipmentHeader/Remark

If TransactionCode is IU and the RemarkSequence does not exist, then Transportation and Global Trade Management Cloud will automatically generate a sequence number and add the remark.

If TransactionCode is IU and the RemarkSequence does exist, Transportation and Global Trade Management Cloud updates with a new RemarkQualifier and RemarkText.

If you supply neither a RemarkSequence nor a RemarkQualifier, Transportation and Global Trade Management Cloud adds the RemarkText as new Remark.

You can delete (and replace) using the GenericStatusUpdate interface.

In the Shipment element, if you set the transaction code to RC and set the ReplaceChildren/ManagedChild element to "ShipmentStop", Transportation and Global Trade Management Cloud deletes all shipment stops for that shipment and replaces the deleted shipment stops with the shipment stops from your transmission.

Note: This does not apply to shipment stops marked IsPermanent (same as Permanent check box in Transportation and Global Trade Management Cloud web interface).

In the Shipment element, if you set the transaction code to RC and set the ReplaceChildren/ManagedChild element to ShipmentStopDetail, Transportation and Global Trade Management Cloud replaces the existing ship units with the ship units in your transmission.

Note: This does not apply to existing ShipmentStopDetails marked IsPermanent.

Note: Within ShipmentStopDetail, the removal of the reference to the ShipUnitGID(s) will not remove the S_Ship_Unit from the system. Only the reference to the object is removed.

In the Shipment element, if you set the transaction code to U and the Shipment ID is missing from either the transaction or the database, you will receive an error.

When a new shipment referencing a ship unit is added with missing ship unit data, then the ship unit data is pulled from the database. When a new shipment referencing a ship unit is added with new data, then the ship unit data passed in through integration is used.

Adding Stops

There is no way to insert a new stop to a shipment via shipment actuals unless the new stop has a stop number that does not already exist on the shipment (like adding stop #3 to a 2-stop shipment, or adding stop #2 to a shipment with stops 1 and 99).

Adding Ship Units

An added ship unit should be linked to an order release that is on a shipment (this order release must be planned on the initial shipment) and should be linked to the initial pickup location. If the check box on the Shipment Header indicates "Propagate Updates," the Transportation and Global Trade Management Cloud integration layer will call business logic to add the new ship unit to subsequent stop on the initial shipment and all affected succeeding shipments.

To add a ship unit to a shipment, the following must be done in the ActualShipment XML interface:

Specify a flag to indicate that new ship unit should be applied to downstream shipments.
```
AcutalShipment.Shipment.ShipmentHeader.IntCommand.IntCommandName = "PropagateShipUnitChanges"
```
Indicate that Drop-off stop should be determined for the shipment, but not to propagate the ship unit changes.
```
ActualShipment.ShipmentHeader.IntCommand.IntCommandName = "DetermineShipUnitDropoff"
```

Specify the new ship unit.

ActualShipment.ShipmentHeader.Shipment.ShipUnit.ShipUnitGID =

Specify the Transaction Code (optional).

ActualShipment.ShipmentHeader.Shipment.ShipUnit.TransactionCode = "I" or "IU"

Specify the pickup stop for the ship unit.

ActualShipment.ShipmentHeader.Shipment.ShipmentStop.ShipmentStopDetail.Activity = "P"
ActualShipment.ShipmentHeader.Shipment.ShipmentStop.ShipmentStopDetail.ShipUnitGID = ShipUnit.ShipUnitGID

ShipmentFrom and ShipmentTo Locations can in the Shipment.ShipUnit element are ignored. They will be based on the release.
Assign an SEquipment for the new ShipUnit via one of the following options:
Using the ShipUnit.SequipmentGID element, do the following:
1. Allow integration to assign it by using the following:
```
ActualShipment.ShipmentHeader.Shipment.ShipUnit.SEquipmentGIDQuery.SequipGIDMatchOption = "Any"
```
2. Query the SEquipmentGID using the follwing:
```
ActualShipment.ShipmentHeader.Shipment.ShipUnit.SEquipmentGIDQuery.IntSavedQuery
```
3. Have the business logic assign it by not specifying the element in the ship unit.

Updating Ship Units

The updating of ship units means packaged items can be deleted or added to those ship units. Quantities from existing items can also be changed.

The following options are available via integration:

In the SShipUnit XML interface:

SShipUnit.TransactionCode = "RC"
SShipUnit.ReplaceChildren.ManagedChild = "ShipUnitContent"

In the ActualShipment XML interface:

Shipment.ShipmentHeader.TransactionCode = "RC"
Shipment.ShipmentHeader.ReplaceChildren.ManagedChild = "ShipUnitContent"

In the Shipment.ShipUnit.SShipUnit XML interface:

ActualShipment.Shipment.ShipUnit or ActualShipment.Shipment.SShipUnit
SShipUnit adds the ability to query for the ShipUnitGID if it's not known

Deleting Ship Units

Deleting a ship unit only removes the link between the shipment stop and the ship unit, as well as the link between the ship unit and equipment. The actual ship unit will not be deleted from the database. integration will also attach the ship unit remark, "Ship Unit Not Picked Up" to the ship unit.

A ship unit can be marked for removal from the shipment via the TransactionCode as follows:

ActualShipment.Shipment.ShipUnit.TransactionCode = "DR"

where "DR" corresponds to "Delete Reference." The ship unit will be removed from the shipment, but not deleted from Transportation and Global Trade Management Cloud.

Alternatively, you can delete ship units from a shipment using the IntCommand via integration. You can either delete all the ship units from the shipment, or only those that are marked as non-permanent. When used, the ship unit record, its shipment stop detail record, and any corresponding equipment, is deleted.

Specify the integration command as follows:

To remove all ship units:

<IntCommand>
    <IntCommandName>RemoveAllShipUnits</IntCommandName>
</IntCommand>

To remove only non-permanent ship units (where IsPermanent = 'N'):

<IntCommand>
    <IntCommandName>RemoveNonPermanentShipUnits</IntCommandName>
</IntCommand>

To remove orphaned ship units, use the command below. This specifies that the ship units that have been removed from the shipment via the DR transaction code should be deleted if no other shipments refer to them. Without this command, those ship units are left in the system and can later be added to other shipments.

<IntCommand>
    <IntCommandName>DeleteOrphanedShipUnits</IntCommandName>
</IntCommand>

Alternative Interfaces for Updating Ship Units

For alternatives to using this interface to update ship unit information, see SShipUnit and TransOrder.

Tips for Shipments As Work or SAWs

Element	Description
ShipmentHeader2	In Shipment/ShipmentHeader2, the most important element is ShipmentAsWork and it should almost always be set to "Y". The exception is when: 1. The shipment is new AND 2. There is at least one release associated with the shipment OR the shipment.ShipmentHeader2. AutoGenerateRelease = "Y" To avoid confusion, set the Perspective element to "B." If Perspective is not specified, it will default to "B". All other elements in this branch are completely optional from a schema and business perspective.
ShipmentHeader, use correct rate	In the Shipment/ShipmentHeader, if you can get them, it is good to provide the RateOfferingGID and the RateRecordGID. This helps Transportation and Global Trade Management Cloud use the rate for the service provider that actually took the load. If you can't get information for these elements, the ServiceProviderGID would be the next best thing to use.
sPlannedTimeFixed	If you want to send in old shipments (past dates) and want Transportation and Global Trade Management Cloud to rate with correct rates (pertaining to correct effective/expiration dates), then you may want to use the Shipment/ShipmentStop/ArrivalTime/EventTime/IsPlannedTimeFixed flag set to "Y". You only need to insert the ArrivalTime element at the first stop (only) and that the date here should be the same as the StartDate of the shipment.
SEquipment	Transportation and Global Trade Management Cloud requires at least one SEquipment object. When you insert a new SAW, Transportation and Global Trade Management Cloud creates a default SEquipment if you do not provide one. If there are several ship units, the same (created equipment) is specified for each ship unit. The only thing really required in SEquipment is the SEquipmentGID. To avoid problems later, include the SEquipment element and set the SEquipmentGID to the same value as the ShipmentGID. This makes it easier to identify and manage the SEquipment, if there is ever a need in the future to specify multi-equipment, or update the shipment with additional ship unit information. Note: When you update a SAW with a new ship unit, you must include the SEquipmentGID. Transportation and Global Trade Management Cloud cannot create one for you.
TransOrder	The Shipment/TransOrder element is outbound only so you cannot include it. Any TransOrderHeader info should be specified in the Release/TransOrderHeader element.
Locations	When specifying source and destination locations in the Shipment/Release/ShipFromLocationRef and Shipment/Release/ShipToLocationRef elements, refer to locations already defined in Transportation and Global Trade Management Cloud instead of defining new ones (using Shipment/Release/ShipFromLocationRef/LocationRef/Location). This saves you the effort of providing all the Location elements. To refer to existing locations, use the Shipment/Release/ShipFromLocationRef/LocationRef/LocationGID element.
ShipUnits	Set ShipmentHeader2/AutoGenerateRelease to "Y" to avoid having to populate both Shipment/Release/ShipUnit and Shipment/ShipUnit. Note: Transportation and Global Trade Management Cloud generates an error if AutoGenerateRelease is set to "Y" and you still include the Shipment/Release element.