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. 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

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.

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.

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. When there are changes that are not backwards-compatible, Riege Software will create a new XML schema version and increment the schemaVersion attribute of the eventMessage. 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