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.

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.

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):

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