4.1. FreeRooms: room availability notifications

The parameter request must contains an OTA_HotelAvailNotifRQ document.

Clients and servers typically wish to exchange only delta information about room availabilities in order to keep the total amount of data to be processed in check.

However, for simplicity let us first consider a request where the client transmits the complete availability information as might be the case for a first synchronization.

Consider the outer part of the example document:

An OTA_HotelAvailNotifRQ may contain just one AvailStatusMessages (note the plural) element, hence at most one hotel can be dealt with in a single request.

The UniqueID element with attribute Instance = CompleteSet and Type = 16 indicates that this message contains the complete information (as entered by the user). When receiving such a request, a server must remove all information about any availability it might have on record regarding the given hotel.

The attribute ID is needed for compatibility with OTA, the value is ignored by AlpineBits^®.

A client might want to let a server know its availability data should be purged based on internal business rules. An example might be availability data that is considered stale, because it hasn’t been updated by the user for some time. The client then should send a request using an UniqueID element with attribute Instance = CompleteSet and Type = 35. A server must accept this value (without returning an error or warning) and could make use of this hint and keep the availability data it has on record marking it as purged. Otherwise such a message should be considered equivalent to the one with Type = 16.

If the UniqueID element is missing, the message contains delta information. In that case the server updates only the information that is contained in the message without touching the other information that it has on record.

AlpineBits^® requires the attributes HotelCode or HotelName to be present (and match information in the server’s database). The fictitious hotel in the example is the "Frangart Inn" with code "123". Specifying both — code and name — is redundant, but allowed, as long as both are consistent.

AlpineBits^® requires a match of HotelCode, HotelName to be case sensitive.

Second, consider the inner part of the example that contains AvailStatusMessage (note the singular) elements for three different rooms.

Let’s start with the availabilities for room 101S.

The use of the InvCode attribute tells us we’re dealing with a specific room (101S) that belongs to the room category given by the InvTypeCode (double).

Alternatively, using a InvTypeCode without a InvCode attribute would indicate that the availability refers to a category of rooms, not a specific room.

AlpineBits^® requires a match of InvCode or InvTypeCode to be case sensitive.

An AlpineBits^® server must be able to treat at least one case out of the two cases (specific rooms or categories). A client should perform the getCapabilities action to find out whether the server treats the room case (token OTA_HotelAvailNotif_accept_rooms), the category case (token OTA_HotelAvailNotif_accept_categories) or both.

Mixing rooms and categories in a single request is not allowed. An AlpineBits^® server must return an error if it receives such a mixed request.

The attribute Start and End indicate that room 101S is available from 2010-08-01 to 2010-08-10 and from 2010-08-21 to 2010-08-30.

Regarding the first interval, this means the earliest possible check-in is 2010-08-01 afternoon and latest possible check-out is 2010-08-11 morning (maximum stay is 10 nights).

Check-ins after 2010-08-01 and stays of less than 10 nights are allowed as well, provided the check-out is not later than 2010-08-11 morning.

Idem for the other block of 10 nights from 2010-08-21 to 2010-08-30 (latest check-out is 2010-08-31 morning).

Note that AlpineBits^® does not allow AvailStatusMessage elements with overlapping periods. This implies that the order of the AvailStatusMessage elements doesn’t matter. It is a client’s responsibility to avoid overlapping. An AlpineBits^® server’s business logic may identify overlapping and return an error or may proceed in an implementation-specific way.

The integer value of the attribute BookingLimit indicates the number of available rooms. Since in the example we’re dealing with a specific room here (InvCode is 101S), the only meaningful value of BookingLimit is 0 or 1 (the same room can not be available more than once). In the category case, numbers larger than 1 would also be allowed.

BookingLimit numbers are always interpreted to be absolute numbers. Differential updates are not allowed.

A server may support handling rooms that are considered free but not bookable (see section GuestRequests for the description of bookings) and must set the OTA_HotelAvailNotif_accept_BookingThreshold capability accordingly.

If the capability is set, a client must send the BookingThreshold attribute in the AvailStatusMessage element. A client that is only sending bookable rooms must set BookingThreshold to 0.

The number of bookable rooms are hence given by BookingLimit - BookingThreshold.

Since overbooking is not allowed and the number of bookable rooms cannot exceed the number of free rooms the inequality 0 ≤ BookingThreshold ≤ BookingLimit holds.

If the server does not have the capability set, a client must not send the BookingThreshold attribute in the AvailStatusMessage element, and all the rooms are implicitly considered bookable.

It also requires exactly one StatusApplicationControl element with attributes Start, End, InvTypeCode and (optional InvCode) for each AvailStatusMessage element. It must return an error if any of these are missing. There is however one exception: to completely reset all room availability information for a given Hotel a client might send a CompleteSet request with just one empty AvailStatusMessage element without any attributes. The presence of the empty AvailStatusMessage element is required for OTA validation.

AlpineBits^® recommends that Implementers that use delta requests should send the full set of information periodically.

A server that supports delta requests must indicate so via the OTA_HotelAvailNotif_accept_deltas capability. As always, it is the client’s responsibility to check whether the server supports deltas before trying to send them.

The server will send a response indicating the outcome of the request. The response is a OTA_HotelAvailNotifRS document. Any of the four possible AlpineBits^® server response outcomes (success, advisory, warning or error) are allowed.

See Appendix A for details.