Skip to main content

Preference

The Preference plugin works by prioritizing options that align with your preferences and presenting them in a preferred order. This plugin is particularly useful if you're using Hotel-X in aggregation mode and want to prioritize certain options over others, thereby aligning the search results with your preferences. For instance, if you aggregate your search options by hotel and board, and there are three providers offering different prices for the same hotel and board, the system would typically return the cheapest option. However, you might want to give preference to one provider over another for certain hotels. With this plugin, you can load a rule that applies a percentage tolerance to a specific provider for those hotels. There are various criteria for applying these preferences, which are detailed below.

This plugin follows a sequential process, where rules are checked one by one until a matching rule is found. When a match is found, the process stops, and your preference is applied. If no matching rule is found, the option will be validated.

To determine matches, the plugin uses the clientTokens field, which identifies the provider and helps filter which business rules can be applied to a specific request you send.

Preference Plugin Workflow

  1. Starts getting all the args set by the client in the query, like options, parameters (primaryKey among others), client tokens, etc.

  2. Gets the rules stored in database which will establish which options will be added or discarded based on several factors as % of tolerance of the price, options status, hotelcodes, supplier, etc.

  3. Builds a group function which will help to clasify the options slice in 'n' different groups based on the primary key established in the query by the client and the rules stored in the data base (SFTP preference file).Sorts the options in price order (from cheap to expensive).

  4. Go over each option and group them by primary key index. However not all the options will be filled in these aggrupations. This is where the rules come into play. To determine if an option will be discarded or not we have to check the group function which does the following:

    • If it is the first option in the pk index, this option will be automatically added.
    • If the rule says that the competitors has to be discarded, all the options of that pk index will be discarded except for the first (the cheapest).
    • If it isn't the first option and there aren’t any rule that matches the option, this option will be discarded.
    • If it isn't the first option and the price is higher than the tolerance % established in the rules for that pk index, the option will also be discarded.
  5. With the resulting options grouped by pk indexes, finally collects all of them and return them to the service process which has used the plugin.

Example

Preference Rule Loaded: Tolerance Percentage = 1% for all SUP1 hotels and 'filterCompetitors' is enabled.

Scenario:

  • Supplier SUP1 offers 126€ for Hotel Santo Domingo (Double Room, All Inclusive).
  • Supplier SUP2 offers 125€ for the same hotel and room type.

By default, SUP2 wins because it has the lowest price.
However, with the preference rule applied:

  1. We first group all options with the same aggregation primary key (Hotel Santo Domingo - Double Room - All Inclusive).

  2. Since there is a preference rule for SUP1 hotels, we apply the tolerance check:

    Formula:
    Cheapest option price * (1 + tolerance%)
    125€ * (1 + 1/100) = 125€ * 1.01 = 126.25€

  3. Since 126.25€ is higher than 126€ and 'filterCompetitors' is enabled, the SUP2 option is discarded, making SUP1 the only winner.

If 'filterCompetitors' were disabled, SUP1 would be added to the group, and both options would be returned in the results.

To get started with the Preference plugin, follow these simple steps:

1. Create and Upload your Preference File

To get started, create your preference file in the correct format and then upload it to your SFTP account. We've provided a template file below ⬇️ to help you with this process. Just click on the file name, add your own rules, save it in CSV format, and then upload it to the corresponding folder in your SFTP.

sftp.xmltravelgate.com

📁HotelX
     📁HotelX_0000
         📁BusinessRules
             📄BuyerContext_sequential_preference.csv

note

If you need assistance with requesting your credentials to access the SFTP server, determining the endpoint and directory format, or learning how to upload, update, and delete SFTP files, please refer to the overview section of Plugins.

File Format Specification

  • File Name: BuyerContext_sequential_preference.csv
  • Directory: HotelX/HotelX_0000/BusinessRules
  • Delimiter: Comma (,)
  • Header Row:
    • RuleId (mandatory): Rule identifier
    • ClientTokens (mandatory): Identifier provided by the client that is used to filter which business rules can be applied for the sent request
      • Separator for multiples codes in the same row: Semicolon ;
    • SupplierCodes (mandatory): Supplier codes you want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • NotSupplierCodes (mandatory): Supplier codes you don't want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • BookingDateFrom: Booking date from (yyyy-mm-dd)
    • BookingDateTo: Booking date to (yyyy-mm-dd)
    • StartDateFrom: Start date from (yyyy-mm-dd)
    • StartDateTo: Start date to (yyyy-mm-dd)
    • HotelCodes: Hotel codes you want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • NotHotelCodes: Hotel codes you don't want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • ChainsCodes: Chain codes you want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • NotChainCodes: Chain codes you don't want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • DestinationCodes: Destination codes you want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • NotDestinationCodes: Destination codes you don't want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • Status: Option status (OK, RQ) you want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • NotStatus: Option status (OK, RQ) you don't want the preference to be applied to.
      • Separator for multiples codes in the same row: Semicolon ;
    • Percentage (mandatory): Commission value, decimal separator must be point .. Percentage represents the tolerance you allow over the net price to avoid discarding the option. In other words, options that meet the criteria of this rule will not be discarded, even if they are up to X% more expensive than the cheapest option.
    • FilterCompetitors (mandatory): true/false value. If set to true, it means that if an option exists that meets the criteria of this rule, only that option will be kept, and all others will be discarded. This ensures you only retain the option that follows the rule's criteria.
📹Learn how to change the format of the csv file in order to edit and save it

2. Execute Preference Plugin in your Query

Once you've uploaded your preference file, to use the plugin add the following field to the settings node of your request. Note that preference plugin can just be executed in search query. In order to successfully execute the preference plugin, you will need to create the request with the following variables.

  • step: "RESPONSE"
  • type: "PRE_STEP"
  • name: "preference"
  • parameters:
    • primaryKey: Criteria used to aggregate, separated by commas. For example: "hotel, supplier, board". Possible values are:
      • hotel
      • supplier
      • board
      • binding
      • cancelPolicy
      • currency
      • market
      • payment
      • promotion
      • rateRules
      • refundable
      • room
      • supplement
      • surcharges
      • ratePlan
      • status
"settings": {
"plugins": [
{
"step": "RESPONSE",
"pluginsType": {
"type": "PRE_STEP",
"name": "preference",
"parameters" : [
{
"key" : "primaryKey",
"value" : "hotel,board,room"
}
]
}
}
]
}