Riege SoftwareTechnical description xml-transportorder

Scope Transportorder Message

Purpose

Interface for Scope to send order data to the haulage contractor when printing a transport order.

For more details see https://service.riege.com/en/knowledge/transport-order-interface.

Background

The transportorder message has been designed to feed external truckers with transportorders generated by Scope.

Transportorders entered in Scope for shipments can be sent out to external truckers using the RSI internal generic transportorder XML format.

The message transmission is triggered by printing the transportorder in Scope.

The specific message format version is provided in the processing Clearing Center.

Message format details

Protocol

The interface supports outgoing direction only, meaning that Scope can send but will not receive those messages.

Structure

Each message contains exactly one transportorder.

Root Element

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<transportOrderMessage xmlns="http://dtd.riege.com/scope/transportorder"
xmlns:to="http://dtd.riege.com/scope/transportorder" schemaVersion="1.15">

The root element transportOrderMessage contains the used version of the provided transportorder. This information is provided by attribute schemaVersion and can be configured in the processing clearing center.

A message consists below the root element transportOrderMessage of following two child elements:

Message Header

<messageHeader messageCreation="YYYY-MM-DDThh:mm:ssZ">
    <sender code="ABC">Alpha Beta Club</sender>
    <recipient code="DEF">Delta Echo Fanclub</recipient>
    <messageId>1234567890</messageId>
    <contact>John Doe</contact>
</messageHeader>

The header contains

By field <messageId> the specific message can be identified.

This id does not identify a specific transportorder.

Message Body

Depending on the transportorder to be transmitted, exactly one of the following two elements is used:

<transportOrderMessage>
    <messageHeader/>
    <transportOrder transportOrderId="ID_123456789" transportOrderType="pickup">
      ...
    </transportOrder>
</transportOrderMessage>

or

<transportOrderMessage>
    <messageHeader/>
    <fclTransportOrder modeOfTransport="road" transportOrderId="ID_123456789" transportOrderType="fclPickup">
        ...
    </fclTransportOrder>
</transportOrderMessage>

Both elements have following mandatory attributes:

Following additional mandatory attribute exists for a the fclTransportOrder:

In case of a transportOrder, the following transportOrderType values are available:

In case of a fclTransportOrder, the transportOrderType values are:

Child Elements

Each of above two types of transportorder has a slightly different list of possible child elements. The main differences for both types are the following ones:

Type transportOrder

Type fclTransportOrder

Child elements of above two types are:

Element specific additional Information

In this section we do not describe all elements of the whole schema, but describe only specifics or differences in case of usage in the different transportorder types transportOrder and fclTransportOrder.

Element goods:

<goods>
    <totals>
        <package packageType="PX">24</package>
        <grossWeight unit="KGM">2400.000</grossWeight>
        <netWeight unit="KGM">2157.000</grossWeight>
        <volume unit="MTQ">7.850</volume>
        <loading unit="MTR">2.150</volume>
    </totals>
    <natureOfGoods>Goods Description ....</natureOfGoods>
    <gid/>
    <gid/>
    <gid/>
    ...
</goods>

The goods element

Each gid element describes one specific cargo item:

<gid>
    <totals>
        ...
    </totals>
    <natureOfGoods>Nature of goods description</natureOfGoods>
    <dims/>
    <labels/>
    <dangerousGoods/>
    <handlingInfo/>
    <stackability/>
    <temperatureRange/>
</gid>

In case of transportorders of type fclTransportOrder, each gid element also holds an optional attribute loadedInto which holds the id of the relating container, which then need also to be defined in the message in the element group containers. By this id the message describes, which cargo item is loaded into which container. If the loadedInto is not defined, the cargo item is interpreted as non-containerized:

<gid  loadedInto="container-id">
    ...
</gid>

Example for the relation between a gid element and a container:

...
<goods>
    ...
    <gid loadedInto="container-id-132456">
        ...
    </gid>
    ...
</goods>
<containers>
    <container containerId="container-id-132456" ...>
        ...
    </container>
    ...
</containers>
...

Element containers and container:

The element containers is only available - as said above - for fclTransportOrders. This element is used to describe all containers of the transportorder and must contain at least one container element.

<containers>
    <container containerId="container-id-132456" number="TEMU0220422" shippersOwned="false">
        <type>22G0</type>
        <sealNumber>YMAC307601</sealNumber>
        <settings/>
        <outOfGauge/>
        <stops/>
    </container>
    <container>
        ...
    </container>
    ...
</containers>

Attribute containerId is mandatory and must be unique among all containers described in the message, since this id is used in the gid elements to describe, which cargo is stuffed into which container. The other two attributes (number and shippersOwned) are optional.

Elements of a single container:

Element stop:

The stop element is used in all transport messages. While a list of stops is defined per container in a message of type fclTransportOrder, messages of type transportOrder have exactly two stops, which are not named stop, but pickupLocation and the deliveryLocation.

Each stop has following structure:

<stop role="pickup">
    <address/>
    <contact/>
    <location/>
    <intervalLower/>
    <intervalUpper/>
    <references/>
    <remarks/>
</stop>

As said above, in case of a message of type transportOrder, elements pickupLocation and deliveryLocation are used (but have the same list of child elements):

<pickupLocation role="pickup">
    <address/>
    ...
</pickupLocation>
<deliveryLocation role="delivery">
  <address/>
  ...
</deliveryLocation>

Besides element address all other elements of a stop element are optional and hold additional information concerning the defined stop address (like who is to contact, UN locode of the address, from when until when to arrive at given address, references and remarks).

Attribute role is mandatory and can have one of following values:

Elements for additional shipment data

Elements to allow transmission of additional shipment data are:

These elements are optional and contain specific information about the relating air, sea or road shipment. All of them may hold information of the main addresses of the shipment:

In addition shipmentDataAir may contain information about the security status of the shipment, the main shipments loading and destination UN locode and the relating flights.

In case of shipmentDataSea the main shipments receipt, loading, destination and release locations (UN locodes), carrier and vessel information and some dates (ets, eta, closing) can be transmitted.

Resources

XML Schema File

Examples

The first four examples show messages with the absolut minimum of data for a

These examples do not make to much sense, since they really provide only the minimum data to please the relating schema. So we continue with examples for “properly filled” transportorders of the different types, before continuing with specific examples on specific areas:

In the following one example is given, where a goods entry (element gid) holds a list of dimensions (available as a list of dims elements):

Following example shows a transportorder with two pdf documents, which can be transferred as base64 encoded strings. These are transferred in the attachment elements:

Now an example with several stop addresses for a container:

Finally an example with dangerous goods cargo:

Disclaimer: This technical description is not part of any contractual agreements.
This description is published by Riege Software under UPL license. Imprint. Privacy.
View project on GitHub