Service Description



asrv.aero

Baggage Information Exchange Service - BIX



Namespace: http://www.asrv.aero/webservices/1.1/BIXService


Document revisions

Date
Description
Author
2020-03-22First complete version of the documentation
Ole Nymoen






1. Introduction

1.1. Overview

This service description defines one service with a set of operations to set baggage oriented data. All baggage related data elements are defined by the Airport Data Dictionary.

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

There are a set of use cases that can be realized using the operations and data available, for example:

      • Set baggage data captured when a bag is checked in, manually or at a self service baggage drop (SBD). The SetBagCheckinData operation is meant to cover this.
      • Set baggage data from a baggage handling system (BHS). The SetBhsEventData suited for this.
      • Set data when a bag tag is scanned at some location, possibly as part of a baggage reconciliation system (BRS). The SetBagScanData cover this.
      • Data about any baggage event can be set using the SetBagEventData operation.

.The  SetBagEventData operation covers data in all the other operations. The reason to have multiple operations is:

      • It makes it simpler for developers as the data model is restricted to what is (readily) available.
      • It makes for more stable data definitions as the restricted entities for baggage related data are expected to change much less frequently than the all inclusive one.

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. And 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. SetBagCheckInData ( transData: TransData, bagCheckInData: BagCheckInData ): ResponseStatus

Sets data collected when the passenger delivers the bag to an airport/airline/handler for further processing. This will typically be at a manual or self service baggage drop point.

Parameters: 

Returns: ResponseStatus  - See definition under Data entities .

 

3.2. SetBhsEventData ( transData: TransData, bhsEventData: BhsEventData ): ResponseStatus

Sets data associated with a bag scanning or decision event in a BHS (baggage handling system). Typically this will be when

  • the bag tag is actively scanned.
  • the BHS makes a decision about the bag, typically where to route it.

Parameters: 

Returns: ResponseStatus  - See definition under Data entities .

 

3.3. SetBagScanData ( transData: TransData, bagScanData: BagScanData ) : ResponseStatus

Set data associated with the BagTag being scanned, manually or automatically. 

Parameters: 

Returns: ResponseStatus  - See definition under Data entities .

 

3.4. SetBagEventData ( transData: TransData, bagEventData: BagEventData ) : ResponseStatus

Used to set data associated with any bag event.

Parameters: 

Returns: ResponseStatus  - See definition under Data entities.


3.5. SetBagLostData ( transData: TransData, bagLostData: BagLostData ): ResponseStatus

Sets data collected when the bag is reported lost. This operation is somewhat special as part of the data set is open ended, see BagLostData for details. 

Parameters: 

Returns: ResponseStatus  - See definition under Data entities .


3.6. SetBimData ( transData: TransData, bimData: BimData ): ResponseStatus

Sets IATA BIM (BaggageInformation Message) data. BimData contains a string element that is the actual IATA baggage information message (BSM, BUM, BPM, .....).  

Parameters: 

Returns: ResponseStatus  - See definition under Data entities .


3.7. SetFlightBinData ( transData: TransData, flightBinData: FlightBinData ): ResponseStatus

A flight leg oriented operation that sets all bins that are planned to be used, or actually being used, for one flight leg departure.

Parameters: 

Returns: ResponseStatus  - See definition under Data entities .

 

4. Data entities

4.1. BagCheckInData
ADD Term Description

BagTagNumber
The 10 digit bag tag (licence plate) number as defined by IATA. The BagTagNumber is a concatenation of BagTagLeadingDigit, BagTagIssuerCode and BagTagSerialNumber.
BagEventAirportIATA
The AirportIATA code associated with the BagEventLocation where a BagEventCode occurred.
BagEventCode 
Code for an event that happened to a bag (Baggage). Often the event will really be for a BagTag as that is what is scanned, and it is "assumed" that a bag is associated with it. Some events are predefined, see "Legal values" below. Other, system specific, events can be added as needed.
BagEventTimestamp
Timestamp defining when a BagEventCode occurred.
BagEventDescription
Descriptive text for an event (BagEventCode) that happened to a bag (Baggage). The descriptions are system specific, and there can be multiple descriptions for the same BagEventCode.
BagEventLocation
The location where a BagEventCode occurred. The location is identified with a text string that is meaningful in the context it is used. The way/codes to identify a location will typically vary across the different implementations.
BagDepartureFlightId
The FlightId for the flight the bag is supposed to depart on.
BagNextAirportIATA
The AirportIATA code for the next airport the bag should be sent to.
BagFinalAirportIATA
The AirportIATA code for the final airport the bag should be sent to.
BagPhysical See Data entities / BagPhysical for description of entity.
BagPnrCode
The PnrCode associated with a BagTag. This will often be the owner of the bag, but might not be.

 

 

 


4.2. BagEvent
ADD Term Description
BagEventCode  Code for an event that happened to a bag (Baggage). Often the event will really be for a BagTag as that is what is scanned, and it is "assumed" that a bag is associated with it. Some events are predefined, see "Legal values" below. Other, system specific, events can be added as needed.
BagEventTimestamp Timestamp defining when a BagEventCode occurred.
BagEventDescription Descriptive text for an event (BagEventCode) that happened to a bag (Baggage). The descriptions are system specific, and there can be multiple descriptions for the same BagEventCode.
BagEventAirportIATA The AirportIATA code associated with the BagEventLocation where a BagEventCode occurred.
BagEventLocation The location where a BagEventCode occurred. The location is identified with a text string that is meaningful in the context it is used. The way/codes to identify a location will typically vary across the different implementations.
BagEventErrorCode The relevant error code for events that indicate some form of failure, for instance BagRejected, BagSecScreenRejected and BagToBhsBinProblem. Having the error code in a separate element makes it easier to process the different errors. Any description of the error should be in BagEventDescription.

 

 

 


4.3. BagEventData
ADD Term Description
BagTagNumber The 10 digit bag tag (licence plate) number as defined by IATA. The BagTagNumber is a concatenation of BagTagLeadingDigit, BagTagIssuerCode and BagTagSerialNumber.
BagEvent See entity BagEvent for more information.
BagPreviousAirportIATA The AirportIATA code for the airport the bag came from. Not relevant for bags that start their journey on "this" airport.
BagNextAirportIATA The AirportIATA code for the next airport the bag should be sent to.
BagFinalAirportIATA The AirportIATA code for the final airport the bag should be sent to.
BagSegment See entity BagSegment for more information.
BagDepartureFlightId The FlightId for the flight the bag is supposed to depart on.
BagPhysical See entity BagPhysical for more information.
BagPnrCode The PnrCode associated with a BagTag. This will often be the owner of the bag, but might not be.
BEBFT The Bag Estimated BHS Finish Time is the DateTimeUTC when the baggage handling system estimates that the bag will be finished and ready for further handling. This will typically be, for baggage handling systems with sorting, when the bag is placed in a bin. This is an estimate for the  BagEventCode "BagToBhsBin". Always UTC.
BagPlannedBin The bin/location where the bag is planned to be delivered to by the baggage handling system. The location is identified with a text string that is meaningful in the context it is used. The way/codes to identify a location will typically vary across the different implementations. Use the same values as used by BagEventLocation for the BagToBhsBin event.

4.3.1. BagEventData - all entities


4.4. BagImage
ADD Term Description
MediaType Mime media type. Values are not strictly defined.
Image The image of something. Image format would typically be defined by MediaType. Encoding is base64Binary.

 

 

 


4.5. BagLostData
ADD Term Description

BagTagNumber
The 10 digit bag tag (licence plate) number as defined by IATA. The BagTagNumber is a concatenation of BagTagLeadingDigit, BagTagIssuerCode and BagTagSerialNumber.
BagLostIrregularityCode
The BagIrregularityCode associated with the bag being registered as lost.
BagLostAirportIATA
The AirportIATA code where the bag is reported to have been lost.
BagLostDate
The date the bag was lost. Mainly to help make the BagTagNumber unique on the BagLostAirportIATA. Not guaranteed to be correct, best effort value. Always UTC.
BagLostFlightId
The FlightId for the flight where the bag became lost. Not guaranteed to be correct, best effort value.
BagLostAdditionalData

Open ended string containing JSON formatted data. Contains any additional information about the lost bag as name:value pairs. For example:

{
   "CARRIER_CD ": "XX",
   "ROUTING": "PUS/PEK/CPH/OSL"
}

 

 

 


4.6. BagPhysical
ADD Term Description

BagTypeIndicator
Indication if baggage contains special goods.

BagSizeIndicator

 Indication if baggage is unconventional size or weight.
BagWeight The weight (in kilos) of one bag.
BagLength The length (in Centimeter) of one bag.
BagWidth The width (in Centimeter) of one bag.
BagHeight The height (in Centimeter) of one bag.
BagImage Entity


4.7. BagScanData
ADD Term Description

BagTagNumber

 The 10 digit bag tag (licence plate) number as defined by IATA. The BagTagNumber is a concatenation of BagTagLeadingDigit, BagTagIssuerCode and BagTagSerialNumber.
BagEventAirportIATA The AirportIATA code associated with the BagEventLocation where a BagEventCode occurred.
BagEventCode  Code for an event that happened to a bag (Baggage). Often the event will really be for a BagTag as that is what is scanned, and it is "assumed" that a bag is associated with it. Some events are predefined, see "Legal values" below. Other, system specific, events can be added as needed.
BagEventTimestamp Timestamp defining when a BagEventCode occurred.
BagEventDescription Descriptive text for an event (BagEventCode) that happened to a bag (Baggage). The descriptions are system specific, and there can be multiple descriptions for the same BagEventCode.
BagEventLocation The location where a BagEventCode occurred. The location is identified with a text string that is meaningful in the context it is used. The way/codes to identify a location will typically vary across the different implementations.


4.8. BhsEventData
ADD Term Description

BagTagNumber

 The 10 digit bag tag (licence plate) number as defined by IATA. The BagTagNumber is a concatenation of BagTagLeadingDigit, BagTagIssuerCode and BagTagSerialNumber.
BagEventAirportIATA The AirportIATA code associated with the BagEventLocation where a BagEventCode occurred.
BagEventCode  Code for an event that happened to a bag (Baggage). Often the event will really be for a BagTag as that is what is scanned, and it is "assumed" that a bag is associated with it. Some events are predefined, see "Legal values" below. Other, system specific, events can be added as needed.
BagEventTimestamp Timestamp defining when a BagEventCode occurred.
BagEventDescription Descriptive text for an event (BagEventCode) that happened to a bag (Baggage). The descriptions are system specific, and there can be multiple descriptions for the same BagEventCode.
BagEventLocation The location where a BagEventCode occurred. The location is identified with a text string that is meaningful in the context it is used. The way/codes to identify a location will typically vary across the different implementations.
BagDepartureFlightId The FlightId for the flight the bag is supposed to depart on.
BagNextAirportIATA The AirportIATA code for the next airport the bag should be sent to.
BagFinalAirportIATA The AirportIATA code for the final airport the bag should be sent to.
BagSegment See BagSegment for description.
BEBFT The Bag Estimated BHS Finish Time is the DateTimeUTC when the baggage handling system estimates that the bag will be finished and ready for further handling. This will typically be, for baggage handling systems with sorting, when the bag is placed in a bin. This is an estimate for the  BagEventCode "BagToBhsBin". Always UTC.
BagPlannedBin The bin/location where the bag is planned to be delivered to by the baggage handling system. The location is identified with a text string that is meaningful in the context it is used. The way/codes to identify a location will typically vary across the different implementations. Use the same values as used by BagEventLocation for the BagToBhsBin event.


4.9. BimData
ADD Term Description

BagTagNumber
If known, the bag tag associated with the BIM.
The 10 digit bag tag (licence plate) number as defined by IATA. The BagTagNumber is a concatenation of BagTagLeadingDigit, BagTagIssuerCode and BagTagSerialNumber.
BagEventAirportIATA
If known, or relevant, the airport the BIM relates to.
The AirportIATA code associated with the BagEventLocation where a BagEventCode occurred.
BagInfMsg
A standard IATA baggage information message as a text string. Start and end token ("BSM"/ENDBSM, BPM/ENDBPM, ....") included.

 

 

 


4.10. FlightBinData
ADD Term Description
FlightId

The FlightId of the departing flight - for which bin information is provided below.
FlightDepartureDate

If known, the FlightDepartureDate for the departing flight. If not known the bin information is assumed to be for the first upcoming flight with the given FlightId.

The scheduled date (based on UTC) of departure of flight. For flights with multiple legs this is the departure of the first leg. This date must not change once set as it is used to make the FlightIds unique.
DepartureAirportIATA Identifies the airport the flight is departing from, and where the bins are.



FlightBin
Bin A baggage bin that has been allocated to the flight.
BinSegregationCode

Code/string defining which baggage segregation that are associated with the relevant Bin. Codes are system/handler specific.


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

Status codes must be documented by the service implementation.
statusText : ResponseStatusText
A textual description of ResponseStatusCode.


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