Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. The Developer Center continues to support Commerce 6.13.0 through 7.4.1.Visit new site

Promotion rule parameters

Promotion rule parameters

The promotion rule editor can be extended to support additional rule elements such as conditions and actions. Conditions and actions typically require parameters such as product ids and discount amounts to fully specify the rule element. New elements can be added by following the steps in the promotion rule engine technical design document. Those steps are sufficient for adding new rule elements that use the existing set of parameters. However, if a new parameter type is required by a new rule element, modifications must be made to the Commerce Manager promotion rule editor. Developers who extend the rules engine subsystem should be familiar with the promotion rule engine technical design document.

Standard rule parameters

The following rule parameters are available out-of-the-box. The constant key names of the rule parameters are listed.

  • categoryId - The UidPk of a category.
  • productId - The UidPk of a product.
  • discountAmount - The amount to be discounted.
  • discountPercent - A percentage amount to be discounted.
  • currency - The currency selected by the shopper.
  • customerGroupId - The UidPk of a customer group.
  • subtotalAmount - The shopping cart subtotal.
  • numItems - Represents a quantity of items, typically products or SKUs.
  • skuCode - The SKU code of a Product SKU.
  • shippingServiceLevelId - The UidPk of a shipping service level.
  • booleanCondition -Represents a true or false value.
  • brandCode - The code value for a brand associated with a product.

Key files

  • NewPromotionWizardRulesPage - UI for adding a new rule
  • PromotionRulesDefinitionPart - UI for editing a rule
  • PromotionRulesWidgetUtil - utility methods for creating UI elements and performing rule element parameter data binding
  • PromotionsMessages - defines localized text for the rule element
  • PromotionsResources.properties - localized text for the rule element

How to add a new rule parameter

There are many ways that new rule parameters can be specified by the user. For example, some rule parameters may be well supported by free-form input while for other parameters the user should be prompted with a pre-set list of values. In other cases, it is desirable to open a dialog box to allow the user to select a parameter. Because of the diversity of rule parameter input techniques, there is no simple list of steps to follow when creating new parameters in the Commerce Manager promotion rule editor. However, the following points provide some items to consider when creating new rule parameters.

  1. Define a new constant in RuleParameter.java.
  2. Add a new "else if" case for your rule parameter in NewPromotionWizardRulesPage and PromotionRulesDefinitionPart.
    if (RuleParameter.CATEGORY_ID_KEY.equals(paramKey)) {
    	util.addCategoryFinderLink(ruleParameter, ruleComposite, null, EpState.EDITABLE);
    } else if (RuleParameter.PRODUCT_ID_KEY.equals(paramKey)) {
    	util.addProductFinderLink(ruleParameter, ruleComposite, null, EpState.EDITABLE);
    ...
    } else if (RuleParameter.BRAND_CODE_KEY.equals(paramKey)) {
    	util.addBrandCombo(ruleParameter, ruleComposite, this, getDataBindingContext(), EpState.EDITABLE);
    }
    
  3. If you need a custom UI component for entering the rule parameter value then add a method in PromotionRulesWidgetUtil.
    public void addBrandCombo(final RuleParameter ruleParameter, final IEpLayoutComposite ruleComposite,
    		final DisposeListener disposeListener, final DataBindingContext dataBindingContext, final EpState epState) {
    
    	// create the combo box
    	final CCombo brandCombo = ruleComposite.addComboBox(epState, null);
    	brandCombo.pack();
    
    	final BrandService brandService = ServiceLocator.getService(ContextIdNames.BRAND_SERVICE);
    	final List<Brand> brands;
    	if (scenario == RuleScenarios.CATALOG_BROWSE_SCENARIO) {
    		brands = brandService.findAllBrandsFromCatalog(catalog.getUidPk());
    	} else {
    		brands = brandService.findAllBrandsFromCatalog(store.getCatalog().getUidPk());
    	}
    
    	// populate the combo box
    	int selectedIndex = 0;
    	int currBrandIndex = 0;
    
    	for (final Brand currBrand : brands) {
    		brandCombo.add(currBrand.getDisplayName(CorePlugin.getDefault().getDefaultLocale(), true));
    
    		...
    
    		brandCombo.setData(binding);
    		brandCombo.addDisposeListener(disposeListener);
    	}
    }
    
  4. Add a new entry and mapping in PromotionsMessages.
    public static String BrandCondition;
    
    ...
    
    localizedPromotionEnums.put(RuleElementType.BRAND_CONDITION, BrandCondition);
    
  5. Add the rule element text in PromotionsResources.properties
    BrandCondition=Brand is [{0}]