Riege SoftwareTechnical description xml-event

Scope Events Message Format

Purpose

The Scope Events message format is used to send status messages from Scope to third party applications (outbound) or to receive status messages from third party applications into Scope (inbound).

For more details see https://service.riege.com/en/knowledge/event-out-interface and https://service.riege.com/en/knowledge/event-in-interface.

Applications

Status Messages from Scope to Third Party Applications (Outbound)

An event message is generated

The interface does not support cancellation. You may interpret the receipt of an event with the same ID (see below) as an update. The interface does not support acknowledgment or receipt messages externally. Scope does not send binary attachments. Scope uses the uniqueShipmentIdentifier ID type when referring to a shipment, or the customsReferenceNumber ID type when referring to some kind of customs procedure; other references are optional. Status messages are not grouped or pooled in any way.

Status Messages from Third Party Applications to Scope (Inbound)

Third-party applications send event messages to Scope whence they should be processed. Scope stores the event first. In a following step the application tries to resolve the entity it refers to via the entityId element.

If the entity is resolved, the corresponding tracking plan is updated to reflect the event. Binary attachments are stored. If the entity was resolved successfully, the attachment is visible as file in the entity’s documents tab.

Entity Resolution for inbound events

Scope has to resolve the entity an incoming status message is referring to, within an environment. If the entity for an inbound status message cannot be resolved, the message will be rejected. If multiple candidate entities are resolved for one “identifier”, the latest one will be selected as target.

Example:

<eventMessage>
  <event>
    <refs>
      <entityId idType="REF_TYPE_IDENTIFIER">REF_VALUE</entityId>
      ...

Depending upon different entity classes, different reference types might be possible. See below for details about different entity classes with the possible reference type identifiers and reference value descriptions.

Shipment

Status messages may refer to shipments. A shipment may be realized via multiple different files in a Scope environment (e.g. an Export Shipment file at station x is an Import Shipment file at station y). Scope supports the following identifiers for processing inbound shipment-related status messages:

Identifier Description
houseDocumentNumber The number of the House Waybill
transportDocumentNumber The number of the Carrier Waybill. For a consolidation, the status message is processed on Master level.
uniqueShipmentIdentifier The USI is the ID of a logical Scope shipment. This is the preferred identifier.
shipmentNumber The number of the shipment in the recipient branch. Note that this might be a rather unrobust identifier, depending on the forwarder’s organization. Scope will try to resolve the relevant entity using a “best-effort” heuristic.

Booking / Shipping Order

Incoming events can only be processed on bookings if the booking is the result of a data import via the shipping order interface. Additionally, the EDI profile resolution from the event data in Scope is required to determine the same profile which got determined during the shipping order data import.

Reference to determine the booking needs to match one of the reference identifier and value from the shipping order.

Identifier Description
shipmentEDIIdentifier the ID used in the shipping order to identify the booking

Customs Order

Status messages may refer to customs order. Scope supports the following identifiers for processing inbound customs-order-related status messages:

Identifier Description
originalMessageId Message ID of the outgoing Scope Customs Interface message
customsOrderAgentRef Agents reference as entered in the created customs order
shipmentNumber Shipment Number on which the customs order was created

Transport Order

A Transport Order is a physical file in Scope. The following identifiers may be used to refer to a transport order:

Identifier Description
transportOrderObjectIdentifier The technical ID of the transport order file. This is used as an identifier when submitting transport orders via EDI.
transportOrderNumber The human-readable number identifying the transport order in the environment.

Sea-Freight Container

A sea-freight container does not exist as a logical entity in Scope. Instead, each physical file holds its own copy. Scope will require an additional identifier to resolve the correct entity.

Identifier Description
containerNumber Globally unique ID of the sea-freight container, without any spaces, e.g. “RIEZ6666660”

Package

A package is a physical file in Scope. The same package is referred to by export and import files. For packages the default conflict resolution (use the latest entity when multiple candidates exist) is disabled, because the risk of resolving the wrong entity is too high.

Identifier Description
packageLabel Any of the labels captured in Scope

Event Codes

For inbound messages, only scopeEventCode may be used. The following event codes are supported by Scope. Providing an unknown event code in an event message to Scope will result into an error in Scope.

Code Description
ARR Consignment Arrived at Destination
AWR Documentation Arrived at Destination
CAP Customs Declaration Accepted
CCD Customs Cleared
CCE Customs Declaration Received Intervention
CCL Customs Declaration Cancelled
CDR Customs Duties Reassessed
CDS Customs Declaration Sent
CFN Customs Declaration Finished
CGA Guarantee Charged or Discharged
CLD Customs Declaration Released
COK Customs Declaration Registered
CPR Exceptions during customs clearance
CRR Customs Declaration Received Error
CRV Customs Duties / Taxes Reversed
CTA Customs Presentation Step2 Made Applies for Exit Presentation and Transit Arrivals
CTX Customs Duties / Taxes Received
DAK_FR Dakosy Loading Released / Freigabe
DAK_NRL Dakosy Not Released / Vorläufige Z-Nummer
DAK_RLS Dakosy Released / Erlaubnis zum Ausgang
DAK_VS Dakosy Loading Blocked / Verladestopp
DAK_ZAPP Dakosy Z or B Number assigned
DEH Departed at Export Hub
DEP Consignment Departed
DEW Departed at Export Warehouse
DIH Departed at Import Hub
DIH Departed at Import Hub
DIS Discrepancy
DLV Consignment Physically Delivered
DOC Truck arrives at Departure Airline Warehouse
FCL_BARGE_IN Full Container Loaded on Barge
FCL_BARGE_OUT Full Container Offloaded off Barge
FCL_DEPOT_IN Empty Container Arrived at Depot
FCL_DEPOT_OUT Empty Container Departed at Depot
FCL_INLAND_IN Full Container Arrived at Inland Container Yard
FCL_INLAND_OUT Full Container Departed at Inland Container Yard
FCL_LOAD_IN Empty Container Arrived at Loading Address
FCL_LOAD_OUT Full Container Departed at Loading Address
FCL_TERMINAL_IN Full Container Delivered at Terminal
FCL_TERMINAL_OUT Full Container Picked Up at Terminal
FCL_TRAIN_IN Full Container Loaded on Train
FCL_TRAIN_OUT Full Container Offloaded off Train
FCL_TRUCK_IN Full Container Loaded on Truck
FCL_TRUCK_OUT Full Container Offloaded off Truck
FCL_UNLOAD_IN Full Container Arrived at Unloading Address
FCL_UNLOAD_OUT Container Departed at Unloading Address
FOH Freight On Hand
NFD Consignee Notified
OFD Out for Delivery
POD Proof of Delivery
PUP Pick Up at Shippers Location
RCF Consignment Physically Received
RCS Freight Received from Shipper
REH Received at Export Hub
REW Received at Export Warehouse
RIH Received at Import Hub
RIW Received at Import Warehouse
TO_ACK Transport Order Accepted
TO_REJ Transport Order Rejected
WH_IN Received at Warehouse
WH_OUT Departed at Warehouse

Document Types

Attachments contain a <documentType> Element. It denotes the type of document from a business perspective rather than a technical one. If not mutually agreed otherwise between parties exchanging the documents it is recommended to use UN/EDIFACT 1001 document name codes in format ‘unedifact-nn(n)’. See (https://service.unece.org/trade/untdid/d16a/tred/tred1001.htm) for reference.

UN/EDIFACT documents known by Scope 23.8ff:

Additional documentTypes known by Scope:

Deprecated (use unedifact-nnn instead):

Additional attributes for inbound events

For forwarding-related entities, additional attributes on inbound events are supported.

Package totals

For events related to physical movements, e.g. warehouse take-in or proof of delivery, Scope interprets the <packages> element and will evaluate the values in a shipment’s tracking plan, for example:

<event>
    ...
    <packages>
        <pieces>42</pieces>
        <weight unit="KGM">1337.0</weight>
    </packages>
</event>

Reference numbers

For some Scope entities (mostly shipments of all kinds), reference numbers included in event messages are stored on the resolved entity. Note that this only works for non-system reference types, i.e. you may not overwrite a House Waybill number or shipment number of a shipment using an event message. This mechanism is intended for interactions with other parties which supply their own reference numbers for an event, e.g. a warehouse take-in reference number or a tour number.

Reference numbers of the same type are not replaced. Instead, any newly detected, unique reference number is added to the entity.

The following reference qualifiers are supported:

The technical link will be established on a per-project basis. Riege Software provides different communication services. For this interface, we recommend a push-based protocol (both directions). When the technical link necessitates the use of files, Scope will produce file names according to the following format: “scope_event_” + timestamp + “_” + messageId + “.xml”.

Versioning

Riege Software tries to keep schema changes backwards-compatible. From version 2.0.0 on we are using semantic versioning, so each version consists of a MAJOR, MINOR and PATCH level. This is done to keep the version of the library (and repository) in sync with the XML Schema. Changes to the XSD will now require a new XML schema version and incrementing of the schemaVersion attribute of the eventMessage at the appropriate level:

    MAJOR version when you make incompatible API changes
    MINOR version when you add functionality in a backward compatible manner
    PATCH version when you make backward compatible bug fixes

The XML namespace will not be changed, it will always be http://dtd.riege.com/scope/event.

Resources

XML Schema File

Current XSD Schema File

XSD schema files of deprecated versions are available via http://dtd.riege.com/scope/events/scope_event-version.xsd)

Examples

Generic

Customs-Specific

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