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

hostConnect Extensions

hostConnect Version: 2.07.020 and above

Date: December 9, 2008

1 Overview

The standard hostConnect interface was designed for third parties to use to interace 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.

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
ForceStdBookOpRightsBoolean

This attribute of the Requestelement 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

Integer

Every booking has a BookingUpdateCountand 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 additional capabilities for AddService are covered under

three 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 only be supplied for fixed services.

Changes for existing fields

Data itemNature of change
DateFrom

In the extended hostConnect interface DateFromis 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 ini 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.

UDText1to

UDText5

String (60)User defined text fields. Optional.
TourplanConsultantString (6)

Tourplan consultant code. Note, must be one of the Intials values setup in Bookings / Consultant in CodeMaint. Optional.

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 must be in RTF. Optional.

PaxText1to

PaxText5

String (60)Additional per pax text fields. Optional.
SupplierConfirmationString (30)Supplier confirmation code. Optional.
SendSupplierMessageBoolean

If the ICOM_SEND_MESSAGE ini is set to Athen 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 sent. If the ICOM_SEND_MESSAGE ini is set to Y 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 set if it is Y or N. Optional.

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

SupplierCode

Integer

String (6)

The supplier (creditor) that this service is being supplied by.
TourplanServiceStatusString (2)

Mustbe a valid Tourplan service status.

Required (for fixed services).

Pickup_DateDate

Can be used in the rare situation where the pickup date is different to the service date. Optional (defaults to DateFrom).

Dropoff_DateDate

The date the service finishes. Optional (defaults to DateFrom).

SequenceNumberInteger

By 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).

DBAnalysisCode1to

DBAnalysisCode3

String (2)

Database analysis codes. Each value supplied must beone of the codes setup in Tourplan for that particular analysis code. Optional.

VText1to

VText10

String (60)Voucher text lines 1 to 10. Optional.

InvoiceText1

InvoiceText2

String (60)Two lines of invoice text. Optional.
MessageFormatTypeString (2)

Tourplan message format for the service line. Should be one of the Message Types defined in codemaint. 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&nbsp(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 default currency for the agent the service is being booked for. Required.

AgentExclusiveDecimal&nbsp(2 d.p.)The agent price, exclusive of tax. Required.
AgentTaxDecimal&nbsp(2 d.p.)The amount of tax to be added to the agent price. Required.
RetailExclusiveDecimal&nbsp(2 d.p.)The retail price, exclusive of tax. Optional.
RetailTaxDecimal&nbsp(2 d.p.)The amount of tax to be added to the retail price. Optional.
ScuFocQtyInteger

The 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 href="#GetSendSupplierMessage">GetSendSupplierMessage for details of the contents of MessageDetails).

2.3 DeleteService

In the extended version of DeleteService there is an additional optional boolean input parameter called ForceDeleteAttempt. By default hostConnect will delete the service if that is possible, and set the service status to the internet cancellation requested status if that is not possible.

Another mode of operation supported by the extended hostConnect interface is to force an attempt to delete the service, and to leave the service status unchanged if deletion is not possible.

This mode is enabled by supplying a value of Y for ForceDeleteAttempt and by setting to N the Internet ini setting ICOM_DELETE_CAN_CANCEL.

If (in this mode) a service cannot be deleted, a code is returned in the DeleteService reply (in DeleteRefusalReason) specifying why deletion is not possible. DeleteRefusalReason is one of:

1000

Service status is not in the list of deletable service status in the Internet ini setting ICOM_DELETABLE_STATUSES.

1001Unable to delete Service Lines from this Package.
1002

Unable to delete Package Service Line as Package Details can not be located.

1003

You are unable to delete this Service Line because the Voucher Status is Closed.

1004You are unable to delete this Service Line because it is a liability.
1007Unable to delete this service because resources are allocated.
1008Unable to delete this service because it has financial transactions.
1009

Unable to delete this package service because it has financial transactions.

2.4 GetBooking

There is a new boolean input field (NotesInRtf; optional, defaults to Y). If this field is N then any booking and service line notes returned are converted to, and returned as, plain text. Otherwise they are returned as RTF.

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: TourplanBookingStatusUDText1 to UDText5TourplanConsultantSalesAnalysis1 to  SalesAnalysis3.

  • At the service line level, for all services: Pickup_DateDropoff_DatePaxText1 to PaxText5SupplierConfirmationPriceCodeTourplanServiceStatus, service line notes.

  • At the service line level, for fixed services:

    LocationCodeServiceCodeDBAnalysisCode1 to DBAnalysisCode3VText1 to VText10InvoiceText1, InvoiceText2MessageFormatType 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 chracter field that can have the values blank (new service line), N (no cost), C (closed), L (liability only), R (reprint required) and P (printed).

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.5 GetBookingMessage

New input fields

Data itemTypeDescription
MessageCodeString

Message code for a Tourplan agent message. This field is an an alternative to MessageLabel.

2.6 OptionInfo

New output fields

Data itemTypeDescription
PriceCodeString

Returned as part of the OptDateRangeelement for date range rates (versions 2.05.300 and above).

PreferInteger

Returned as part of the OptStayResultselement for (versions 2.05.400 and above). It is the Prefer value for the first day of the stay.

2.7 AgentInfo

New output fields

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

2.8 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 bevalid Tourplan booking statuses). When this request is processed, the booking status is changed to TourplanBookingStatus if and only if the bookingstatus 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.

EnteredDateDate

By defalt 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 must be in RTF. Optional.

Name


String (60)Name of the party for whom the booking is being made (required). Note that in some systems Name is forced to upper case. ** This is the Booking Name and NOT the passenger name. Passenger names cannot be updated. **

The following additional data items are returned.

Data itemTypeDescription
TourplanBookingStatusString (2)The current booking status.

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 sevice 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
ReturnAllSubCodesBoolean

If 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 FromCurrencyToCurrencyCurrencySubCode and a series of CurrencyConversion elements containing the remaining data items. Entries are sorted in increasing order of FromCurrencyToCurrencyCurrencySubCodeDateFrom.

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

Whether 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 an invoice is created for the amount not yet invoiced (which may be less than, the same as, or greater than the amount received). 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.

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

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

SendMethodString

Preferred way of sending the message. One of E (send via e-mail), F (send via fax) or R (do not send). Required.

OutputFormatString

Format 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 TourplanServiceStatusis 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 Rthen the service status

    is not changed. Otherwise,

  • If MessageCodewas 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

    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

String

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

SubjectString

Subject 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 withing a MessageDetails element.

Data itemTypeDescription
MessageCodeStringThe message code used to generate the message.
SendMethodString

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

SubjectString

The subject of the message sent. Only returned if SendMethod is R.

OutputFormatString

Format that the message is returned in. One of txt (plain text), rtf (rich text format) or pdf. Only returned if SendMethod is R.

MessageString

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

SendToAddressString

The address the message was sent to (not returned where SendMethod is R).

StatusString

The current hostConnect service status (following any changes in status caused by the GetSendSupplierMessage request).

TourplanSeviceStatusString

The current Tourplan service status (following any changes in status caused by the GetSendSupplierMessage request).