Aloha POS Punchh Integration (Fresh Install)

Punchh Activation Steps

A. Prepare POS for Punchh Integration
B. Prepare Environment
C. Provide installation details to Punchh Customer Success or Implementations Manager
D. Punchh Application Installation

A. Configure POS for Punchh Integration

1. Create Punchh Comp for use by Punchh
2. Create Punchh Menu Item used for "Checkins"
3. Create Redemption Menu Item used for Punchh Redemptions
4. Create or identify Void Reason in case POS operator removes a checkin or redemption item from a check

A.1 Comp Setup for Punchh:

Create a Comp In Aloha which will be used by the Punchh application for redemptions

A.2 Create Punchh Menu Item used for "Checkins"

When a guest checks in on the POS, this item will be used to show the checkin:

A.3 Create Punchh Menu Item used for "Redemptions"

When a Punchh redemption is applied to a check, Punchh will use this menu item to show the redemption code on the check

A.4 Create a Void Reason for when a POS operator removes a checkin or redemption item from a check

When a POS Operator needs to reverse a checkin or redemption they will remove the Punchh menu item from the check.  When this occurs the designate 

B. Prepare the POS Environment

Follow the directions in the Aloha Firewall Site Setup

Be sure to run the Firewall Validation Steps

C. Provide installation details to Punchh

• New locations for an existing, live brand, follow steps in the Aloha New Site Activation Process guide to allow installation of Punchh on a new location
• For a new Punchh customer that is just being on-boarded, provide the following to your Implementations or Customer Success manager:
  Punchh Comp created in step A.1 
  Punchh "Checkin" Menu Item created in step A.2
  Punchh "Redemption" Menu Item created in step A.3
  Punchh Void assigned/or created in Step A.4 

D. APPLICATION INSTALLATION

D.1 Enable FOH Com and identify Punchh apps

Run Installation program on Aloha Back Of House computer

PunchhConf.exe will be launched to configure initial setting for Punchh software
D.1 AlohaPunchSetup.exe

• Install the Applications on the Back Office Computer

              
The setup application will install:

• AlohaPunchh Service - application that communicates to FOH terminals and external servers
• PunchhMonitor.exe - application that monitors AlohaPunchh service. It also monitors program updates and configuration changes (e.g receipts messages, comp id)
• PunchhConf.exe application that allows user to complete installation and configure settings used by Punchh programs

D.2 Launching PunchhConf.exe

Normally, the PunchhConf.exe application will not present the user interface.  If the following conditions are met:

• Firewall setup is The Punchh Aloha configuration setup properly
• The information required in step C have been provided and the conformation that the Aloha Punchh configuration server has been setup

The installation of the PunchhSetup.exe will automatically pull the sites configuration details from the Aloha configuration server and the PunchhConf.exe application Window will open and close, automatically setting the PunchhConf screen values

The PunchhConf application sets the following:

• Store id to the Punchh store identifier
• Enables bar code printing on guest check
• Identifies Aloha Comp id used for redemptions
• If needed, Identifies the Category of items that earn Punchh points
• If needed, identifies the categories of items that are allowed for redemptions
• Aloha Punchh Redeem Item Id
• Bar Code Header: message text appearing above the bar code on guest check
• Bar Code Footer : message text appearing below the bar code on guest check
  

D.2 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)
Click on an open button location to save the location for the table service system
   

D.3 Enable Punchh Application on FOH terminal: 

1. Go to Maintenance > Store > Store Settings
   Enter PunchhInter.ActivityHandler into a free "External integrated software component"
   This is how aloha attempts to load the Punchh Dll's (PunchhPrt.Dll and PunchhInter.dll)
2. The Punchh application dll's files need to be registered on each terminal
   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
   This file can be run to register the Dll's manually, if needed by opening Windows File Explorer and double click on it or run from a command window
   
3. Set the 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
   
    (To enable accessing Punch from the Aloha COMP pr Promo screen follow the Aloha POS Table Service Access Punchh from Comp or Promo Screens)
4. Set Aloha 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
      
5. Quick Service - Defining Punchh Redeem Button
   1. Create the desired button.
   2. Function -> Action = Custom Function
   3. Function -> Custom Text = PUNCHH_REDEEM_CODE
      
6. 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 step 5c
7. 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
      
   7. 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:

Enter the Customer's Phone number or
Scan the user's mobile app

Successful User Lookup:

        

        Useful Lookup Fails:

Earning Points: 

       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

        Redemptions:

        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:

Error Messages are displayed using a message box like the following example:

Here is a list of the current error messages:

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:

%windir%\Microsoft.NET\framework\v2.0.50727\regasm.exe %localdir%\bin\PunchhPrt.dll

%windir%\Microsoft.NET\framework\v2.0.50727\regasm.exe %localdir%\bin\PunchhInter.dll

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:

1. AlohaPunchhSvc.exe - The service that listens to FOH punchh apps and transmits check data from store to punchh.com. It also handles redemption processing.
2. PunchhMonitor.exe - Service that monitors AlohaPunchhSvc and monitors configuration changes made to store (e.g. receipt message)
3. 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.

Some Notes:

1. 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:

Uninstalling Punchh: 

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