Transaction meta data
The Head element in HotelML plays the role of structuring transaction meta data, such as what nodes to process, where the instance document has been and where it is going, and any error conditions that occurred along the way.
For reference, the following models illustrate the parent child relationships of the Head component:
Head Element Content Model
Making a request
The Process element is used to aggregate information about a specific operation that is to be performed on a node in the instance document. The essential information is fairly basic, requiring the path to the node to operate on, the function to perform, and a token to include in each response structure that is generated by processing.
Note: While this model inherently supports multiple operations on multiple data structures (including batching), multiple operations on multiple data structures is not supported at this time. Only one operation on one data set is allowed per instance document.
The following example illustrates a request.
<?xml version="1.0"?>
<HotelML xmlns="
http://www.xpegs.com/v2001Q3/HotelML
"> <Head>
<Process Function="TI_PropertyInformationV1_1" DataPath="/HotelML/Form/PropertyInformation" Token="992535807859"/>
<Route Source="SGACode" Destination="00"/> </Head>
<Form>
<PropertyInformation PropertyCode="XX;12345" DataSet="Basic"/> </Form>
</HotelML>The following example illustrates a response.
<HotelML xmlns=”
http://www.xpegs.com/v2001Q3/HotelML
”> <Head xmlns="
http://www.xpegs.com/v2001Q3/HotelML
">
<Route xmlns="
http://www.xpegs.com/v2001Q3/HotelML
" Source="00" Destination="SGACode">
<Operation xmlns="
http://www.xpegs.com/v2001Q3/HotelML
"
Action="Create" DataPath="/HotelML"
StartTime="2001-07-11T15:40:01.365-05:00"
TotalProcessTime="14463" App="TIDispatcher"
AppVer="1.1" Success="true"/>
</Route>
</Head>
<Property Token=”992535807859”> … </Property> </HotelML>
Route
The Route element is very important to record where an instance document has been or where it is going for a number of reasons. Primary motivations would include debugging an instance document that may have been corrupted during creation or routing, commissions for bookings, and transaction distribution statistics.
Note: Routing information is often, if not always, contractually required by RateGain. Please refer to the relevant business agreements for clarifications on required routing information.
The information that is collected requires, at minimum, the source and destination of a single route where every arc of a route must be persisted in a Route element.
If an operation is performed by the Source, important information about the operation must be persisted in a child Operation element, recording the action, path to the node operated on, start time, processing time, and essential application information.
The following example illustrates a route and operation where an immediate customer created a PropertyInformation request and sent the request directly to RateGain.
<?xml version="1.0"?>
<HotelML xmlns="
http://www.xpegs.com/v2001Q3/HotelML
"> <Head>
<Process Function="TI_PropertyInformationV1_1" DataPath="/HotelML/Form/PropertyInformation" Token="992535807859"/>
<Route Source="SGACode" Destination="00"/>
</Head>
<Form>
<PropertyInformation PropertyCode="XX;12345" DataSet="Basic"/> </Form>
</HotelML>
The following example illustrates a route and operation where RateGain processed a PropertySearch request and sent the response back to the customer.
<HotelML xmlns=”
http://www.xpegs.com/v2001Q3/HotelML
”>
<Head xmlns="
http://www.xpegs.com/v2001Q3/HotelML
">
<Route xmlns="
http://www.xpegs.com/v2001Q3/HotelML
"
Source="00" Destination="SGACode">
<Operation
xmlns="
http://www.xpegs.com/v2001Q3/HotelML
"
Action="Create" DataPath="/HotelML" StartTime="2001-07-11T15:40:01.365- 05:00" TotalProcessTime="14463"
App="TIDispatcher" AppVer="1.1" Success="true"/>
</Route>
</Head>
<Property Token=”992535807859”> … </Property> </HotelML>A real example
<?xml version=”1.0”?>
<HotelML xmlns=”
http://www.xpegs.com/v2001Q3/HotelML
” > <Head>
<Process DataPath=”/HotelML/Form/PropertySearch[1]” Function=”TI/PropertySearch/V1_1” Token="12ab />
<Route Source=”ADSCode” Destination=”PEGSCode” > <Operation Action=”create”
DataPath=”/HotelML/Form/PropertySearch[1]”
StartTime=”23:59:59.999”
TotalProcessTime=”00:00:00.025” App=”SomeKillerApp”
AppVer=”4.5.2” Success=”True” />
</Route>
</Head>
<Form>
<PropertySearch MaxCount=”100” PrimarySortOrder=”PropertyName”> <DateRange InDate="2000-12-24" OutDate="2000-12-25" /> <BasicSearch>
<Brand Code="BW" />
</BasicSearch>
</PropertySearch>
</Form>
</HotelML>
In this example, it is important to note the following important information:
XML processing instruction
Process element with the desired operation, node to process, and token
Route element with source and destination with child Operation element to record the creation of the instance document.
PropertySearch element with structure containing all data required to perform requested operation.
Receiving a response
HotelML is built in such a way that the aggregation of responses is facilitated, however, it is in no way required. While each response will only have the result set of the submitted form, HotelML allows for a series of transaction responses to be summed into one big instance document that could be thought of as a session. This may be achieved through XSL -Transforms or other means. Since the processing of a response is essentially up the BSP, there is little more to cover here other than to provide an example.
A real example
Note: For simplicity, the data of the PropertySearchState element has been omitted
<?xml version=”1.0”?>
<HotelML xmlns=”
http://www.xpegs.com/v2001Q3/HotelML
” > <Head>
<Route Source=”PEGSCode” Destination=”ADSCode” > <Operation Action=”create”
DataPath=”/HotelML/PropertySearchState[1]”
StartTime=”01:01:02.001”
TotalProcessTime=”00:00:00.240” App=”NAS” AppVer=”2.3”
Success=”True” />
</Route>
</Head>
<PropertySearchState MoreProps=”” StateId=”” NumResults=”” Token=”12ab” >
<Property Code="" AvailabilityStatus="" Name=""
MatchedAmenityCount=”” >
<Phone Number="" Type=”” />
<PostalAddress Line1="” Line2="” Line3="” Line4="” City="” StateCode="” PostalCode="” CountryCode="” Type=" />
<GeoInfo Latitude="" Longitude="" /> <PriceRange Min="" Max="" Currency=”” />
</Property>
</PropertySearchState>
</HotelML>
In this example, it is important to note the following important information:
XML processing instruction
Route element with source and destination with one child Operation element to record the creation of the response.
PropertySearchState element with token and the results of the search.
Errors
All systems have errors, and the XML UltraDirect interface is no different. In order to provide effective error recovery, a variety of information will be provided on each error that occurs. The cause of the error has been divided into classes and the severity of the error has been divided into types. The following sections expand on the classes and types of errors.
Errors
The last class of metadata about an instance document is error information. The following list provides a brief overview of the types of errors that may occur.
Error Type
Description
Malformed
XML instance document does not conform to format as dictated by XML 1.0 specification.
Validation (Schema/DTD)
XML instance document does not conform to grammar/syntax rules as dictated by Schema or DTD.
Usage (XSL Transform or Application)
XML instance document does not conform to minimum data requirements defined by XSL Transform.
Security
Requestor is not authorized to perform requested function.
System Status Error
Critical system is not available.
Process
The local or remote system that processed the request encountered an error.
Classes of errors
Each of the types of errors just covered could vary in severity. The actual error information will be aggregated in an element that signifies the severity of the error. These elements are generally defined as follows:
Error Class
Description
<Warning>
An error that did not prevent processing and the subsequent generation of a response, however there are conditions associated with the error that should be looked at.
<Error>
An error that prevented processing from occurring, but the system recovered and was capable of providing information about the error.
<Fatal>
An error that resulted in the abortion of processing and the system did not recover.
Error information set
Each type of error will, for the most part, collect the same type of information in attributes. Therefore a common set of attributes is used by each of the elements that represent an error type.
For more specific information, see the Head component in the HotelML Schema documentation
Attribute
Description
Code
The actual error code that was returned. This code is used to look up a description of the error.
Type
This is the type of error that occurred. The types were enumerated and explained above.
Description
This is the textual description of the error that occurred. It is anticipated that this description could be provided in multiple languages, however this is not supported in the first version of the XML Transaction Interface.
FormDataPath
This is an XPath style expression that points to the node on which the operation was performed that created the error. This should help to narrow down the offending data structure for debugging purposes.
ResultDataPath
In the event that a result was generated, this is an XPath style expression that points to the node created by the operation, or more specifically, to the portion of the result that is in question.
Examples
Given this information, the following examples illustrate how an error might appear in an instance document.
A warning condition:
<HotelML>
<Head>
<Warning Code=”” Type=”” Description=”” FormDataPath=””/> </Head>
</HotelML>An error condition:
<HotelML>
<Head>
<Error Code=”” Type=”” Description=”” FormDataPath=”” ResultDataPath=””/>
</Head>
</HotelML>A fatal error condition:
<HotelML>
<Head>
<Fatal Code=”” Type=”” Description=”” FormDataPath=”” ResultDataPath=””/>
</Head>
</HotelML>Limitations and caveats
Because HotelML is implemented in XML Schema to take advantage of namespaces, strong datatypes, and XML-based syntax not found in DTD’s, there are some system limitations and caveats that must be kept in mind.
Any element that has occurrence from zero to one time will be overwritten if the element appears more than once, violating the occurrence rule. Future versions of HotelML data-binding classes should handle this error condition as expected.
Last updated