Technical description xml-prealert

Scope Prealert-Message

Purpose

The Scope Prealert message format is used to exchange pre-alert data with amongst forwarder agents, from Scope to third party applications (outbound) as well as receiving from third party applications into Scope (inbound).

For more details see https://service.riege.com/en/knowledge/pre-alert-interface-outbound and https://service.riege.com/en/knowledge/pre-alert-interface-inbound.

Background

The prealert message has been designed to allow the processing of shipment notifications sent by the shipper or the export agent to the recipient or import agent before the arrival of a shipment.

The interface is supported in both directions:

• from Scope to an external recipient
• from an external recipient to Scope
• from a Scope system to another Scope system

This documentation will provide examples for several schema versions, but will only describe the latest version.

It is highly recommended to use the latest schema version.

Prealert XML Root Element

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<prealertMessage xmlns="http://dtd.riege.com/scope/prealert"  schemaVersion="1.6"/>

It is important to provide the xmlns and the schemaVersion inside the root element <prealertMessage>.

Header

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

The header contains

• mandatory message generation timestamp inside <messageHeader>
• mandatory <sender> and <receiver> codes with optional names
• mandatory unique <messageId>
• optional <contact>

Prealert Message Types

There are currently 4 Types of prealert messages

• <prealertMasterAir>
• <prealertAir>
• <prealertMasterSea>
• <prealertSea>

At least one of these nodes is required, each node has unbounded occurrences.

Message Structure

Air Shipment

One or multiple Air Shipments can be transmitted using one of these types:

• house
• direct
• backToBack

The structure is like this:

<prealertMessage>
    <messageHeader/>
    <prealertAir shipmentType="house|direct|backToBack"/>
    ...
</prealertMessage>

Sea Shipment

One or multiple Sea Shipments can be transmitted using one of these types:

• house
• single

The structure is like this:

<prealertMessage>
    <messageHeader/>
    <prealertSea shipmentType="house|single"/>
    ...
</prealertMessage>

Prealert Master Air

A <prealertMasterAir> with houses is transmitted using the following structure:

<prealertMessage>
    <messageHeader/>
    <prealertMasterAir>
        <manifest>
            <houseShipmentId>HOUSE-ID-1</houseShipmentId>
            <houseShipmentId>HOUSE-ID-2</houseShipmentId>
            <houseShipmentId>HOUSE-ID-3</houseShipmentId>
        </manifest>
    </prealertMasterAir>
    <prealertAir shipmentType="house"/>
    <prealertAir shipmentType="house"/>
    <prealertAir shipmentType="house"/>
    ...
</prealertMessage>

The manifest section needs to list all houses assigned to the master like this

Prealert Master Sea

A <prealertMasterSea> with houses is transmitted using the following structure:

<prealertMessage>
    <messageHeader/>
    <prealertMasterSea>
        <manifest>
            <houseShipmentId>HOUSE-ID-1</houseShipmentId>
            <houseShipmentId>HOUSE-ID-2</houseShipmentId>
            <houseShipmentId>HOUSE-ID-3</houseShipmentId>
        </manifest>
    </prealertMasterSea>
    <prealertSea shipmentType="house"/>
    <prealertSea shipmentType="house"/>
    <prealertSea shipmentType="house"/>
    ...
</prealertMessage>

The manifest section needs to list all houses assigned to the master.

Data Elements

Each prealert contains the following data elements:

• <parties> (mandatory)
• <refs> (mandatory)
• <placeOfReceipt>(mandatory)
• <placeOfDelivery> (mandatory)
• <incoterm> (optional)
• <service> (optional)
• <movementScope> (optional)
• <flights> (optional, Air only)
• <voyages> (optional, Sea only)
• <totals> (optional)
• <gids> (optional)
• <containers> (optional, Sea only)
• <charges> (optional)
• <cpa> (optional, Air only)
• <moas> (optional)
• <remarks> (optional)
• <attachment> (optional)

Data Elements

Parties

<parties> must contain at least

• <exportAgent>
• <importAgent> with addresses

Address

<address addressId=""> must contain attributes:

• <name1>
• <street1>
• <country code=""> Both examples below are considered valid

<parties>
    <exportAgent addressId="ADDRESS_ID">
        <name1/>
        <street1/>
        <city zip="12345">Berlin</city>
        <country code="DE">Germany</country>
    </exportAgent>
    <importAgent  addressId="ADDRESS_ID">
        <name1/>
        <street1/>
        <city/>
        <country code="DE"/>
    </importAgent>
</parties>

References

<refs> must at least contain the unique <shipmentID> but can contain one or multiple of:

• AWB: AWB Number
• OBL: OBL Number
• SRN: Shipment Number
• CU: Shipper Reference
• AAO: Consignee Reference
• BN: Booking Reference

<refs>
    <shipmentId>XXX</shipmentId>
    <ref qual="AWB">XXX</ref>
    <ref qual="CU">XXX</ref>
    <ref qual="CU">XXX</ref>
</refs>

Place of Receipt / Delivery

Air

<placeOfReceipt iataCode=""> and <placeOfDelivery iataCode=""> both require the iataCode

Sea

<placeOfReceipt unlocode=""> and <placeOfDelivery unlocode=""> both require the unlocode

Seafreight GID

Seafreight goods need to be linked to a possibly existing container like this

<gids>
    <gid loadedInto="MAEU1234567">
        <pieces packageType="PK">100</pieces>
        <grossWeight unit="KGM">12900.00</grossWeight>
        <natureOfGoods>Goods Description</natureOfGoods>
    </gid>
    <gid loadedInto="MAEU1234567">
        <pieces packageType="PK">80</pieces>
        <grossWeight unit="KGM">2700.00</grossWeight>
        <natureOfGoods>Goods Description</natureOfGoods>
    </gid>
</gids>

The corresponding container(s) need to be provided like this:

<containers>
    <container shippersOwned="false" humidification="false">
        <containerNumber>MAEU1234567</containerNumber>
        <containerType>22G0</containerType>
        <tareWeight unit="KGM">1900.000</tareWeight>
    </container>
</containers>

Seafreight Master GID

Goods inside the master need to be linked to the corresponding house like this

<gids>
    <gid house="HOUSE-ID-1">
        <pieces packageType="PX">1</pieces>
        <grossWeight unit="KGM">1300.00</grossWeight>
        <natureOfGoods>spare Parts</natureOfGoods>
    </gid>
    <gid house="HOUSE-ID-1">
        <pieces packageType="PK">10</pieces>
        <grossWeight unit="KGM">4003.00</grossWeight>
        <volume unit="MTQ">12.000</volume>
        <natureOfGoods>other spare parts</natureOfGoods>
    </gid>
    <gid house="HOUSE-ID-2">
        <pieces packageType="PX">10</pieces>
        <grossWeight unit="KGM">13920.00</grossWeight>
        <volume unit="MTQ">25.000</volume>
        <natureOfGoods>parts</natureOfGoods>
    </gid>
</gids>

Resources

XML Schema File

XSD Schema File 1.0
XSD Schema File 1.1
XSD Schema File 1.2
XSD Schema File 1.3
XSD Schema File 1.4
XSD Schema File 1.5
XSD Schema File 1.6

Examples

prealert Air v1.6
prealert Master Air v1.6
prealert Sea v1.6
prealert Master Sea v1.6
——————————————————————–

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