HotelX Feature: Mapping

The mapping feature is used to change the supplier’s native codes to the Buyer’s own codes or vice-versa. There are these types:

  • Hotel Map
  • Board Map
  • Room Map
  • Rate Map
  • Amenity Map
  • Promotion Map
  • Room Description Map

Our mapping formats share a common structure. In order to load your maps you just need to follow the instructions below:

File Format

The file should be in the following format:

  • Encoding: UTF-8

  • File Name: [Context Source]_[Context Destination]_[entity]_map.csv

    • Context Source: it corresponds to the client code

    • Context Destination: it corresponds to the supplier code

    • 1 file for each supplier

  • Header Row: Code Source,Code Destination

    • Context Source: it corresponds to the client codes

    • Context Destination: it corresponds to the supplier codes

  • Delimiter: Comma (“,”)

  • Directory: /F[folder code]_[unique code]/HotelX_[unique code]/Maps/[entity]/

File Names

All map files must have the same name structure as follows - you need create a file for Context Destination

Entity File Name
Hotel [Context Source]_[Context Destination]_hotel_map.csv
Board [Context Source]_[Context Destination]_board_map.csv
Room [Context Source]_[Context Destination]_room_map.csv
Rate [Context Source]_[Context Destination]_rate_map.csv
Amenity [Context Source]_[Context Destination]_amenity_map.csv
Promotion [Context Source]_[Context Destination]\promotion_map.csv
Room Description [Context Source]_[Context Destination]\roomdescription_map.csv

Directories

Entity File Name
Hotel /F[folder code]_[unique code]/HotelX_[unique code]/Maps/Hotel/
Board /F[folder code]_[unique code]/HotelX_[unique code]/Maps/Board/
Room /F[folder code]_[unique code]/HotelX_[unique code]/Maps/Room/
Rate /F[folder code]_[unique code]/HotelX_[unique code]/Maps/Rate/
Amenity /F[folder code]_[unique code]/HotelX_[unique code]/Maps/Amenity/
Promotion /F[folder code]_[unique code]/HotelX_[unique code]/Maps/Promotion/
Room Description /F[folder code]_[unique code]/HotelX_[unique code]/Maps/Room/

Sample Files

Let’s suppose we have the following client code and supplier code, then we need to create one file for each supplier we have:

  • Client code: GUE

  • Supplier Code: BVJ

Name: GUE_BVJ_hotel_map.csv

Code Source, Code Destination
10,c11\#10
10000,7604
10000,1274249

How to use mapping

Nowadays, mapping can be used in Booking-Flow and Content APIs.

Use in Booking-Flow

There are two ways of using mapping in Booking-Flow: * If the context used in the query is different from supplier/s context that are used in the operation. In that case, HotelX will try to map all entities(hotel, board, etc.)(but amenities and promotions) to query’s context. * If the mapping plugin is requested (only boards, amenities and promotions), only entities requested in the query will be tried to map.

Context in plugins via parameters You can also specify a context for each of the plugins you’ll use in your query. This context will be the context in which you want to map the supplier codes. To do so, you’ll only need to specify it via parameters. This context, if specified, will have priority over the context specified via settings in your query. This in an example:

{
    "plugins": {
        "step": "RESPONSE_OPTION",
        "pluginsType": [
            {
                "type": "BOARD_MAP",
                "name": "board_mapX",
                "parameters": [
                  {
                    "key": "context",
                    "value": "yourContext"
                  }
                ]
            }
        ]
    }
}

Important: Mapping in booking-flow is only usable in Search service.

Here you have the nodes where you can find mapped codes in Search response:

Hotel: search.options.hotelCode (hotelCodeSupplier will contain the hotel’s code in supplier’s context)
Board: search.options.boardCode (boardCodeSupplier will contain the board’s code in supplier’s context)
Room: search.options.rooms.code (supplierCode will contain the room’s code in supplier’s context)
Rate: search.options.rooms.ratePlans.code (supplierCode will contain the rate plan’s code of the room in supplier’s context)
Amenity: search.options.amenities.code and/or inside rooms (amenitySupplierCode will contain the amenity’s code in supplier context)
Promotion: search.options.promotionCode (promotionCodeSupplier will contain the promotion’s code in supplier’s context)
Room Description: search.options.rooms.code (code will contain the description maped code and supplierCode will contain the room’s code in supplier’s context)

Examples of plugin that executes board and/or amenity and/or promotion mapping:

Boards:

{
    "plugins": {
        "step": "RESPONSE_OPTION",
        "pluginsType": [
            {
                "type": "BOARD_MAP",
                "name": "board_mapX"
            }
        ]
    }
}

Amenities:

{
    "plugins": {
        "step": "RESPONSE_OPTION",
        "pluginsType": [
            {
                "type": "AMENITY_MAP",
                "name": "amenity_mapX"
            }
        ]
    }
}

Promotions:

{
    "plugins": {
        "step": "RESPONSE_OPTION",
        "pluginsType": [
            {
                "type": "PROMOTION_MAP",
                "name": "promotion_mapX"
            }
        ]
    }
}

Room descriptions:

{
    "plugins": {
        "step": "RESPONSE_OPTION",
        "pluginsType": [
            {
                "type": "ROOM_MAP",
                "name": "room_map",
                "parameters":[{"key":"description", "value":"true"}]
            }
        ]
    }
}

Use in Content

The use of mapping plugin in Content is entirely different from Booking-Flow. Currently this is only available in Hotel-List query and only amenity map are available. In order to request mapping in content, it is necessary to query an specific field called mappings. This field is a list of mappings that will contain the code of the entity amenity in supplier context and the context of the supplier. It is also necessary to indicate the group code and destination context in query variables.

How to request inside Hotel-List for amenities:

 allAmenities(mapOptions: [{ groupCode: $amenitiesGroupCode, context: $amenitiesContext }]) {
              edges {
                node {
                  amenityData {
                    amenityCode
                    mappings {
                      context
                      code
                    }
                  }
                }
              }
            }

MapOptions is a list of {groupCode, context} pairs. The groupCode is the HotelX group assigned to your organization: (e.g. HotelX_…), and the context is the destinationContext you want to receive the codes in.
For each pair in this list, the mapping will be applied for each amenity. In other words, Hotel-List will change amenityCode to the context set in destinationContext

Other Maps

Room map by provider hotel

This plugin converts the room codes in the supplier’s context by hotel. It’s the same plugin (room map) as explained above, but it offers the possibility to map by supplier and hotel.

Format File

The file must be in the below format:

  • Encoding: UTF-8 
  • File Name: [Context Source]_[Context Destination]_room_map.csv
  • Header Row: Code Source,Code Destination,Code Hotel
  • Directory: /F[folder code]_[unique code]/HotelX_[unique code]/Maps/

If you are using a file of room map, it’s necessary to modify this file adding a new column. Please see the example below:

Sample File

Name: xtg_provider_room_map.csv Data:

Code Source,Code Destination,Code Hotel
1,X,A
1,Y,A
1,Z,A
2,X1,B
2,X2,C
3,X3,D
4,X4,
5,X5,

As you can see, the same file combined mappings with 3 values and mappings with 2 values. The rows with two values are mapped by supplier. The files with three values are mapped by supplier and hotel. It’s possible to use only the mapping by supplier hotel, in this case, your file only will have rows with three values.

Application

What happens if you use the combined plugin (room map and room map by provider hotel)? In this case, all the rooms with provider hotel map will be mapped to your context (the context put in the first value of file’s name (client context)) and the room codes that don’t have provider hotel map, will be mapped with provider map code (in case that exists). If no map codes are found, the option can be discarded (this rule is configurable, please contact us in order to change it and discard those options. By default, no options will be discarted).

Execution example

{
    "plugins": {
        "step": "RESPONSE_OPTION",
        "pluginsType": [
            {
                "type": "ROOM_MAP",
                "name": "room_map",
                "parameters":[{"key":"hotel", "value":"true"}]
            }
        ]
    }
}

Room Description map by provider hotel

It works the same way as room map by provider hotel plugin, but it uses the provider room description to map the room code in the hotelx response.

Execution example

In this example the context applied by the plugin will be used instead of the settings context.

{
    "plugins": {
        "step": "RESPONSE_OPTION",
        "pluginsType": [
            {
                "type": "ROOM_MAP",
                "name": "room_map",
                "parameters":[{"key":"description", "value":"true"},{"key":"hotel", "value":"true"},{"key":"context", "value":"CTX"}]
            }
        ]
    }
}

Default Codes

This feature allows to set a default code for each code in the source (provider) context. The entities that can have default codes are:

  • Board
  • Room
  • Rate
  • Amenity
  • Promotion
  • Room Description

Important: this feature only must be used in Booking-Flow. Only one default code can be assigned to each supplier context.
In order to use this feature, it is necessary to append the default code to the FTP.

Example file with default code

File name: sourceContext_destinationContext_entity_map.csv

Code Source,Code Destination
10000,7604
10000,1274249
MY_DEFAULT_CODE,*

MY_DEFAULT_CODE is the code that will be returned in response.

In the example above, all the codes of entity “entity” of provider with context destinationContext that are not found in the file, will be MY_DEFAULT_CODE in response.

Remember that, if you do not use default codes, in case that a mapping is not found, and the option is not discarded, in the response you will receive:

code: codeInSupplierContext
supplierCode: codeInSupplierContext

This feature is useful to control those codes which are not not mapped, and in case that you use aggregation plugins, all this options will be grouped in the same group and discarded.

Modifying data through FTP

Once mapping files are loaded, we can perform the following operations on them: Update and Delete