Skip to main content

CpqSelectProduct Component

Zuora

CpqSelectProduct Component

The CpqSelectProduct component gives developers a reusable global product selector component that can be inserted on Visualforce pages. With the CpqSelectProduct component, end users can add or modify product rate plan charges when creating a new subscription, amendment, or renewal quote. The CpqSelectProduct component supports the following:

  • Allows users to add new product rate plan charges when creating a new subscription.
  • Allows users to edit tiered charges through custom tiers.
  • Allows users to add, update, or remove product rate plan charges when creating amendments and renewals.
  • Allows users to undo an action for updated or removed rate plan charges.
  • Supports custom fields by defining your own fields and update them from rate plan charge list.  Supported field types:  Text, Text Area, and Picklist.
  • Allows users to modify multiple product rate plan charges from a single page.
  • Allows inline editing of rate plan charge lists.
  • Customizes rate plan charge list columns through the Salesforce field set.
  • Supports both view and edit mode.
  • Supports for an Integrated lookup component to product and rate plan with an auto-complete feature.
  • Supports a Query plugin for the product  and rate plan lookup component. You can define your own query with additional conditions when developing your own Salesforce page.

The CpqSelectProduct component is available in the Versions 7.0 and later of Zuora Quotes.

The CpqSelectProduct component consists of the following:

  • CpqSelectProduct.component: The Visualforce UI component

  • CpqSelectProductController.class:The Apex controller class for the CpqSelectProduct UI component

  • SelectProductComponentOptions:The Apex class that stores the configuration options specified by the developer and used by the controller to render the component

  • SelectProductComponentOptions.IFilterPlugin: The custom Filter Plugin Interface used to define additional filtering criteria for both production and rate plan selections

  • SelectProductComponentOptions.IGuidedSellingFlowPlugin: The custom Guided Selling Flow Plugin interface to generate Guided Selling button bars on Product Selector s

  • SelectProductComponentOptions.IAddRemoveRatePlanPlugin: The custom plugin to control addition and removal of rate plans in the Product Selector

  • SelectProductComponentOptions.ISaveRatePlanPlugin: The custom Save Rate Plan Plugin to validate the charge groups of a quote when saving them in the product selector
  • ZQuoteRulesEngine.QuoteRulesEnginePlugin: The custom Product and Price Rules engine plugin

CpqSelectProduct Component Attributes

The CpqSelectProduct component has the following attributes.

Attribute Type Required Description
id String Optional An identifier that allows the component to be referenced by other components in the page.
options zqu.SelectProductComponentOptions N/A

The configuration options for the component.

See the next table for detail.

rendered Boolean Optional Specifies whether the component is rendered on the page. The default is True.

SelectProductComponentOptions Class

The following table describes the properties available on the SelectProductComponentOptions global class.

Property Type Required Description
addBundleProductsUrl String Optional

The page URL to navigate to upon clicking the Add Products button on the Lightning Guided Product Selector.

If you are using the EditQuoteProduct component, this parameter will automatically be set to the page URL of the component.

addProductsPageParams Map <String, String> Optional

A map containing all of the URL parameters that should be persisted when clicking on the Add Products button on the Product Selector.

Available in Zuora Quotes Version 7.4+.

cancelPageParams Map <String, String> Optional

A map containing all of the URL parameters that should be persisted when exiting the Enhanced Product Selector through the Cancel button.

Available in Zuora Quotes Version 8.0+.

cancelUrl String Optional The page URL to navigate to upon clicking the Cancel button
filterPlugin zqu.
SelectProductComponentOptions.
IFilterPlugin
Optional

The filter plugin instance that defines additional filtering criteria for both product selection and rate plan selection.

Does not apply when the class is used for the CpqSelectProduct component.

mode String Required

The mode of the component.  

Available options are:

  • MODE_EDIT
  • MODE_DETAIL
  • MODE_INLINE_EDIT
MODE_DETAIL Static String N/A

The detail mode of the component

MODE_EDIT Static String N/A

The edit mode of the component

MODE_INLINE_EDIT Static String N/A

The inline edit mode of the component.

Use this mode if you want to embed the product selector on a page with other components.

ooportunityId String N/A Id of the associated opportunity
previousPageParams Map <String, String> Optional

A map containing all of the URL parameters that should be persisted when clicking the Back button on the Enhanced Product Selector.

Available in Zuora Quotes Version 8.0+.

previousUrl String Optional The page URL to navigate upon clicking the Previous button
productFilterSoqlFragment String Optional

The SOQL fragment for the Select Product filter.

Does not apply when the class is used for the CpqSelectProduct component.

productSoqlFragment String Optional

The SOQL fragment for the Select Product Lookup component. Used to define a query for additional conditions if required.

Does not apply when the class is used for the CpqSelectProduct component.

quoteId String Required The ID of the quote that is using the component
quoteType String Required

The type of quote that is using the component. Available options:

  • Amendment
  • Renewal
  • Subscription
ratePlanFilterSoqlFragment String Optional

The SOQL fragment for the Select Rate Plan filter.

Does not apply when the class is used for the CpqSelectProduct component.

ratePlanSoqlFragment String Optional

The SOQL fragment for the Select Rate Plan Lookup Component. Used to define a query for additional conditions if required.

Does not apply when the class is used for the CpqSelectProduct component.

savePageParams Map <String, String> Optional

A map containing all of the URL parameters that should be persisted when clicking on the Submit button on the Product Selector.

Available in Zuora Quotes Version 8.0+.

saveUrl String Optional The page URL to navigate upon clicking the Save button
sfdcAccountId String Optional Salesforce Account Id for the quote
subTitle String Optional

The subtitle of the component

title String Optional

The title displayed at the top of the component

Component Plugins

The CpqSelectProduct component supports the following plugins on the SelectProduct component.

Add / Remove Rate Plan Plugin 

The SelectProduct component provides a filter plugin interface that you can use to create a custom plugin to control addition and removal of rate plans in the Product Selector.

The Add / Remove Rate Plan Plugin is available in the Versions 6.2 and later of Zuora Quotes.

The plugin interface is defined as global SelectProductComponentOptions.IAddRemoveRatePlanPlugin and contains the following interface methods: 

  • void onAdd (String, List): Customizes the additional actions to take place based on the product rate plan added to the quote. For example, you can specify to add a related rate plan when a certain rate plan is added to a quote.
  • void onRemove (String, List): Customize the additional actions to take place based the product rate plan removed from the quote. For example, you can prevent certain rate plan from being removed from a quote.

See Add/Remove Rate Plan Plugin Example for a sample use case.

Save Rate Plan Plugin  

The Save Rate Plan Plugin is available in the Versions 6.41 and later of Zuora Quotes.

You can use the Save Rate Plan Plugin interface to:

  • Detect changes (add, remove, update) to charge groups on a quote when saving those charge groups in the Product Selector.
  • Perform validations on those charge groups.

The plugin interface is defined as global SelectProductComponentOptions.ISaveRatePlanPlugin and contains the following interface method and parameters:

void onSave(
   List<zChargeGroup> addedChargeGroups, 
   
List<zChargeGroup> updatedChargeGroups,
   List<zChargeGroup> removedChargeGroups,
   List<zChargeGroup> persistedChargeGroups);

where :

  • onSave: Checks the current state of all charge groups on save.  Includes the following parameters:
    • addedChargeGroups: All added charge groups during the current save.
    • updatedChargeGroups: All updated charge groups during the current save.
    • removedChargeGroups: All removed charge groups during the current save .
    • persistedChargeGroups: All previously saved but unedited charge groups.

Zuora does not recommend modifying the charge group or charge group list in the Save Rate Plan Plugin.

See Save Rate Plan Plugin Example for a sample use case.

Quote Rules Engine Plugin 

The SelectProduct component provides the Quote Rules Engine plugin interface. The default plugin registers and enables the Product and Price Rules engine. You can create a custom rules plugin and replace the default rules engine plugin if you do not require the full configuration capability of our Product and Price Rules. For example if you only need a simple rules engine for automatic price/rules calculations happen, create your custom plugin class, and register your plugin as described in Component Registration.

The plugin interface contains the following interface methods:

  • void runPriceRules
    ​  (List<zqu.ZChargeGroup> zcgs,
       List<zqu.ZQuoteRulesEngine.ChangeLog> logs)
  • Map> runProductRules
    ​  
    (zqu__Quote__c quote,
       List<String> ratePlanIds,
       List<zqu.ZQuoteRulesEngine.ChangeLog> logs)
  • Boolean runValidationRules
    ​  (zqu__Quote__c quote,
       List<ZChargeGroup> zcgs,
       List<ChangeLog> logs)

See Quote Rules Engine Plugin Example for a sample rules engine plugin code.

Rate Plan Customization Plugin 

Use the Rate Plan Customization Plugin on the SelectProduct component to manipulate the charge groups before adding them to the quote, e.g., setting default values of some fields, adding or removing features.

This plugin is only supported in the old Guided Selling Product Selector and not supported in the Lightning Guided Product Selector.

The plugin interface is:

SelectProductComponentOptions.IRatePlanCustomizationPlugin

The plugin contains the following global method:

  • void updateZChargeGroups(Quote__c quote, List<ZChargeGroup> zcgs)

This plugin executes on the add, removal, and saving of a product.

See Rate Plan Customization Plugin Example for a sample plugin code.

The above plugins are not compatible with the new CPQ X flow. To review the list of plugins compatible with CPQ X, see CPQ X supported plugins.

Sample Code for the CpqSelectProduct Component

Visualforce Page

Add the CpqSlectProduct component to your Visualforce page inside an <apex:form> tag to set up the component options in your controller. Use the zqu__QuoteWizardTemplateNoForm template to ensure that your Visualforce page will have the Quote Wizard context.

<apex:page sidebar="false" tabStyle="zqu__Quote__c" standardController="zqu__Quote__c" extensions="CustomProductSelectorController">
  <apex:composition template="zqu__QuoteWizardTemplateNoForm" >
    <apex:define name="PageBody" >
      <apex:form >
        <zqu:CpqSelectProduct options="{!theOptions}"/>
      </apex:form>
    </apex:define>
  </apex:composition>   
</apex:page>

Apex Controller

public with sharing class CustomProductSelectorController {
  public zqu.SelectProductComponentOptions theOptions { get; set; }
  public CustomProductSelectorController(){
    theOptions = new zqu.SelectProductComponentOptions();
    theOptions.title = 'Sample Code';
    theOptions.subTitle = 'Choose Product and Charges';
    theOptions.mode = zqu.SelectProductComponentOptions.MODE_EDIT;
    // Read-only mode, used to display all the selected product rate plan charges
    //theOptions.mode = zqu.SelectProductComponentOptions.MODE_DETAIL;
    theOptions.quoteType = 'Subscription';
    theOptions.quoteId = 'a0AE0000005aFovMAE';

    // Set the page url for buttons if necessary
    theOptions.previousUrl = '';
    theOptions.saveUrl = '';
    theOptions.cancelUrl = '';
    theOptions.filterPlugin = new CustomProductFilter();
  }
}