Service Description
asrv.aero
Bag Drop Service v 1.0
Namespace: http://www.asrv.aero/webservices/1.0/BagDropService/
The service description is a work in progress, and without version control, as long as this note is here.
1. Service facts
-
Name: BagDropService
-
Operations, see Service operations
- Operations are accessed using GET or POST, as specified per operation.
- Service security: Decided by implementation
-
Standard return codes are described here: HTTP Return Codes and Error Response
2. Introduction
2.1. Overview
This service description defines one service with a set of operations designed to support typical (self-service) bag drop systems. The operations used to communicate with a DCS (departure control system) are based on the IATA CUWS standard.
All flight related data elements are defined by the Airport Data Dictionary.
The service is designed to meet the need of a bag drop system provider.
A set of use cases are described here: Avinor use cases
2.2. Implementation considerations
Any implementation of this service MUST use the XSD files provided here: XSDs
It is however up to the service provider which data elements to support.
Any service provider should make available documentation about the actual implementation, including:
-
- the address of the service.
- any limitations in the implementation.
2.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 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.
-
2.4. Intended readership
-
- IT architects
- Developers
- Business architects
- Interested parties in the aviation community
3. Service operations
3.1. Overview
3.2. HTTP Return Codes and Error Response
3.3. Return codes
The service uses the following HTTP return codes:
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not found
- 500 Internal Server Error
- 503 Service Unavailable
3.4. Error reponse
3.5. Operations
3.5.1. GetConfiguration ( airportIATA : AirportIATA, bagDropUnit : BagDropUnit ) : BagDropConfiguration
Returns any configuration data found for this (self-service) bag drop.
Access method: GET
Parameters:
- airportIATA : AirportIATA
Identifies the airport where the bag drop unit is placed. - bagDropUnit : BagDropUnit
Identifies the actual bag drop unit.
Returns:
- 200 OK and BagDropConfiguration if any configuration data is found.
- 404 Not found if the bag drop unit is unknown.
- See HTTP Return Codes and Error Response for other HTTP return codes.
3.5.2. GetStatus ( )
Returns, as a HTTP return code, the status of the service. 200 OK means that the service is working normally.
Access method: GET
Parameters:
None.
Returns:
- 200 OK if service is running normally. Anything else indicates problems.
- See HTTP Return Codes and Error Response for other HTTP return codes.
3.5.3. GetDcsStatus ( airportIATA : AirportIATA ) : DcsStatus
Returns a list of airlines with DCS support that should be available for this airport (as received by GetConfiguration), and the current availability of each DCS.
Access method: GET
Parameters:
- airportIATA : AirportIATA
Indicates the airport for which DCS status is unknown.
Returns:
- 200 OK and DcsStatus.
- See HTTP Return Codes and Error Response for other HTTP return codes.
3.5.4. GetOperatingCarrier ( TransactionId, AirportIATA, BagDropUnit, BagTagNumber ) : CarrierInformation
Returns carrier information (operating carrier and flight information) if the bag tag is found. This information is typically from a BSM received by the airport. It is necessary to use GetOperatingCarrier as the BagTagIssuerCode from the bag tag might not be for the actual operating carrier (i.e. a marketing flight).
Access method: GET
Parameters:
- transactionId : TransactionId
Identifies the transaction. See Use of TransactionId. - airportIATA : AirportIATA
Identifies the airport where the bag drop unit is placed. - bagDropUnit : BagDropUnit
Identifies the actual bag drop unit. - bagTagNumber : BagTagNumber
The bag tag for which operating carrier information is needed.
Returns:
- 200 OK and CarrierInformation if any carrier information is found.
- 200 OK, explanatory string and CarrierInformation if no carrier information is found. BagDepartureOperatingAirlineIATA will then just be derived from the BagTagNumber (BagTagIssuerCode). Flight information will be missing. This is usually caused by no BSM being received.
- See HTTP Return Codes and Error Response for other HTTP return codes.
3.5.5. LocalVerifyBag ( LocalVerifyBagInput )
Verifies that the bag drop complies to local, the current airport, rules. Does not involve the operating airline's DCS.
Access method: POST
Parameters:
Returns:
- 200 OK if the bag verifies ok locally.
- 400 Bad Request and additional explanatory text if the bag can't be verified.
- 404 Not found if the bag is unknown.
- See HTTP Return Codes and Error Response for other HTTP return codes.
3.5.6. BagNotify ( BagNotifyInput )
Notifies the airport about a successful bag drop, or a failed bag drop.
Access method: POST
Parameters:
Returns:
- 200 OK indicates that the notification was accepted without any problems.
- See HTTP Return Codes and Error Response for other HTTP return codes.
3.5.7. BaggageConformanceIdentify ( TransactionId, AirportIATA, BagDropUnit, BagTagNumber ) : BaggageConformanceIdentifyResponse
To establish whether the scanned bag tag is recognized by the DCS, and return related flight and passenger information
Access method: GET
Parameters:
- transactionId : TransactionId
Identifies the transaction. See Use of TransactionId. - airportIATA : AirportIATA
Identifies the airport where the bag drop unit is placed. - bagDropUnit : BagDropUnit
Identifies the actual bag drop unit. - bagTagNumber : BagTagNumber
The bag tag that is to be identified.
Returns:
- 200 OK and BaggageConformanceIdentifyResponse if the DCS recognizes the bag tag.
- 400 Bad Request and additional explanatory text if there is an error response from the DCS.
- 404 Not found
- See HTTP Return Codes and Error Response for other HTTP return codes.
3.5.8. BaggageConformanceVerify ( BaggageConformanceVerifyInput )
To establish whether the bag is acceptable for carriage for the given location, point in time and bag data supplied (e.g. weight and dimension). The location may dictate which verification rules will be employed. The bag will be activated as part of a verification step if a bag gets injected into the baggage handling system.
The input parameter is mostly a copy of what was returned from BaggageConformanceIdentify, but with some additional details regarding the baggage.
Access method: POST
Parameters:
Returns:
- 200 OK if the DCS accepts the bag.
- 400 Bad Request and additional explanatory text if there is an error response from the DCS.
- See HTTP Return Codes and Error Response for other HTTP return codes.
3.5.9. PassengerConformanceIdentify ( PassengerConformanceIdentifyInput ) : PassengerConformanceIdentifyResponse
To identify the passenger in the host departure control system and return contextual data associated to the location and device type. In the case of self-service bag drop this will be; passenger name, thru-checked flight detail and assigned bag tag numbers. The data returned will outline the passenger, their bags and their weight entitlement per bag. This is only a data retrieval operation that will not apply any applicability or eligibility rules.
Access method: POST
Parameters:
Returns:
- 200 OK and PassengerConformanceIdentifyResponse if the DCS identifies the passenger.
- 400 Bad Request and additional explanatory text if there is an error response from the DCS.
- 404 Not found
- See HTTP Return Codes and Error Response for other HTTP return codes.
3.5.10. PassengerConformanceVerify ( PassengerConformanceVerifyInput )
To verify the passenger is eligible for further transactions at his location through verification against policy.
Access method: POST
Parameters:
Returns:
- 200 OK if the passenger is verified by the DCS.
- 400 Bad Request and additional explanatory text if there is an error response from the DCS.
- 404 Not found
- See HTTP Return Codes and Error Response for other HTTP return codes.
4. Data entities
4.1. BagDropConfiguration
|
|
|
4.2. DcsStatus
|
|
|
4.3. CarrierInformation
|
|
|
4.4. LocalVerifyBagInput
|
|
|
4.5. BagNotifyInput
|
|
|
4.6. BaggageConformanceIdentifyResponse
|
|
|
4.7. BaggageConformanceVerifyInput
|
|
|
4.8. PassengerConformanceIdentifyInput
|
|
|
4.9. PassengerConformanceIdentifyResponse
|
|
|
4.10. PassengerConformanceVerifyInput
|
|
|
4.11. FlightSegment
|
|
|
5. Avinor use cases
6. Overview
This section describes how Avinor plan to use this service from self service bag drop stations. Other airports might use the service in a different way.
7. Use of TransactionId
8. Use cases
8.1. Configuration and status checking
|
|
The sequence diagram shows the typical initial use of the BagDropService by the SBD.
|
8.2. Using BagDropService and only scan the bag tag - no scan of boarding pass
Configuration and regular status checks while the SBD is idle is described here: Configuration and status checking.
BagDropService is responsible for managing all aspects of the DCS communication.
NB! All calls to BagDropService related to one bag delivery process must use the same TransactionId. See also Use of TransactionId.
|
|
|
8.3. Using BagDropService and scan of bag tag and scan of boarding pass
Configuration and regular status checks while the SBD is idle is described here: Configuration and status checking.
BagDropService is responsible for managing all aspects of the DCS communication.
NB! All calls to BagDropService related to one bag delivery process must use the same TransactionId. See also Use of TransactionId.
|
|
|
8.4. Using BagDropService and DCS direct connection
Configuration and regular status checks while the SBD is idle is described here: Configuration and status checking.
It is possible for the SBD to have direct communication with a DCS, including through a broker, and only use the BagDropService for local configuration/information and transaction logging (BagNotify). The sequence diagram below shows the use of BagDropService in this setting.
The SBD is responsible for managing all aspects of the DCS communication.
NB! All calls to BagDropService related to one bag delivery process must use the same TransactionId. See also Use of TransactionId.
|
|
|
9. XSDs
| File | Created | Comment |
|---|---|---|
| 2023-03-17 11:43 |