Summary

This document describes the installation procedure used to add support for the Sparkfly Platform to the Squirrel POS system.

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

BOH OS Windows 7 minimum, Server 2012+ recommended.
.NET Framework .NET Framework 4.5.2
Network BOH must be able to reach ps.sparkfly.com on port 8100
Squirrel Squirrel 10.2+
SQCURDIR environment variables must be set.
Terminals OS Linux or Windows. All terminal types with Java 1.3+ are supported.
Java Java 1.3+
Network Terminals must be able to reach BOH on port 5003.
Squirrel Squirrel 10.2+

Squirrel environment variables must be set, or parameters must be passed in to the installer defining these settings. The SQCURDIR setting identifies where the Squirrel software is located on the back office machine. If these environment variables are not present, they may be passed to the MSI installers as installer properties with the same name.

Installation Overview

The installation involves several steps:

  1. The Squirrel Back Office system will require installation of the Sparkfly Squirrel Extension package that will install the Java extension files into C:\Squirrel\Program\Pos, install and start a Windows service "Sparkfly Squirrel Gateway". The Sparkfly Squirrel Gateway is a Windows service that brokers communication between our extension, running on the terminals, and the Sparkfly platform. Our Squirrel extension talks to our gateway, and our gateway relays that communication to the Sparkfly platform.
  2. Using the Squirrel Back Office software, buttons will need to be modified with Pre and Post execute hooks. These hooks tell Squirrel to notify the Sparkfly extension before or after the buttons are executed by Squirrel.
  3. A menu item will need to be created with a price of $0.00. This menu item is used by our extension to add members, coupons or other credentials to the checks.
  4. 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.
  5. New buttons will need to be created trigger the code entry dialog, or to allow removing of codes from the check.

Installing the Sparkfly Extension

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

Install Sparkfly Squirrel Extension MSI

This installer is designed to be run from the command line.

  1. Obtain the Setup file from Sparkfly (Sparkfly-SquirrelExtension-<VERSION>.msi)
  2. Run the install command provided by your Sparkfly or partner Account Manager.

The general format for this command is:

msiexec /i Sparkfly-SquirrelExtension-<version>.msi API_USERNAME=<API_USERNAME> API_PASSWORD=<API_PASSWORD> STORE_NUMBER=<STORE_NUMBER>

Configuring Squirrel

Note: This configuration step should be performed after Sparkfly Squirrel Extension has been installed. When creating buttons, or adding pre- or post- event hooks to buttons, Squirrel will verify that the relevant extension exists in C:\Squirrel\Program\Pos\extended. Therefore, it is impossible to complete these steps without the Sparkfly extension installed.

Add Sparkfly Extension Hooks to Existing Buttons

The Sparkfly extension needs to be notified after the order is modified or sent to the kitchen. This can happen when the user clicks SEND ORDER, SEND & STAY, PRINT CHECK or similar buttons. The Squirrel UI is heavily customizable, and it is likely your specific UI will vary widely. The main goal here is to be sure that the SFReassignMember extension is hooked to Pre-execute on those buttons. To do this:

  1. Open the Squirrel Back Office
  2. Click Daily Setup
  3. Click Point of Sale Screen Setup under the Screen Setup section.
  4. Using the dropdown at the top of the screen, select the department you wish to add Sparkfly support to. Note that you will need to configure these hooks for every department you wish to use Sparkfly with.
  5. Locate your SEND ORDER, PRINT CHECK and SEND & STAY buttons.
  6. For each of these buttons, double click the button to summon the edit dialog. Set the Pre Execute field to SFReassignMember. If this field is already occupied, then another extension in your Squirrel install is already hooked to this event, and due to Squirrel limitations, this is a major conflict. Please contact Sparkfly or your loyalty partner to resolve this conflict.
  7. Repeat step 6 for every SEND ORDER, PRINT CHECK or SEND & STAY button in your system.
  8. Locate your SEPARATE button, typically on the CHECK tab of the Squirrel POS UI. Set the Pre Execute field to SFSplitCheck.

The below table summarizes the buttons that must be modified for the Sparkfly Squirrel Extension to function correctly.

Squirrel Button Extension Type Purpose
SEND ORDER SFReassignMember Pre Notifies the Sparkfly Extension that the check may have changed. May result in application of new promos.
SEND & STAY SFReassignMember Pre Notifies the Sparkfly Extension that the check may have changed. May result in application of new promos.
PRINT CHECK SFReassignMember Pre Notifies the Sparkfly Extension that the check may have changed. May result in application of new promos.
SEPARATE SFSplitCheck Pre Notifies the Sparkfly Extension that the number of checks on the table has changed.

Add Sparkfly Extension Hooks to Monitor.ext, EFiscalReceipt.ext, Gateway.ext

Sparkfly's extension requires installing a Monitor extension, an EFiscalReceipt extension, and a Gateway extension. These provide real-time check monitoring and finalization of transactions.

To install them, you must edit Monitor.ext, EFiscalReceipt.ext and Gateway.ext located in `C:\Squirrel\PosData.

The contents of Monitor.ext should be:

SFMonitor

The contents of EFiscalReceipt.ext should be:

SFFiscalReceipt

The contents of Gateway.ext should be:

SFGateway

If these files do not exist, they must be created. If they exist and there is already data in them, this means you have existing extensions installed and you cannot install the Sparkfly hooks. Due to Squirrel limitations, this will require development work. Please contact Sparkfly for more information.

Create Sparkfly Buttons

The Sparkfly extension has several commands which can be bound to Squirrel UI buttons. The below table describes these buttons and their recommended usage. For basic function, at least one SFAssignMember button should be created, ideally on the CHECK tab of the POS display. Generally, the below buttons operate on the current check if they are recommended for the CHECK tab. If they are recommended for the SUMMARY tab, they are tools that can be used without a check currently active.

Extension Recommended Screen Purpose
SFAssignMember Check Assigns a member to the current check.
SFUnassignMember Check Removes all assigned members from the current check.
SFActivateCard Summary Requests a member card number to activate. Used for loyalty partners. Ignores the current check.
SFLookupMember Summary Requests a member card number to look up information for without assigning it to the current check. Used for loyalty partners. Ignores the current check.
SFReplaceCard Summary Requests a member card number (or phone number), and a second member card number which is to replace the member's current card with. Ignores the current check.

As an example, this is a typical setup for SFAssignMember. Other actions would be implemented similarly:

Sparkfly Assign Button

Create Sparkfly Menu Item

The Sparkfly extension needs a menu item with a $0 value to track assigned members on the check. To create this item:

  1. Open the Squirrel Back Office.
  2. Open Menu Entry Setup under the Menu Setup section.
  3. Create a new menu entry
  4. Set the following fields:
  5. Menu Entry Name = Sparkfly
  6. PLU Number = An available PLU in your system
  7. Check 'Open Name'
  8. The Type should be 'Item'
  9. Category = MISC.
  10. Set all prices to 0.00

Below is a screenshot of this item setup. In the screenshot, we used PLU number 1505.

Sparkfly Menu Entry

Update Sparkfly configuration

Next, we must ensure that the Sparkfly configuration file is up to date. Follow these steps:

  1. Using Notepad or another text editor, locate and open the file C:\Squirrel\PosData\sparkfly.ini.
  2. Locate the line with the setting CREDENTIAL_PLU. Update this value to match the PLU of the Sparkfly item you created above. For example, if the Sparkfly item was PLU 1505, then the line should read CREDENTIAL_PLU=1505. This tells our extension which menu entry to use when tracking members on the check.
  3. If SITE_ID is not set to the correct value for this site, update it. This value is provided by your Sparkfly account representative.
  4. Save and close the file.

Send Setup Changes and Test

Our changes are complete. At this point, you should Send Setup Changes to Terminals. Once this has completed, you should be ready to test assigning a member to the check.

Troubleshooting

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