Access Keys:
Skip to content (Access Key - 0)

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

hostConnect Extensions

hostConnect Version: 4.01.000
Date: 2018-10-09

Table of Contents

...

Table of Contents
maxLevel3
minLevel2

 

1 Overview

The standard hostConnect interface was designed for third parties to use to interface with Tourplan. Over time, a series of extensions have been made to offer greater functionality to Tourplan users who have developed in-house systems to communicate with hostConnect. This document details these extensions, which take the form of a number of new fields for standard hostConnect requests, and some new requests.

One of the most significant extensions is the ability to add fixed services to a booking. Ordinary service lines are the normal Tourplan service lines that are costed by Tourplan. All service lines added through Fastbook and the standard version of the hostConnect interface are ordinary service lines. A fixed service is priced external to Tourplan and added through hostConnect. Details of the pricing (plus some additional analysis fields needed in Tourplan) are included in the  AddService  request that adds the fixed service to the booking.

Tourplan knows comparatively little about the details of a fixed service. For example, it has no information on how the costs are broken down into components, such as the per room charges, charges for extra like breakfasts and so on. This detailed information is needed in various Tourplan messages, including agent and supplier messages. Consequently, where fixed services are used, a number of service line notes will be needed for each service to support messaging. Each note will contain detail appropriate to one particular message type.

1.1 Changes In This Version

Significant changes between this version and the previous version:

  1. There is a new value (C, for cancel penalty) for ServiceCategory.
  2. DeleteService no longer supports the ForceDeleteAttempt field.

1.2 Changes that are not backwards compatible

  • From 2.75.000, the  InvoiceText1 InvoiceText2, and  MessageFormatType  fields are no longer under the  Pricing  element. They are now in  AddServiceRequest UpdateServiceRequest  and  Service.

2 Extensions of Standard Requests

2.1 New fields for all requests

This group of data items can be supplied for all request types. Note that for each data item it may not be relevant for certain request types.

Data itemTypeDescription
ForceStdBookOpRightsBooleanThis attribute of the Request element was added to say that even though extensions are enabled, the standard booking operation rights should still be applied. This means that bookings whose travel dates have past are read-only, and that the standard checks are done to see whether services can be cancelled/deleted or accepted. All other extensions described in this document are available. Optional (defaults to N).
TourplanUserString (30)For requests that update bookings, TourplanUser is recorded as the person who made the change. TourplanUser does not have to be one of the Tourplan users setup within Tourplan. Optional (defaults to the Tourplan user the internet booking engine runs as).
BookingUpdateCount
ServiceLineUpdateCount
IntegerEvery booking has a BookingUpdateCount and every service line in the booking has a ServiceUpdateCount. These values are updated when the booking header is updated (for BookingUpdateCount) and when a service line is updated (for ServiceLineUpdateCount). The update counts for a booking and its service lines are returned by the GetBooking request. To be sure that a booking has not changed between getting it out of hostConnect and updating it, one or both of these values can be supplied with any type of update request, in which case the supplied values are compared with values in the database, and if there is a mismatch the request is aborted and an error is returned.

2.2 AddService

The hostConnect extensions provide two new modes for booking services: fixed services (where pricing is supplied in the  AddService  request) and direct booking of a service line in an external supplier system. These new modes are mutually exclusive (a service cannot be both fixed and booked in an external supplier system). Also, there are additional fields that can be specified for all types of service line. The additional capabilities for  AddService  are covered under the headings:

  • Changes to the rules relating to standard AddService fields.
  • New fields that can be supplied for any service (ordinary or fixed).
  • New fields that can be supplied services booked in an external supplier system.
  • New fields that can only be supplied for fixed services.

Changes for existing fields

Data itemNature of change
DateFromIn the extended hostConnect interface DateFrom is allowed to be in the past.

New general fields (ordinary and fixed services)

A number of new fields can be supplied for ordinary and fixed services. Those that apply at the booking level are listed in the table below. Note that either the  UDText  fields or  Email  can be specified (but not both). This is because the  Email  value is actually stored in one of the  UDText  fields (the field used is specified in the Internet settings in Tourplan).

Data itemTypeDescription
TourplanBookingStatusString (2)Tourplan booking status (can only be supplied in the AddService request that creates the bookings). Note, must be one of the Code values setup in Bookings / Booking Status in CodeMaint. Optional.
UDText1 to
UDText5
String (60)User defined text fields. Optional.
TourplanConsultantString (6)Tourplan consultant code. Note, must be one of the Initials values setup in Bookings / Consultant in CodeMaint. Optional.
TaxIndicatorInteger (0 to 8)Tax indicator. Optional (if not specified the agent tax indicator is used).

A number of additional fields can be supplied at the service line level.

Data itemTypeDescription
NoteCategory
NoteText
String (3)
String (60000)
Zero or more service line notes can be included in the AddService request. NoteCategory for each must be a valid Tourplan note category that has type BS and that does not allow multiple notes. The contents of NoteText can be plain text or RTF. If the format is different to that of the Tourplan note category, a conversion is done. If RTF is converted to plain text, then all formatting is lost. Optional.
PaxText1 to
PaxText5
String (60)Additional per pax text fields. Optional.
SupplierConfirmationString (30)Supplier confirmation code. Optional.
PriceCodeString (2)Price code to book the service line under. Does not have to be a price code the agent login is associated with. PriceCode can be made available in standard mode by setting the hostConnect setting priceCodeInStandardMode to Y (in that case only agent price codes can be used). Optional.
SendSupplierMessageBooleanIf the ICOM_SEND_MESSAGE ini is set to A then a message is sent unless a value of N is supplied for this field (if Y is supplied or this field is omitted then a message is sent). If the ICOM_SEND_MESSAGE ini is set to Y then a message is not sent unless a value of Y is supplied for this field (if N is supplied or this field is omitted then a message is not sent). If the ICOM_SEND_MESSAGE ini is set to N then a message is never sent, no matter what is supplied for this field. If extensions are not enabled then no value can be supplied for this field, which means a message is sent if the ICOM_SEND_MESSAGE ini is set to A, and not sent if it is Y or N. Optional (defaults to N).
InvoiceText1
InvoiceText2
String (60)Two lines of invoice text. Optional (can only be supplied for fixed services or external supplier services).
MessageFormatTypeString (2)Tourplan message format for the service line. Should be one of the Message Types defined in CodeMaint. Optional (can only be supplied for fixed services or external supplier services).

New fields (external supplier services)

A number of fields can (optionally) be supplied when an external supplier service is booked. The various credit card fields occur under the element  CreditCardDetails  (if that element is not supplied and credit card details are needed, then credit card details configured into Tourplan will be used). There is also a special class of external supplier services for Air Services. These are identified by the presence of an ExternalAirRouting element which contains FlightSector and Token elements. A number of fields cannot be supplied:  OnRequest PriceCode, fixed service fields.

Data itemTypeDescription
ExternalRemarks1,ExternalRemarks2StringOptional fields that can be specified if ExternalRateDetails is present. These fields are relayed to the external system. The maximum length of each is dependent on the external system.
CardHolderStringName of credit card holder. Must be supplied if a CreditCardDetails element is present.
CardNumberStringCredit card number (digits only; should contain no other characters such as spaces and dashes). Must be supplied if a CreditCardDetails element is present.
CardTypeString (2)Type credit card holder. Supply the standard two character card type: VI (Visa), MC (Mastercard), AX (American Express), DC (Diners Club), etc. Must be supplied if a CreditCardDetails element is present.
CardExpiryYearIntegerYear the card expires in. Must be supplied if a CreditCardDetails element is present.
CardExpiryMonthInteger (1..12)Month the card expires in. Must be supplied if a CreditCardDetails element is present.
CardSecurityCodeStringCard security code (sometimes called the card verification number). Optional.
puExternalPointIDIntegerUsed to identify the depot that the service will start from, used in services such as rental cars. Should be one of the Point_ID values returned during the product search.
doExternalPointIDIntegerUsed to identify the depot that the service will end at, can be different from the puExternalPointID. Should be one of the Point_ID values returned during the product search
ExternalAirRoutingsXML elementUsed to supply information about the external air product to book. This is a list of ExternalAirRouting elements, each of which contain costed data about a routing collected via the ExternalAirInfoRequest.

The ExternalAirRoutings element consists of:

Data itemTypeDescription
ExternalAirRoutingXML ElementElement that describes the collection of flights/sectors that could be used to complete the routing requested along with the token used to operate the routing.

The ExternalAirRouting element consists of:

Data itemTypeDescription
FlightSectorsXML ElementElement that describes the collection of flights/sectors that could be used to complete a routing.
TokenStringAn array of encoded Tokens that the external flight engines require for subsequent operations.

New fields (fixed services)

All of these new fields are at the service line level (none are at the booking level). The fields are discussed in two groups. The first group (listed in the following table) are the extra fields that do not hold price information. The second group of fields are those that specify the prices for this service line. Note that a service line is a fixed service if  SupplierID  or  SupplierCode  is included in the  AddService  request.

Data itemTypeDescription
SupplierID or SupplierCodeInteger
String (6)
The supplier (creditor) that this service is being supplied by.
TourplanServiceStatusString (2)Must be a valid Tourplan service status. Required (for fixed services). Ignored if ServiceCategory is E.
Pickup_DateDateCan be used in the rare situation where the pickup date is different to the service date. Optional (defaults to DateFrom).
Dropoff_DateDateThe date the service finishes. Optional (defaults to DateFrom).
SequenceNumberIntegerBy default Tourplan assigns the service sequence number, but if SequenceNumber is specified then it is used as the sequence number. Optional.
LocationCodeString (3)A valid Tourplan location code. Required for fixed services (for reporting purposes).
ServiceCodeString (2)A valid Tourplan service code. Required for fixed services (for reporting purposes).
DBAnalysisCode1 to
DBAnalysisCode3
String (2)Database analysis codes. Each value supplied must be one of the codes setup in Tourplan for that particular analysis code. Optional.
VText1 to
VText10
String (60)Voucher text lines 1 to 10. Optional.

The remaining group of data items contain pricing information. Up to four prices can be supplied:

  • Cost (the amount to be paid to the supplier).

  • Sell (the "normal" selling price).

  • Agent (the amount to be paid by the agent).

  • Retail (the price the agent will sell to their customer at).

Cost and agent prices (currency, tax amount, tax exclusive amount) must be supplied. The sell price is unlikely to be supplied (the sell currency is the same as the cost currency). The retail price can be supplied (retail currency is the same as agent currency).

Data itemTypeDescription
ItemDescriptionString (30)A description of the item (such as Two twin rooms). Displayed in the Service Costs screen in Tourplan. Optional.
CostCurrencyString (3)The currency that cost and (if present) sell prices are in. Must be a valid currency for the supplier the booking is for. Required.
CostConversionRateDecimal (8 d.p.)The exchange rate Tourplan should use (for this service line) to convert CostCurrency to booking currency (at present booking currency and AgentCurrency must both be the agent's default currency). Whether an amount in CostCurrency is converted to booking currency by multiplying or dividing by CostConversionRate is determined by the Internet ini setting ICOM_EXCHANGERATETYPE. Required.
CostExclusiveDecimal (2 d.p.)The cost price, exclusive of tax. Required.
CostTaxDecimal (2 d.p.)The amount of tax to be added to the cost price. Required.
SellExclusiveDecimal (2 d.p.)The sell price, exclusive of tax. Optional.
SellTaxDecimal (2 d.p.)The amount of tax to be added to the sell price. Optional.
AgentCurrencyString (3)The currency that agent and (if present) retail prices are in. Must be the booking currency (if this is the first service line in a new booking, then the booking currency is the default agent currency). Required.
AgentExclusiveDecimal (2 d.p.)The agent price, exclusive of tax. Required.
AgentTaxDecimal (2 d.p.)The amount of tax to be added to the agent price. Required.
RetailExclusiveDecimal (2 d.p.)The retail price, exclusive of tax. Optional.
RetailTaxDecimal (2 d.p.)The amount of tax to be added to the retail price. Optional.
ScuFocQtyIntegerThe number of second charge units that are free of charge. Optional (defaults to 0).

New returned fields

If an attempt is made to send a supplier message, then if an error occurred  SupplierMessageError  is returned and contains details of the error. Otherwise a  MessageDetails  element is returned containing details of the message sent (see GetSendSupplierMessage for details of the contents of  MessageDetails ).

2.3 GetBooking

NoteFormat and NotesInRtf are optional fields that control the format in which booking and service line notes are returned. See the OptionInfo section in the documentation of the standard hostConnect interface for details of the values taken by these fields.

Another boolean input field is  ReturnPackageServices  (optional, defaults to  N ). If this field is  Y  then all package service lines are returned, rather than just package service lines that were originally optional. See Section 4 for details on what happens if package service lines are returned.

The GetBooking return information has been expanded. For the most part the changes mirror the additional fields that can be entered through  AddService. These are:

  • At the booking level:  TourplanBookingStatus UDText1  to  UDText5 TourplanConsultant TaxIndicator SalesAnalysis1  to  SalesAnalysis6.

  • At the service line level, for all services:  Pickup_Date Dropoff_Date PaxText1  to  PaxText5 SupplierConfirmation PriceCode TourplanServiceStatus  and service line notes. Also, if  ReturnPackageServices  is  Y  then a number of other fields are returned.  ParentServiceLineId  is the service line id of the package this service is part of. If this service is part of a package within a package, then  ParentServiceLineId  is the second level package header (and  HeaderServiceLineId  is the top level package header). Where a service is an ordinary service within a top level package,  ParentServiceLineId  and  HeaderServiceLineId  are the same. The integer  PackageLineId  is returned for each package service line (it is a link to the line in the package definition). The boolean  IsStandardPackageLine  is returned for each package service line to indicate whether the service line is a standard part of the package, or an optional extra (which may or may not have been accepted in this booking).

  • At the service line level, for fixed services and external supplier services:  InvoiceText1 InvoiceText2, and  MessageFormatType.

  • At the service line level, for fixed services:  LocationCode ServiceCode DBAnalysisCode1  to  DBAnalysisCode3 VText1  to  VText10  and the fields containing pricing information.

At the booking level, booking header notes are returned (see the UpdateBooking section for details). At the service line level,  Voucher_Status  is returned for every service line. It is a one character field that can have the values blank (new service line), N (no cost), C (closed), L (liability only), R (reprint required) and P (printed). Also,  ServiceCategory  is returned for every service line. It is a one character field that can have the values A (air service), C (cancel penalty service line), E (service linked to external supplier system), F (iCom supplier fixed service), G (iCom option fixed service), H (package header service), P (package line service), S (Standard service). A package header service is a component of another package  HeaderServiceLineId  is returned for the package service header.

For fixed services, because of the way the the pricing information is stored, the room configuration returned just lists the pax in the booking (to preserve room configuration information, it should be saved as text in a note record).

2.4 GetBookingMessage

New input fields

Data itemTypeDescription
MessageCodeStringMessage code for a Tourplan agent message. This field is an an alternative to MessageLabel.

2.5 OptionInfo

New input fields

Data itemTypeDescription
ExternalSearchModeString

hostConnect can return rates held in the Tourplan database, and rates retrieved direct from external systems. This parameter plays in a major role in determining where hostConnect looks for rates. If it is  I  then only internal rates are returned. If it is  E  then only external rates are returned. If it is  A  then all rates, internal and external, are returned. At present external rates are returned for stay pricing only (Info=S). If  RateId  is supplied then the value of  ExternalSearchMode  is ignored, and only external rates are returned.

If  ExternalSearchMode  is not specified the following happens. If a price selection method is in effect then internal and external rates are searched for; otherwise only internal rates are examined. A price selection method is in effect if  PriceSelectionMethod  has been specified, or the INI ES_ICOM_PRICE_SELECTION has a non-blank value.

Note that for  A  and  E  multiple rates can be returned, each in its own  OptStayResults  element. At present for  I  no more that one  OptStayResults  element is returned.

PriceSelectionMethodString

Only has any effect if rates from external system(s) are available. This setting defines what stay rate (or rates) are returned for an option. If  E  is supplied than all rates are returned. Otherwise, the best rate (according to some criteria) is returned. If there are one or more rates with confirmed availability then the best of the confirmed availability rates is returned. Otherwise the best on request rate is returned.

There are a number of ways of determining the best rate:

  • L means lowest selling price.
  • A means highest margin amount.
  • P means highest margin percentage.

If  PriceSelectionMethod  is not specified then the value of ES_ICOM_PRICE_SELECTION is used. If that value is blank or not specified then no best price selection occurs.

RateIdStringRateId element returned by a previous OptionInfo request can be supplied as an input parameter. It is an error if RateId is specified and the search is for more than one option. It RateId is for an external rate, then the ExternalSearchMode is forced to E, overriding any value supplied, and only rates associated with the specified RateId are returned.
ExternalGetRateRulesBooleanThis field only applies if RateId is supplied. If ExternalGetRateRules is Y (by default it is N) then the external system is asked for an extra level of rate detail to be returned (some external systems refer to this as asking for rate rules). What additional information (if any) is returned is dependent on the external system rates are coming from.
PriceCodeString (2)If specified then all rates returned (for stay prices, stay rates, and date range rates) are from the specified price code (whether or not the agent login used has access to the specified price code). PriceCode can be made available in standard mode by setting the hostConnect setting priceCodeInStandardMode to Y (in that case only agent price codes can be used).
EndLocationCodeString (3)This field is used to specify the end location of the service for options which have a start and end location, such as external rental cars where it is possible to pickup the car from one depot and drop off at another. When not supplied the end location is assumed to be the same as the start location for the service.

New output fields

Data itemTypeDescription
WarningStringZero or more warning message are returned. They report cases problems that occurred during the search. For example, searching for an option failed because some of the option's information on the database is not valid (overlapping rates for the same price code, for example). Or because of an error searching in an external system. These errors do not abort the search and cause a hostConnect error return as if that happened it would prevent OptionInfo from returning a results for options that were searched without error.
PriceCodeStringReturned as part of the OptDateRange element for date range rates.
PreferIntegerReturned as part of the OptStayResults element. It is the Prefer value for the first day of the stay.

2.6 AgentInfo

New output fields

Data itemTypeDescription
CurrencySubCodeStringCurrency sub-code assigned to the agent.
UDText1 to UDText10StringsUser defined text fields.

2.7 UpdateBooking

Most of the additional input fields for this request work in the same way as the corresponding input fields of the  AddService  request (see the DTD for the full field list). The input fields that do not fall into this category are detailed in the table below.

Data itemTypeDescription
TourplanOldBookingStatus
TourplanBookingStatus
String (2)
String (2)
To change the status of the booking, both of these data items must be supplied (and both must be valid Tourplan booking statuses). When this request is processed, the booking status is changed to TourplanBookingStatus if and only if the booking status is currently TourplanOldBookingStatus. If this is not the case, then the rest of the updates are still done. The current booking status is returned in the reply, and this can be compared with TourplanBookingStatus to see whether the change occurred or not. Optional.
EnteredDateDateBy default the entered date of a booking is the day it was created. However, this date can be changed by specifying a new EnteredDate. Optional.
NoteCategory
NoteText
String (3)
String (60000)
Zero or more booking notes can be included in the UpdateBooking request. NoteCategory for each must be a valid Tourplan note category that has type BH and that does not allow multiple notes. The contents of NoteText can be plain text or RTF. If the format is different to that of the Tourplan note category, a conversion is done. If RTF is converted to plain text, then all formatting is lost. Optional.

The following additional data items are returned.

Data itemTypeDescription
TourplanBookingStatusString (2)The current booking status.

2.8 CancelServices

As noted above in the  AddService  section, it is now possible to cause a service to be added to an external supplier system. If  CancelServices  is attempted on a booking that contains one or more service lines linked to an external supplier system, then the  CancelServices  request will fail unless all such service lines are already cancelled (via the  DeleteService  request).

2.9 SupplierInfo

This request has been updated such that it is now possible to get information via agent or supplier login. When AgentID is used the request operates as it has always done. When SupplierLogin is used to login the request will only return data on the login supplier, it is not valid to supply SupplierCode or SupplierID values.

Data itemTypeDescription
SupplierLoginStringThe supplier login name.

3 New Requests

3.1 UpdateService

All of the fields that can be updated in the  UpdateService  request are ones already covered in relation to  AddService. Note that for fixed services all fields can be updated by an  UpdateService  request. Also, the room configuration must be supplied; all other fields are optional. For regular service lines, only the following fields can be updated: SequenceNumber, puTime, puRemark, doTime, doRemark, Remarks, SupplierConfirmation (for releases after 2.05.274), TourplanServiceStatus, ServiceLineNotes.

UpdateService  can be used on fixed and normal service lines for internet bookings, and (from 2.05.400 on) on normal service lines in non-internet bookings.

3.2 GetCurrencyConversions

This request returns details of currency conversion rates currently setup in Tourplan.

Data itemTypeDescription
ReturnAllSubCodesBooleanIf true, then conversions for all currency sub-codes are returned. If false, only conversions for the currency sub-code of the agent login used for the request are returned. Optional (defaults to false).

In the response, a number of  CurrencyConversionSet  elements are returned, each with a  FromCurrency ToCurrency CurrencySubCode  and a series of  CurrencyConversion  elements containing the remaining data items. Entries are sorted in increasing order of  FromCurrency ToCurrency CurrencySubCode DateFrom.

Data itemTypeDescription
FromCurrencyString (3)From currency for this set of conversion rates.
ToCurrencyString (3)To currency for this set of conversion rates.
CurrencySubCodeStringCurrency sub-code for this set of conversion rates.
DateFromDateDate that this particular conversion applies from.
DateToDateDate that this particular conversion applies to.
ConversionRateDecimal (12 d.p.)The conversion rate.
IsMultiplierBooleanWhether conversion is done by multiplying (Y) or dividing by ConversionRate.

3.3 GetBookingPaymentSummary

This request accepts the standard parameters for identifying a booking, and returns a payment summary of the booking. Output data items are summarised in the table below. It also returns agent and retail pricing, broken down into the tax and tax-exclusive components (commission is the difference between the agent and retail totals).

Data itemTypeDescription
CurrencyString (3)Booking currency. All amounts returned are in booking currency.
InvoicedExclusiveIntegerTotal amount invoiced for this booking (exclusive of Tax).
InvoicedTaxIntegerTax component of retail total.
CreditsExclusiveIntegerTotal value of credit notes issued for the booking (exclusive of Tax).
CreditsTaxIntegerTax component of credit notes issued.
ReceivedExclusiveIntegerTotal value of credit notes issued for the booking (exclusive of Tax).
CreditsTaxIntegerTax component of credit notes issued.
TotalReceiptsIntegerTotal amount received for this booking.
RetailExclusiveIntegerRetail total (exclusive of tax).
RetailTaxIntegerTax component of retail total.
AgentExclusiveIntegerAgent total (exclusive of tax).
AgentTaxIntegerTax component of agent total.

3.4 RecordBookingPayment

This request records a payment against the specified booking. If the booking is not yet fully invoiced then either an invoice is raised so that the booking becomes fully invoiced, or an invoice for the amount of the payment is raised (depending on the value of the  ICOM_MAKEPAYMENT_INVOICE  Internet INI setting). A receipt for the amount received is always created.

This request accepts the standard parameters for identifying a booking, plus the ones in the following table.

Data itemTypeDescription
CurrencyString (3)The currency the amount received is in (must be the same as the booking currency). Required.
AmountIntegerThe amount received. Required.
ReceiptTypeString (6)A valid Tourplan receipt type. Required.
UDText1
UDText2
UDText3
String (60)Three user defined text fields for information about the payment. Optional.
TourplanBookingStatusString (2)Tourplan booking status. If supplied, then if the payment is successfully recorded, the Tourplan booking status is changed to the status specified (if not supplied the booking status does not change). Note, must be one of the Code values setup in Bookings / Booking Status in CodeMaint. Optional.

One data item is returned.

Data itemTypeDescription
ReceiptReferenceString (20)The Tourplan reference for the receipt created.

3.5 GetSendSupplierMessage

This request gets hostConnect to generate a supplier message for a nominated service line, and then to either send the message to the supplier (via email or fax) or return the message back to the caller. Also, this request can change the service status of the service line.

This request accepts the standard parameters for identifying a booking, plus the ones in the following table.

Data itemTypeDescription
ServiceLineIdIntegerThe service line that the supplier message will be generated for.
MessageCodeStringThe code of the message to send. The message code must be a valid booking supplier message code. If a MessageCode is not supplied then hostConnect determines which message to use. If the service option is auto-messaging enabled then the message to send is determined by auto-messaging defaults. Otherwise, the ICOM_MESSAGE_STATUS ini setting is used.
SendMethodStringPreferred way of sending the message. One of E (send via e-mail), F (send via fax) or R (do not send). Required.
OutputFormatStringFormat that the message is returned in. One of txt (plain text), rtf (rich text format) or pdf. Optional (defaults to txt). Ignored if SendMethod is not R. Also ignored for container messages, where the message definition determines the output format.
TourplanSeviceStatusString

If  TourplanServiceStatus  is supplied then the service status is updated to this value after the message has been generated and (if  SendMethod  is not  R ) sent. What happens if  TourplanSeviceStatus is not supplied depends on other fields:

  • If SendMethod is R then the service status is not changed. Otherwise,
  • If MessageCode was not supplied then the new service status is determined by hostConnect (from auto-messaging defaults and the ICOM_MESSAGE_STATUS ini setting). Otherwise,
  • It is an error not to specify TourplanServiceStatus (this happens if SendMethod is not R and a MessageCode was supplied.

Note that the current and new service statuses must have the same values for the hold allocation and include in booking flags.

SendToAddress
SendToContactType
StringIf SendMethod is not R, then one or other of these fields can be specified to tell hostConnect where to send the message. If SendToAddress is specified then it contains an email address or fax number (depending on the value of SendMethod). If SendToContactType is specified then supplier phone book entries of this type are looked up. If SendMethod is E then email will be used if there is an email address; otherwise fax will be used (and similarly fax then email will be used if SendMethod is F). Optional (if not specified then the ICOM_CONTACT_TYPE is used as SendToContactType.
SubjectStringSubject to use for the email or fax. Optional (default is to use the subject that is generated in the message).

Data items returned are listed below. The message-related ones all appear within a  MessageDetails  element.

Data itemTypeDescription
MessageCodeStringThe message code used to generate the message.
SendMethodStringHow the message was sent. Is the same as the requested send method, except where email (fax) was requested, and the address was located in the Tourplan phone book, and there was only a fax (email) address available.
SubjectStringThe subject of the message sent. Only returned if SendMethod is R.
OutputFormatStringFormat that the message is returned in. One of txt (plain text), rtf (rich text format) or pdf. Only returned if SendMethod is R.
MessageStringThe message content. Only returned if SendMethod is R. For container messages the container part is not returned (only the main body of the message). Note that if the output format is PDF then the contents of message are encoded in base64 format.
SendToAddressStringThe address the message was sent to (not returned where SendMethod is R).
StatusStringThe current hostConnect service status (following any changes in status caused by the GetSendSupplierMessage request).
TourplanSeviceStatusStringThe current Tourplan service status (following any changes in status caused by the GetSendSupplierMessage request).

3.6 GetAccountingMessage

This request gets hostConnect to generate an invoice message for a nominated transaction associated with a booking.

This request accepts the standard parameters for identifying a booking, plus the ones in the following table.

Data itemTypeDescription
TransactionIdIntegerThe transaction that the invoice message will be generated for. Must be an invoice or credit note transaction for the specified booking.
MessageCodeStringThe code of the message to send. The message code must be a valid invoice message code.
OutputFormatStringFormat that the message is returned in. One of txt (plain text), rtf (rich text format) or pdf. Optional (defaults to rtf). Note that for container messages, if a format is specified in the message then the format specified in the message takes precedence.

Data items returned are listed below.

Data itemTypeDescription
OutputFormatStringFormat that the message is returned in. One of txt (plain text), rtf (rich text format) or pdf. Optional (defaults to rtf). Note that for container messages, if a format is specified in the message then the format specified in the message takes precedence.
MessageStringThe message content. Note that if the output format is PDF then the contents of this field are encoded in base64 format.

3.7 ExternalAirInfoRequest

This request allows external air service providers that have been configured in the host Tourplan system to be queried.

The request has 2 styles of operations. The first is a search mode where minimal information about the dates and routing required can be provided and all matching routings and their pricing information are returned. There is a second Fare Breakdown mode that accepts data returned by the search response that enables a detailed fare breakdown for a specific Flight/Fare combination.

The request accepts the following parameters.

Input data items

AgentID, Password. Also:

Data itemTypeDescription
InfoStringSpecifies the categories of flight/airfare data to return. Operates differently to its use in OptionInfo as it is a switch for either (S)earch level data or Fare (B)reakdown level data. An optional flag (R)ules can be added to bring back fare rule information if supported by the external provider.
RoomConfigsXML ElementThe room configuration being priced. See the the AddService section for more information on RoomConfig. Note that PersonId cannot be specified in an ExternalAirInfo RoomConfig as it is only valid for booking operations, such as AddService (people are attached to bookings).
Branch
Department
SalesAnalysis1 to
SalesAnalysis6
StringsThese fields are all optional. By default costing is done in the context of a booking made with the default values for all of these fields. For each one supplied, the value supplied is used instead of the default in the costing process.
FlightSectorXML ElementDetails of the flight sector being requested. At least one must be provided and if more than one is provided then the pricing information return will be for all sectors, that is the entire routing.
TokenStringAn array of encoded Tokens that the external flight engines require for subsequent operations.
RateIdStringA RateId element returned by a previous ExternalAirInfo request can be supplied as an input parameter. and only rates associated with the specified RateId are returned. Would be used when Info=B to ensure correct Form of Payment information is sent to the external system
CreditCardDetailsXML ElementWhen requesting with Info=B then credit card details can be sent to ensure the correct total is returned from the external system. See AddService for details of the contents.

The FlightSector element consists of:

Data itemTypeDescription
OriginStringStart point for the flight
DestinationStringEnd point for the flight. The external air provider will be searched for all flights/fares between each pair of Origin and Destination values. For example SYD-BNE and BNE-SYD will return all SYD-BNE and BNE-SYD flights that can be booked in conjunction with each other.
Depart_DateDateDate that the flight is departing
Depart_TimeTimeOptional time of flight departure
CarrierString (2)Carrier code. This is expected to be one of the carrier codes defined in the host Tourplan system and will be mapped to a Tourplan supplier code.
SupplierCodeString (6)An alternative to the Carrier code. Mapping data in Tourplan will associate carriers and suppliers and so normal usage of the interface will be to provide suppliers or carriers rather than both.
FlightIntegerFlight number for the sector to be flown. Optional, and not expected to be supplied for a general search.
SectorSequenceInteger

A sequence number to indicate the grouping of sectors required to complete a single point to point journey. Only required when Info=B.

Some flight requests will result in options for direct and indirect flights SectorSequence will pair these together. For example a Hobart-Brisbane request may result in HOB-BNE Direct and HOB-MEL-BNE Indirect flights being offered. The HOB-MEL and MEL-BNE sectors will share the same SectorSequence value, indicating that they operate as a pair to complete the requested HOB-MEL journey.

Data items returned are listed below.

Data itemTypeDescription
FlightRoutingXML ElementElement that describes the collection of flights/sectors that could be used to complete the routing requested.

The FlightRouting element consists of:

Data itemTypeDescription
FlightSectorResultsXML ElementElement that describes the individual sectors making up the selected routing. Routings for direct flights will contain a FlightSectorResult and associated airfares. Where routings have indirect flights then the routing will contain multiple FlightSectorResults covering all of the flights required to complete the journey.
AirFareXML ElementElement that describes the available fare structures for a flight routing, including all tax and additional fee charges.

The FlightSectorResults element consists of:

Data itemTypeDescription
OriginString (3)Start point for the flight
DestinationString (3)End point for the flight. The external air provider will be searched for all flights/fares between each pair of Origin and Destination values. For example SYD-BNE and BNE-SYD will return all SYD-BNE and BNE-SYD flights that can be booked in conjunction with each other.
Depart_DateDateDate that the flight is departing
Depart_TimeTimeTime of flight departure
CarrierString (2)Carrier code. This is expected to be one of the carrier codes defined in the host Tourplan system and will be mapped to a Tourplan supplier code.
SupplierCodeString (6)This is the Tourplan supplier code as determined by the mapping data between that and the carrier code in Tourplan
FlightIntegerFlight number for the sector to be flown.
Arrive_DateDateThe date, in local time, that the flight is expected to arrive.
Arrive_TimeTimeThe local time at which the flight is expected to arrive
OriginTerminalStringThe terminal name/number the flight is departing from
DestinationTerminalStringThe terminal name/number the flight is arriving at
AircraftTypeStringThe type of aircraft servicing this sector
FlightDurationStringThe expected flight time
SectorSequenceInteger

A sequence number to indicate the grouping of sectors required to complete a single point to point journey.

Some flight requests will result in options for direct and indirect flights SectorSequence will pair these together. For example a Hobart-Brisbane request may result in HOB-BNE Direct and HOB-MEL-BNE Indirect flights being offered. The HOB-MEL and MEL-BNE sectors will share the same SectorSequence value, indicating that they operate as a pair to complete the requested HOB-MEL journey.

AirFareXML ElementElement that describes the fare structure for a flight, including all tax and additional fee charges.

The AirFare element consists of:

Data itemTypeDescription
FareCodeStringThe code by which the airline knows this fare detail as.
FareNameStringThe name that fare is known by, if the external air provider has supplied it
RateIdStringThe rate identifier in the external system and used to perform a look up into the Tourplan mapping data.
PlatingCarrierString (2)The carrier on whose plate the tickets will be issued. Normally the same as the carrier but may vary in code sharing situations
SupplierCodeString (6)This is the Tourplan supplier code as determined by the mapping data between that and the PlatingCarrier code in Tourplan. This is the carrier that will actually issue the ticket and therefore charge for teh flight rather than the airline that will operate the flight.
CabinClassStringClass of the flight, economy, business etc
CurrencyString (3)The currency code that the amount is described in which will be the Agent currency used by HostConnect.
TotalRateAmountDecimalTotal tax Exclusive value for the flight for all pax specified
TotalRateTaxDecimalTotal amount of accountable taxes chargeable for this flight
TotalAgentAmountDecimalTotal tax Exclusive value the Agent will pay for the flight for all pax specified
TotalAgentTaxDecimalTotal amount of accountable taxes chargeable to the Agent for this flight
CommissionPercentageDecimalNominal commission that the agent has earnt. Note that the dollar value earnt is the difference between TotalRateAmount and TotalAgentAmount. As not all components of the fare are commissionable this may not match the percentage value returned.
BaggageCountIntegerThe per person number of bags permitted with this flight/fare. The costs associated with bagage will be described in the fare detail itself.
BaggageWeightStringMaximum per person allowable baggage weight
FareAmountXML ElementDescription of the various fare components that apply for this flight/fare
TokenStringAn array of encoded Tokens that the external flight engines require for subsequent operations.
FareRuleStringAn array of fare rule information that apply for this flight/fare.

The FareAmount element consists of:

Data itemTypeDescription
AppliesToString

A string value describing the type of passenger that this fare component applies to. Valid values are:

PerAdultThe charge described applies per adult pax
PerChildThe charge described applies per child pax
PerInfantThe charge described applies per infant pax
PerPaxThe charge described applies per pax, regardless of classification
OneOffThe charge described is a one off fee, normally things like booking credit card fees etc
AmountTypeString

The type of amount being described. Will be one of:

FareThe amount describes a fare value
TaxThe amount describes a tax value
SurchargeThe amount describes a surcharge value. Surcharges are information only have have already been included in the equivalent Fare amount value. They are used for items that are compulsory when booking this fare and are expected to be pax or pax type based.
FeeThe amount describes an additional fee that may be chargeable. Similar to surcharges, but the value described is not already included in the Fare of the equivalent type.
StandardBaggageThe amount describes the standard baggage allowance costs if not included in the fare.
OptionalExtraThe amount describes an optional extra, these items are not part of the fare makeup but can be added to it to select the extra item/service if required.
AmountCodeStringA code returned to further categorise the AmountType. In the case of Tax amounts it will contain the tax code whilst for Fare amounts it will repeat the code, Per Adult Fare or Per Child Fare etc. For Fee, Surcharge, StandardBaggage and OptionalExtra amounts it will contain a descriptive code returned from the external system.
RateAmountDecimalThe value of the Fare component. This is the amount that the agent will be charged.
AgentAmountDecimalThe value of the Fare component to the Agent. This is the amount that the agent will be charged.
CommissionableBooleanIndicator as to whether this item attracted agent commission.
TokenStringAn array of encoded Tokens that the external flight engines require for subsequent operations.

The FareRule element consists of:

Data itemTypeDescription
RuleAppliesToString

A string value describing the type of passenger that this fare rule component applies to. Valid values are:

AdultThe rules applies to adult fares
ChildThe rules applies to child fares
InfantThe rules applies to infant fares
AllThe rules applies to all pax class fares
RuleTypeStringA string value that type/class of the rule.
RuleCategoryStringA code returned to further categorise the AmountType.
RuleBodyStringThe rule body text, passed through in whatever format was supplied by the external system.

4 Accessing package service lines

The standard hostConnect behaviour for packages is that only one service line is returned (that of the package header). The  LinePrice  returned is the line price of the package, and the  Status  is the least available status across all of the package service lines. When optional services were introduced in 2.07, this behaviour was changed so that service lines that are optional in the package are returned as separate service lines by hostConnect.

It is now possible to ask to for "standard" package service lines (those that are not optional in the package definition) using the  GetBooking  field  ReturnPackageServices. If  ReturnPackageServices  is  Y then:

  • Standard package service lines are returned as well as package service lines that are optional in the package definition. For each package service line the field  IsStandardPackageLine  indicates whether the package service line is a standard one or an optional part of the package.

  • The  LinePrice  of the package header service line is the selling price of the standard service lines (as per normal). The  LinePrice  fields of all of the standard package service lines will either by 0, or add up to the package.

  • The hostConnect operations available on standard package service lines are somewhat limited. Only  UpdateService  and  SendSupplierMessage  can be used on package service lines.

  • It is possible for a package to be optional (either the top level package, or a package that is a component of a top level package). In this case, optional services within an optional packages are returned, but they cannot be manipulated in any way. Also, each  IsStandardPackageLine  value for a service in an optional package shows whether the service is optional or not in the context of that package.

...

Tourplan Pacific Ltd reserves the right to change, modify, add or remove portions of this interface at any time.