When pushing entities into CargoWise through its CargoWise eAdaptor HTTP+XML interface it is often desirable to check if an entity already exists before proceeding. Without having the internal CargoWise entity key present this is not possible to do through the eAdaptor interface for most entities, but there is a workaround if some minimal details are available which include an external key or id.

The following example demonstrates such a workaround using CargoWise Warehouse Orders:

Minimal Entity Stub

The first step is to carefully craft a stub of an entity that will be posted to the eAdaptor interface. The purpose of this minimal entity stub is to obtain an CargoWise entity key for an existing entity if it already exists or generate the stub of a new entity to populate further with the full entity details.

For example:

<?xml version="1.0" encoding="utf-8"?>
<UniversalShipment xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
    <Shipment>
        <DataContext>
            <DataTargetCollection>
                <DataTarget>
                    <Type>WarehouseOrder</Type>
                </DataTarget>
            </DataTargetCollection>
        </DataContext>
        <Order>
            <OrderNumber>TEST-SO-00012345</OrderNumber>
            <Warehouse>
                <Code>LON</Code>
            </Warehouse>
        </Order>
        <OrganizationAddressCollection>
            <OrganizationAddress>
                <AddressType>ConsignorDocumentaryAddress</AddressType>
                <OrganizationCode>TESTERCLT</OrganizationCode>
            </OrganizationAddress>
        </OrganizationAddressCollection>
    </Shipment>
</UniversalShipment>

Care should be taken not to include any details that may have been subsequently updated in CargoWise by staff, else these details will be overwritten. If serialising an object to XML to create the stub, be sure to make any other non-stub properties present nullable else default values may accidentally be passed in as part of the entity stub. For Warehouse Orders I initially had a non-nullable int TotalUnits property on the Order part of the request that was overwriting the true value with 0's as it wasn't nullable originally.

Obtain the CargoWise Entity Key

Posting the entity stub to the eAdaptor interface will result in a response being returned that includes the internal CargoWise entity key for either an existing entity that matches the stub details or a newly created entity if none matched and the stub resulted in a new entity being created.

In the response snippet below the entity key returned is W00000123:

<?xml version="1.0" encoding="utf-8"?>
<UniversalResponse version="1.1" xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
    <Status>PRS</Status>
    <Data>
        <UniversalEvent xmlns="http://www.cargowise.com/Schemas/Universal/2011/11" version="1.1">
            <Event>
                <DataContext>
                    <DataSourceCollection>
                        <DataSource>
                            <Type>WarehouseOrder</Type>
                            <Key>W00000123</Key>
                        </DataSource>
                    </DataSourceCollection>
    ...

Request the Full Entity

Use the obtained CargoWise entity key to request the full entity details.

For Warehouse Orders the following XML request can be sent:

<?xml version="1.0" encoding="utf-8"?>
<UniversalShipmentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="1.1" xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
    <ShipmentRequest>
        <DataContext>
            <DataTargetCollection>
                <DataTarget>
                    <Type>WarehouseOrder</Type>
                    <Key>W00000123</Key>
                </DataTarget>
            </DataTargetCollection>
        </DataContext>
    </ShipmentRequest>
</UniversalShipmentRequest>

Check to see if it's New

If the full entity returned meets the following conditions, it can be considered a new entity that didn't already exist in CargoWise:

  1. Only the stub details originally provided are present as entity properties, and CargoWise default values for any other entity properties.
  2. The entity MilestoneCollection only contains a single item with an EventCode of "WHE" with sibling Description of "Entered". This indicates no further edits have taken place apart from the initial entity stub creation.

Perform Additional Logic

In the scenario I was coding for, if the entity already existed in CargoWise further updates would be skipped as it had already previously been imported. If it was indeed a new entity creation, we'd go on to update the entity with the full details to be imported as we're confident we won't be overwriting any staff made edits.