Technical description xml-ocean-event

Ocean-Event-Message

Rationale

The Ocean Event Message has been designed to allow the processing of incoming container-level or shipment-level tracking information from any external event-provider.

The message processing supports full-featured container level tracking. Meaning that the message will be processed in the same way as messages originating from a Riege partner integration.

Limitations

The set of events (event codes) supported by this message is limited by intention. Please reach out to service@riege.com if you think that an important type of event might be missing.

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

Version History

Date	Version	Changes
2025-MAY-23	1.1	Added support for LCL events
2024-MAY-17	1.0	Initial Version

Message Content

Root Element

<?xml version="1.0" encoding="UTF-8"?>
<oceanEventMessage xmlns="http://dtd.riege.com/ocean-event/1.1" schemaVersion="1.1"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="http://dtd.riege.com/ocean-event/1.0 https://dtd.riege.com/scope/ocean-event/ocean-event-1.1.xsd">

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

<header>
  <sender>SENDERCODE</sender>
  <receiver>RECEIVERCODE</receiver>
  <messageId>ID1234567890</messageId>
  <messageTime>2023-02-05T12:01:00Z</messageTime>
</header>

The header contains

the <sender>
and <receiver> codes,
a unique <messageId>
and the message generation timestamp as <messageTime>.

All fields are mandatory.

FCL / LCL Event

The message allows to contain multiple events of type FCL and / or LCL in any order.

FCL events do populate container details (number is mandatory, ISO code type is optional)
LCL must not provide any container details

Attributes

The following attributes to the <lclEvent> exist:

code (mandatory)
scac (mandatory)

<lclEvent code="EMPTY_PICKUP" scac="MAEU"/>

The <fclEvent> contains these attributes:

code (mandatory)
scac (mandatory)
containerNumber (mandatory)
iso6346 to indicate the ISO Container-Type (optional)

<fclEvent code="EMPTY_PICKUP" scac="MAEU"
          containerNumber="MAEU1234567" iso6346="40OT"/>

Event Codes

The event code has to be one of

EMPTY_PICKUP
POSITIONING
PICKUP
TERMINAL_IN
TERMINAL_OUT
ONBOARD
DEPARTURE
ARRIVAL
DISCHARGE
DELIVERY
EMPTY_RETURN
STUFFED
STRIPPED

Child Elements

The <fclEvent> or <lclEvent> element contains the following child elements:

<creationTime>: Time when the event has been created (mandatory). It can but does not have to be identical to the <messageTime> from the <header>
<eventTime type="actual/estimate">: Actual or estimated time of the event (mandatory).
Use type="actual" for events that have already occurred
or type="estimate" to transmit a new estimate date and time for a future event.
<eventLocation unlocode="DEHAM"/>: Event location as UNLOCode (mandatory)
<carrierReferences>: Needs to contain at least one (or both) of these carrier references:
<bl>: Ocean BL Number
<booking>: Carrier Booking Number

<fclEvent code="EMPTY_PICKUP" containerNumber="MAEU1234567"
          scac="MAEU" iso6346="40OT">
    <creationTime>2023-02-05T12:01:00Z</creationTime>
    <eventTime type="actual">2023-02-05T12:01:00+01:00</eventTime>
    <eventLocation unlocode="DEHAM"/>
    <carrierReferences>
        <bl>123456</bl>
        <booking>123456</booking>
    </carrierReferences>
</fclEvent>

Resources

XML Schema File

XSD Schema File

Examples

scope_event.xml

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