Aloha POS integration to Mews Property Management System (PMS) offers a possibility to process payment data based on the items bought at the Aloha Point of Sale (POS, interchangeable with FOH). Transaction data are sent to the Aloha Payment Solution (APS) and onwards to PMS software for authorization.
At the same time, it shall be archived on the Back of House (BOH) machine. As a part of the integration, there is a management tool to configure the payment solution as well as the PMS plugin.
All transactions (not including any sensitive data, like card numbers) are stored in a database on the BOH.
1.1. Supported Features
- Inquiry Operation
- Payment Operation
- Void Operation
- Custom Category Mapping
- Limited support for 3rd party handhelds, (e.g. Time Is Money (TIM))
1.2 Out of Scope
- Support with other handhelds (Aloha Mobile, etc.)
- Support for other Aloha Connect clients (Kiosks etc.)
- Refund support
- Cashback support
- Day Parts
- Hybrid tenders
- End of Day (EOD) Settlement
- Combined modifiers
- Any other features that are not defined within this document
2 Solution Integration
2.1 APS Installation
‘AlohaPaymentSolutionSetup.exe’ and accepting the licensing terms, the next installation setup step is the Database Settings. This step is optional and is only required if recording transactions and running reports is necessary. The option to not enable “Use SQL database” is available if this utility is not needed. Otherwise, set the correct address of the SQL server.
The APS installer will automatically test the connection with the database. If it is successful, it will state “Connection to DB succeeded” and the button “Next” will be visible. If “Use SQL database” is not enabled, the APS installer will create a local
‘ps.db’ (SQLite database) file for its internal use.
When the database is correctly created, continue the installation steps. The next step is selecting the plugin(s) desired. For this integration, “Mews” should be selected and enable “Install APS only on BOH”. Upon completion, the installation should create “NCR Aloha Payment Solution” ApsService service. If this service is not running, restart the PC or check if the service is running in Windows. If it is not, start it manually.
NOTE: When making any changes within APS, a restart of ApsService is required for the changes to take effect.
Then select the plugin(s) you want to install and push the button to install it.
2.2 Aloha inTeGration Installation
ATG requires Microsoft WSE 3.0 for its installation. This software can be downloaded from http://www.microsoft.com/download/en/details.aspx?id=14089. While installing WSE, accept the license agreement and select Developer version. When WSE is installed, download and run the ATG installation package on your BOH machine. Accept the license agreement.
After installation, ATG will be automatically distributed to the POS, if the BOH can be reached by pc name from the POS.
2.2.1 Configure ATG
“AlohaTransactionGateway.cfg” file in %IBERDIR%\DATA folder. Configure the following:
- Specify if Quick Service(IberQS.exe) or Table Service(Iber.exe) is used:
“<AtgSetting key="InterfaceServerName" value="Iber.exe" />”
- Set value to match environment variables:
“<AtgSetting key="NumTerms" value="2" />”
“<AtgSetting key="InterfaceServerId" value="TermNumber" />”
- Set value to ‘true’:
“<AtgSetting key="AutoStartAtgService" value="true" />”
“<AtgSetting key="AtgConnect" value=”true" />”
- Set the key “TERMSTR+TERM” to match terminal in use and the associated IP Address:
“<AtgSetting key="IpAddressToBind"> <AtgSetting key="TERMSTR+TERM" value="192.168.X.X" /> </AtgSetting>”
Save the file to %IBERDIR%\DATA and NewDATA, run the ATG installer on BOH. When the installation is finished on BOH, restart all FOHs, this will deploy ATG to them. When Aloha 15.1 is installed, use RAL for the ATG deployment. When using the RAL, ATG should be automatically deployed and registered.
Note that ATG runs as "NCR Aloha Transaction Gateway" (ATGService), a service. In case any changes are applied to the
“AlohaTransactionGateway.cfg” the configuration file, the service needs to be restarted. It is recommended to restart the "NCR Aloha Transaction Gateway Helper" (AtgHelper) service instead of ATGService itself.
2.3 Aloha CFC Setup
For the proper run of the PMS payments integration, it is necessary to configure several settings in the Aloha Manager (AM) or Configuration Center (CFC). In the following text, CFC configuration is described; AM settings are analogous.
2.3.1. Configure the Tender(s)
Open CFC and navigate the Tab Menu at the top.
Maintenance > Payments > Tenders.
To create a new tender, on the Menu along the right side, select the Drop-Down menu on ‘New’. Select ‘Property management’ and then ‘OK’. A New Tender Configuration panel should replace the current one.
Configure the Tender with the following:
- "Number" = <SelectAvailableNumber>
- "Name" = <CustomNameForButton>
- “Button Position” or “First available button position” = Use either to place the button as desired. "Report as" = "Current"
- "Default amount behavior" = <Preference>
- Also, Enable the following:
o Print Check on Close
o Close check upon Payment
o Other options that are desired.
- “PMS tender ID” = Tender “Number” that was selected in the previous section.
- Enable the following:
o Require identification
o Print on Check
- “Prompt” = <DesiredTextAtPrompt>
- “Minimum” = <DesiredValue>
- “Maximum” = <DesiredValue>
- “Valid” = Select ‘Exclude’
2.3.2 Setting Interface terminal
For payments, there needs to be at least one Interface Terminal configured.
Configure the Interface terminal with the following:
- “Name”: APS + number of interface terminal, in this case, it is “APS 1”
- “Interface host”: Name of POS terminal, in this case, it is “Spacemeubel”
: Interface Terminal reserved for use with MEWS APS plugin should be located on a non-BOH terminal. This also allows other plugins to utilize their Interface Terminal(s) on the BOH without causing conflicts. (ex. TIM)
Save all configuration changes and refresh data in CFC > Utilities > POS > Refresh POS data
2.4 Aps Management, Configuration
Once APS is installed, the plugin is now ready to be configured. To configure, go to ‘bootdrv/APS/’ and run APSManagement.exe. It may also be present in the Start Menu as ‘NCR APS Configuration’. This will open the ‘APS Management’ interface.
2.4.1 APS Logging Level for GDPR Compliance
For General Data Protection Regulation (GDPR) compliance, the logging level must be set no higher than “INFO” to prevent sensitive data remaining on devices. The logging level is configurable in 2 places in APS, APS Core Configuration and APS Plugin Configuration.
The appropriate files to configure are in the BootDrv\APS directory. For each configuration file, locate
<level value=”” /> and ensure it is set to “INFO”.
- To set logging level in
‘Debout.AlohaPaymentSolutions.[DATE].[TERM].txt’, navigate to BootDrv\Aps directory and edit
- To set logging level in
‘Debout.ApsMewsPlugin.[DATE].[TERM].txt’, navigate to BootDrv\Aps\Plugins directory and edit
“ApsPluginMews.dll.config” is configured with debug level “INFO”. This file is found in BootDrv\APS\Plugins\. The key to edit is “level value”.
<level value="INFO" />
<level value="INFO" />
“AlohaPaymentService.exe.config” is configured with debug level “INFO”. This file is found in BootDrv\APS. The key to edit is “levelMin value”.
<levelMin value="INFO" />
<appender name="RollingLogFileAppender" type="NCR.Intl.Common.Logging.ExtendedRollingFileAppender">
<levelMin value="INFO" />
<acceptOnMatch value="false" />
2.4.2 Configure APS
The following Sections should be configured:
- “Default PMS plugin” = "Mews PMS [GUID]”
- “Enable PMS support” = ‘True’
Pos integration Section:
- “Interface server address” = IP address of the POS terminal used.
- “Interface server terminal id” = Terminal ID of the POS Terminal that hosts the Interface Terminals that are intended for use by this plugin.
- “Interface terminal name prefix” = Prefix of the Interface Terminals that are intended for use by this plugin.
Pos Integration Mode Section should have the following fields to be set to:
- “POS Integration Mode” should be set to ‘FohRedundancy’.
After making the changes, select OK to return to the APS Management interface. If no more changes are desired, ApsService should be restarted to apply any changes.
2.4.3 Configure Plugins
Switch to the ‘Plugin specific’ Tab.
In the MEWS PMS section:
- “AccessToken” – Provides access to data in the system. Access Tokens are provided by MEWS.
- “Client Service Id” – Client Service ID. Methods to retrieve the Client Service ID may require API tools to identify the desired ID.
- “ClientToken” – Should be already filled with correct production token assigned for NCR Aloha POS. Please do not modify unless you are using a specific testing environment which requires different tokens. Masked for security.
- “PlatformAddress” – URL for MEWS platform. It is prepopulated with the production URL by the installer but it can be updated with Demo URL if needed. Please ensure that the Demo URL use is restricted to demo/test environments.
In the MEWS PMS Categories section:
- “Categories” – Mapping of Aloha categories to MEWS Categories.
- “Default Category” – Default MEWS Category for unmapped Aloha categories.
The following section will provide PMS Category Mapping details.
2.4.4PMS / Aloha Category Mapping
For reporting purposes, mapping Aloha Categories with PMS Categories is required. PMS Categories may be retrieved and identified by using API tools or with MEWS support. The APS Configuration UI is in APS Management, “Configure Plugins”, and “MEWS PMS Categories” section.
Selecting the [...] button in the “Categories” “Collection” field opens “MewsCategoryMapEntry Collection Editor” interface. The list of Aloha Categories is automatically populated in the “Members” (left-side) column from Aloha. Select the Aloha Category to map to generate the configuration UI on the right-side column, in the “MEWS Category” field. It is possible to map multiple Aloha categories to a single PMS category and select multiple Aloha Categories to map a single PMS MEWS Category at the same time.
If an Aloha category mapping is not found in the list, it is displayed as “?”. Unmapped categories are automatically mapped to the Default PMS category.
2.4.5 Final Steps
After making the desired changes, select OK to return to the APS Management interface. If no more changes are desired, ApsService should be restarted to apply any changes.
3. User Instructions of PMS Functions
The APS PMS integration is utilizing the same POS UI elements as the EDC/PMS. The supported operations on the POS should include: Inquire, Room Charge, and Void.
The operation should be started using the button on the tender screen and allow the lookup by:
- Guest Name
- Room number
The results of a PMS Inquiry are limited to 3 items and may be reduced if a customer has a large volume of notes. The results will display the following:
1. Room Number
2. Reservation Number
4. Guest Credit Status
a. If the guest is flagged as “CashList” then the icon “($)” will appear next to the name.
3.2 Room charge
The operation will be started by pressing the button on the tender screen and allows entering the amount and the lookup information (similar to the inquire operation).
The POS will display the list of the matching reservations where the user would confirm the reservation to complete the room charge request. The results of the PMS inquiry when applying a room charge is displayed differently. It is limited to 8 results and displays as “Room Number(Reservation Number) ; Name”.
3.3 Void Payments and Items
When Voiding Items on a check with payment in Aloha, the payment MUST be voided before any items can be removed. This is to preserve the accurate reporting of sales and any related modifies like taxes, discounts, or partial payments.
4 Troubleshooting & Known Issues
Main Debout Log Files to review when an issue occurs:
4.1 APS Installer Issues
4.1.1 SQL database server validation
Affected version(s): APS 18.3.0
Description: APS Installation using SQL server with wrong IP address does not time out and still tries to access the DB.
Workaround: Utilize the correct IP address or do not enable the option “Use SQL Database”.
4.1.2 APS cannot be configured with SQL Server
Affected version(s): APS 18.3.0
Description: APS installer is stuck at SQL DB configuration screen – “Next” button is not available. This has been identified as a known installer issue when the TERMSTR environment variable ends with “-“ character. (Error in log: TERMSTR is missing from configuration. Please add and attempt installation again)
Workaround: Utilize a TERMSTR that does not end with “-“.
4.2 Miscellaneous Issues
4.2.1 APS Mews Plugin Debout is storing client information
To comply with privacy, ensure that “ApsPluginMews.dll.config” is configured with debug level “INFO”. This file is found in BootDrv\APS\Plugins\. The key to edit is
<level value="INFO" />
4.2.2 Aloha crashes during Payment or Void transaction
In the event that Aloha crashes during a transaction, it will be necessary to verify if there is a transaction discrepancy between Aloha Transaction Log and MEWS reporting.