Service Description



asrv.aero

Bag Event Notification Service - BEN



Until this note is removed the documentation is a work in progress, and revisions to the documentation will not be tracked.


Namespace: http://www.asrv.aero/webservices/1.0/BENService


Document revisions

Date
Description
Author
yyyy-mm-dd First complete version of the documentation
Ole Nymoen






1. Introduction

1.1. Overview

This service description defines one service with one operations to set baggage oriented data using IATA Baggage XML.

The service is primarily designed to meet the need of airport partners, but availability is the decision of the service provider.

All use cases envisioned by IATA for Baggage XML can be realized using this service. Given that both parties implement the service the data flow can be two way. There are a set of use cases that can be realized using the available operations and Baggage XML payload. Examples:

      • Set baggage data captured when a bag is checked in, manually or at a self service baggage drop (SBD).
      • Set baggage data from a baggage handling system (BHS).
      • Set data when a bag tag is scanned at some location, possibly as part of a baggage reconciliation system (BRS).
      • Setting of IATA BIM (Baggage Information Messages) data.

1.2. Implementation considerations

Any implementation of this service MUST use the WSDL and XSD files provided here: WSDL and XSDs

It is however up to the service provider to decide which data elements to actually update. As clients vary wildly in their capabilities most elements are optional

Any service provider should make available documentation about the actual implementation, including:

      • the address of the service.
      • any limitations in the implementation.
      • any limitations on how often a client can use the service.

1.3. Purpose of this service description

This service description has the following purpose:

      • Describe of service in enough detail for a service provider to implement it.
      • Describe the service so that a client (of this service) developer can use it.
      • Make available the WSDL and XSD files necessary to implement and use the service.
      • Make it possible for relevant people at airports, airlines, handlers and other aviation partners to understand the available functionality and then to decide if to implement/use it or not.

1.4. Intended readership

    • IT architects
    • Developers
    • Business architects
    • Interested parties in the aviation community

2. Service overview

The figure below shows the available operations on the BaggageInformationExchangeService. The operations are described in detail in Service operations.

3. Service operations

3.1. BagEventNotif (transData: TransData, bag: Bag ) :  ResponseStatus 

Sends a notification of one bag event using IATA Baggage XML data.

Parameters: 

  • transData: TransData  - See definition under Data entities. Metadata related to this transaction (event notification). 

  • bag: Bag  - See definition under Data entities. This is the IATA "Bag" element defined as part of "BagXML".

Returns: ResponseStatus  - See definition under Data entities .

 

4. Data entities

4.1. Bag

"Bag" is the IATA BagXML type. It is defined and owned by IATA, and new versions are the responsibility of IATA. To make it more understandable it is mapped to Airport Data Dictionary terms here: Example mapping from IATA BagXML to ADD.

NB! There is no guarantee that the mapping is correct. It is based on the current understanding of BagXML and will most likely change as the understanding gets better and feedback is received.

The BagXML XSD is attached to this page, ref: IATA_BagEventNotif 2017-07-11.xsd

 

4.2. ResponseStatus
statusCode : ResponseStatusCode

ResponseStatusCode indicates if the operation succeeded or failed, and if it failed - why. ResponseStatusText is a textual description of ResponseStatusCode. For all operations the set of response codes must be defined. The actual set is dependent upon the context.

 

  • "OK": Operation succeded.
  • "ERR01":
  • "ERR02":
  • "":
  • "":
  • "ERR99": Other error. "statusText" should describe the error.

 

Must be defined!
statusText : ResponseStatusText A textual description of ResponseStatusCode.

 

4.3. TransData
CorrelationId Identifier that can be used to correlate messages, transactions, log entries etc. The identifier should be unique across all relevant systems. It is the responsibility of the creator of the message/transaction/log entry/...  to guarantee uniqueness. The CorrelationId can for instance be a GUID, or something shorter based on site specific rules.
SourceOrganization Name of the organization/company that created the original data. This will typically be an airline company or an handler. The value set are site specific.
SourceSystem Name of IT system, in the SourceOrganization, that was the source of the data The value set are site specific.

SourceTimestamp

UTC timestamp for when the source was updated. If unknown, use current (UTC) time.

DateTimeUTC
XML dateTime always in UTC. NB! A 'Z' shall always be appended to indicate UTC!

5. XML Usage

5.1. Nil Values in Schema

For any particular data element, there is an important distinction between the following cases:

(a) the element is missing
(b) the element is present but has a 'nil' attribute assigned to it

In the first case, this means that the sender is supplying no information about the element. This would typically be because no information is available, or because there has been no change in the value of the element. A recipient would not be expected to take any action as a result of this. In particular, it would not be expected to clear any existing value.

In the second case, this means that the sender has explicitly cleared the element. As a result of this, a recipient would typically clear any value that it had previously stored for this element.

The following table shows an example sequence of messages, and the expected actions taken by the data recipient. It should be noted, however, that the action is up to the recipient. The message from the sender is a notification, and not a command for the recipient to take action.

Message contents

Expected action by recipient

aircraftRegistration element missing

Does not set or change aircraft registration value

<aircraftRegistration>ABC123</aircraftRegistration>

Sets the value to ABC123

aircraftRegistration element missing

Does not change the value

<aircraftRegistration xs:nil=’true’>

Clears the aircraftRegistration value

Note that the sender should not use blank data elements such as <aircraftRegistration/> or <aircraftRegistration></aircraftRegistration> as these may cause validation errors. For example, if the schema specifies a format or a minimum length for an element, then a zero-length element will be invalid. This problem does not occur if using the nil attribute.

Note - Where a field is defined as mandatory in the schema, it must not contain a nil value.

6. WSDL and XSDs


  • No labels