Summary

This document describes the installation procedure used to add support for the Sparkfly Platform to the NCR Aloha POS systems.

Before You Begin

This installation process involves the execution of MSI installation packages that require several properties to be passed from the command line. Your Sparkfly account manager will have provided you with an install command line appropriate for your environment. If you do not have these commands, please contact Sparkfly before continuing.

System Requirements

OSWindows XP SP3
.NET Framework For BOH systems:
Windows XP: .NET Framework 4.0 w/ KB2468871
Windows 7+: .NET Framework 4.5.2

For FOH systems:
.NET Framework 2.0
Network BOH must be able to reach:
   posapi.sparkfly.com:443 (Production)
   posapi-staging.sparkfly.com:443 (Staging)

FOH must be able to reach BOH on port 6003
Aloha 5.01+ with an Aloha Connect License.
Aloha SERVER and IBERDIR environment variables must be set.

If your environment is running on Windows XP, you must run .NET 4.0, and have the patch KB2468871. Otherwise, please install .NET Framework 4.5.2. Sparkfly strongly recommends upgrading to a modern operating system, as Windows XP is no longer receiving security updates, and Windows 7 has stopped receiving updates in January of 2020. The installer for .NET Framework 4.5.2 can be downloaded here.

Aloha environment variables must be set, or parameters must be passed in to the installer defining these settings. The SERVER setting defines the Back of House Server for the installation, and the IBERDIR setting identifies where the Aloha software is located on the target machine. The BOH Server normally has IBERDIR set to C:\BootDrv\Aloha, while Front of House Terminals will often set IBERDIR to C:\Aloha. If these environment variables are not present, they may be passed to the MSI installers as installer properties with the same name. If none of these variables are present, our installer will attempt to locate the Aloha directory automatically.

Installation Overview

The installation involves several steps:

  1. The Aloha Back of House system will require installation of the Sparkfly HTTP Gateway, a standlone Windows service that provides a secure connection to the Sparkfly Platform. The BOH will also require installation of the Sparkfly Aloha BOH Components.
  2. A COM interface interceptor must be set. If the store uses the Configuration Manager, the interceptor must be set there.
  3. The Front of House (FOH) Terminals will each require the Sparkfly Aloha FOH Components to be installed.
  4. A Comp will need to be created to allow deductions to be made from the check.
  5. A menu item button will need to be programmed with a specific item. This button will trigger the display of the Sparkfly Code entry screen. The system will query the Sparkfly Platform for the validity of the code and apply any returned comps to the check.

Configuring Aloha

Enable COM Interception

The Aloha COM Interceptor settings need to be configured to tell Aloha to load the Sparkfly integration.

  1. Log in to the Aloha Manager
  2. Open the Maintenance > Store Settings pane.
  3. Select System in the Group dropdown.
  4. Select the Interfaces tab.
  5. Make sure the Use FOH COM Interface box is checked.
  6. Verify that AlohaSF.AlohaSF.1 is in one of the External Activity Interceptors text fields.
  7. If all of the slots are full, contact Sparkfly Support.
  8. Save the settings if they have been changed.

An example of COM interception correctly configured is shown below.

COM Interface Setup

Create Comp

  1. Open the Comps panel under Maintenance > Payments
  2. Enter an unused number to create a new Comp
  3. Note the number used for this Comp and make sure to provide the number to Sparkfly. The ‘Check’ entry will be printed to the check. Use a default of “Sparkfly”. Check the Active, Print Check and Must Enter Amount checkboxes. Set Eligible Items to ALL ITEMS, and Percent Off must be set to 0.0. Maximum should be set to 0.0. NOTE: This comp is never manually applied to the POS – do not set a Button Position
  4. Taxes should be removed from any discounted items, permitting a zero balance when an entire check is discounted. Under the Taxes tab, make sure the Guest Pays Tax checkbox is unchecked. NOTE: This tax setting might be adjusted according to regional tax laws.
  5. Restrictions should be set in such a way as to permit multiple discounts to be applied to a check. It is recommended that all of the checkboxes be checked except Promo Items Eligible and Comp Items Eligible. The Max Per Check and Max Per Table should be set to 9.
  6. Save the changes.

The below screenshots mirror the described comp above:

Comp 1 Comp 2 Comp 3

Add a Sparkfly Menu Item

  1. In the Aloha Manager, log in as a user with menu editing authority.
  2. Open the Items panel under Maintenance > Menu
  3. Create a new item by entering a number not in-use by other menu items.
  4. Add "Sparkfly" as the name for this item.
  5. Save the new item.
  6. Edit the item again, and click the No Category button. Add the item to the desired sales or retail category.
  7. On the Category Maintenance page, select the desired category.
  8. Locate the new item on the right-hand pane, highlight it, then click Include
  9. Save the change to the Category, and then close the Category pane.
  10. On the Items pane, select the dropdown beside Primary Tax. Select the desired tax category.
  11. Subsequent versions of the Aloha Management system may have additional fields available. They need to be set to values that do NOT require additional information from the user. For example, do not select a checkbox for ‘Ask for description’. Uncheck a setting like that if checked by default.
  12. Save the Item.

The below screenshots demonstrate the configuration process:

Create Menu Item 1 Create Menu Item 2 Create Menu Item 3 Create Menu Item 4 Create Menu Item 5

Aloha QuickService ONLY – Add the Sparkfly Button

If using TableService, skip this section.

  1. In the Aloha Manager, log in as a user with menu editing authority.
  2. Open the Panel Editor under Maintenance/Menu
  3. Click Commands, Open Existing Panel, Button Functions
  4. Select the appropriate button panel - Your button description and placement may vary, normally Sparkfly recommends using the button group that offers the cashier the ability to apply coupons or discounts to the transaction after everything has been ordered.
  5. Place a new button on the screen following the procedure described in the Aloha documentation.
  6. The settings for the new button should be as follows:
    1. Function: Order Item
    2. Text: ‘Sparkfly’
    3. Item: Select Sparkfly Item setup in ("Add a Sparkfly Menu Item")[#add-a-sparkfly-menu-item]
  7. Save the button settings, and save each screen on the way out.

Below are screenshots of this process.

Add QS Button 1 Add QS Button 2 Add QS Button 3

Aloha TableService ONLY – Add the Sparkfly Button

If using QuickService, skip this section.

Sparkfly supports two methods of triggering the Sparkfly code entry dialog on Table Service. The first option is to create a menu item button. The second method is to edit TSButton.cfg to add a Sparkfly button to the close screen.

Method 1: Menu Item

This method allows the code entry to occur during normal ordering.

  1. Open the Submenus panel under Maintenance > Menu
  2. Select the Submenu where the new item button will reside.
  3. Double click on the location for the new item’s button. This brings up the Submenu Item selection. Select the new item from the list. Pricing option can be left at Price and 0.00.
  4. Click OK, then save the Submenu Maintenance changes.
  5. Verify the Comp and Item data setup in the previous steps using Utilities > Verify Data. Correct any issues reported.

Add TS Button 1 Add TS Button 2 Add TS Button 3 Add TS Button 4

Method 2: Close Screen

This method allows the button to be present on the close screen. This method is more technical, and requires hand-editing the TSButton.cfg file located in [ALOHDIR]\DATA\TSBUTTON.CFG. If this file does not exist, you must create it. The format of this file is Aloha-specific, and documentation for it is provided by NCR. If you need this documentation, please contact NCR or your reseller.

Below is an example TSButton.cfg which places the Sparkfly button on the Comps tab of the Aloha close screen:

4,0,1,Sparkfly,SparkflyAlohaAgent.exe assign,1

Installing Sparkfly

Your Sparkfly account manager will have provided you with multiple install commands appropriate for your environment and Sparkfly account. If not, please contact Sparkfly before continuing.

Install Sparkfly HTTP Gateway on BOH Server

  1. Obtain the Setup file from Sparkfly (Sparkfly-HTTPGateway-<VERSION>.exe)
  2. Run this on the BOH Server
  3. Choose the destination folder if different from the default, then click Next.
  4. Installer should display installation is complete. Click Finish.
  5. Ensure that the Service is running:
    1. Press WinKey+R
    2. Type services.msc
    3. The Windows Services window will open. Locate Sparkfly HTTP Gateway in the list. The service should have a Status of Started.
    4. If it is not, it needs to be started manually. Right click and select Start.
    5. Verify that it stays running by clicking Refresh and observing the status.
    6. If it does not remain in the Started state, contact Sparkfly Support.

Install Sparkfly Aloha Connector on BOH Server

This installer should be run from the command line. Your Sparkfly account manager should have provided the command line correct for your envionment.

Install Sparkfly Connector on FOH Terminals

This step will install the necessary COM registrations on each FOH terminal. The FOH Components install package is separate from the BOH package — be sure to use the correct MSI on the correct systems.

This is a manual process. If your environment uses Aloha RAL, or you are looking for more automated deployment mechanisms, please contact Sparkfly.

The standard manual install process is (per FOH terminal):

  1. Copy the SparkflyAlohaConnector_FOH_<VERSION>.msi to the FOH terminal
  2. Run the MSI and complete the installation. The installer may warn that it has auto-detected your Aloha directory. This is normal and occurs if the LOCALDIR and IBERDIR environment variables are not set on the terminal.

Once the installer has completed on the FOH terminals, you must Refresh Data from the BOH.

Verify Sparkfly Installation

Sparkfly setup is complete. You must verify each FOH terminal’s ability to bring up a Sparkfly Code Entry screen and communicate to the Sparkfly Promotions Engine. To do this, access an Aloha FOH terminal and locate the Sparkfly menu item created in section 4.3 or 4.4. Clicking this button should summon the code entry dialog:

Network/Firewall Configuration

The POS Terminals must be able to communicate via TCP/IP to the Server, and the Server must be able to access the external internet. The Sparkfly HTTP Gateway expects to use port 443 for its secure connection so an outgoing connection will need to be permitted through any firewalls at this port. Firewalls can restrict traffic to posapi.sparkfly.com for port 443 for our production environment, and posapi-staging.sparkfly.com for our staging environment. No inbound connections will be made to the BOH from the Internet. Inbound connections will be made to the BOH from our FOH software, on port 6003.

The next sections will lay out the procedure for modifying the Microsoft Firewall settings to permit communication between the Sparkfly components. Other firewall products may be in use, the procedure for altering those are beyond the scope of this document.

Windows Firewall Settings – BOH Server

  1. Open the Control Panel, select Windows Firewall
  2. If the firewall is enabled, select Advanced
  3. Create inbound rule for communications from the FOH terminals to the BOH server:
    1. In Advanced Firewall Settings, select Inbound Rules and New Rule
    2. Create a Port Rule for TCP 6003 on all Profiles that allows traffic. Name it “Sparkfly Inbound 6003” and save it.

Windows Firewall Settings – All FOH Terminals

  1. If the FOH terminals are running a Windows Firewall, and that firewall is active, this will have to be performed on each terminal.
  2. Using the procedure from the previous section, create an outbound rule for TCP port 6003 on all Profiles that allows traffic. Name it “Sparkfly Outbound 6003 and save it.

Troubleshooting

Problem: Sparkfly Code Entry Screen does not appear

The keyboard not appearing is a very generic problem and can be caused by several issues. The best approach is to verify all installation steps have been carried out to their desired ends. Common causes are:

  1. Sparkfly Connector DLL is not installed properly.
    1. Verify Interceptors are set correctly on the BOH (Enable COM Interception)
    2. Verify FOH installer has been run on this terminal (Install Sparkfly Connector on FOH Terminals)
    3. Verify terminal has been restarted twice since the installation
  2. Sparkfly button is not properly set up (Add a Sparkfly Menu Item)
    1. Verify steps were followed exactly
    2. The Sparkfly button needs to trigger an Order Item, or Smart Item, not Comp or Promo
    3. The item added by the Sparkfly button needs to be the Sparkfly trigger item created in (Add a Sparkfly Menu Item)
    4. Make sure that the contents of SPARKFLY.INI match what you have configured in Aloha. The item_code field should match the number of the Sparkfly menu item created in (Add a Sparkfly Menu Item)
      1. Browse to the Aloha directory on the BOH.
      2. Open the DATA folder
      3. Open Sparkfly.ini
      4. Verify the configuration looks correct. If no errors are present, send this file, along with the symptoms of your problem to support@sparkfly.com

Network communication errors can be caused by several common problems:

  1. The Sparkfly HTTP Gateway is not running on the BOH. Verify it was installed and running (Install Sparkfly HTTP Gateway on BOH Server).
  2. The network path between the FOH and the BOH is blocked. Verify the FOH terminal can communicate with the BOH on port 6003.
  3. The network path between the BOH and the Sparkfly Platform is blocked.
    1. Verify the BOH can reach the internet on port 443.
    2. Verify the BOH can resolve the host posapi.sparkfly.com and posapi-staging.sparkfly.com
    3. Verify the BOH can open port 443 for posapi.sparkfly.com and posapi-staging.sparkfly.com

Other Errors

Please contact your Sparkfly account representative if you need assistance, or e-mail support@sparkfly.com.