Upgrade from legacy CPQ UI to Quote Studio UI
This article outlines the important factors to consider when upgrading from the Legacy CPQ User Interface (UI) to the Quote Studio UI. Based on how your business has adopted Legacy CPQ UI already, you need to consider the prerequisites and other considerations mentioned in this article. The prerequisites and considerations in this article are based on the assumption that you have already enabled Orders in the Legacy CPQ UI under Zuora Config > Advanced Quoting Configuration Settings.
To upgrade to Quote Studio UI, you must meet the following requirements:
- Orders or Orders Harmonization must be enabled for your Zuora tenant. If you have any questions or issues while enabling orders, you can create a support ticket for the Orders team.
Note that enabling the Orders or Orders Harmonization in your Zuora tenant does not enable Orders in your Salesforce org, and you will continue to use the Subscribe and Amend API in Zuora CPQ. To use the Orders API and switch to Quote Studio UI, you must complete additional steps to enable Orders in your Salesforce org. - Quote Studio is part of the same managed package you have, but to leverage all of its functionalities, you must be on or upgrade to the latest version of Zuora Quotes (See the Release Notes for the latest version).
- CPQ X must be enabled in your Salesforce org. See Enable CPQ X for your organization.
- The Store Existing Products setting in Advanced Quoting Configuration Settings must be enabled. If you are using this feature for the first time, you will notice that during the creation of Amendment or Renewal Quotes, a separate "Original Products" hierarchy is generated to store existing products. This change has affected some customers who report on Quote Rate Plan Charges and Quote Charge Summaries, as these original product lines were not considered before enabling Store Existing Products
Other considerations for upgrade
Data Model
Quote Studio UI intends to use the same data structure as Legacy CPQ UI, as long as Orders is enabled in your legacy CPQ UI. You can access a Quote created using the Legacy CPQ UI with the new functionalities of Quote Studio UI. We have added new fields and behaviors, particularly around preview metrics, leading to notable changes in reporting. You may see some data missing when switching from one flow to another. Additionally, in Quotes version 10.36, we have added an object type called Charge Segments, significantly impacting customers who originally built reports using Quote Rate Plan Charge and Quote Charge Summaries. See Charge Segment.
Legacy CPQ UI to Quote Studio UI
Quote Studio UI is a single-page application, which means data remains in the browser until you explicitly choose to save the quote. In contrast, Legacy CPQ UI saves the quote on each page, the Rules Engine does not trigger until all products are added to the quote, and previewing occurs only on the Quote Detail page. The change in UI has the following significant impacts:
- Understanding the instances when quote data is saved to the database.
- Timing of rules engine execution.
- Timing of quote previews.
- Understanding why user configurations are not visible in the database when rules are triggered.
- Understanding why your custom updates to the database are not reflected in the live configuration Quote.
- Recognizing that in-memory Quote Studio data can be manipulated through the Extensibility Framework. See Extensibility Framework.
Guided Product Selector alternative in Quote Studio UI
The Guided Product Selector has the following impact:
- There are options to use the legacy Guided Product Selector Flows in conjunction with Quote Studio. See Combine guided selling with Quote Studio. Instead of the Guided Product Selector, you can use the Quick Filter and Product Filter feature in Quote Studio UI, which offers a more intuitive product filtering system, helping sales users choose the right products easily. See Configure product filters and quick filters.
- Quote Studio UI does not allow adding custom components to the Guided Selling steps. As an alternative to adding custom field sets, Quote Studio UI provides the option to use the existing Additional Fields field sets and relabel them to add new sections in the UI. See Customize labels and Customize field sets.
- Legacy layout configuration is unavailable in Quote Studio UI. Alternatively, in Quote Studio UI, you can configure the layout using field sets similar to Legacy CPQ UI. See Customize field sets for CPQ X.
- Quote Studio UI does not allow custom components or custom field sets to be inserted within the Quote Studio UI, which was supported in the Legacy CPQ UI through the layout configuration settings. As an alternative to adding custom field sets, Quote Studio UI provides the option to use the existing Additional Fields field sets and relabel them to add new sections in the UI. See Customize labels and Customize field sets.
- Customizing sections, adding, or hiding buttons on the Quote Studio page is not yet supported. Relabelling button names or sections in the Quote Studio UI is possible through the Salesforce Translation workbench override feature. See Localize and customize labels and messages.
- The JavaScript plugin is not supported in Quote Studio UI. However, the Custom Action Plugin is available in Quote Studio, which can do everything the JavaScript plugin does and more. Additionally, you can use the Extensibility Framework to write JavaScript to manipulate in-memory Quto Studio data.
- The legacy QuickFilter Component and QuickList Component are not supported in Quote Studio UI. Alternatively, you can use the Quick Filter option in Quote Studio UI. See Configure product filters and quick. filters.
Rules Engine Considerations
The Legacy CPQ Rules Engine is fully available in Quote Studio UI. However, due to significant changes in data residency with Quote Studio UI, the following key pointers should be considered when adopting Quote Studio UI with an existing Rules Engine configuration.
- You must enable the Rules Engine in Quote Studio UI. See Enable Rules Engine.
- Custom Action Plugins - Custom Action Plugins are a huge consideration when adopting Quote Studio UI. If you have already implemented it in Legacy CPQ UI, the following changes apply:
- API usage differences - A key change with Quote Studio UI adoption is using the Quote Studio UI API set, altering how the Rules Engine processes rule actions. Most importantly, Custom Action Plugins now receive the QPlan data model instead of the zChargeGroup object model. This shift invalidates many existing Custom Action Plugin implementations and is a critical factor to consider when adopting Quote Studio UI. See CPQ X API.
- Data Residency and Expectation Changes - With the Quote Studio single-page application replacing the main quoting flow, some Custom Action Plugins that previously relied on Quote and related data being saved in the database during Rules Execution are also impacted. Custom Action Plugins must now rely on the DataObject attribute to access in-flight Quote data. Reading from the database will yield outdated information, leading to inaccurate Custom Action Plugin execution.
- Rules Engine Plugin - Another backward incompatibility of Quote Studio UI is the removal of the Rules Engine Plugin support, which was previously used to run custom logic before Rules Engine evaluation. We recommend using the beforeRulesExecution hooks in the Extensibility Framework as an alternative for implementing custom logic. See Headless component - hooks.
- Timing - Quote Studio UI features Quote Studio as a streamlined Quoting experience, emphasizing the importance of rules firing at various stages of the quoting process. Quote Studio UI includes the concept of "Trigger Events," which categorizes rules based on their execution timing. Currently, we support the following out-of-the-box trigger events when:
- The Quote Studio page loads
- You make changes to the quote
- You save or exit the Quote Studio page
The ability to define when the rules need to trigger improves product performance so that rules are not executed all the time. The larger the Quote or the more rules you have will impact the performance if they are triggering all the time. Using the trigger events improves the product performance.
- Time awareness - Quote Studio UI makes it intuitive to quote future-dated actions. This highlights the limitation of the Rules Engine, which cannot evaluate rules with a date context. We have mechanisms available to execute logic against the subscription time awareness element through the following recent releases.
- Quotes version 10.36.1
- Review the active interval from which the user is triggering rules.
- Execute the Rules Engine on demand and filter the rules to be executed using the Extensibility Framework implementation. See Headless component - hooks.
- Quotes version 10.37 - Add, update, or remove a rate plan on a specific date instead of the Quote Start Date using the Custom Action Plugin. See Custom Action.
- Quotes version 10.36.1
- MSQ support - Currently, the Rules Engine cannot recognize Quotes under the same parent Quote. We are actively working on a solution to address this issue.
Extensibility Framework
Since CPQ X no longer supports Quote Wizard or step pages for executing Apex Triggers or custom code, you may require a programmatic way to interact with the live Quote in the browser.
To address this, we introduced the Extensibility Framework, which enables the real-time injection of custom logic as you edit quotes using the following mechanisms:
- You can create a Custom UI component that slides out within the Quote Studio page to interact with the Quote Studio data with user input.
- You can create a Headless component to execute your custom logic to manipulate in-page data in Quote Studio.
The Extensibility Framework offers the following two key capabilities:
- Tap into the in-flight Quotes data in the browser
- Detect user actions on the Quote Studio page
By utilizing hooks (logic that executes when specific events occur) and events (notifications prompting actions on the page), you can achieve a wide range of custom functionalities, including replicating a rules engine directly on the page, without being limited by Apex constraints. See Extensibility Framework.
Considerations for other customizations
Triggers
Triggers that relied on Quote-level data being saved at each step in the Legacy CPQ UI now require reconsideration in the Quote Studio UI. Since Quote data is not written to the database until you click the Save or Submit button, the timing and execution of these triggers need to be re-evaluated.
Custom Components
The legacy CPQ extensibility tools that existed, such as the Zuora CPQ Component Library, Zuora CPQ Global Classes, Product Selector JavaScript Plugin, and Zuora CPQ Global Components, no longer directly apply when adopting Quote Studio.
If you use Custom Components in your legacy CPQ implementation, analyze them using the following questions:
- What business case does the component or mechanism of the Extensibility Framework solve?
- Is the business case natively resolved within Quote Studio through configuration or user experience? If not, how can the business case be optimized using the Quote Studio Extensibility Framework?
Based on your analysis, assess whether the out-of-the-box experience in Quote Studio UI or new features in Billing supported by Quote Studio resolve some of these business cases natively without requiring customization.
In case you identify that there are a few customizations that are still required based on the business needs for your organization that are not natively satisfied through Quote Studio UI or Billing features supported in Quote Studio, then you can use the following tools to achieve the customization:
- Rules Engine
- Rules Engine with custom action plugin
- Extensibility Framework
- Quote Studio supported plugins
Components on the Quote Details page can remain unchanged and should continue functioning as they did in the Legacy CPQ UI. However, those embedded within the Legacy CPQ UI steps must be scrutinized.
API (Global Methods) Difference
The Quote Studio page introduced a new set of Global Method APIs: QPlan, QCharge, QTier, and QAmendment. Unlike the legacy zChargeGroup and zCharge objects, these new APIs are designed for improved performance and include built-in remove and revert methods. Combined with utility classes QPlanBuilder and QPlanWriter, they replace traditional zQuoteUtil methods to provide a more modular and scalable approach to quote manipulation. For sample code, see Sample code using zChargeGroup.
Custom Fields
Certain legacy custom fields originally mapped as "text" in Zuora but of different data types in Salesforce can trigger errors in Orders API calls. We recommend migrating and remapping the Zuora custom fields to their correct data types. However, we have provided a backward-compatible solution if you have long-standing implementations based on these custom fields and cannot migrate them. You can add fields to the Retain Custom Field Data Type object field sets and when the Legacy Support: Send SF Custom Fields to Zuora as String setting is enabled, any custom fields included in this field set are excluded from conversion to strings when sending the quote to Zuora. See Quote Configuration Settings.
Usage Tracking
With the upgrade to CPQ version 10+, there is a remote site setting to enable callouts to Amplitude. This allows Zuora to track user telemetry and usage analytics, primarily focusing on Quote creation data and errors. Data collection is limited to Quote Studio UI usage and does not affect Legacy CPQ UI.
Lightning Web Security (LWS) enablement
This security framework enhances communication between components and modules across different namespaces for the Lightning Web Component Framework. Enabling LWS significantly boosts Quote Studio UI performance, particularly when enabling custom components. However, one key consideration is the compatibility of other integrations, as not all AppExchange packages support LWS. You may encounter issues when you enable LWS for Quote Studio UI. We strongly recommend testing LWS in a fully replicated sandbox environment to prevent disruptions when implementing Quote Studio UI.
Internationalization considerations
Quote Studio UI does not currently offer out-of-the-box support for internationalization. However, you can configure particular language support using the Translation Workbench in Salesforce. See Localize and customize labels and messages.
If you encounter any text that is unavailable for translation in the workbench, create a support ticket.
You can use the override feature of the translation bench to override the custom label in Quote Studio. See Localize and customize labels and messages.
ICU Locale Concerns
All Quote Studio UI components are built with API versions above 58.0, thus compatible with ICU locale requirements. With Quotes version 10.20, Zuora CPQ for Salesforce is fully compatible with the ICU (International Components for Unicode) locale enforcement by Salesforce. See International Components for Unicode (ICU) Locale Formats.
We are actively working on upgrading our Legacy CPQ UI components to API versions post 45.0, but given the incompatible API version warning, the package should function without error. See the community post.