Projects:LoyaltyManagement/Technical Guide/LoyaltyIntegration

Contents 1 How to create a Loyalty Integration 1.1 Introduction 1.2 Register the Loyalty Integration in Application Dictionary 1.2.1 Create the Loyalty Integration 1.2.2 Assign the Loyalty Integration to a Loyalty Program 1.3 Create the Loyalty Integration 1.3.1 Introduction 1.3.2 Loyalty Result 1.3.3 Init Method 1.3.4 Get Balance Method 1.3.5 Accumulate Points Method 1.3.6 Redeem Points Method 1.3.7 Cancel Redemption Method 1.3.8 Full Example

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;
  }
 
}