Service Description

asrv.aero

DeIce Airside Status Submit Service

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/DeIceAirsideStatusSubmitService

Document revisions

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

1. Introduction
2. Service overview
3. Service operations
- 3.1. SubmitDeIceAirsideStatusData( deIceAirsideStatusDataIn: DeIceAirsideStatusDataIn )
4. Data entities
- 4.1. 97616660
5. Service Return Codes
6. XML Usage
- 6.1. Nil Values in Schema
7. XSD

1. Introduction

1.1. Overview

This service description defines an interface to submit de-ice status data for one airport. All data elements are defined by the Airport Data Dictionary.

The service is primarily designed to meet the need some de-ice related system to submit de-ice data for an airport, to make the data available for other systems.

As it is always the latest de-ice status that is submitted using NIL values is not supported.

The service, as designed, is intended to be accessed using HTTP(S) POST.

1.2. Implementation considerations

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

It is however up to the service provider to decide which data elements to actually update.

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 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 DeIce Airside Status Submit Service. The operations are described in detail in Service operations.

The operations can set the following types of data:

De-ice status data

3. Service operations

3.1. SubmitDeIceAirsideStatusData( deIceAirsideStatusDataIn: DeIceAirsideStatusDataIn )

Submits data about the de-ice status on an airport. This is mostly about any queues at de-ice platforms.

Parameters:

deIceAirsideStatusDataIn: DeIceAirsideStatusDataIn
Contains transaction metadata and the actual de-ice status.

Returns: See Service Return Codes for the used HTTP/S return codes.

4. Data entities

4.1. 97616660

The 97616660 applies to one airport identified by AirportIATA and AirportICAO. All the data elements are airport oriented, and are given for the whole airport - apart from the data below DeIcePlatform. It is only possible to submit data for one de-ice platform at a time as the common situation is for one platform to be used at a time.

Airport Data Dictionary Element	Description
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.
SourceTimestamp	UTC timestamp for when the source was updated. If unknown, use current (UTC) time.

DeIceAirsideStatusData	Airport oriented
AirportIATA	AirportIATA and AirportICAO identifies the airport that the de-ice status data applies to. Until DeIcePlatform the data applies to the whole airport. IATA code which uniquely defines an airport. Where an official IATA code does not exist for an airport, it is the standard to use the ICAO code. Where neither exist, pseudo-codes can be created if required (e.g. oil rigs, grass strips, etc.) The standard codes are defined in the ""Airline Coding Directory"".
AirportICAO	ICAO code which uniquely defines an airport. Where an official ICAO code does not exist for an airport, it is the standard to use the IATA code. Where neither exist, pseudo-codes can be created if required (e.g. oil rigs, grass strips, etc.) The standard codes are defined in ICAO Document 7910.
DeIceConditionCode	The code for the (weather) condition that led to de-icing being requested, and possibly performed. The codes listed under "Legal values" should always be supported. Additional codes can be defined if necessary. Codes defined here are always two digits.
DeIceConditionDescription	A textual description for the relevant DeIceConditionCode.
	De-ice platform oriented The rest of the data set is for the platform given below.
DeIcePlatform	The platform where the de-icing occurred. The names are airport specific. De-icing is typically done either on stand or on a dedicated de-icing platform.
DeIcePlatformQueueCount	The number of aircraft that are in the queue to a particular de-ice platform, given by DeIcePlatform.
DeIceAverageQueueTime	The average time the last X aircraft have been in a de-ice queue. X is system/airport dependent.
DeIceMedianQueueTime	The median time the last X aircraft have been in a de-ice queue. X is system/airport dependent.
DeIceAverageTimePerAircraft	The average time it has taken to de-ice the last X aircraft. X is system/airport dependent.
DeIceMedianTimePerAircraft	The median time it has taken to de-ice the last X aircraft. X is system/airport dependent.
DeIceAircraftOnPlatform	The number of aircraft that are on a given de-ice platform. The platform is identified by DeIcePlatform.
DeIcePlatformLanesOccupied	The number of lanes that are occupied on a given de-ice platform. The platform is identified by DeIcePlatform.
DeIceExpectedNext30	The number of aircraft that is expected to need de-ice in the next 30 minutes.
DeIceExpectedNext60	The number of aircraft that is expected to need de-ice in the next 60 minutes.
DeIceExpectedNext120	The number of aircraft that is expected to need de-ice in the next 120 minutes.
DeIceCompleteLast30	The number of aircraft that finished de-ice in the last 30 minutes.
DeIceCompleteLast60	The number of aircraft that finished de-ice in the last 60 minutes.
DeIceCompleteLast120	The number of aircraft that finished de-ice in the last 120 minutes.

5. Service Return Codes

The service uses standard HTTP return codes - as follows:

200 OK - the request has succeeded.
400 Bad Request - The server will not process the request due to XML-schema validation error.
401 Unauthorized - The request has not been applied because it lacks valid authentication credentials.
403 Forbidden - The access is permanently forbidden and tied to the application logic, such as insufficient rights to a resource.
405 Method Not Allowed - The request method is known by the server but is not supported by the target resource (we only support HTTP POST).
500 Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.
503 Service Unavailable - The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.

6. XML Usage

This service does not support using NIL values to delete data. It is always the latest airside de-ice status that is submitted.

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

Space shortcuts

Page tree