Run Installation program on Aloha Back Of House computer
PunchhConf.exe will be launched to configure initial setting for Punchh software
Configure Aloha settings in Aloha POS used by Punchh software
a. Enable FOH Com and identify Punchh apps
b. Create Punchh Comp for use by Punchh.
c. Create Punchh Menu Item used for "Checkins".
d. Create Redemption Menu Item used for Punchh Redemptions.
e. Create or identify Void Reason in case pos user removes a checkin or redemption
i. Install the Applications on the Back Office Computer
ii. AlohaPunchh Service - application that communicates to FOH terminals and external servers
iii. Installs PunchhMonitor.exe - application that monitors AlohaPunchh service. It also monitors program updates and configuration changes (e.g receipts messages, comp id)
iv. Installs PunchhConf.exe application that allows user to complete installation and configure settings used by Punchh programs
1.Sets store id to the punchh store identifer.
2.Enables bar code printing on guest check
3.Identifies Aloha Comp id used for redemptions
4.If needed, Identifies the Category of items that earn punchh points.
5.If needed, identifies the categories of items that are allowed for redemptions.
6.Redeem Item Id : An open menu item created in aloha for the purpose of writing punchh redeem message on guest check.
7.Bar Code Header: message text appearing above the bar code on guest check.
8.Bar Code Footer : message text appearing below the bar code on guest check.
b. Redemption button location on Table Service
When the configuration program is run on a Table Service system, it will attempt to find a free location to install the redemption button on your system's tender screen (see below). Just Click on an open button location to save the location for the table service system.
C. Enable Punchh Application on FOH terminal:
1. Go to Maintenance > Store > Store Settings
i. Enter PunchhInter.ActivityHandler into a free "External integrated software component"
ii. This is how aloha attempts to load the Punchh Dll's (PunchhPrt.Dll and PunchhInter.dll)
2. The dll's need to be registered on each terminal
i. The Setup program will create a file named FOHADM.BAT that will be pushed to terminals. If site has Command Center installed on terminals, the this file will be run automatically upon restarts.
ii. This file can be run to register the Dll's manually, if needed. Just open explorer and double click on it or run from a command window.
d. Comp Setup for Punchh:
1. Setup a Comp In aloha which will be used by the Punchh Redemption.
a.Set the Maximum Amount desired for you operation.
b.Set Restrictions for your desired operations.
c.Set the Eligibility for your desired operation
2. Note the numeric ID, as that is what the punchh program uses to reference the comp you have defined
e. Open Menu Item for Punchh Scan and Checkins
1. There will be two (2) Open items that NEED to be configured
a. One item will be used for Scanning Check in code from Customer's smart phones
b. A second open item will be used for Scanning in a Redemption code for a customer's smart phone
2. Listed below is an example of how these open items need to be configured
3. Setup an Open Item menu item for punchh to use. This item is utilized to insert the a message on the guest check which shows the Punchh Redemption verification code
4. Check the "Ask for Description" option to allow for the verification code to be inserted onto check
f. Punchh Redeem Button location on Table Service Tender Screen
Here's an example of the Punchh Redeem button being located on the Tender Screen, which was configured by the PunchhConf.exe program
g. Quick Service Buttons
With Aloha QS, buttons will have to be defined to call the functions we're using for Punchh. The screen below shows two buttons that are defined:
1. The Redemption button is called when process a Punchh Redemption
2. The Punchh Scan Button is used to process a guest's checkin
h. Quick Service - Defining Punchh Redeem Button
1. Create the desired button.
2. Function -> Action = Custom Function
3. Function -> Custom Text = PUNCHH_REDEEM_CODE
i. Quick Service - Defining button to call coupon alpha/numeric entry
1. Coupon entries are entered using the same user interface as the redeem codes entered above at step h.
j. Table Service - Check in
Create a new order entry panel to allow for the 'Check In' button to be available
1. Create a new order entry panel using the screen editor
2. Add the existing buttons with desired functions
3. Add a button titled check in
4. Set the Check in button's function to Custom Activity
5. Set the customer text to: PUNCHH_REDEEM_CODE
6. Save the panel and exit screen editor
k. Table Service - Check in
1. Add an event to set the newly created order screen for each job code that will need
to be able to access Punchh
FOH USER INTERFACE:
1. Enter the Customer's Phone number or
2. Scan the user's mobile app
Successful User Lookup:
Useful Lookup Fails:
1. Lookup User
2. Click on Earn button to apply customer's data to the check
3. If successful, a message will be displayed showing points have been awarded
4. In the POS, a message will be added to the check window
1. After a user has been looked up, clicking on one of the reward buttons displayed in the box labeled: "Available Rewards" (e.g: A free drink reward)
2. Scan or manually enter a customer's reward code from their mobile application
After choosing the reward or entering the reward code, the POS operator be prompted to verify that they want to apply the reward
When the reward has been applied, a message box will be displayed showing the customer has been rewarded. The comp will be applied to the POS check.
Error Messages are displayed using a message box like the following example:
Here is a list of the current error messages:
|Punchh Operation||Error Type||What to Do Message||Note|
|Redeem||Redemption Failed||User Lookup Failed||This is the default message|
|Discount qualification on receipt failed for customer||Ensure required items are on the check.|
|Discount qualification on receipt failed for customer||Inform customer that logging out of the app and back in may resolve the error. Have the customer scan the bar code on the receipt.|
|User Not Found for the redemption code entered||Verify number entered and retry redemption or use lookup|
|Not enough rewards balance on account||Verify account balance and retry redemption|
|A Communication Error occurred||Retry Redemption|
|Discount qualification on receipt failed for customer||Ensure required items are on the check|
|Reward is not accessible for this customer||Click on Guest Lookup button to refresh rewards|
|Due to POS related Error||Ensure Cash drawer is assigned|
|Invalid Coupon code error||Ensure Coupon code is correct|
|Invalid Check error||Ensure check data is entered correctly|
|Code has already been processed||Ensure code being entered is current|
|The Amount on check does not qualify||Ensure items on the check are correct|
|The customer currently has an open transaction||Try operation again in a few seconds|
|Earn Error||No points were added due to an error. Customer was not awarded points due to an error||Rescan the QR Code|
|No points were added due to an error. Customer was not awarded because the check has 0 items||Enter menu items on the check|
|User Lookup Error||Lookup failed for customer||Verify number entered and retry lookup|
Punchh FOH Application/Files:
1. PunchhPrt.dll -This application extension intercepts the guest check messages and appends the desired Punchh Messages and bar code.
2. PunchhInter.dll -This application extension intercepts the check data before printing and transmits check contents to the boh service program (i.e. AlohaPunchhSvc.exe).
3. AlohaPunchh.exe -this application accepts redemption code from pos operator, verifies redemption code and applies comp when punchh.com approves redemption code.
4. PunchhInter.config -config file that stores variables used by punchh Apps (e.g. receipt header, footer and comp id)
5. TounchKbd2.dll, TouchBtn2.dll, BgcInterop.INTERCEPTACTIVITYLib.dll,BgcInterop.AlohaFOHLib.dll -Components used by Punchh apps
6. Register Punchh DLL's:
The files: PunchhPrt.dll and PunchhInter.dll must be registered on the FOH terminals in order for aloha to utilize them. If the file, FOHADM.BAT is not present when the setup program is run, the setup program will install it with the following commands:
If these commands are not run successfully, then punchh will not produce a bar code and/or send check data to punchh
7. The Punchh programs will create log files in the aloha tmp folder for debuggin and trouble shooting. They are named: PunchhInter*.log and AlohaPunchh*.log
Using RAL to register dll's:
Punchh BOH Applications:
- AlohaPunchhSvc.exe - The service that listens to FOH punchh apps and transmits check data from store to punchh.com. It also handles redemption processing.
- PunchhMonitor.exe - Service that monitors AlohaPunchhSvc and monitors configuration changes made to store (e.g. receipt message)
- PunchhConf.exe - Initial configuration program
NOTE: Firewall settings on BOH and Router must be setup to allow access from BOH to the Punchh Service endpoints.Please see the guide here: Aloha Firewall Site Setup
Bar Code Printing Process: Troubleshooting Barcode Printing:
Punchh Troubleshooting Tips:
1. Barcode Issues
a. Barcodes are NOT printng on Guest Check
i. Verify the Punchh Dashboard setting have been setup to print barcodes
ii. Verify the Punchh Dashboard does NOT have diag flag checked
b. Barcodes are printing all 9999999's
i. This is an indication that the FOH terminal(s) have a communication issue with the Proxy service on the BOH
1. Verify that Punchh Service is running on BOH computer
2. Verify the TCP Port Punchh proxy service is running on the BOH
a. Check the most recent proxy logs found in C:\program files\punchh\bin\logs. There will be an entry showing the Port number (e.g. 8008) that is being used
b. If the Punchh Proxy can NOT start on the port, it will log an error indicating that it has an issue
c. The port being used by Punchh Proxy is stored in the file: c:\program files\punchh\bin\config\Aloha.cfg
3. Verify the TCP Port used by the FOH applications. It should match what is used by the proxy found in item 2 above (e.g. 8008 is the most common setting)
a. The file names PunchhInter.config, which is located in the Aloha bin folder has a line identifies the proxy port:
i) <proxyport value="8008" />
4. Verify that the port used for Proxy communications is allowed to pass through any firewall /antivirus programs running on the boh (e.g. Windows Firewall, Landesk, Norton). The the firewall configuration guide for hardware and software firewall, Anti Virus and application whitelisting setup here Aloha Firewall Site Setup
2. Redemption Issues:
a. BOH is showing offline in status window
i. Verify punchh proxy setting (see notes previously listed for Bar codes are printing 999999's).
ii. Check the foh terminal log: AlohaPunchh*.log (e.g. AlohaPunchh_20150915.log), which is found in Aloha TMP folder. All errors, warnings and other debug info is logged in this file for troubleshooting use
b. Redemption discount is NOT applied to the guest check
i. The program uses an Aloha Comp to apply the redemption to the guest check. Verify that the comp id used is found in PunchhInter.config:
1. <compid value ="17" />
ii. If the comp id is correct in PunchhInter.config, verify that the Comp is defined correctly in aloha. It should be setup to per the Comp Setup in this Documentation.
c. The Redemption code is NOT written on guest check
i. The program uses an open menu item to write info on the guest check (e.g. part of redemption code). Verify that menu item used is in the punchhInter.config file:
1. <redeemitemid value="1000" />
ii. Verify that the menu item is setup according to the notes found in Open Menu Item for Punchh Scan and Checkins
3. Checkin / Earning Issues:
a. Scanning interface form does not appear when button in aloha is clicked
i. Verify that the button is setup to call the Custom Function in aloha named PUNCHH_SCAN_CODE
b. QR Code information is not added to guest check after scanning the code and earning
i. Verify that the open menu item defined for use in adding this information to the guest check is setup and defined correctly in the PunchhIner.config file:
1. <punchhitemid vaue ="104" />
4. Large Log Issues:
a. Some customers have found that logs created in the aloha tmp folder may grow very large (e.g. greater that 500 kb). This is usually because of an enabled a setting in aloha used for special debugging called Record Capture Activities. The setting to turn off these extra messages can be found below:
Aloha Database Items needed:
1. Comp ID number (see notes re: comp setup)
2. Punchh Menu Item (an open menu item used to write Check in info on guest check)
3. Redemption Menu Item (an open menu item used to write redemption info on guest check)
4. Void Reason (used in case cashier voids a check in or redemption code)
Working with Aloha's Item Categories:
Most store's associate and group their menu items by some simple category identifiers for reporting purposes like the one shown below.
- Sales and Retail Categories:
Each menu item in aloha must be assigned to a Sales or Retail Category and they can only be assigned to one of these categories. For instance, if grape soda is assigned to the Soft Drink sales category above, it cannot be also assigned to the Food sales category.
2. General Categories:
Menu items can be assigned to multiple general categories for the store's reporting needs
3. To run specific campaigns, the business should use the general categories to earn and reward specific groups of items. A helpful method used in naming convention for these categories is to use the prefix of "Punch". Also, to prevent confusion, it's recommended that these items are assigned to distinct general categories vs multiple general categories. Here's an example:
1. The Installer on the Back Office will uninstall the Punchh services when used from the Control Panel -> Programs function. Before running uninstall, please see item 2.
2. NOTE: Uninstalling the Foh apps will depend upon what your business has deployed on the Back office computer, as some applications (e.g. Take Out and various on-line ordering platforms) will cause iber.exe or iberqs.exe to run and may load the punchhInter.dll and punchhPrt.dll. Here's how to remove them:
a. If Iber.exe or iberqs.exe is running on the back office computer, then you can issue a STOP front of house. Beware, if this occurs during business hours, then it will stop the POS terminals, so it's suggested you plan the uninstall after close of business.
b. After the instance of iber or iberqs has been stopped on the Back office, you can uninstall punchh from the Control panel and the punchh apps found in Aloha's bin folder will be removed too.
3. Unregistering punchh on Front of house. While not necessary, you can unregister the dll's used by punchh with these 2 commands on the terminals:
%windir%\Microsoft.NET\framework\v2.0.50727\regasm.exe /unregister %localdir%\bin\PunchhPrt.dll
%windir%\Microsoft.NET\framework\v2.0.50727\regasm.exe /unregister %localdir%\bin\PunchhInter.dll
4. The Punchh apps may still reside on the terminals due to aloha copying them prior to running the control panel's uninstall. To remove them from the POS Terminals you have a couple of options:
a. If the FOH is still stopped (see item 2), you should be able to delete them manually. Due to network policies, you may not have access to the Front of House bin folder where these apps are stored (I.e. Aloha's bin folder). Once removed, you can restart the terminals and "START" the front of house if you've performed a "STOP Foh" operation.
b. If your site uses a SyncInclusionList.cfgfile, then remove or remark out the punchh files listed in this file and refresh terminals. This will purge the terminal's bin folder and copy just the files listed in this file
c. If punchh needs to be removed during business hours, the using the Syncinclusionlist.cfg may be the easiest option to employ. Once the punchh entries are remarked out, just refresh the terminals or wait until End of Day to run