Installation and configuration

System Requirements 

  • Operating systems
    • Microsoft Windows 8, 7, Server 2008, Vista, Server 2003, or XP
    • Linux
      • kernel 2.6.16 or above
      • glibc 2.4 or above
      • NPTL 2.4 or above
  • Hardware
    • 64‑bit: Any x64 (AMD64/Intel 64) or compatible
    • 4GB of RAM [at least]
    • 40GB of hard drive space
    • 2 processors [at least] 
  • Internet connection
    • Cable or DSL

 

IMPORTANT: APITUDE – Scan Service has not been certified under virtualized environments like Amazon EC2.

To install the Cache API – Scan Service first download the software installer provided by your XML Support Agent. The installer is approximately 40 MB in size. You must have administrator privileges on your server.

NOTE: We recommend the ratio between processors and RAM memory is 3:1 maximum. This means that if you have a system with 20 processors and 10GB RAM, you could include in .properties file (processors) maximum 6 processors.

Download our Software

Installation Guide

Windows

After download execute the file cache-scan-service-setup.exe.

 

You must accept the terms of the license agreement in order to proceed with the installation and click next to proceed with the installation. Click next to proceed with the installation.

Select the installation folder. You can change the default location clicking Browse. After selection please click Next.

It is necessary you select the location of the properties file you will use for Scan. You can use Browse button to find the correct location. After selection please click Next.

NOTE: If you have never used CacheAPI - Scan before, in this step you need to specify only the directory where the .properties file will be (the installation does not check if the .properties file is located there). Once the installation is completed, you will need to get the .properties file (aif2-scan.properties) located in CacheScan folder (C:\Program Files\CacheScan\), fill the necessary fields and paste it into the directory you specified during the installation.

Select the port you will use to connect to Scan and click Next.

Select the Start menu folder for the Cache API – Scan service and click Next.

Installation progress.

The installation has been completed successfully. Click Finish.

 

In order to start the service you must click Start/Programs/HotelBeds/Cache API – Scan Service/Start cache-scan-service

If you want to stop the service you must click Start/Programs/HotelBeds/Cache API – Scan Service/Stop cache-scan-service

NOTE: The service is called cache-scan-service.exe in the Windows Task Manager. It is automatically started when Windows starts.

IMPORTANT

You must set the user properties before the first start.

Linux

After download execute the file ./cache-scan-ws-setup.

You must accept the license agreement.

-- CACHE API - SCAN SERVICE --

1.      DEFINITIONS

"Software" the accompanying software and associated data.

"Licensee" in this license agreement, you are referred to as "Licensee" or

"You" or "The User."

"Licensor" Hotelbeds Group

"Software Internal Data" all data used internally by Software to calculate

availabilities or inform of inventories

"License" This License Agreement

2.      ACCEPTANCE AND AGREEMENT

This Commercial License Agreement, including the grant of license and disclaimer of warranties contained herein will become a valid and binding agreement of the parties.

3.      COMMERCIAL USE GRANT

Licensor grants Licensee a non-transferable license to use the Licensed Software which must retain all of the original proprietary notices. Licensee may not disclose the internal data of the software. The use of the software is restricted to software data inputs and outputs. Software internal data shall not be disclosed or manipulated.

4.       TERMINATION

Without prejudice to any other rights, Licensor may terminate this Agreement if Licensee breaches any of its terms and conditions. Upon termination, Licensee shall destroy all copies of the Licensed Software held or controlled by Licensee.

5.      OWNERSHIP

Title to and ownership of the intellectual property rights in the Licensed Software, all copies thereof, and all documentation related thereto, belongs to the Licensor. The Licensee agrees to take all steps which are reasonably necessary to protect the Licensor's ownership rights to the Licensed Programs in the conduct of the Licensee?s licensed commercial activity with the Licensed Programs, and will not take any action to jeopardize, limit or interfere in any manner with such rights.

6.      DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY

The Software is distributed and licensed "AS IS". The Licensor does not represent or warrant that the functions contained in the Licensed Software will meet the Licensee?s requirements or will operate in the combination selected by the Licensee or that the operation of the Licensed Software will be error free. In no event shall the Licensor be liable for any incidental, indirect, special or consequential damages whatsoever (including, but not limited to, lost profits or interruption of business) with respect to, arising out of, in connection with, or related to this Agreement.

----------------------------------------

I accept the agreement

Yes [1], No [2]

1

This will install Cache API - Scan on your computer.

OK [o, Enter], Cancel [c]

o

Then you select the path where the software will be installed

Where should Cache API - Scan be installed?

It is necessary to specify a path for the .properties file.

NOTE: If you have never used CacheAPI - Scan before, in this step you need to specify only the directory where the .properties file will be (the installation does not check if the .properties file is located there). Once the installation is completed, you will need to get the .properties file (aif2-scan.properties) located in CacheScan folder (C:\Program Files\CacheScan\), fill the necessary fields and paste it into the directory you specified during the installation.

The specified folder must contain aif2-scan.properties file

[]

The port from where you will should be included

The specified port will be used to run ScanServer

ScanServer port

[]

Xxxx

Create symlinks?

Yes [y, Enter], No [n]

Y

Select the folder where you would like Cache API - Scan to create symlinks, then click Next.

[/usr/local/bin]

Extracting files...

Setup has finished installing AIF2 on your computer.

Finishing installation...

 

NOTE 1: You must set the user properties then start service.

NOTE 2: Memory dedicated to the CacheAPI - Scan tool will no longer be configured in .properties file (max.memory). Instead you need to go to the installation folder (C:\Program Files\CacheScan\) and open the file cache-scan-start.vmoptions in the root of the installation folder. Once you open this file, you will see the value -Xmx2G, which means that there are 2Gb dedicated by default. You can change this value with Gb (G) or Mb (M), for example, -Xmx20G (20Gb of memory dedicated) or -Xmx1800M (1800Mb of memory dedicated).

Uninstall 

Windows

Go to Start/Programs/HotelBeds SLU/Cache API – Scan Service/ and click the Uninstall button.

Please, be sure the windows service is not registered in the Windows Services panel.

Linux

Go to the installation path and run the Uninstall script

Updates

With Cache API – Scan Service is possible to get updates automatically.

First you will be informed via email that a new update will be available. We will inform you about a concrete date to do the update.

 

Windows

In order to get an automatic installation of the Cache API – Scan Service you need to open the Cache API – Scan Service setup, and it will inform you about new version:

 

If you do not want to make the update at this moment, you can cancel the update and keep working with the same previous version until you can do it (please note that updates must be done in order to guarantee the correct working of the service. If they are not done, we will not be responsible of the malfunctioning of the service.).

In case, you want to cancel the update to do it later, you can just cancel it and the service will work with the previous version (every time you start the application, a reminder about the new version will prompt):

If you go on with the update and push the button Next, you will see the progress of the downloading:

 

When the download of the new version is finished, the app will inform you about the new installation of the update just downloaded. As before, it is possible to postpone it or go on with it. We recommend to go on with the installation:

 

Linux

 In order to get an automatic installation of the Cache API – Scan Service you need to open the Cache API – Scan Service setup, and it will inform you about new version:

If you do not want to make the update at this moment, you can cancel the update and keep working with the same previous version until you can do it (please note that updates must be done in order to guarantee the correct working of the service. If they are not done, we will not be responsible of the malfunctioning of the service.).

In case, you want to cancel the update to do it later, you can just cancel it and the service will work with the previous version (every time you start the application, a reminder about the new version will prompt):

If you choose to install it, you would need to manually execute the installer you have just download:

You can select if you want to update the current scan you are using or install it in a new folder (new installation).

Configuration

The Cache API – Scan Service set up is very easy and only required to set the user information and scan server identifier to run the service. Default parameters are configured during the software installation.

All the configuration parameters are included in the aif2-scan.properties file located in the PATH~TO~INSTALLATION/aif2-scan.properties

Parameter

Mandatory

Default value

Min

Max

Description

user

YES

-

 

 

Your HotelBeds Interface XML credentials. Mandatory and only for Nexgen (XML 2) clients

apitude.api.key YES - Your Hotelbeds APITUDE APIkey. Mandatory and only for APITUDE clients
apitude.shared.secret YES - Your Hotelbeds APITUDE Secret code. Mandatory and only for APITUDE clients

path.results

YES

/aif2-scan/output/

 

 

Path to the folder where the Availability output file and Inventory Output file will be stored

The path is absolute

host.data

YES

testaif2.interface-xml.com

 

 

Host to the HotelBeds Cache API service

allow.incremental

NO

false

 

 

Allow the system for incremental update requests

We do not recommend incremental feature if you want to calculate a big Scan Plan

force.full.on.startup

NO

true

 

 

Once the service is started a full request will be sent in order to update data

refresh.data.update

NO

120

 

60

 

 

Update frequency of the HotelBeds DataBank. Time in minutes

generate.inventory

NO

false

 

 

If value is false the Inventory Output File will not be generated

If value is true the Inventory Output File will be generated

wait.request

NO

1000

 

 

Time in milliseconds to wait until get response in the ScanValuedAvailRQ operation.

If the system can not process the request in this time, the response status will not be READY.

processors

NO

Maximum allowed

 

1

 

8

Number of processors dedicated to the service

max.memory

NO

1073741824

 

 

Maximum memory in bytes to manage destinations

proxy.host

NO

None

 

 

Proxy host if required

proxy.port

NO

None

 

 

Proxy port if required

proxy.user

NO

None

 

 

Proxy user if required

proxy.pass

NO

None

 

 

Proxy pass if required

scan.id

NO

1

 

1

 

4

Scan server identifier

scanplan.generation

NO

false

 

 

Inform if automatic ScanPlan will be generated when service started

scanplan.destinations

NO

-

 

 

Inform the ScanValuedAvailRQ/ScanPlan/Destination@code with the list of destinations.

If empty, then all your available destinations will be included

scanplan.frequency

NO

8

1

 

Inform the time in hours between the Scan Plan executions

If the complete Scan Plan calculation takes 10 hours and the scanplan.frequency is 8, the Scan Plan will start again automatically.

If the complete Scan Plan calculation takes 4 hours and the scanplan.frequency is 8, the Scan Plan will start again after 4 hours (8-4) automatically.

scanplan.duration

NO

90

1

360

Inform the ScanValuedAvailRQ/ScanPlan/Date@duration

scanplan.paymentmodel

NO

BOTH

 

 

Inform the ScanValuedAvailRQ/ScanPlan@packaging

scanplan.packaging

NO

YES

 

 

Inform the ScanValuedAvailRQ/ScanPlan@packaging

scanplan.hoteloccupancylist

NO

30:30,30:30,30-8

 

 

Inform the ScanValuedAvailRQ/ScanPlan/HotelOccupancyList/Ocupancy age and pax type

Each Ocupancy is separated by :

Each pax type is separated by -

Each pax age is separated by ,

Examples:

  • 2 adults
    • 30,30
  • 2 adults, 2 adults + 1 child
    • 30,30:30,30-8
  • 2 adults (20 and 30 years old) + 2 childs (8 and 12 years old)
    • 30,30:30,30-8,12

scanplan.lengthsofstay

NO

1,2,3,4,5,6,7

 

 

Inform the ScanValuedAvailRQ/ScanPlan/LengthsOfStay/LengthOfStay

lite

NO

false

 

 

Enables lite version

lite.promotions

NO

false

 

 

Shows promotions info (lite version needed)

lite.cancellation.fees

NO

false

 

 

Shows cancellation fees info (lite version needed)

lite.handling.fees

NO

false

 

 

Shows handling fees fees info (lite version needed)

lite.capacity

NO

false

 

 

Shows capacity room info (lite version needed)

rules.mode YES true Mandatory to use the new version of Cache API - Scan

You can add your own remarks with the # character at the beginning of the line.

Multi-server setup

The scan.id parameter identifies each one of the servers that run the Cache API – Scan Service and aims to allow synchronization downloading data changed from Hotelbeds data bank.

When working in incremental mode it should take into account that the updates between two requests for the same product (destination or hotel) must be on the same server.

Example:

Suppose the case of having two instances of Cache API – Scan Service running on two different servers: scan.id=1 and scan.id=2.

Fist we run a single request on the server identified as scan.id=1 and setting the parameter update=”false”. As result in the output file will appear all combinations of prices requested.

After an hour, we run the same ScanPlan on the server identified as scan.id=1, but this time indicating the parameter update=”true”.

Now as result in the output file will appear only the data that has changed since the first run.

If the update requested would has been executed on a different server (scan.id=2), instead of appear only the data that has changed since the first run, will appear all combinations of prices requested.

This is because information regarding changes is stored independently on each server.

Scan plan generation

The scanplan.generation parameter allows pre-building a scan plan from properties file from Cache API – Scan Service that will be sent automatically after some time (frequency).

When working in incremental mode it should take into account that the updates generated will be regarding the scan plan you defined on fields fromscanplan.generation.

This functionality will start generating the file as soon as the download of the contracts is done (when the Cache API – Scan Service is started, the service automatically download the contracts of all the destinations registered). Because of that, it is not necessary to use the Debug mode (http://servername:port/aif2-scan-ws/debug), as you will use the scanplan.generation instead.

Example:

Suppose the scan plan to get is the following through ScanValuedAvailRQ in Debug mode:

<ScanValuedAvailRQ xmlns="http://www.hotelbeds.com/schemas/2005/06/messages">
       <ScanPlan update="false" packaging="BOTH" paymentModel="BOTH">
               <SourceCountry>EN</SourceCountry>
               <Date from="20140623" duration="30"/>
               <ScanList>
                       <Scan>
                               <Destination>PMI</Destination>
                               <HotelOccupancyList>
                                       <Occupancy>
                                                       <AdultCount>2</AdultCount>
                                                       <ChildCount>0</ChildCount>
                                       </Occupancy>
                               </HotelOccupancyList>
                               <LengthsOfStay>
                                       <LengthOfStay>2</LengthOfStay>
                                       <LengthOfStay>3</LengthOfStay>
                                       <LengthOfStay>5</LengthOfStay>
                               </LengthsOfStay>
                       </Scan>
               </ScanList>
       </ScanPlan>
</ScanValuedAvailRQ>

In properties file, configuration would be the following:

scanplan.generation = true
scanplan.destinations = PMI
scanplan.frequency = 2
scanplan.duration = 30
scanplan.paymentmodel = BOTH
scanplan.packaging = BOTH
scanplan.hoteloccupancylist = 30,30
scanplan.lengthsofstay = 2, 3, 5

Where scanplan.frequency informs the time in hours between the Scan Plan executions, so if for example the complete Scan Plan calculation takes 10 hours and the scanplan.frequency is 8, the Scan Plan will start again automatically, but if the complete Scan Plan calculation takes 4 hours and the scanplan.frequency is 8, the Scan Plan will start again after 4 hours (8-4) automatically.

Scan Lite

The lite parameter reduces the current output file size around 60-80%. This reduction will take effect over the size of the file, not the time of the generation process of the file.

With this functionality, you can select the information you want to receive in the output file regarding promotions (lite.promotions), cancellation fees (lite.cancellation.fees) and handling fees (lite.handling.fees).

For those optional fields removed from output file through this parameter, you will receive the field empty.

NOTE: This improvement will take effect over optional fields only if lite parameter is true, if not, even some optional fields are selected to be removed, the output file will contain all the information including those optional fields.

Example:

Suppose not interested to get neither cancellation fees nor handling fees but interested on promotions in output file. It is necessary to activate the lite parameter in properties file and put lite.cancellation.fees and lite.handling.fees to false in order to they do not appear in output file (as mentioned above, the field will appear empty) but lite.promotions will have the value true instead.

#Lite version
lite = true

#Shows promotions info (it takes effect only if lite version is activated)
lite.promotions = true

#Shows cancellation fees (it takes effect only if lite version is activated)
lite.cancellation.fees = false

#Shows handling fees (it takes effect only if lite version is activated)
lite.handling.fees = false

#Shows capacities of the room (it takes effect only if lite version is activated)
lite.capacity = false

Environments

The Cache API – Scan Service can be used with two different environments: TEST and LIVE.

The TEST environment is connected to the same TEST environment used in the XML Interface Specification. This way you will be able to test both systems with the same data base source.

On the other hand, with the LIVE environment you will get all the real information from HotelBeds Databank.

Due to IP restriction control, please provide your XML Support Agent the IP/IP’s from which you are planning to run the Scan Service. HotelBeds will grant your installed instance the access to our systems.

In order to switch between environments you need to change the corresponding set up parameter in the configuration file. Please, note that no update requests for Scan Plan will be supported once you change the environment and a full Scan Plan calculation will be automatically processed by the service.

Access

Once the Cache API – Scan Service is installed and running you have to open a direct HTTP connection to the interface and POST valid xml requests according to the XML Schema definitions.

To connect to the interface using HTTP direct connection you must use the following URL:

  • http://servername:port/aif2-scan-ws/scanservice

where servername corresponds to the IP or hostname of the server in which the Scan Service has been installed.

You must send the HTTP POST request with a parameter called xml_request with the XML message [ScanValuedAvailRQ or ScanDetailRQ].


WORKFLOW

Create a new Scan Plan

This workflow generates a new Scan Plan. As it is the first time you create this Scan Plan then a full scan results will be generated.

Preconditions

  • The Cache API – Scan Service is installed successfully

The first step consists in create a ScanValuedAvailRQ message with all the required parameters: destination, occupancies, lengths of stays, etc… You have to send this message to the Scan Service.

The ScanValuedAvailRS has 3 different statuses: when ERROR you have to correct the request and start the process again. When READY the Scan Plan is finished and you can get the output results in the response message. Otherwise, when RUNNING then the Scan Plan is in process by our service and a Scan Plan Unique Identifier is informed in the response message.

If you got the RUNNING status, then in next step, you send a ScanDetailRQ operation with the Scan Plan Unique Identifier retrieved. The same 3 different statuses may appear in the           response message: when READY the Scan Plan is finished and you can get the output results in the response message. When RUNNING then the Scan Plan is still in progress. You have to wait a period of time and start again the step 4 sending the same ScanDetailRQ.

When ERROR status then you have to check the error message and contact with HotelBeds.

We recommend setting up the timer between ScanDetailRQ greater than 1 minute.

Get Update Scan Plan

This workflow generates the updated results. It will automatically calculate the new prices, eve if never were requested. This way you are able to process only the differences between the full Scan Plan, with only the updated information from our DataBank: change in allotments, new prices, etc…

Preconditions

  • The Cache API – Scan Service is installed successfully 

The workflow is mainly the same as the full scan request workflow.

The only difference is that you have to provide the ScanPlan@update attribute set to true.

The rest of the workflow is the same as explained in the full scan.

Note that if there are new destinations or new hotels, the Scan Service will automatically generate the consolidated results.

If the availability output file has not informed the Net Price field, it means that this availability has expired and is not more available.

We recommend setting up the timer between ScanDetailRQ greater than 1 minute.

Add or remove destinations

In order to add or remove destinations, please contact your XML Support.

Limit of ScanValuedAvailRQ active requests

When a ScanValuedAvailRQ request is sent, care must be taken not to exceed the total limit of active requests allowed by the service. 
When this limit is exceeded, on the ScanDeatilRS response will show the error code: REQ-0001, which means that the request exceeds the limit of active requests and it must retry the sending.

This limit is calculated using the following criteria: 
Total active request (queued + processing) = Number of processors (processors) * 5

Limit example:

  • Scan Service configured with 4 processors. The total active requests send to the Scan Service must be lower than 4 * 5 = 20 requests.

Error example:

<ScanValuedAvailRS xmlns="http://www.hotelbeds.com/schemas/2005/06/messages">
  <AuditData>
    <Status>ERROR</Status>
    <TimeStamp>2013-03-06 13:00:47</TimeStamp>
    <Release>0.10.3</Release>
    <SourceData>38578004</SourceData>
    <MessageList>
      <Message type="ERROR" code="REQ-0001">The request exceeds the limit of active requests</Message>
    </MessageList>
  </AuditData>
</ScanValuedAvailRS>

 


Docs Navigation