User Guide on the installation and use of Global Blue’s Middleware Agent.
Terms & Abbreviations
GB: Global Blue
PMS: Property Management System
POS: Point Of Sale
GUI: Graphic User Interface
URL: Uniform Resource Locator
Middleware Agent Overview
The Middleware Agent is a windows service bundled with a GUI that listens to incoming messages from PMS/POS and directs them to the correct configured terminal within the network and vice versa.
An example of how the Middleware Agent works is displayed below:
In simplified words the purpose of the Middleware is sit within the hotel network and to receive requests from one/many hotel systems, to translate the request and redirect the requests to the appropriate payment terminals.
Benefits & Purpose
Some of the key benefits and purposes of the Middleware are laid out below.
1. The Middleware provides a Dashboard/UI for the hotel to monitor and troubleshoot all their terminals on site.
2. The Middleware acts as 1 endpoint for the entire hotel for any and all transactions, this makes it easier for the hotel to manage and troubleshoot from just 1 point.
3. The Middleware is built for message translations from the Hotel System’s language into a language that the payment terminal understands and vice versa. This allows the hotel or the payment provider the chance to work with each other where they wouldn’t have been able to.
4. The Middleware is also a go-to for Hotel Systems that are in the cloud and need to direct the transaction onto a terminal within the hotel network
5. With the creation of the Middleware, a generic IPPI specification will be created for Terminal Vendors that enables the Middleware to talk to a whole host of terminals.
6. The Middleware also reduces the requirements for Terminal Vendors to be certified with certain Hotel Systems (e.g., OPI) since the Middleware will be responsible for the message translation and redirection.
7. Fault Tolerance – The Middleware can be quickly set up on multiple servers within the hotel network which greatly reduces the chances of a blackout during transactions.
8. The Middleware only process financial transactions with credit card token and no credit card data will be pass through.
Hardware & Software Requirements
The Middleware Service & Agent GUI require the following configurations to run smoothly.
Minimum Hardware Requirements
OS: Windows 10 and above or Windows Server 2012 and above
CPU: Quad Code CPU 2.0GHZ (or above)
RAM: 8GB
Storage: 250GB
Firewall Requirements:
Installation
The Middleware Agent can be installed using the “Global Blue Middleware.msi”. The installer requires Administrator privileges once it starts installation as it registers a service, creates folders under “ProgramData” and a start-up GUI application.
Installation screens are included below:
To verify that the installation has been completed successfully, the user should be able to see an icon created on the desktop as well as a windows service registered as “Global Blue Middleware Agent” with status “Running”.
Upgrade
Upgrading the Middleware is a simple process, the user needs to run the new installer and proceed with the same process as above.
A visual guide is included below:
The User may be asked to reboot if the installer cannot update the files correctly at the end of the installation.
The user can confirm that the upgrade was installed successfully by making sure the Windows Service is running/Middleware Agent GUI shows “Running and accepting requests” and Windows Program & Features shows the new version.
Removal
The Global Blue Middleware can be uninstalled like any other application installed on a Windows machine.
Note: Make sure the Services window is closed as it may interfere with the removal of the application.
The prompts for the removal of the application are highlighted below:
A user may be required in certain cases to reboot the machine in case the uninstaller cannot remove the services, the usually cause of this is if the Services window is open.
Once clicking “OK”, the application should uninstall the service and the GUI.
Log Locations & Config Locations
The log files for the Middleware are stored under C:\ProgramData\Global Blue\Middleware\log with the extension of .log.
This contains all logs that are produced from the Middleware Agent.
Config Locations
Configuration files for the Middleware Agent are also stored under C:\ProgramData\Global Blue\Middleware. This includes the configuration.json, sites.json and transaction.json files.
1. The configuration.json is the main file that stores all the configuration for the application to connect out to cloud/backend service. Sensitive information is encrypted using AES256 to protect the applications functionality.
The Middleware can also run in offline mode, but requires a download of the configuration.json file from the Dashboard. The file must be placed in the C:\ProgramData\Global Blue\Middleware folder for the Middleware Agent to function.
The configuration file also contains information about the Proxy server (if present) and can be modified from the file directly to match the requirements.
2. The sites.json file contains the information about the sites assigned to the Middleware Agent such as the endpoints of the terminal, type of terminal, endpoint of the PMS/POS, etc.
3. The transactions.json file temporarily holds the transactions that have passed through the Middleware Agent. The transaction file is only populated if the Middleware Agent is unable to communicate with its API endpoint and needs to continue functioning. The file is flushed as soon as outward connectivity is restored with the API.
Application Logging
The application also logs internal messaging for easy debugging of problems, these logs are stored at C:\ProgramData\Global Blue\Middleware\log.
A variety of difference log types are available as below:
Files named as middleware-****-**-**.log record the start up of the Agent, the requests passing through the Agent and also the configuration that is being loaded onto the Middleware Agent.
Files named as .****************************.log record the names of the middleware-****_**-**.log to track the last 7 days’ worth of files.
Files named as ui-****–**-**.log records the data from the Middleware Agent UI and its paths.
Files named as startup-****-**-**.log records data from the start-up of the Middleware service.
Windows Service
The Middleware Agent installs a Windows Service while completing the installation process. The service is installed under the name of Global Blue Middleware Agent or service name as gb-middleware-agent and starts up automatically on installation.
UI Application
The Middleware Agent comes bundled with a GUI Application which can be used to show the connection status, a configuration overview, quick configuration option without having to change the configuration.json file. The GUI Application runs in the system tray as a minimized application.
NOTE: Any configuration change on the Dashboard or Middleware Agent requires a restart of the Middleware Service.
A visual guide of the GUI is highlighted:
The General Configuration page allows the user to update Site Codes, Logging Level and Connection Mode.
Site Codes: This comma separated field stores the Site short code that has been set up on the dashboard. This means that the agent can only connect and fetch configuration of this site.
Logging Level: This is useful when the user needs more information on what is happening within the agent. Logging levels available are Debug, Info, Warning, Error. For a normal user, the Info level logs collect all the required information to help resolve issues.
Connection Mode: The Middleware Agent is capable of running by itself without having to connect outside the network to the API to fetch new config.
The Connectivity page allows for a deeper configuration of the Middleware Agent such as the Azure API URL, Azure Key and other configuration to allow the functioning of the application.
The About section has basic information such as the OS that the application is running on and the Home Drive where the application is installed.
