A. AlpineBits® server response outcomes¶
For each data exchange action the server will send a specific response.
The response document type obviously depends on the action. For instance, a FreeRooms response will be a OTA_HotelAvailNotifRS document, whereas a response to a GuestRequests message will be a OTA_ResRetrieveRS document, as listed in section 4 (see the table at the beginning of the section for an overview). The information in the response varies accordingly. E.g. a successful OTA_ResRetrieveRS response contains a ReservationsList element, whereas an OTA_HotelAvailNotifRS obviously cannot contain such an element.
What all responses have in common, however, is that they indicate the success or failure of the data exchange action. AlpineBits® distinguishes four outcomes that are modeled using the three elements provided by OTA in this context: Success, Warnings and Errors. The four outcomes are: success, advisory, warning and error and are explained in the following sections.
Responses with an AlpineBits® success outcome
The client’s request could be completely received, correctly parsed, was deemed syntactically valid and its contents could be processed successfully by the server. All business rules were satisfied. In case of a successful outcome the response contains one empty Success element, no Warnings and no Errors:
The client, in order to safeguard the validity of the transmitted data, should always make sure that the following conditions are true:
-
The XML composed by the client does represent the actual data.
-
All the checks that are indicated in this document as "client responsibility" were performed by the client.
|
The client does not need to take any further action, upon receiving a response with a successful outcome.
Responses with an AlpineBits® advisory outcome
As is the case for the successful outcome, the request could be correctly parsed, was deemed syntactically valid and could be processed successfully in its entirety. All business rules were satisfied.
However, one or more non-fatal problems were detected and the server wishes to let the client know about them.
In this case, the response contains one empty Success element followed by one or more Warning elements with the attribute Type set to 11, meaning "Advisory" according to the "Error Warning Type" (EWT) list in the OTA code list 5.
Each Warning element should contain a human readable text.
Here is an example of FreeRooms response with an advisory outcome. Let’s imagine a server that handles FreeRooms with delta messages but wishes to receive at least one full data set each 48 hours and a client that hasn’t send one in the last 48 hours. The server might then proceed to accept another delta message, but advise the client with the following response:
|
|
A server might or might not implement responses with advisory outcomes.
However, a client must recognize advisory outcomes and visualize or log the human readable text, so that the non-fatal problem can be analyzed and corrected at a later stage. Of course, there is no need to resend the message as the server has already processed it successfully.
Responses with an AlpineBits® warning outcome
The request could be correctly parsed, was deemed syntactically valid, but could not be processed successfully in its entirety, because some business rules were violated.
Some examples for messages that cause a business rule violation are:
-
A message with an unknown HotelCode.
-
A RatePlans message having overlapping Rate elements with the same InvTypeCode attribute.
-
A GuestRequests acknowledgement message with an unknown ID.
In this case, the response contains one empty Success element followed by one or more Warning elements with the attribute Type set to any value allowed by the "Error Warning Type" (EWT) list in the OTA code list 5 other than 11 ("Advisory").
Each Warning element should contain human readable text.
Here is an example of RatePlans response with an warning outcome. Let’s imagine a client that sent rate information concerning dates in the year 2107 because there was a data entry error. While the request was formally correct, the server could not process the request (and thus could not store the information about the rates) because it does not deal with dates in the distant future. So the server will proceed to refuse the request with the following warning response:
|
|
The value 3 for attribute Type stands for "Biz rule" according to the EWT.
Upon receiving an AlpineBits® warning outcome, a client must consider the request as failed in its entirety and must act accordingly. Since the request violated a business rule, there is no use to just try resending it. The client must rather escalate the failure. When run interactively, this means alerting the user. When run in an automatized way, this means alerting someone using appropriate means.
It is important to understand that despite the meaning of the word "warning" in other contexts, an AlpineBits® warning outcome indicates a failed request (due to violation of business rules). It cannot be safely ignored.
Note that AlpineBits® uses the Warnings element also for acknowledgements in the GuestRequests section (see 4.2.3). Those messages are not considered responses (as indicated by the RQ in OTA_NotifReportRQ) and are thus unrelated to the discussion in the present section.
Responses with an AlpineBits® error outcome
The request caused one or more of the following problems:
-
It could not be correctly parsed.
-
It was deemed syntactically invalid.
-
Some error occurred while processing the request.
and therefore the request could not be be processed successfully in its entirety.
In this case, the response contains one or more Error elements with the attribute Type set to 13, meaning "Application error" according to the "Error Warning Type" (EWT) list and the attribute Code set to any value allowed by the "Error Codes" list in the OTA code list 5.
Each Error element should contain a human readable text.
As an example, let’s imagine a client sends a message that requires one of the attributes HotelCode or HotelName to be present, but doesn’t include any of the two. This makes the request invalid and the server must answer with a response indicating the error outcome. Here is an example:
|
Here, the Code 321 stands for "Required field missing" according to the "Error Codes" list.
Upon receiving an AlpineBits® error outcome, a client must consider the request to be failed in its entirety and must act accordingly.
If a client software has reason to assume the problem is temporary and occurred for the first time, it might try to resend the request at a later moment (and bail out after a small number of retries with no success).
The client must then escalate the failure. When run interactively, this means alerting the user. When run in an automated way, this means alerting someone using appropriate means.
Note that a server that receives a request that is not authenticated, has missing or invalid POST parameters, will just respond with an ERROR string as explained in sections 2 and 3. Since at that point no action can be identified the request type and hence the response type is unknown and no exchange of XML documents takes place.
A server could perform additional checks after an outcome success answer (asynchronous checks). In case of inconsistencies with a previous stored state, a server may request a complete sets of data as decribed below.
Responses with a request for complete sets of data
Along with the previous response cases, a server can request the client to send a full data set right after the current communication ends. The requested data may refer to different data from that received in the originating AlpineBits® request (For instance the server may request a full transfer of Availability information upon receiving a request for Rateplans).
In this case, the response contains one or more additional elements whose type depend on the outcome of the request:
-
One or more Warning elements in case of a success, advisory or warning outcome.
-
One or more Error elements in case of an error outcome.
These elements must be empty, must have the attribute Type set to 11 (“Advisory”) and must have the mandatory attribute Status with a value chosen among the following, based on the desired complete data set:
-
Status =
ALPINEBITS_SEND_HANDSHAKEto request the handshake update -
Status =
ALPINEBITS_SEND_FREEROOMSto request the full set of free rooms data -
Status =
ALPINEBITS_SEND_RATEPLANSto request the full set of rate plans data -
Status =
ALPINEBITS_SEND_INVENTORYto request the room configuration
If the server sends more than one of such elements, they must be referred to different data types, meaning that, at the current AlpineBits® version, a server can send up to three different requests: one for each of the above Status values.
Upon receiving a response with one or more of these elements, the client should transmit the corresponding data set as soon as possible in any order (see Tips and best practice).
The server should only send requests for kind of data supported by the client (the logic by which the server keeps track of these information is beyond the scope of this specification). The client must support receiving requests regarding any data, even if it is not directly supported/handled by it. The client is free to ignore request for data it does not handle, but might process such requests as it deems more appropriate, for instance by notifying the user.
Tips and best practice
A server should not request a complete data set in response to a complete set just received regarding the same data type. In this case, a client must ignore the request.
It is a client’s responsibility to keep track of which data was requested by the server in case it receives more than one element requesting a different complete data set.
A server should use this feature with common sense and only when necessary in order to avoid useless heavy-data transfer.
A client should implement a precaution against too frequent complete set requests, for example limiting its number in a given timespan.
Some examples:
The server accepts the message and requests a full synchronization of FreeRooms data:
|
The server sends a warning together with a request for a full synchronization of RatePlans data:
|
The server sends an error together with a request for a full synchronization of Inventory and FreeRooms data:
|