Modules:LoyaltyManagement/Configuration Manual
Contents |
Introduction
This article explains how to configure the module Loyalty Management. It assumes the reader knows how to configure Openbravo Commerce Platform and other entities like payment methods.
As it has been mentioned before, this module needs to be integrated with a third party (Loyalty Program's Vendor) and thus customizations will be required on top of this module, to adapt it to the selected program. Hence, this module provides the skeleton and necessary structure in the backoffice with that purpose.
The idea is that customer accounts (with the points balance) are managed in the vendor's platform, so rewards can be earned from different retailers and sent to the vendor's platform to be accumulated/redeemed in a single point. Vendor's rules for accumulation and redemption are replicated in Openbravo to be able to earn and redeem points in Web POS under the Loyalty Program rules. Additionally, it is also possible to check the customers balance systems from Web POS by means of online webservices and identifying the customer's account by reading the customer's loyalty card.
The following sections will describe how to configure all the necessary and common entities to all loyalty programs.
A new entry in the menu has been added for all Loyalty windows:
Loyalty Program Configuration
First thing to configure is the Loyalty Program, where we will declare all details of the program we are integrating with. The information here configured is first of all general info and second information regarding Accumulation and Redemption. Navigate to Loyalty Program window and create a new record following these guidelines:
- Name: Loyalty program name
- Reward's name: each program has its own rewards name, e.g Miles for flying loyalty programs
- Reward's symbol: reward abbreviation or symbol for the program, to be used when indicating quantities
- Reward's symbol at the right side: check it if the symbol needs to be placed at the right side of the amount
- Minimum amount required for accumulation: some programs require a minimum amount (in the Store Currency) to allow accumulation. E.g the ticket total needs to be 10$ of minimum amount to start earning Miles
- Minimum amount required for redemption: same way, indicate if it is required minimum amount to pay with the loyalty program
- Rounding accumulation: check it if the earned rewards will be rounded after their calculation
- Accumulation rounding type: the ones implemented are Up, Down, Half up, Half down
- Rounding redemption: check it if the quantity to be paid with the loyalty program will be rounded after their calculation
- Redemption rounding type: the ones implemented are Up, Down, Half up, Half down
- Business Partner: this is the business partner that represents the Loyalty Program Vendor
- Loyalty Integration: select here your own Loyalty integration, that means you will need to create and develop one. Please follow this article [1] for more details]
- Allow refunds: check it if refunds in redemption are permitted. That means a customer pays a ticket of 1000 Miles and wants to return the items or cancel the payment and have the Miles back in his account
Sponsorship Definition
This window serves to gather different accumulation rules under a common activity o sponsorship. so they can be all grouped under the same sponsorship. The sponsorship has a relation with the business partner that sponsors the rule, but this is defined in Rules for Accumulation, so different rules can have different business partners, but same sponsorship.
- Name: sponsorship name
- Search Key: sponsorship search key
- Generic Rewards: check it if it is a generic reward, which means that generic rewards will be separated from the rest of the earned points in the customer receipt
Rules for Accumulation
Create all accumulation rules as needed using the dates fields to set up the validity, so a historic can be kept for a specific rule if needed. There are two different type of rules: generic or non generic. Generic rules are the ones applying to all products of the assortment. Non generic rules will only apply to the product specified in the definition.
The way rules are applied in Web POS is as follows: all valid rules for the given date will be applied in cascade. Example: let's say there are two rules defined, one generic and one non generic for Alpine Poles product. A customer buys 1 quantity of Alpine Poles, that means that both rules will be applied and the result of summing the points earned for both rules will be the total of awards earned after the purchase.
Each accumulation rule needs a sponsor, that is the business partner sponsoring the points earned (so the retailer can invoice him for that).
- Name: name for the accumulation rule
- Starting date: date where the rule will be applied from
- Ending date: date where the rule will be not longer valid
- Product: for generic rules leave it empty, for non generic rules select the product that the rule applies to. The example is a generic rule as this field is empty
- Loyalty Sponsorship: select the sponsorship previously defined
- Rate: indicate the conversion rule. Example, if conversion is 0.1, and EUR is the store currency, means that customer will earn 1 Mile for each 10EUR
- Business Partner: select the business partner that is sponsoring this rule
- Active: by default always checked. Only active rules will be applied
Rules for Redemption
Same way, rules for redemption need to be defined, where basically a conversion rate and valid dates need to be specified. Hence, when customer wants to pay with the loyalty program a specific amount, the currency will be converted to the loyalty currency with the specified conversion.
- Starting date: date where the rule will be applied from
- Ending date: date where the rule will be not longer valid
- Rate: conversion rate for redemption. In the example, 0.075 EUR (store currency) are equal to 1 Mile
- Active: by default always checked. Only active rules will be applied
Assign Loyalty Program to Stores
Navigate to Organization window, and select the store where you want to assign the Loyalty program you just created.
In Web POS Formats group of fields, select the new templates for printing receipts:
- Print ticket Template: select the new template Loyalty Receipt Template
- Invoice Template: select Loyalty Invoice Template
- Layaway Template: select Loyalty Layaway Template
Create a new record under Loyalty Manager tab:
- Loyalty Program: select the loyalty program you just created
- Rewards Balance Template: select Rewards Balance Template for the receipt printed when customer balance is requested from Web POS
Loyalty Management respects organizational hierarchy, that means that if a group of stores (under the same node) share the same Loyalty Program, you can assign the program at the node in the higher level and thus not having to assign it one by one per store. However, if you had an old program in one store, and decide to assign one at a higher level, you will need to clear cache to see the changes in Web POS.
![]() | Even the system allows you to assign more than one loyalty program per store, Multi-Loyalty Program is not supported currently in Openbravo. |
New Payment Method for Redemption
In order to redeem points, that is, pay with the Loyalty Program, a new payment method will be required.
This article assumes that the reader has experience creating payment methods for Openbravo Commerce Platform, otherwise check the following wiki article [[2]]. You will need to create previously a new payment method, the one in the example has been named Miles Club.
POS Terminal Type Configuration
Navigate to POS Terminal Type window, and for VBS POS, create a new record under Payment Method tab called Miles Club to be used for redemption:
- Search Key: it is mandatory to write OBPOS_Loyalty
- Name: name it as you desire, in the example Miles Club
- Payment Method: select the new payment method, in the example Miles Club
- Currency: select the same currency as the store has
- Document Type: configuration as standard payment method
- G/L Item for Writeoff: configuration as standard payment method
- Payment provider: here you will need to create your own payment provider, which basically means that you will need to develop what happens after the payment method Miles Club is selected in Web POS. In the current example we have developed one for a specific customer that will invoke online a Web Service to the Vendor's platform to decrease customer balance for the points redeemed in the payment
- Refund Provider: same way, select our own. In case of not having refunds for this payment method, just select Loyalty payment provider
- Allow Open Drawer: configuration as standard payment method
- Open Drawer Before Closing Ticket: configuration as standard payment method
- Cash: configuration as standard payment method
- Print twice: configuration as standard payment method
- Leave as credit: check it if your tickets paid with this new payment method will be handled as left as credit (for example if your company will invoice monthly to the Loyalty's Vendor for the tickets paid with this payment method)
- Not compatible with accumulation: check it if it is not allowed to earn and redeem points in the same transaction
POS Terminal Configuration
Naviagte to POS Terminal window and for VBS-1 create a new record under Payment Method tab:
- Search Key: it is mandatory to write OBLOY_payment.loyalty
- Name: name it as before, Miles Club in the example
- Payment Method: select the payment method just created Miles Club
- Cash up Event: leave it blank as it was said to leave as credit after redemption, so no financial amount movements will take place during cash up
- Line: write 10 to place this payment method at the top of the list in Web POS payments interface
Security Preferences
Some preferences need to be configured in order to use loyalty functionality:
- Allow points accumulation from Menu: if set at Y, there is a new menu entrance in Web POS to accumulate loyalty awards
- Allow points accumulation when clicking on ticket total if set at Y, every time the total is selected to pay the ticket, there will be an intrusive pop-up to accumulate loyalty awards, so accumulation will be mandatory in each sales transaction
- OBLOY Enter card number by keypad: if set as Y, it is possible to introduce manually the customer's loyalty card number for balance request, points accumulation or redemption. Otherwise, it will be mandatory to use a card or barcode reader
- Allow rewards balance request: if set as Y, a new menu entrance will be accessible to request customer's rewards balance
Communication with External Systems
It has been mentioned that this module it is meant to be integrated with an external system where to request customer's balance or redeemed certain quantity of awards when paying a ticket.
Each integration will be different so there is no standard structure provided by Openbravo, nevertheless, we show in this section how it could be developed to guide the reader to develop something similar.
The idea is a window to declare all communications with the external system. In the example there are parameters for web service (URL, user name, password, id, etc) and other parameters for an FTP Server used to send a daily file with the accumulated points in Openbravo (IP, port, username and password).
Additionally, a child tab can be included to register all webservice issues, saving the Request and Response to be able to track the error afterwards.