Projects:LoyaltyManagement/Technical Guide/LoyaltyIntegration
Contents |
How to create a Loyalty Integration
Introduction
Each loyalty program needs a custom implementation of the Loyalty Integration. There are 5 actions that can be implemented:
- Init
- Get Balance Link to functional specs pending
- Accumulate Point Link to functional specs pending
- Redeem Points Link to functional specs pending
- Cancel Redemption Link to functional specs pending
Each of the actions are ready to be launched from Openbravo WEB Pos Retail and the the implementation should implement the actions to integrate with the Loyalty System.
Some examples could be: call a webservice, create and upload a file, insert records in other database, etc...
Register the Loyalty Integration in Application Dictionary
Create the Loyalty Integration
To define your custom integration is needed to log as System Administrator and create a new record in:
Loyalty Management > Configuration > Loyalty Integration
- Name: The name that user will see on the Loyalty Program window
- Java Class: The Java Class created for the integration explained later
Once created you will be able to select the record in your Loyalty Program.
Assign the Loyalty Integration to a Loyalty Program
As Admin Role go to your defined loyalty program in:
Loyalty Management > Configuration > Loyalty Program
and select your Loyalty Integration
Create the Loyalty Integration
Introduction
All the custom loyalty integration must extend from the abstract class:
org.openbravo.retail.loyalty.communication.LoyaltyIntegration
Is necessary to override 5 methods:
/* * Initialize Integration */ abstract public void init(); /* * Return the numbers of points available */ abstract protected LoyaltyResult doGetBalancePoints(String memebershipId, JSONObject data) throws Exception; /* * Accumulate a certain numbers of points */ abstract protected LoyaltyResult doAccumulatePoints(String memebershipId, Order order, JSONObject data) throws Exception; /* * Redeem a certain numbers of points */ abstract protected LoyaltyResult doRedeemPoints(String memebershipId, OBLOYRedeemedPoints redemptionPoints, JSONObject data) throws Exception; /* * Cancel a redemption */ abstract protected LoyaltyResult doCancelRedemption(String memebershipId, OBLOYCancelRedemption oBLOYCancelRedemption, JSONObject data) throws Exception;
During this document we will see an explanation of each one and at the end of the document you will find an example.
Loyalty Result
All the methods returns an instance of LoyaltyResult.
LoyaltyResult result = new LoyaltyResult();
Is expected that the implementation will create, fill and return a LoyaltyResult with the result of the action. There are 5 variables that you can set.
- 1. success type: boolean
Mandatory, it defines if the action has been performed successfully or not.
Used in:
- always
example:
result.setSuccess(true);
- 2. succesMessage type: String
Message shown to the user in case of success.
Used in:
- Get Member Balance (see later)
example:
result.setSuccesMessage("The balance is " + balance);
- 3. errorMessage type: String
Message shown to the user in case of error. success = false
Used in:
- always
example:
result.setErrorMessage("Error processing the action");
- 4. balance type: String
Actual balance of the member
Used in:
- Get Member Balance (see later)
- Redeem Points (see later)
example:
result.setBalance("100");
- 5. authcode type: String
Code from the Integration System authorizing the operation
Used in:
- Redeem Points (see later)
- Cancel Redemption (see later)
example:
result.setAuthcode(authCode);
- 6. customerName type: String
Name of the customer of the loyalty card
Used in:
- Get Member Balance (see later)
example:
result.setCustomerName("Dummt Customer");
- 7. properties type: JSONObject
See Optional Functionally > In Progress...
Init Method
Init method will be called always before perform any action. There are not specific actions to be executed here, this method is created for your convenience and can be used for example to load a custom configuration. You can also leave it empty.
Example:
private MyCommconf myConf; @Override public void init() { OBCriteria<MyCommconf> confCrit = OBDal.getInstance().createCriteria(MyCommconf.class); confCrit.add(Restrictions.eq(MyCommconf.PROPERTY_CLIENT, OBContext.getOBContext() .getCurrentClient())); confCrit.setMaxResults(1); if (confCrit.list().isEmpty()) { throw new OBException(OBMessageUtils.getI18NMessage("My_ConfMissing", null)); } else if (confCrit.list().size() > 1) { throw new OBException(OBMessageUtils.getI18NMessage("My_ConfCommMoreThanOne", null)); } else { myConf = confCrit.list().get(0); } }
Get Balance Method
Get Balance Method is called from Get Balance Functionality -- ADD LINK
You can return a message to be displayed in the UI and can send the balance to be printed on the balance points ticket.
You receive the memebershipId as a parameter. You also can access to more information from WebPOS using the "data" object. See Optional Functionality.
Example:
@Override public LoyaltyResult doGetBalancePoints(String memebershipId, JSONObject data) throws Exception { LoyaltyResult result = new LoyaltyResult(); String balance = "0"; boolean isSuccess = false; // Do stuff to get the balance using the memebershipId, remember you have all the information // coming from webPOS on "data" for your convenience balance = "100"; name = "Dummy Customer"; isSuccess = true; // if (isSuccess) { result.setSuccess(isSuccess); result.setSuccesMessage("The balance is " + balance); result.setBalance(balance); result.setCustomerName(name); } else { result.setSuccess(isSuccess); result.setErrorMessage("Error getting the balance"); } return result; }
Accumulate Points Method
Accumulate Points is the only action that is performed offline. This means that you can accumulate points from your members without connection with the server. As the tickets do, once the connection is reestablished the information will be sent to the back-end.
In order to not overload the process of loading tickets from the WebPOS to the back-end the accumulation information is stored in the back-end without processing the Accumulate Points action.
The process is called: Loyalty Process Accumulation and must be launched for Organization *. It will take care for all the accumulation information from all the tickets from all the organizations in the client.
You can set the timing you wish: every hour, every day, every week...
You receive as parameters the memebershipId, information coming from webPOS in "data" and also the object "order" for your convenience.
Example:
@Override protected LoyaltyResult doAccumulatePoints(String memebershipId, Order order, JSONObject data) throws Exception { LoyaltyResult result = new LoyaltyResult(); boolean isSuccess = false; // Do stuff to accumulate points using the memebershipId, remember you have all the information // coming from webPOS on "data" and also the object "order" for your convenience if (isSuccess) { result.setSuccess(isSuccess); } else { result.setSuccess(isSuccess); result.setErrorMessage("Error accumulating points"); } return result; }
In case of errors you can found the information stored in the entity OBLOYAccumprocess, table: OBLOY_Accumprocess
TODO: Show errors somewhere
Redeem Points Method
Redeem Points action will be logged in the system in OBLOYRedeemedPoints entity. See Functional Guide LINK.
You can keep an authorization code of the redemption for later use or for cancellations.
You will receive the parameters memebershipId, information coming from webPOS on "data" and also the object "redemptionPoints" for your convenience.
Example:
@Override protected LoyaltyResult doRedeemPoints(String memebershipId, OBLOYRedeemedPoints redemptionPoints, JSONObject data) throws Exception { LoyaltyResult result = new LoyaltyResult(); String authCode = ""; boolean isSuccess = false; // Do stuff to redeem points using the memebershipId, remember you have all the information // coming from webPOS on "data" and also the object "redemptionPoints" for your convenience authCode = "123"; // if (isSuccess) { result.setSuccess(isSuccess); result.setAuthcode(authCode); } else { result.setSuccess(isSuccess); result.setErrorMessage("Error redeeming points"); } return result; }
Cancel Redemption Method
Cancellations will be logged in the system in OBLOYCancelRedemption entity. See Functional Guide LINK.
You can keep an authorization code of the cancellation for later use.
You will receive the parameters memebershipId, information coming from webPOS on "data" and also the object "oBLOYCancelRedemption" for your convenience.
You can also access easily to the redemptionPoints that you are canceling.
Example:
@Override protected LoyaltyResult doCancelRedemption(String memebershipId, OBLOYCancelRedemption oBLOYCancelRedemption, JSONObject data) throws Exception { LoyaltyResult result = new LoyaltyResult(); String authCode = ""; boolean isSuccess = false; // Do stuff to cancel redemption using the memebershipId, remember you have all the information // coming from webPOS on "data" and also the object "oBLOYCancelRedemption" for your // convenience OBLOYRedeemedPoints redemptionPoints = oBLOYCancelRedemption.getObloyRedeemedpoints(); authCode = "123"; // if (isSuccess) { result.setSuccess(isSuccess); result.setAuthcode(authCode); } else { result.setSuccess(isSuccess); result.setErrorMessage("Error canceling redemption"); } return result; }
Full Example
package org.openbravo.retail.sampleloyalty.communication; import org.codehaus.jettison.json.JSONObject; import org.openbravo.model.common.order.Order; import org.openbravo.retail.loyalty.OBLOYCancelRedemption; import org.openbravo.retail.loyalty.OBLOYRedeemedPoints; import org.openbravo.retail.loyalty.communication.LoyaltyIntegration; import org.openbravo.retail.loyalty.communication.LoyaltyResult; import org.slf4j.Logger; import org.slf4j.LoggerFactory; public class SampleIntegration extends LoyaltyIntegration { final private static Logger log = LoggerFactory.getLogger(SampleIntegration.class); @Override public void init() { } @Override public LoyaltyResult doGetBalancePoints(String memebershipId, JSONObject data) throws Exception { LoyaltyResult result = new LoyaltyResult(); String balance = "0"; boolean isSuccess = false; // Do stuff to get the balance using the memebershipId, remember you have all the information // coming from webPOS on "data" for your convenience balance = "100"; isSuccess = true; // if (isSuccess) { result.setSuccess(isSuccess); result.setSuccesMessage("The balance is " + balance); result.setBalance(balance); } else { result.setSuccess(isSuccess); result.setErrorMessage("Error getting the balance"); } return result; } @Override protected LoyaltyResult doAccumulatePoints(String memebershipId, Order order, JSONObject data) throws Exception { LoyaltyResult result = new LoyaltyResult(); boolean isSuccess = false; // Do stuff to accumulate points using the memebershipId, remember you have all the information // coming from webPOS on "data" and also the object "order" for your convenience if (isSuccess) { result.setSuccess(isSuccess); } else { result.setSuccess(isSuccess); result.setErrorMessage("Error accumulating points"); } return result; } @Override protected LoyaltyResult doRedeemPoints(String memebershipId, OBLOYRedeemedPoints redemptionPoints, JSONObject data) throws Exception { LoyaltyResult result = new LoyaltyResult(); String authCode = ""; boolean isSuccess = false; // Do stuff to redeem points using the memebershipId, remember you have all the information // coming from webPOS on "data" and also the object "redemptionPoints" for your convenience authCode = "123"; // if (isSuccess) { result.setSuccess(isSuccess); result.setAuthcode(authCode); } else { result.setSuccess(isSuccess); result.setErrorMessage("Error redeeming points"); } return result; } @Override protected LoyaltyResult doCancelRedemption(String memebershipId, OBLOYCancelRedemption oBLOYCancelRedemption, JSONObject data) throws Exception { LoyaltyResult result = new LoyaltyResult(); String authCode = ""; boolean isSuccess = false; // Do stuff to cancel redemption using the memebershipId, remember you have all the information // coming from webPOS on "data" and also the object "oBLOYCancelRedemption" for your // convenience OBLOYRedeemedPoints redemptionPoints = oBLOYCancelRedemption.getObloyRedeemedpoints(); authCode = "123"; // if (isSuccess) { result.setSuccess(isSuccess); result.setAuthcode(authCode); } else { result.setSuccess(isSuccess); result.setErrorMessage("Error canceling redemption"); } return result; } }