Summary

This document describes the installation procedure used to add support for the Sparkfly Platform to the Micros 3700 systems.

Prerequisites

To install the Micros 3700 integration, you will need to have obtained the following from your Sparkfly account management team:

System Requirements

OS Windows 7+
.NET Framework .NET Framework 4.5.2+
Network Outbound access from the Micros 3700 BOH server to posapi.sparkfly.com:443
Micros 3700 Micros 3700 server version >= 3.0
PMS/SIM Interface licensed and active

Sparkfly strongly recommends upgrading to a modern operating system, as Windows XP is no longer receiving security updates, and Windows 7 will stop receiving updates in January of 2020. The installer for .NET Framework 4.5.2 can be downloaded here.

Installation Overview

The following is an overview of the installation steps:

Installation

Configure SIM Interface for the Sparkfly Micros Gateway

This section defines the Sparkfly Micros Gateway specific settings to be used on the Interfaces settings within Configurator. By enabling this interface, the Sparkfly Micros Gateway will receive SIM messages from the Micros 3700 system.

  1. Login to Configurator
  2. Choose Devices → Interfaces → +
  3. A new interface entry will be created. Change the interface number to 12. This value corresponds with the ISL scripts we will be installing on the terminals later — and must match! If number 12 is in use, select a different number and note the value. When installing the ISL later, you must recall this value.
  4. Enter the following details for the interface configuration:
General Tab
Outgoing Message NameSet to an easy to remember name. Typically "Sparkfly"
TimeoutDesired value in seconds (Recommended 10 seconds)
Network Node99 Server (or your server node)
Number ID Digits9
Interface TypeTCP
SIM InterfaceChecked
Interface Tab
TCP Server NameThis should be the IP address of the device that will be running Sparkfly Micros Gateway.
TCP Port NumberThe port number the Sparkfly Micros Gateway is litening on. By default the Sparkfly Micros Gateway listens on 15009.

The configuration should look similar to this:

General Tab Interface Tab

Save the interface and close the Interfaces window.

Setup Sparkfly Discount

The Sparkfly integration relies on a discount to function properly. The discount is configured to allow for dynamic valuing from our integration, enabling a single discount to be used for multiple offer campaigns of varying values. In this example, we are using a subtotal discount. Our integration also supports item discounts. Configuring them is the same as a subtotal discount, with the exception of the Item Discount flag.

In our experience, the most flexible discount to use is a subtotal discount.

  1. Login to Configurator
  2. Go to Sales → Discounts
  3. Click the + button to create a new discount
  4. Configurator will automatically select a discount number. You may change this value. This value must be provided to Sparkfly.
  5. Name the discount something memorable such as Sparkfly
  6. Select the Discount
    1. Under General, set the following options:
      1. Type: Manual
      2. Amount: 1.00
    2. Under Options, set the following options:
      1. Amount: Checked
      2. Reference Required: Checked
      3. Other options: Unchecked
    3. Under Discount, set Restrictions to No Restrictions
    4. Under Itemizers, set restrictions as desired. For simplicity, select all itemizers.
    5. Tax options and other similar options may vary by business rules and local rules. Apply as needed. Some settings may cause the discount to apply incorrectly. Testing is critical with these settings, and Sparkfly is happy to help resolve any conflicts.
    6. Click Save

Example configuration of a subtotal discount for use with Sparkfly:

General Tab Options Tab Discount Tab

Setup Sparkfly Menu Item

The Sparkfly Extension Application relies on a pre-existing Menu Item record to function properly. The menu item will be used to annotate the check with the coupon code or loyalty number applied to the transaction.

This is a two step process, first creating a Menu Item Class and then a Menu Item.

  1. Login to Configurator
  2. To create the Menu Item Class:
  3. Go to Sales → Menu Item Classes
  4. Click + to create a new record.
  5. Change the following settings for the newly created Menu Item Class:
    1. Choose Record Number as available.
    2. Set the record name to Sparkfly and click on OK
    3. Under General Options set Reference Required to Checked.
    4. Save the record.
  6. To create the Menu Item:
  7. Go to Sales → Menu Items
  8. Click + to create a new record.
  9. Change the following settings for the newly created Menu Item:
    1. Choose Record Number as available. Take note of this value, as it will be used later to configure gateway.ini.
    2. Set the record name to Sparkfly or the name of your discount or loyalty program. This will print on the check next to any coupon codes or loyalty numbers applied to the transaction.
    3. Set the Menu Item Class to Sparkfly. This should be the same Menu Item Class we created in the prior step.
    4. Under Reporting, set Major Family Group and Minor Family Group to appropriate values for your organization. This menu item is simply a placeholder item to track the attachment of a coupon or loyalty code to the check, so it is not unusual for this category to be "Misc." or something similar.
    5. Save the record.

Create Inquiry Button for the Sparkfly Application

The final step is to map a touch screen button to bring up the code entry keyboard for use with Sparkfly. Typically the best place for this button is the payment screen, as it is best to apply discounts at the end of the transaction lifecycle.

To create the Sparkfly button:

  1. Login to Configurator
  2. Go to Hardware → Touchscreen Designer.
  3. Select the Payment screen from the dropdown in the top-left.
  4. Right-click on the page design and click Insert Keys button
  5. Configure the button as follows:
    1. Legend: Enter desired button text. "Sparkfly" for example.
    2. Category: SIM/PMS Inquire
    3. Interface: Sparkfly. This should be the SIM interface we configured previously.
    4. Inquire Number: 7
    5. All other settings are superficial and can be configured to suit your environment.

The button should appear similar to this:

Example Button

Install Sparkfly ISL Files on Terminals

Each terminal must receive a copy of the Sparkfly ISL file. This script runs on each terminal and responds to various events within Micros. This file is named pms12.isl by default. If you selected an interface number other than 12 in the SIM Interface configuration step, you must rename this file to match that interface number.

If the 3700 has PC workstations with hard drives, copy pms12.isl to the \MICROS\RES\POS\Etc folder on each workstation.

If the 3700 system uses WS4s and/or HHTs, copy pms12.isl to the \MICROS\RES\CAL\WS4\Files\CF\Micros\Etc folder on the MICROS 3700 server.

Configure & Install Sparkfly Micros Gateway

The Sparkfly Micros Gateway is a Windows service that provides an encrypted connection from the Micros 3700 Server to the Sparkfly Platform. It is a standalone Windows service, and should be installed on the Micros 3700 server.

  1. Obtain the setup file from Sparkfly (SparkflyMicrosGateway.msi)
  2. Copy the setup file to the Micros 3700 server
  3. Run the Setup/Installer
  4. Insure the firewall permits outbound connections through port 443 and inbound connections on port 15009

Configuration

The Micros Gateway requires a configuration file — gateway.ini — to function correctly. This file will need to be created and configured specifically for your environment. The gateway.ini file should be placed in the install directory of the Sparkfly Micros Gateway.

A gateway.ini should be included in the install package with some initial configuration, such as API credentials, and a Site ID. Note that the Site ID must change for each store. Sparkfly will have provided you with a list of Site IDs to use for each of your stores.

Once the gateway is installed, and the gateway.ini file is located in the install directory, you will need to update some values in the gateway.ini file. The file should come preconfigured with API settings (endpoint, user, password, etc.), but there will be a placeholder for credentialItemId. Set this to the Menu Item number used in the Setup Sparkfly Menu Item step.

Once the value is updated, restart the Sparkfly Micros Gateway using the Windows Services control panel.

Reload Terminals

Restart the Micros terminals to begin testing.

Verify Sparkfly Communication

The Sparkfly configuration is complete. A final step is to validate the setup and proper communication with the Sparkfly platform.

  1. Ring a sample transaction and press the Sparkfly button created in this guide.
  2. When prompted for the Code, enter 1 for the code and hit Enter.
  3. The POS should communicate with the Sparkfly platform and return a “[200] Code is Invalid” message.
  4. If a failure message is received (ex: “No Response to Message”), verify the configuration has been completed, network communication is active, the firewall is allowing access, and the database and interface server have been refreshed.

Troubleshooting

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