Skip to main content

Customize Quote Studio with Extensibility Framework

Zuora

Customize Quote Studio with Extensibility Framework

  1. Last updated
  2. Save as PDF

Lightning web components (LWC) and Aura components are the two Salesforce programming models, based on which you can build Lightning components. LWC and Aura components can coexist in an app and interoperate with each other. 

The CPQ X Extensibility Framework feature enables you to include:

  • Your own LWC or Aura components in the Quote Studio sidebar. It can significantly improve the extensibility and usability of Quote Studio.
  • A headless component to execute your custom logic without a User Interface (UI). For more information, see Headless component - hooks.

The following image shows the Quote Studio sidebar component.

Quote Studio sidebar

The high-level steps to customize Quote Studio sidebar are:

  1. Create your own components
  2. Register and dispatch events
  3. Register a new component in CPQ X

Create your own components

You must create your own Lightning web components or Aura components. See the following Salesforce documentation for steps about creating LWC or Aura components:

When creating components, you must ensure your component implementation meets the following requirements:

  • The pageState, metricState, quoteState , and textTitle attributes must be declared as global attributes.
    Component type Code example
    LWC @api quoteState;
    @api metricState;
    @api pageState;
    @api textTitle
    Aura <aura:attribute name="quoteState" type="Map" access="global" />
    <aura:attribute name="metricState" type="Map" access="global"/>
    <aura:attribute name="pageState" type="Map" access="global"/>
    <aura:attribute name="textTitle" type="String" access="global"/>
  • Custom components must be declared globally or exposed.
    Component type Code example
    LWC   In LWC metadata file:<isExposed>true</isExposed>
    Aura  <aura:component access="GLOBAL">

Register and dispatch events

After your component is implemented, you need to register and dispatch events in your code implementation. See the following Salesforce documentation for instructions:

Aura example

If you want to register the updateQuote event for an Aura component, you can use the following sample codes:

<aura:registerEvent name="updateQuote" type="zqu:quoteUpdate"/>

Then use the following code to fire the event:

let quote = component.get("v.quoteState.quote");
let updateQuote = cmp.getEvent("updateQuote");
updateQuote.setParams({ quote: quote });  
updateQuote.fire();

LWC example

When dispatching custom events in LWC, it is important to adhere to the standard of using all lowercase letters for event names. Uppercase letters are not allowed in custom event names as per LWC guidelines. Here's an example to illustrate this:

const updateQuote = new CustomEvent('updatequote', {
    detail: { quote: this.quoteState.quote },
  });
  this.dispatchEvent(updateQuote);

Events should be dispatched with the listed parameters to persist any data changes within the Quote Studio page. For more information, see Headless and sidebar component - events.

Register custom component in CPQ X

After you have completed the code implementation of your components, you must register your components in CPQ X so that the custom UI components are rendered in the Quote Studio sidebar.

Take the following steps to register a custom component in CPQ X:

  1. Navigate to Zuora Config > Quote Studio Settings > Custom Component Settings.
  2. Click the Create New Component button.
  3. Complete the component information for registration. 
    • (Optional) Component Namespace: Enter the namespace of your component.
    • Component Name: Enter the name of the component. 
    • Component Type: Select Aura or LWC from the dropdown lists.
    • (Optional) Component Event Action: Select the event actions you want to handle in your component.
      Sometimes, after you upgrade your Zuora CPQ package from the previous version, newly created events in the upgraded package might not be available. In such cases, you will have to create the event picklist with the value and name as the one present in Event Type for the field zqu__Component_Event_Action__c in the object zqu__Add_on_component_registration__c
    • (Optional) Use as Headless Component: Check this box to designate the component as headless. For more information, see Headless component.
      Headless Components will not appear in the Quote Studio Sidebar.
    • Active: Select this check box if you want to activate the registered component on registration.
    • Sort Order: Enter the number of the sequence number such as 1. The registered components are sorted and displayed in the ascending order based on the Sort Order value. 
    • (Optional) Title Text: The title text for the registered component.
    • Image Resource Name: Enter the name of your component. It should be identical with the name of the image file that is uploaded to static resource in Salesforce.
  4. Click Create.

If the created component is added to the table in the Manage Existing Components tab, the component is successfully registered.

Update display order of custom components

If you have registered multiple custom components, you can customize the display order of these components.

Take the following steps to update the display order of registered components:

  1. Navigate to Zuora Config > Quote Studio Settings > Custom Component Settings.
  2. Click the Update Order button.
  3. Edit the number in the Order column for different entries. The components are sorted in the ascending order of the Order value. Therefore, if you want to move a component to the top, you should specify the lowest value in the Order column for this item, and vice versa.
  4. Click Save to save the change.

After your updates are saved, the registered components are reorganized based on the updated Order value.