Micros RES Punchh Integration POS Setup (for customer on proxy version older than 7.12.2)

PUNCHH INTEGRATION SETUP

Prerequisites:

1. Verify, that you have the valid “POS Configurator” user name and password which gives you edit access to the application
   (Interfaces, Screen Designer, Print Designer, Discounts)

2. Find out from the POS owner\operator, where do they want the Check-in and Redeem buttons to be placed.

3. Verify that the site network firewall is setup to allow communication to Punchh service endpoints following the Micros RES Firewall Site Guide

4. Verify that your MICROS configuration includes the PMS/SIM license Add-On:

   1. Navigate to Micros Application -> Utilities -> Micros License Manager -> POS 3700
      

      

   2. Verify that the PMS/SIM parameter is check-marked in green

      

5. Verify if the MICROS Database is up and running

   

   

    

Set up Punchh Service:

1. Log in as an Administrator

2. Execute the SetupPunchh.msi installer

   

   

   

   

   

3. Verify that the Punchh Installer has started the Punchh service:(Open Services on the PC and find Punchh service)
   

   

Micros POS Configuration:

Log in the Micros POS Configurator application

1. Start the POS Configurator application: "C:\Program Files\MICROS\Res\Pos\Bin\poscfg.exe

   

2. Log in: <Enter Your Log in Credentials> -> click OK button

   

3. Navigate to the Devices screen: Devices tab -> Devices button

   

4. On the Devices screen, go to the Record View applet

   

5. On the Record View applet find your printer(s) that will need to print the Guest Receipts with the Punchh Barcode and Check Message and notate the printer types for these printers

   1. Identify the printer types for each Receipt Printer
      Ex. 12-W5ABar1 Ptr record) = IDN Printer

      

      Ex. 1- Printer = RS232

      

      Make a note of your printer types.
      
      Ex - 100 Printer - TCP/IP Interface

      

      
      Set the Printer Interface IP with default port : 9100 (for Epson printers) [It can vary depending upon what printer model you are using]
      

      

      
      You will need to enter the corresponding value for the IDNPrinter parameter in the Punchh Configurator

   2. If there is more than one printer type record, per the requirement mentioned above you cannot have a mix of IDN and RS-232 printers. If this is attempted, only one type or printer will be enabled to print the Punchh messages and barcode based on the value set in the Punchh Configurator

6. Close the Devices screen

Setup Micros Punchh Discount

1. Navigate to the Record View screen: Sales tab -> Discounts button:

   

2. On the Discounts screen, go to the Record View screen, verify the values existing in the Number fields, and create a new Punchh discount record:

   

   1. If the value “300” in the Number field is NOT associated with any record, then create a new Punchh record and put a value “300” into the Number field (This is the default value that the Punchh Configurator will assign when first installed)

   2. If the value “300” in the Number field is associated with any existing discount, then define any other number (for instance, the value such as “299”), create a new Punchh record, and put a value “299” into the Number

   3. Keep the new Punchh Discount record selected, and navigate to the right applet (the General tab is selected by default)

   4. Verify, that the following parameters in the fields associated with your new Punchh discount record, are up to date, or enter the required values manually:
      

      

      General  tab: Type: Manual (select from drop-down list)

      1. Other settings may be configured per business need

      2. Any restrictions in the POS Punchh Discount MUST be matched in the Punchh Portal Qualifying Criteria. If they do not match,
         there will be a risk of a Punchh approved discount not able to be applied to the POS check and the user will have their reward
         deducted from their account and not receive the Punchh POS discount on the check.

   5. Create a new SLU record named “Punchh Discount”

   6. On the SLU applet, hit the Browse button and navigate to the Descriptors screen

      

      On the Descriptors screen, create a new SLU record named “Punchh Discount”
      Save the “Punchh Discount” record and close the Descriptors screen.
      The Punchh SLU is not referenced on any other button. This SLU without a button reference is to ensure the Punchh discount is not accessible for manual application on a check. The Touchscreen style should also be left blank.

3. On the General screen, navigate to the SLU field and select there your new Punchh Discount record and save changes

   

4. Navigate to the Options applet under the Options tab on the right, and select the Amount check-box

   

5. Hit Save located on the Dashboard

6. Navigate to the Discount applet under the Discount tab on the right, and set or unset the Item Discount checkbox. Leaving this checkbox unchecked will ensure that multiple Punchh loyalty discounts can be added to a check. This includes being able to delete and then re-add Punchh discounts. When this option is enabled, Punchh Loyalty discounts will not be divided up amongst all items on the check but remain as a singular separate discount item.
   

   

7. Navigate to the Itemizers applet under the Itemizers tab on the right, and select at least one Itemizer:

   

8. Save the record And exit

Interface Parameter

By default, Punchh Integration service is using interface #90 to integrate to the Micros. It creates pms90.isl files in the etc folders as required. If Punchh service finds out that pms90.isl file is already there and it was not created by Punchh, then that will be reported in the log file. Punchh integration will not be complete in such case. To avoid this issue, navigate to the Interfaces screen and verify if the value “90” in the Number field is already associated with any existing interface.

1. Navigate to Devices Tab → Interfaces button

2. On the Interfaces screen, go to Record View screen and verify the values existing in the Number field

   

If the value “90” in the Number field is NOT associated with any interface

1. Create a new Interface record named “punchh” (it must be in lower case)

2. Navigate to the Number field of the new Punchh interface record and enter the number “90”

3. Keep the new Punchh interface record selected on the Record View applet, navigate to the General applet under the General tab on the right, and enter data into the following fields:
   

   

   1. Outgoing Message Name: punchh (it must be in lower case)

   2. Timeout: 15

   3. Network Node: Select your particular MICROS server from the drop-down list

   4. Number ID Digits: 9

   5. Backup Interface: leave it blank

   6. Log Transactions check-box: Unchecked

   7. SIM Interface check-box: Checked

   8. Interface Type: TCP

   9. Select SAVE

   10. Navigate to the Interface applet under the Interface tab on the right, and enter data into the following fields:|

       

       1. TCP Server Name: use actual IP address of the internal network or name of the BOH server

       2. TCP Port Number: 2000 (it is a default value, keep it as it is

 Setup Check Trailer on RVC Print Design

1. On the POS Configurator screen, navigate to the Revenue Center tab -> RVC Print Design button:

   

2. On the RVC Print Design screen, go to the Record View applet on the left and select any existing record

3. Navigate to the right applet and hit the Trailers tab

4. On the Trailers screen, hit the Browse button, and it will navigate to the Descriptors screen
   

   

5. On the Descriptors screen, you have to be navigated to the Trailers screen. On the Trailers screen, go to the Trailers Record View applet on the left

6. On the Trailers Record View applet, find and select the record associated with the customer receipt

   

   1. Keeping this record selected, navigate to the Trailers Lines applet on the right and enter the “@@punchh” value like shown below (the “@@punchh” is the placeholder for Punchh message on the checks)

   2. Select Save button located on the Dashboard 

Create the POS Punchh buttons

As per the Prerequisites section, create the Check-in (via QR code, phone number, card) and Punchh Redeem(QR code/number, phone number, card) buttons where the POS owner\operator wants these buttons to be placed. Also verify if Check-in button is required by POS owner\operator. 

Check-in and Punchh Redeem Buttons

1. On the POS Configurator screen, navigate to the Touchscreen Designer screen: Device tab -> Touchscreen Designer button:

   

2. On the Touchscreen Designer screen, create

   1. Check-In button via QR-code
      

      

      Category: SIM/PMS Inquire
      Interface: 90 punchh
      Inquire number: 11

   2. Check-In button via phone number
      

      

      Category: SIM/PMS Inquire
      Interface: 90 punchh
      Inquire number: 13

   3. Check-In button via card

      

      Category: SIM/PMS Inquire
      Interface: 90 punchh
      Inquire number: 12

   4. Punchh Redeem button via QR-code or number
      

      

      Category: SIM/PMS Inquire
      Interface: 90 punchh
      Inquire number: 9

   5. Punchh Redeem button via card

      

      Category: SIM/PMS Inquire
      Interface: 90 punchh
      Inquire number: 10
      
      NOTE: It is also recommended to redefine “Cancel” button by assigning it to:
      

      

      Category: SIM/PMS Inquire
      Interface: 90 punchh
      Inquire number: 1
      
       That will ensure that Punchh receives check cancellation events

Setup Using the Punchh Configurator Utility

Launch the provided Punchh Configurator utility: C:\ProgramFiles\Punchh\PunchhConfigurator.exe

1. The Punchh Configurator screen should pop up, and by default, you should be navigated to the punchh.cfg tab in the Punchh Configurator
   Update the following parameters shown on the screen below with appropriate data using drop-down menu options or direct typing;

   

   1. API = isl (Default)
      Micros specific API endpoint for Micros API calls.
      Do not change

   2. API_Key = <API Key for the location being setup>
      Punchh Portal\Settings\Locations\POS Tab
      Will be unique for each location

   3. Barcode on Redeem = <True or False>
      Whether to print a barcode on checks that have a Punchh Redemption

   4. Business Key parameter = Business Key Value for Brand
      Punchh Portal\Cockpit\POS Integration
      Will need to be provided by Punchh Staff, will be the same value for ALL POS locations

   5. POS_Type = Micros
      Once this is set, the Generic.cfg tab will change to Micros.cfg

      

   6. Currency Symbol = $ (Default)
      Not Applicable to Micros RES

   7. Customer = any (Default)
      This setting is used to provide Micros alternative Error messages and POS Prompts for specific brands
      Requires Development to provide this extended functionality

   8. DBCheckExpirationDays = 10 (Default 10)
      Oldest age of transactions stored in Proxy for Offline uploads are saved on the POS DB for uploading after an Internet outage

   9. DBCleanupIntervalDays = 1
      Qty of days between the Check details DB being purged for transactions older than DBCheckExpirationDays

   10. DisablebarodeFor = Regular Expression (Default value)
       This value may be replaced with a Regular Expression to conditionally allow printing of barcodes on POS transactions
       Ex. Registered User Online Orders

   11. EnableAdvanceMode = True (Default)
       Enabling this functionality add support for new messages and logging data to be written to logs.

   12. IslURL = http://pos.punchh.com (Default)
       Confirm this setting for your Brand with your Punchh Customer Success Manager

   13. KeepSocketsOpen = True
       Setting allows multiple POS<-->Proxy transactions to be performed over a single open TCP thread
       Required for Micro RES for optimal performance and reliability

   14. Language = en (Default)
       Default English
       Supported languages: es (Spanish)

   15. LogUploadURL = https://loguploads.punchh.com (Default)
       This setting is used in conjunction with the Business Key set.
       For older integrations without the Business Key setting available set this to: https://poslogs.punchh.com

   16. LoyaltyButtonName = Punchh
       Used in New UI to name the
       Not Applicable for Micros RES

   17. MaintenanceHour = 4 (Default)
       Hour of the day that log file rotation, uploads and database maintenance is performed

   18. PosUrl = https://pos.punchh.com (Default)
       Confirm this setting for your Brand with your Punchh Customer Success Manager

   19. ProxyDestination = <blank> (Default)
       Set when the POS Network needs to use a Proxy server for connection to internet

   20. ProxyPort = <Empty> (Default)
       Set when the POS Network needs to use a Proxy server for connection to internet

   21. PunchhUIChunkSizeKB = 150 (Default)
       Setting that breaks the PunchhUI application files into smaller chunks for distribution to POS terminals (Micros Simphony)
       Not Applicable for Micros RES

   22. PunchhUIStartupLocation = 1
       New UI starting location when opened
       0 = Display in center of screen
       1 = Upper Left of the screen
       Not Applicable for Micros RES

2. Click the Apply button

3. Verify, that the <POS>.cfg tab is automatically renamed to Micros.cfg

   

4. Set the Micros POS Settings:
   

   

   1. BarcodeHeight = 40
      Based on Epson TM-88 type printers

   2. BarcodeWidth = 3
      Based on Epson TM-88 type printers

   3. DiscountID = 300 (Default)
      Set this to the value set in Setup Micros Punchh Discount - Step 2.a

   4. IDNPrinter = False (Default)
      False for RS-232 / TCP/IP based Printers
      False Plus OPS Prefix = OPOS Printer
      True for IDN Printers

   5. Interface = 90 (Default)
      Set to 90 unless during step Interface Parameter you identified another interface using this ID. In that case set this to the Punchh Interface you created

   6. OPOSPrefix = @ (Default)
      Set to match the correct OPOS Printer Prefix

   7. PathToMicros = d:\Micros
      Path without trailing slash to where Micro is installed on the Micro BOH

   8. Port = 2000 (Default)
      Do not change unless there are known conflicting applications running in the Micro BOH where the Punchh Proxy application will run

   9. PrintVoucher = False (Default)
      True = Pint a redemption voucher chit when a Punchh redemption occurs on the POS order. Used for Cashier redemption validation tracking

   10. SendFamiliyGroupName = False
       False = Send the Micro Family Group ID instead of the Group Name. Best Practice is to use ID since that are less likely to ever be charged on the POS
       True = Send the Micro Family Group text name instead of the ID. This is useful for when the brand is using more than one POS type ad one of the POS’s cannot set the Group ID values
       Once set for the brand, do not change this setting unless all Punchh Portal Line Item Sectors are also updated

   11. SendMajorGroupName = False
       False = Send the Micro Major Group ID instead of the Group Name. Best Practice is to use ID since that are less likely to ever be charged on the POS
       True = Send the Micro Major Group text name instead of the ID. This is useful for when the brand is using more than one POS type ad one of the POS’s cannot set the Group ID values
       Once set for the brand, do not change this setting unless all Punchh Portal Line Item Sectors are also updated

   12. useProperGroups = True

   13. Hit the Apply button to save the changes

Reload the MICROS DB (or Reboot the system)

 NOTE: Screen shots maybe different depending on your version of the POS. 

1. Navigate to the Micros Applications menu and select the Micros Control Panel item

   

2. Click the Front of House button and hit the Reload DB button to get the following status

   

Verify Punchh Service and Punchh Functionality

1. Verify the Punchh Service restarted

   NOTE: You may want to set the following service recovery options as it is shown below (it is OPTIONAL):             

   

2. Verify that the Punchh Service has completed all the required steps successfully:

   • Navigate to the %INSTALL DIR%\Logs directory

   • Open the latest log file and scan for errors & warnings

   • If there are no issues related to the isl file, then the Punchh service reports this kind of information in the log file for each location shown above:

     

   • If the Punchh service finds the isl file already existing in any of the specified directories, then the Punchh service does NOT overwrite the existing pms90.isl file and reports such issues into a log file. For instance:
     

     

   • In Micros.cfg, if you define the path other than Micros installation path then you need to make sure it follows the same directory structure as micros installation folder have.. For example: If you define the path = “D:\punchh\micros“ then you need to make sure subsequent folders Res\Pos\Etc are present and then only it will copy punchh isl file once you restart the proxy service. In this case, business will have a responsibility to manually inject/copy this ISL file to micros installation path : D:\Micros\Res\Pos\Etc where D :\Micros is the default installation path for micros.
     

   • Check the logs and make sure there are entries like that created every 5 minutes. The following is the PING message from MICROS, which confirms successful connection: