Adding Custom Promotion Validators and Calculators

Parallels H-Sphere allows to define custom promotions - flexible discount systems - and assign them for individual plans.

Usually, a customer enters a certain promotion code on signup, the system verifies the entered code if it proves to be valid and corresponds to the chosen plan, that user signs up with that discount. This is called a codeable promotion. There are also codeless promotions that don't require a code. Discount depends on a particular promotion and the way the discount is calculated.

This document explains how to add and configure custom promotion validators and calculators.

To add a custom promotion validator or calculator to Parallels H-Sphere:

1. Log into the CP server as the cpanel user.
2. Create a custom promotion validator or calculator:
   • To create a promotion validator, use the the psoft.hsphere.promotion.PromoValidator Java class interface: http://hsphere.parallels.com/HSdocumentation/sdk/api/psoft/hsphere/promotion/PromoValidator.html.

     The class can also extend the AbstractPromoDataStorage class to store the validator's data in the Parallels H- Sphere database: http://hsphere.parallels.com/HSdocumentation/sdk/api/psoft/hsphere/promotion/AbstractPromoDataStorage.html.

   • To create a promotion calculator, use the psoft.hsphere.promotion.calc.PromoCalculator Java class interface: http://hsphere.parallels.com/HSdocumentation/sdk/api/psoft/hsphere/promotion/calc/PromoCalculator.html.

     The class can also extend the AbstractPromoDataStorage class to store the calculator's data in the Parallels H- Sphere database: http://hsphere.parallels.com/HSdocumentation/sdk/api/psoft/hsphere/promotion/AbstractPromoDataStorage.html.

     Example:

     package psoft.hsphere.promotion.calc;

     import psoft.hsphere.promotion.AbstractPromoDataStorage;

     import psoft.hsphere.Session;

     import psoft.hsphere.Account;

     import psoft.util.USFormat;

     import java.util.Hashtable;

     public class PercentDiscountCalc

     extends AbstractPromoDataStorage implements PromoCalculator {

     private double discountPercent;

     public PercentDiscountCalc(long promoId) throws Exception {

     super(promoId);

     discountPercent =

     USFormat.parseDouble((String) data.get("discount_percent"));

     }

     public PercentDiscountCalc(long promoId, Hashtable data) throws Exception {

     super(promoId, data);

     discountPercent =

     USFormat.parseDouble((String) data.get("discount_percent"));

     }

     public int getDataType() {

     return 2;

     }

     public double getPromoDiscount(Account a, double sum) {

     return sum*discountPercent/100;

     }

     public void updateData(long promoId, Hashtable data) throws Exception {

     super.updateData(promoId, data);

     Session.getLog().debug("Updating discount percent");

     discountPercent =

     USFormat.parseDouble((String) data.get("discount_percent"));

     }

     }

3. Configure custom promotion validator or calculator in the XML configuration file.

   All promotion validators and calculators should be added to and configured in the promotions.xml file. Its default location is ~cpanel/shiva/psoft/hsphere/promotion/xml/. The file location can be altered with the PROMO_CONFIG and CUSTOM_PROMO_CONFIG properties in ~cpanel/shiva/psoft_config/hsphere.properties:

   PROMO_CONFIG=/hsphere/local/home/cpanel/shiva/psoft/hsphere/promotion/xml/promotions.xml

   CUSTOM_PROMO_CONFIG=/hsphere/local/home/cpanel/shiva/custom/xml/promotions.xml

   promotions.xml should be customized according to XML customization rules.

DTD Structure: http://hsphere.parallels.com/HSdocumentation/xmls/promotions.dtd

Example: http://hsphere.parallels.com/HSdocumentation/xmls/promotions.xml

Elements and attributes:

• <promotions> - contains all defined promotion validators.
• <promo> - configuration of a particular promotion validator.

  Attributes:

  • id - a unique promotion identifier: 1,2,...
  • description - a short description of a validator. It shows up in the dropdown list of promotions in Control Panel.
  • class - a name of a Java class for this validator.
  • itype - a type of the validator's interface. If it is set to "AUTO", interface for adding the validator parameter will be built automatically, depending on parameters defined for the validator or calculator; otherwise, values of the add_template and edit_template attributes will be used as template names for adding/editing set of data which is required for a given promotion validator.
  • add_template - a name of a template for adding the validator data; the value of this attribute will take effect only in case if itype is not set to "AUTO".
  • edit_template - a name of a template for editing the validator data; the value of this attribute will take effect only in case if itype is not set to "AUTO".
• <calculators> - contains all defined promotion calculators.
• <calc> - configuration of a particular promotion calculator. Attributes have the same meaning as for promotion validators.
• <params> - contains all parameters used by promotion validators or calculators.
• <param> - configuration of a particular parameter.

  Attributes:

  • label - a name of a label in ~cpanel/psoft/hsphere/lang/hsphere_lang.properties with the message that appears on the page where users enters a promo code.
  • name - the parameter's name. The AbstractPromoDataStorage object stores validators' or calculators' data from HttpRequest using this name with the prefix pv_ for a validator and pc_ for a calculator. For example, if name="percent", AbstractPromoDataStorage expects the pv_percent variable for the validator and the pc_percent variable for the calculator to be present in HttpRequest.