Micros Simphony POS by Punchh Installation & Configuration – Punchh

CONFIGURATION FLOW

CONFIGURATION STEPS

Firewall & Whitelisting Configuration
Configure the Punchh Discount in Micros Simphony EMC
Installation of the Punchh Service
Add “PunchhSimphony” Extension to EMC
Add the IP/PORT DLL in EMC
Configure the Loyalty Button
Setting up/Running the Punchh lookup UI for the first time

System Prerequisites

System requirements for the PC hosting the Punchh service (i.e. the CAPS terminal)
- Minimum OS: Windows 7 w/ SP1 + .NET Framework 4.6.1
System requirements for POS terminals
- Minimum OS: Windows 7 w/ SP1 OR macOS 10.13+ OR Ubuntu 16.04+
There are no Punchh RAM requirements to work alongside Simphony, though, keep in mind that there are minimum requirements for Windows 7:
- 1 gigahertz (GHz) or faster 32-bit (x86) or 64-bit (x64) processor*
- 1 gigabyte (GB) RAM (32-bit) or 2 GB RAM (64-bit)
- 16 GB available hard disk space (32-bit) or 20 GB (64-bit)
- DirectX 9 graphics device with WDDM 1.0 or higher driver

1. FIREWALL CONFIGURATION

PUNCHH Firewall rules. Confirm that the following FQDN (Fully Qualified Domain Names) endpoints are properly whitelisted in the site's firewall/router

(PUNCHH DOES NOT SUPPORT FIREWALL RULES USING IP ADDRESSES)

NETWORK FIREWALL CONFIGURATION

ALLOW:	FROM:	TO:	BY: (Software Firewall on PC running Punchh processes)
TCP using port 443	The PC/Terminal (CAPS/Master Terminal running the Punchh Proxy Service	pos.punchh.com isl.punchh.com poslogs.punchh.com loguploads.punchh.com	Punchh.exe (Running on either back office or CAPS Server)
Websurfing	POS BOH and terminals	https://*.punchh.com

Endpoint Details

Please contact Punchh support if your portal is a dedicated instance to get the endpoints specific for you. If you login to your Punchh portal via any other URL than https://punchh.com, then you will need to get your brand’s specific endpoints.

Default endpoints

pos.punchh.com - Punchh check-in and redemption transactions, Punchh application configuration & update server
isl.punchh.com - Punchh check and barcode details
loguploads.punchh.com - Punchh log file repository #1
poslogs.punchh.com - Punchh log file repository #2

SOFTWARE FIREWALL & ANTI-VIRUS AND APPLICATION WHITELISTING CONFIGURATION

Anti Virus

Files in these folder need to be able to be updated and automatically added to the POS BOH PC application whitelist when updated by our update service.

Verify that the designated directories and sub-directories below are excluded from AntiVirus and real time scanning on the POS
Executable application files in these directories should also be whitelisted in any software application whitelisting control

Location	Directory	Files
CAPS Server/BOH PCF	c:\Program Files\Punchh\* c:\Program Files (x86)\Punchh\*	All files ending in.exe
POS Terminals

Application Whitelisting

Whitelist all of the Punchh EXE in the Application Whitelisting Control to allow communication over network designated in the table above
Whitelist all applications that are digitally signed by “Punchh, Inc.”
- To allow updates without having to go back and “re-fingerprint” individual EXEs

Doing the above whitelisting will allow for updates to be managed without having to “re-fingerprint” the updated individual exe files in the installation directory making updating, when needed, an easier experience.

NETWORK FIREWALL VALIDATION

From the POS CAPS Server or the Backoffice PC (Wherever the Punchh Proxy punchh.exe service is installed)

Open a web browser and navigate to the following web pages
Each web page should return a plain white page with OK
If any page doesn't return OK, the firewall needs to be reviewed to ensure the correct FW rules are in place

2. CONFIGURE LOYALTY DISCOUNT IN EMC

In EMC, navigate to Configuration > Sales > Discounts
Click the “Insert” button:
Check the box for “Use Template” towards the bottom of this pop-up.
Click “Select” and choose the existing Open $ discount from the list that displays and click “OK.”
Input a name for the discount in the field, “Record Name(s)”
Click “OK” to confirm.
After you click “OK”, you will be taken to “Table View” for your discounts. The new discount that you have created should automatically be selected, though if not click on the line containing your new discount.
In this line, your columns should be configured as:
#: Automatic selection of Number
Name: The Name you chose
Zone/Location: Automatic selection of your Property Name
Inheritance Type: Defined Here, No Override
Report Group: 0-None
Activation: 0-Manual (Manually Entered and applied)
Configure the remaining columns:
To modify one of the entries, click the 3 “...” shown to the right of the cell where the entry is held
RVC Type
Configure RVC types by Clicking the “...” where “FFFFFFFF” is currently displayed - you will get a popup.
Select the RVCs (Revenue Centers) that you’d like to apply the discount to. Click “OK” when complete.
For the sake of testing, Punchh utilized all RVCs - your options will likely differ from this screenshot.
Tax classes
1. The tax assessed on Punchh discounted items will be determined based on the tax class selected here:
2. Select the Tax Class Applicable to your environment
Options
With the “Options” panel, make sure that “Discount Combo Meal Group Items” is selected. Punchh will not function properly with only #1 and #2 default options selected.
Itemizers
With Itemizers, think of this as “what options should be able to be discounted.” Some brands choose not to allow for Alcohol to be discounted, if applicable, do not check the box for “Alcohol” if configured in your Simphony.
For testing purposes, Punchh only created one itemizer. Your screen will likely differ. Please note that any restrictions on the POS that are also not set in the Punchh Portal will result failure to apply Punchh reward discounts
Output
The below screenshot shows the default settings. No issues were seen with keeping these as such. However, there are no requirements regarding functionality with this setting.
Order Device
There are no known settings that needed here for Punchh functionality
Percent
If you were configuring a % off discount, such as a 100% off COMP discount, you’d use this field. For the purpose of the Punchh discount, leave this at “0.00”
Amount
Similar to the above “Percent” setting, if the discount were to reduce a specific amount each time, we’d configure this here. For the Punchh discount we’ll skip this and leave the setting at “0.00”
Min Amount
The Minimum Amount setting is used to specify if there’s a minimum to be set up that’s required prior to the discount being applied. Since this can vary, we’ll leave this at “0.00.”
Priv Grp
Select a Privilege Group to restrict the discount to only employees who are linked to the same privilege group. Set the Privilege Group to 0 to allow all employees to use the discount.
Main Level & Sub Level
In the Menu Level Configuration section, select the Active On Main Levels and Active On Sub Levels on which the discount is active.
During our installation, we left all options checked to apply to all levels and saw no issues with functionality.
Main Level Popup/Sub Level Popup & Trans DFLT Main/Trans DFLT Sub
In the Main Level Popup and Sub Level Popup sections, select Transaction Default to return the transaction to the default Main Level or Sub Level after the discount is pressed
Select 0 - Stay Down to keep the current transaction levels, or select one of the levels 1-8 to become active.
Deselect Transaction Default to make the other levels active for selection. In testing, we found no errors with these not being selected.
Condiment Discountability
Select the method to determine how condiment menu items are discounted from the Condiment Discountability drop-down list.
4- Parent and All Condiment Items is suggested.
NLU/SLU/MMH SLU
These options are all optional and do not affect Punchh functionality. Please refer to Oracle’s Documentation regarding these settings
Icon
(Optional) From the Icon drop-down list, select an icon to assign to the discount key.
Trans Excl
No options are needed here for Transaction Exclusions.
Item Excl
No exclusions necessary for Punchh functionality
Rule Type
Set to 0 - Not Active (default)
Trigger MI Group/Trigger Condiment Group
From the Trigger MI Group and Trigger Condiment Group drop-down list, select the menu item group that triggers the discount.
This is an alternative method to using discount itemizers. The discount applies to only those qualifying menu items based on the selected Trigger MI Group, Trigger Condiment Group, and other discount configurations. These settings are not required to be changed for Punchh functionality
Trigger Quantity
Not needed for Punchh functionality
Set to 0
Trigger Total
Not needed for Punchh functionality
Set to 0
Award & Max Count Settings
The following settings may be left at default. There are no issues seen should these be changed and further configured, though there are no configurations needed for Punchh functionality:
Award MI Group
Award Type
Award Count
Award Max Count
Max Count Per Check
Remaining Settings
There are no further configurations needed for Punchh functionality. Leave the remaining settings blank/deselected

3. INSTALL THE PUNCHH SERVICE

Installing & Configuring the Punchh Service & Configurator

Choose a PC at the location to install the Punchh Service on. When choosing this PC keep the following in mind:
1. If there’s a CAPS terminal at the location, then this PC should be the CAPS terminal.
2. This PC needs to have internet access, so that check/transaction data can be sent to the Punchh server.
3. This PC must meet these system requirements:
  Minimum OS: Windows 7 w/ SP1 + .NET Framework 4.6.1
Login as an Administrator, and run the SetupPunchh.msi installer.
Leave the installation path as C:\Program Files (x86)\Punchh.
After installation, check to see that the Punchh service installed and is running.
Do so by pulling up the Windows services and looking for “Punchh.”
You may access the Windows services by:
- Typing WIndows Key + R > typing services.msc >enter
- Searching for “Services” from the Windows start menu.
Navigate to the installation folder C:\Program Files (x86)\Punchh.
Open PunchhConfigurator.exe:
If you or your company use an Application Whitelisting Service, ensure that the contents of this directory are whitelisted so that updates and functionality are not impeded
Enter the location specific API_Key and set the POS_Type to Simphony.
If you are unsure about your location’s “API_KEY” you will find this in the Punchh Platform under:
Settings>Locations>Find your Location>Click on the POS Tab> Scroll down and find the “Location Key.”
Click on the Simphony.cfg tab:
Note: The default port is set to 5614. If this port is already in use by another application, then an error will appear in the log files. See the Troubleshooting section of this document for more details.
Change the value of PunchhDiscountObjectNum :
to the loyalty discount ID from the EMC setup:
Click the Apply button. The Punchh service will be restarted, and the configuration files will be updated.
The PunchhConfigurator.exe will not close automatically - click “Exit” to do so after clicking “Apply.”

4. ADD THE “PunchhSimphony” EXTENSION APPLICATION IN EMC

When the Punchh application is installed on the CAPS server, the Punchh application DLL files will be written to C:\program files (x86)\Punchh
If that computer does not have EMC, then copy these DLLs so that they may be used used in the next step for installing on EMC.

Note: The “PunchhSimphony” extension applications should be configured at the enterprise level so that this section does not need to be repeated at each location.

In EMC, navigate to Setup > Custom Content> Extension Application.
Click the Insert button
Enter “PunchhSimphony” for the Record Name
Click on the record you just created and Toggle to the Form View:
Click “Insert Application Content”
Note: Do not modify the auto-generated DbID
Enter “PunchhSimphony” for ZoneableKey, and give this record an applicable description. Click OK.

Please repeat these 6 steps to add support for Simphony 19.2 and future updates. For the second Extension Application enter “PunchhSimphony_19_2” under ZoneableKey and an applicable description. Click OK.

For Simphony version any to 19.1 add ZonableKey= PunchhSimphony

For Simphony version 19.2 or higher, add ZonableKey= PunchhSimphony_19_2
From the “Content Type” Drop Down Menu, select “DLL.”
Click “Import from a file”, and navigate to C:\Program Files (x86)\Punchh\PunchhSimphony.dll. Click “Open”
Follow the last 2 steps for the second Extension Application but navigate to C:\Program Files (x86)\Punchh\PunchhSimphony_19_2.dll. Click “Open”
Click the “General” tab, click “Insert Application Content” and enter “PunchhSimphony.dll” under Disk File Name for both Extension Applications. The version settings for both Extension Applications should match the settings in the screenshot below.
Click the triple dots button under Option Bits:

Make sure the “Do not load DLL” checkbox is unchecked, then click OK:
Click the Save button found in the toolbar of EMC:

5. ADD THE IP/PORT DLL IN EMC

Note: Since the IP Address of the hosting computer will be different at each location, this process MUST be re-done for each location

In EMC, navigate to Setup > Custom Content>Extension Application
Click the Insert button:
Enter “PunchhConnInfo_<LOCATION NAME>” for the Record Name (replace <LOCATION NAME> with something that uniquely identifies this store)
Ex: PunchhConnInfo_SanMateo
Click Ok
Toggle to the Form View:
Click “Insert Application Content”
For ZoneableKey, enter the same value as the Record Name. Leave the Description blank, then click OK:
From the “Content Type” Drop Down Menu, select “DLL.”
Click “Import from a file”, and select the .dll which contains the IP and Port in the filename:
Click the “General” tab:
Click the triple dots button under Option Bits:
Check the “Do not load DLL” checkbox, then click OK:
Enter the dll filename for the Disk File Name:
Click the Save button found in the toolbar of EMC:

6. CONFIGURE THE PUNCHH LOYALTY BUTTON

In the EMC, navigate to Configuration > User Interface > Page Design
From the available list of pages, choose “Transaction Page.”
Navigate to the page that you want the Loyalty button to appear on. We chose the Payments>Cash location as there was adequate room. You may choose whichever page makes sense to your operation.
Add the loyalty button using Edit > Button
A grey button will show. Drag and drop this to the appropriate location. A detail panel will show on the left hand side
Follow the next steps to configure the Button:
On the GENERAL tab:
Legend: Punchh (this is the name that will display on the button)
Type: Function
Click the arrow
Search for “Run Extensibility App”, select this item then click OK.

Arguments
Click the arrow
Enter the following:
Type: dll
appname:PunchhSimphony
Filename: PunchhSimphony.dll
Function: Main
Click OK
Customize the rest of the button to your liking. There are no further configurations that affect functionality. Click the Save button:

7. SET UP & RUNNING THE PUNCHH LOOKUP USER INTERFACE FOR FIRST TIME

On the computer/terminal hosting the Punchh service,usually referred to as the CAPS Server, verify that the Punchh service is currently running (Services app).
You may access the Windows services by:
- Typing Windows Key + R > typing services.msc >enter
- Searching for “Services” from the Windows start menu.
Start the Simphony client if it’s not already running.
Click the Update Database button, at the bottom of the screen, to fetch the PunchhSimphony.dll, IP/Port dll, and any other new changes from the EMC
Restart the Simphony client by clicking the Close Application button, found on the bottom left of the same screen, then re-run the program. This allows the PunchhSimphony.dll to load.
Ring in an order and navigate to where you placed the Loyalty button in the previous step.
Since this is the first time that the PunchhSimphony.dll is being loaded, some additional files are being fetched from the Punchh Service. Therefore, clicking the Loyalty button during this time may display this message:
This message will only display when the DLLs are being loaded for the first time from the actual Simphony UI.
If you tap the “Punchh” button, and it seems to not respond right away, do not tap again. If you do, this will open multiple loyalty search boxes.
Wait for 5 minutes to allow for these files to be pulled and applied correctly. Click the Loyalty button again and verify that the Loyalty UI appears (Note: the very first load will be slower than normal):

POS Configuration Validation

After the Loyalty UI loads, confirm the last few details to ensure configuration all around:

The “Loyalty Discount” line item should appear when discounts are redeemed:
QR code is being printed correctly when check is closed:
Close the Search UI using the red X in the top-right corner
Repeat the steps for each Simphony client.
Note: If the UI fails to load: Try repeating the above steps for, “Setting Up Simphony Clients.” , However, tap Reload Workstation Database after Update Database. If still having trouble, please refer to the Troubleshooting section.

Note:

For QR code printing, the Summary Totals and Pre-Trailer sections of the receipt will be replaced by the contents of the QR code. These sections should be ignored when defining receipt descriptors in the EMC.

8. TROUBLESHOOTING

Log files

If you are getting errors when applying redemptions or when trying to scan the QR code to earn points please check Punchh logs for errors. Logs are located:

C:\Program Files (x86)\Punchh\Logs
or
C:\Program Files\Punchh\Logs

Log files are named by date, for example:
2017-0223-000050.log
was created on Feb-23, 2017

Port conflict error:

Identification:

If the default port is already in use by another application, a port conflict error will occur. In the log file, please search for the text “Port conflict occurred”. If this text was found, then the error occurred.

Resolution:

To resolve this error, please use the PunchhConfigurator tool to change the default port to an unused TCP port. Some suggested ports, usually not in use, are: 5619, 7482, 24473, 10123.

Loyalty UI fails to load:

If the Loyalty UI fails to load after clicking the Loyalty button, please check this log file located on each POS terminal: C:\Micros\Simphony\WebServer\PunchhSimphony.log

If you don’t know how to resolve the errors, please contact Punchh support with attached log files.

How to make Punchh work in Micros Simphony whenever an IP address gets changed:

Step 1 : Verify IP address and ports are correctly defined in Simphony.cfg
Step 2 : Verify IP Address and ports are correctly defined in EMC (follow confluence doc)
Step 3 : Uninstall Punchh Completely
Step 4 : Remove All folder and files inside C:/Program Files/Punchh except Config , Data, Logs folder.
Step 5 : Go to Run > type %temp% , it will open up temp folder in explorer. Search for PunchhUI. Delete all files related to PunchhUI..
Step 6. Wait for 5 minutes..Check again..

Known Issues

Lookup by swiping or scanning loyalty card is not supported.
QR code may be too large.
No single scan functionality.
Unable to process multiple redemptions

Articles in this section