Summary

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

Before You Begin

This installation process involves the execution of MSI installation packages. 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 7+
.NET Framework For BOH systems: .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 7100
POSitouch Most versions supported, some functionality may vary.
Must be licensed to use the XML Order Placement Interface.

Installation Overview

The Sparkfly POSitouch integration model is through the User Programs feature of POSitouch. Software is installed on each terminal (the "Agent"), and a core service is installed on the BOH (the "Gateway"). Buttons are configured in POSitouch to provide access to the user program. The Gateway receives communication from the Agent, itself communicating to the Sparkfly Platform and various POSitouch XML file-based APIs. XML I/O directories must be configured to allow the Sparkfly Gateway to communicate with POSitouch.

The installation involves several steps:

  1. Configuration of the POSitouch back office (XML I/O directories, items, menu screens, etc.).
  2. Configuration of POSitouch WINTERM.INI on each FOH terminal to specify the path to the Sparkfly User Program.
  3. Configuration of POSitouch MACROS.XML on each FOH terminal to map specified buttons to the Sparkfly User Program.
  4. Installation and configuration of Sparkfly POSitouch Agent on each FOH terminal.
  5. Installation and configuration of Sparkfly POSitouch Gateway on the BOH.

Configuring POSitouch

Create Sparkfly Menu Items

Sparkfly requires two menu items to be created. The menu items are placed on the check during a normal transaction to track the attachment of a credential to the check (a credential is a coupon code, a loyalty member or other identifying information linked to a loyalty account or discounts in the Sparkfly cloud or its partner platforms).

To create Sparkfly menu items:

  1. Using either BOW or RDC Navigator, go to Menu Screens ➔ Menu Items & Recipes
  2. Create the first menu item:
    1. Click Add Record. The Add Record dialog will select an available ID for you. Note this ID.
    2. Click OK to create the record
    3. Change the name to SPARKFLY
    4. Select a Major and Minor Category for the item.
    5. Click Save.
  3. Create the second menu item:
    1. Click Add Record. The Add Record dialog will select an available ID for you. Note this ID.
    2. Click OK to create the record
    3. Change the name to SPARKFLY MEMO
    4. Select a Major and Minor Category for the item.
    5. Click Save.

See the below screenshots for an example of the items. In our case, our main item was Item #60 and our memo item is Item #65.

Sparkfly Credential Main Item Sparkfly Credential Memo Item

Retain the numbers used here, and move onto the screen configuration step.

Create Sparkfly Screen Cells

In order for Sparkfly to use the item and memo item as such, screen cells must be created within POSitouch identifying the items. The screen number and cell numbers used in this process must later be synchronized with the Sparkfly GATEWAY.INI.

To setup the screen cells, following these stpes:

  1. Using BOW or RDC Navigator, go to Menu Screens ➔ Edit an Order Screen
  2. Find an existing screen, or create a new screen. Note that the buttons created for Sparkfly should not be visible to the user -- they will never press them.
  3. Once inside the screen editor for the screen where you wish to place the button, click an empty cell to create the first Sparkfly item.
    1. Inv.# should match the SPARKFLY menu item we created in the previous step. In our example, it was 60. If you are unsure, use the Lookup button to match the item directly.
    2. Cell Type should be set to 1-Primary item, taxed
    3. Prep Cat should be set to None required
    4. All other settings are default.
    5. Save and return to the screen edit screen.
  4. Now, click a second empty cell to create the second Sparkfly item. This item will be a memo item that appears on the check. This item will be used for the memo configuration setting in gateway.ini.
    1. Inv.# should match the SPARKFLY MEMO menu item we created in the previous step. In our example, it was 65. If you are unsure, use the Lookup button to match the item directly.
    2. Cell Type should be set to 9-Memo
    3. Prep Cat should be set to None required
    4. All other settings are default.
    5. Save and return to the screen edit screen.
  5. Now, click a third empty cell to create the third Sparkfly item. This item will be a memo item that does not appear on the check. This item will be used for the hiddenMemo configuration setting in gateway.ini
    1. Inv.# should match the SPARKFLY MEMO menu item we created in the previous step. In our example, it was 65. If you are unsure, use the Lookup button to match the item directly.
    2. Cell Type should be set to 9-Memo
    3. Prep Cat should be set to None required
    4. Exclude from Check? should be checked.
    5. All other settings are default.
    6. Save and return to the screen edit screen.
  6. Now that the items are created, note the Screen Number and Cell Number of all 3 items. In the screenshot below, these are highlighted. In the example, the values are screen 47 and cell numbers 1, 2, and 3. Take note of these values, as they will be used in configuration of GATEWAY.INI.

The following screenshots are example configurations, with key elements highlighted.

Sparkfly Screen Cell for Main Item Sparkfly Screen Cell for Memo Sparkfly Screen Cell for Memo Sparkfly Screen Cell for Memo

Configure XML I/O Directories for Sparkfly

The Sparkfly integration communicates with POSitouch using the XML I/O Directories feature of POSitouch. Sparkfly requires access to several of these virtual printers. Generally speaking, there are 3 types of XML I/O Services: input-only, output-only and input-output. Generally speaking, for input into POSitouch, it is recommended that the directory used is C:\SC\XML\SPARKFLY_IN. For output from POSitouch, it is recommended that the directory used is C:\SC\XML\SPARKFLY_OUT. The XML Ordering interface is an exception to this, and should use its own directories separate from the other input/output functions. For example, C:\SC\XML\SPARKFLY_ORDERIN and C:\SC\XML\SPARKFLY_ORDEROUT.

Finally, the XML directories dedicated to Sparkfly should not be shared by other applications. The Sparkfly integration will actively place files into these directories and delete files sent by POSitouch. Multiple applications accessing these directories will result in problems.

The tables below provide a detailed breakout of the recommended virtual printer configuration for Sparkfly.

Output-Only Services

Virtual Printer Directory Usage
Send Order C:\SC\XML\SPARKFLY_OUT Allows Sparkfly to know when the user has changed a check.
Close Check C:\SC\XML\SPARKFLY_OUT Allows Sparkfly to detect that a check has been paid and closed. This is used for finalization of redemptions and point accrual.
Canceled Check C:\SC\XML\SPARKFLY_OUT Allows Sparkfly to process voided checks.
Open Checks C:\SC\XML\SPARKFLY_OUT Allows Sparkfly to see which checks are currently opened.
User Programs C:\SC\XML\SPARKFLY_OUT Causes POSitouch to send Sparkfly information about the logged in user when our user program is launched.
Check Update C:\SC\XML\SPARKFLY_OUT Allows Sparkfly to detect split check situations.

Input-Output Services

Virtual Printer Directory Usage
Open Checks Request C:\SC\XML\SPARKFLY_IN
C:\SC\XML\SPARKFLY_OUT		 Allows Sparkfly to request check data when needed.
XML Ordering C:\SC\XML\SPARKFLY_ORDERIN
C:\SC\XML\SPARKFLY_ORDEROUT		 Allows Sparkfly to modify the check (adding discounts, attaching credentials).

Input-Only Services

Virtual Printer Directory Usage
XML Services C:\SC\XML\SPARKFLY_IN Allows Sparkfly to display messages to the user and print receipts.

POSitouch only allows one virtual printer to be assigned to each of the above. If you are not currently using virtual printers, you will need to create new virtual printers for Sparkfly. If you have existing integrations relying on virtual printers, you will need to add extra directories to the existing virtual printers that are specific to Sparkfly.

Method 1: No Existing Virtual Printers

If no virtual printers are currently assigned or created for XML I/O, you must create one.

  1. Using either BOW or RDC Navigator, open Restaurant Misc. Data ➔ XML I/O
  2. Click Add Virtual Printer
  3. Enter a name for the virtual printer (SPARKFLY is a good idea), and click OK.
  4. Click Add Virtual Printer again.
  5. Enter a name for the second virtual printer (SPARKFLY ORDERING is recommended). Click OK.
  6. Set the following dropdowns:
    1. Send Order ➔ SPARKFLY
    2. Close Check ➔ SPARKFLY
    3. Check Update ➔ SPARKFLY
    4. Canceled Check ➔ SPARKFLY
    5. Open Checks ➔ SPARKFLY
    6. User Programs ➔ SPARKFLY
    7. XML Ordering ➔ SPARKFLY_ORDERING
    8. Open Checks Request ➔ SPARKFLY
  7. Now we must set the IN/OUT paths for the SPARKFLY printer:
    1. Click Configure to the far right of Open Checks Request. See figure below.
    2. Select the SPARKFLY printer.
    3. In the first slot for Input Folders enter C:\SC\XML\SPARKFLY_IN.
    4. In the first slot for Output Folders enter C:\SC\XML\SPARKFLY_OUT.
  8. Now we must set the IN/OUT paths for the SPARKFLY_ORDERING printer:
    1. Click Configure to the far right of XML Ordering. See figure below.
    2. Select the SPARKFLY_ORDERING printer.
    3. In the first slot for Input Folders enter C:\SC\XML\SPARKFLY_ORDERIN.
    4. In the first slot for Output Folders enter C:\SC\XML\SPARKFLY_ORDEROUT.

Once the above steps are complete, XML I/O configuration is complete. See below screenshots as a reference for the expected configuration.

Virtual Printer Configuration: Input/Output XML I/O

Virtual Printer Configuration: Ordering Input/Output XML I/O

Method 2: Existing Virtual Printers in Place

If virtual printers are assigned to the XML I/O functions already, you must edit those virtual printers to include an input and output directory for Sparkfly's integration. The method of doing this is similar to Method 1, but will vary significantly based on existing configuration. In the below screenshots, an existing Virtual Printer is applied to the XML I/O directories, and Sparkfly directories have been added to the existing printers.

Below are example screenshots of a situation where a hypotehtical existing vendor is installed, and the Sparkfly IN/OUT directories are added to the virtual printer settings. Note that the directories must be added to every virtual printer where the overlap occurs. Depending on the environment, this may be more than one, and possibly several printers.

Example showing non-Sparkfly Virtual Printer's In Use XML I/O

Example showing Sparkfly directories appended to existing printer XML I/O

Example showing Sparkfly directories appended to existing online ordering printer XML I/O

Method 3: Hybrid

In the case where existing printers are assigned to some, but not all of the required XML services, you must perform a hybrid of Method 1 and Method 2. When an existing virtual printer exists, add the Sparkfly IN or OUT directory to the existing printer. In cases where no printer is currently selected for that XML service, create the Sparkfly virtual printer as defined in Method 1, and select that virtual printer for that service. Assigning existing printers used by other applications to XML functions which they were previously not assigned may result in the other application not working correctly.

Virtual Printer configuration in POSitouch is nuanced and often confusing. If you are unsure how to proceed, please contact Sparkfly for support.

This is the end of the back office configuration. Before continuing to install the Sparkfly software, be sure to perform one last Immediate System change (ISC) and restart everything to be sure changes to the back office have taken hold.

Install Sparkfly Software

Sparkfly will have provided you with 3 items:

  1. SparkflyPOSitouchGateway-v1.0.0.0.msi -- This is the Sparkfly POSitouch Gateway installer. This will install a Windows service on the BOH that provides a backend to the FOH agent and communicates with the Sparkfly Cloud Platform. Installs to C:\Sparkfly\Gateway by default. Requires a GATEWAY.INI configuration to start and run.
  2. SparkflyPOSitouchAgent-v1.0.0.0.msi -- This is the Sparkfly POSitouch Agent installer. This should be installed everywhere the POSitouch terminal software is installed (including the BOH, if the terminal software is installed there). Installs to C:\Sparkfly\Agent by default. Optionally allows configuration via AGENT.INI, but configuration is not required if the terminal software is in the default directory of C:\SC.
  3. GATEWAY.INI -- This is the configuration for the Sparkfly POSitouch Gateway. This file should be copied to C:\Sparkfly\Gateway.

To install the software, run the MSI installers by double clicking them, or silently execute them using msiexec.exe. For example:

msiexec /i SparkflyPOSitouchGateway-v1.0.0.0.msi /q

Or for the agent (run on each terminal):

msiexec /i SparkflyPOSitouchAgent-v1.0.0.0.msi /q

Once the installs are completed, copy the GATEWAY.INI to C:\Sparkfly\Gateway. This file will have some default settings in it, and many of them will require updating to synchronize the Gateway configuration with the items created in the back office configuration steps. Notably:

  1. In section [positouchItems]:
    1. mainItem should match the screen/cell numbers we used in back office setup. In the example, this was 47,1.
    2. memo should match the screen/cell numbers we used in back office setup for the "memo item". In the example, this was 47,2.
    3. hiddenMemo should match the screen/cell numbers we used in back office setup for the "hidden memo item". In the example, this was 47,3.
  2. In section [positouchXml] the directories will be populated with recommended defaults (C:\SC\XML\SPARKFLY_IN, etc.). If these were followed during configuration, no change should be required.
  3. For more details on the various flags in GATEWAY.INI, see the Configuration Guide.

Once the configuration changes are complete, restart the Sparkfly POSitouch Gateway by opening the Administrative Tools → Services control panel, or by launching it directly using Start → Run → services.msc. Alternatively, you can use the command line:

net stop sfpgateway
net start sfpgateway

This completes the installation of the Sparkfly software.

Configuring Terminals

Each terminal will need WINTERM.INI updated, and MACROS.XML updated if placing the Sparkfly user program button on a button other than the default user program buttons.

Modify WINTERM.INI

The Sparkfly POSitouch Agent is a "user program" that is installed on each POSitouch terminal. In order for the terminal software to know where to find the executable, WINTERM.INI must be updated.

POSitouch allows up to 5 "user programs" to be configured in WINTERM.INI. Sparkfly requires a minimum of 1 slot, with full functionality requiring 2 slots. The agent runs in 2 possible modes: tx and nontx. tx mode is when the user program is invoked inside of a transaction, and nontx mode is when the user program is invoked outside of a transaction, or to perform non-transactional account maintenance functions. Both commands also accept a second argument which specifies the type of user performing the action. For example, a manager or a server. This flag tells our software how to respect the [acl] section of GATEWAY.INI, as documented in the Configuration Guide.

  1. Locate WINTERM.INI, typically at C:\SC\WINTERM.INI.
  2. Open the file in Notepad or another text editor.
  3. Locate the [WINTERM] section.
  4. Locate any existing user program entries (UserProg_1, UserProg_2, etc.)
  5. Add an entry for Non-Transaction Functions: "C:\SPARKFLY\AGENT\SparkflyPositouchAgent.exe" nontx,SPARKFLY
  6. Add an entry for Transaction Functions: "C:\SPARKFLY\AGENT\SparkflyPositouchAgent.exe" tx,SPARKFLY
  7. Take note of which slots were used, as these will be referenced by MACROS.XML in a later step.
  8. Verify UserProgMinimize is set to NO
  9. Verify UserProgOnTop is set to YES
  10. Verify UserProgPositermMaximize is set to YES

If the above steps were followed, the configuration should be similar to this:

UserProgMinimize=NO 
UserProgOnTop=YES 
UserProgPositermMaximize=YES 
UserProg_1="C:\SPARKFLY\AGENT\SparkflyPositouchAgent.exe" nontx,SPARKFLY
UserProg_2="C:\SPARKFLY\AGENT\SparkflyPositouchAgent.exe" tx server,SPARKFLY
UserProg_3="C:\SPARKFLY\AGENT\SparkflyPositouchAgent.exe" tx manager,SPARKFLY

If you have existing user programs, you may place the Sparkfly entries in slots 3, 4, or 5.

Adding the Sparkfly Button

Method 1: Using existing USER PROGRAM buttons in POSitouch

By default, POSitouch has 2 USER PROGRAM buttons. These can be enabled or disabled in the POSitouch Back Office.

These buttons are hard mapped to the user program UserProg_1 for the USER PROGRAM button the main screen and UserProg_2 for the USER PROGRAM button on the payment screen. If using this approach, the nontx Sparkfly User Program should be in slot 1, and the tx Sparkfly User Program should be in slot 2.

For these buttons to appear, certain things must be true:

  1. UserProg_1 and UserProg_2 must be specified in WINTERM.INI
  2. Allow User Programs at Terminals? must be checked in Restaurant Misc Data → System.
  3. No User Programs? must be unchecked in Hardware → Terminal Stations
  4. The user that is logged in must have the privilege of #93 -- Access to User Program in User Privilege Codes → Assign Privileges

Method 2: Repurposing Existing Unused Button

The second method is to repurpose an existing button within POSitouch. This has some pros and cons:

  1. Pro: Buttons can be placed wherever is convenient for the staff.
  2. Con: Requires creating a macro.
  3. Con: Requires a POSitouch function to be disabled.

To begin, you will need access to the running SPCWIN instance and a terminal. The terminal can be local to POSDRIVER or it can be a physical device — whichever is convenient. You will need to determine which macro slot to use. In the example, we will be using macro slot 1. Investigating MACROS.XML will show existing macros.

To create the macro, complete the following:

  1. On the terminal, navigate to the screen where you wish to place the Sparkfly button.
  2. On the BOH, focus SPCWIN and press Ctrl+Q.
  3. You will be prompted to Enter Macro number (1 to 10):. Enter the macro slot you wish to use. Hit enter.
  4. You will be prompted to Enter Macro button label:. Enter the text you would like on the button, followed by a carot (^), followed by the number of the User Program slot used when editing WINTERM.INI. If this button is for transaction functions (e.g. inside a check), use the tx variant. If this button is for non-transaction functions (e.g. outside of a check), use the nontx variant. For example: POSitouch will interpret SPARKFLY^1 as "name the button 'SPARKFLY' and link it to UserProg_1 in WINTERM.INI". Enter the value and press enter.
  5. You will be prompted to Enter terminal number:. Enter the device number for the terminal you are using to create the macro.
  6. You will be prompted to Touch Button assigned to Macro. This action should be carried out on the terminal. Tap the button you wish to assign the macro to.
  7. SPCWIN will echo Start Macro recording...Hit CTRL-Q when done. Do not hit Ctrl+Q yet.
  8. After you tapped the button in step 6, the name of the button will have changed to match the name of your macro. Tap the button one more time, and switch back to SPCWIN. This records a "tap" of the macro'd button as a part of the macro, a necessary step.
  9. On SPCWIN, Press Ctrl+Q to terminate macro recording. SPCWIN will echo End macro recording.
  10. If you switch back to the terminal you may notice that the macro may disappear. This is normal. Perform an Immediate System Change. When the terminal restarts, the button should be present and functioning. Pressing the button should summon the Sparkfly user program.
  11. MACROS.XML will be updated on the terminal. You must synchronize these changes to all terminals.
  12. If using out-of-transaction member functions, repeat steps 1 through 9 referencing the user program slot with the nontx variant.

Note: You can peform the macro creation process by manually editing MACROS.XML directly. Modifying MACROS.XML is beyond the scope of this install guide. For details please consult the POSitouch documentation or support team.

Testing and Verification

By this step, we should have accomplished the following:

  1. Configured the Back Office database.
  2. Configured the FOH terminals WINTERM.INI and optionally MACROS.XML
  3. Installed and configured the Sparkfly POSitouch Gateway and Sparkfly POSitouch Agent.
  4. Pushed an Immediate System Change and restarted everything.

At this point, pressing the Sparkfly button should present a Sparkfly menu:

Sparkfly Transaction Menu

If this does not occur, proceed to troubleshooting steps or get in contact with Sparkfly as described in Other Errors & Getting Assistance.

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 things to check:

  1. Verify Agent installer has been run on the terminal device.
  2. Verify Sparkfly Agent executable is present in C:\Sparkfly\Agent
  3. Verify Sparkfly Agent executable is referenced correctly in WINTERM.INI
  4. If using macros, verify macro is correctly mapped to the user program # in MACROS.XML.

Network communication errors can be caused by several common problems:

  1. The Sparkfly POSitouch Gateway is not running on the BOH. Verify it is installed and running.
  2. The network path between the FOH and the BOH is blocked. Verify the FOH terminal can communicate with the BOH on port 7100.
  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 & Getting Assistance

Please contact your Sparkfly account representative if you need assistance, or e-mail support@sparkfly.com. To improve our ability to help you, please send us a ZIP file containing the following:

  1. The entirety of C:\Sparkfly from the BOH.
  2. The entirety of C:\Sparkfly from any relevant terminal devices.

This will provide us with your current configuration and diagnostic logs produced by the Sparkfly POSitouch Gateway and Agent.