Home / admin / cpq-guided-selling
cpq-guided-selling
Use this skill when configuring or troubleshooting the Salesforce CPQ Guided Selling wizard: Quote Process records, ProcessInput questions that filter products by field value, mapping answers to Product2 classification fields, and search type choice (Standard, Enhanced, Custom).
Open the skill folder on GitHub
CPQ Guided Selling
Use this skill when configuring or troubleshooting the Salesforce CPQ Guided Selling wizard. Reps answer a structured set of questions, and CPQ filters the catalog to products that match. This skill covers Quote Process and Process Input setup, classification field mirroring, the Enhanced and Custom plugin modes, Auto Select Product behavior, and common filtering failures. It does not cover OmniStudio product selection, standard product browsing, bundle setup, or pricing rules.
Product status: the Salesforce CPQ Developer Guide (Summer '26) states that the Salesforce CPQ managed package "continues to be available for existing customers, however, there is no longer any new feature development", and recommends Revenue Cloud for new implementations. Use this skill for orgs already on CPQ.
Field-name caution: the CPQ object reference is published only on help.salesforce.com, which did not fetch for this pass. UNVERIFIED (2026-10-03): the field API names below for SBQQ__QuoteProcess__c and SBQQ__ProcessInput__c (SBQQ__GuidedProductSelection__c, SBQQ__SearchType__c, SBQQ__AutoSelectProduct__c, SBQQ__SearchField__c, SBQQ__Operator__c, SBQQ__InputType__c, SBQQ__Label__c, SBQQ__Active__c, SBQQ__Required__c, SBQQ__Order__c) and Pricebook2.SBQQ__GuidedSelling__c come from earlier versions of this skill and are not in the CPQ Developer Guide or the CPQ Plugins Guide. Confirm each in Object Manager before writing data loads or automation. The documented names are SBQQ__Quote__c.SBQQ__QuoteProcessId__c and SBQQ__Quote__c.SBQQ__Pricebook__c, and the quote process's Product Search Executor and Product Configuration Initializer fields (labels).
Before Starting
- Confirm the CPQ managed package (
SBQQ__) is installed and the Quote Process and Process Input objects exist. - Identify every Product2 field the wizard filters on. For custom fields, plan a field with the same API name on the Process Input object (see Core Concepts).
- Decide whether plain guided selling is enough, or whether the product search plugin is needed: Enhanced mode (the plugin appends a WHERE clause) or Custom mode (the plugin builds the whole query).
- Decide how the Quote Process is chosen: the org default, or set per quote (
SBQQ__Quote__c.SBQQ__QuoteProcessId__c). - Decide whether Auto Select Product should add the single match automatically.
Questions to Ask Before Configuring
Ask these before creating a Quote Process. Each one traces to a gotcha in references/gotchas.md.
| Question | Why it matters | What a good answer adds | What proper configuration adds over just doing it |
|---|---|---|---|
| "Is this org staying on CPQ, or moving to Revenue Cloud?" | The CPQ package has no new feature development (gotcha 1) | A decision on how much to invest in custom plugin code | Effort spent where the platform is still developed |
| "Which Product2 fields do the questions filter on, and are any custom?" | Custom fields need a same-name field on Process Input (gotcha 2) | A field list with types, mirrored where custom | Answers that actually filter instead of returning the whole catalog |
| "Can every answer be expressed as a simple field filter, or is extra logic needed (inventory, region, ranking)?" | Extra logic means the product search plugin, in Enhanced or Custom mode (gotcha 3) | The plugin mode, or a decision not to use one | No Apex where configuration was enough, and correct Apex where it was not |
| "Which quote fields would plugin logic need?" | Plugins see only a subset of quote fields by default; others need SOQL (gotcha 4) | The quote fields the plugin must query | Plugin logic that works on the first quote |
| "Should a bundle be pre-configured from the answers?" | The configuration initializer works only for standard product option fields (gotcha 6) | Which option fields the answers set | No initializer built for fields it cannot set |
| "Do all possible single matches have a price book entry in every price book used?" | Auto Select can fail on a missing entry (gotcha 7) | A price book coverage check | Auto Select that adds a line instead of raising an error |
What a proper configuration adds over "just turning on the wizard": every answer narrows the catalog as intended, plugin code exists only where configuration cannot express the rule, and reps never see an unexplained empty or unfiltered result.
Core Concepts
Quote Process and the Guided Selling Wizard
A Quote Process record (SBQQ__QuoteProcess__c) holds the wizard configuration; its Process Input records (SBQQ__ProcessInput__c) are the questions. A quote records the quote process it uses in SBQQ__QuoteProcessId__c (CPQ Developer Guide, quote model JSON). The quote process can also name a Product Search Executor (a Visualforce page that further filters guided selling results) and a Product Configuration Initializer (a Visualforce page that preselects bundle options from the answers); both are entered as c__ followed by the page name.
UNVERIFIED (2026-10-03): earlier versions of this skill said the wizard activates only when SBQQ__GuidedProductSelection__c is true, that the org default is set in CPQ Settings, and that a price book can carry its own quote process in Pricebook2.SBQQ__GuidedSelling__c. These are help-only claims; confirm the field and setting names in the org.
Process Input Questions and Field Mapping
Each Process Input defines one question: its label, order, whether it is active and required, how the rep answers, the Product2 field it filters, and the operator. The plugin guide confirms the runtime shape: the answers reach the plugin as a map whose "key is a Product2 API name and the value is the desired search value". UNVERIFIED (2026-10-03): the field-level detail of how CPQ stores each answer on the Process Input record is help-only.
Custom Classification Field Mirroring
When a question filters on a custom Product2 field (for example Deployment_Model__c), earlier versions of this skill state that a field with the identical API name and a compatible type must exist on SBQQ__ProcessInput__c, and that without it the question silently applies no filter. UNVERIFIED (2026-10-03): this mechanism is help-only. It is the first thing to check when answers return the whole catalog, and the mirror field is deployable metadata (see references/metadata-examples.md).
Standard, Enhanced, and Custom Search
| Mode | What runs | Grounding |
|---|---|---|
| Standard | CPQ's own filter from the Process Input answers, no plugin | UNVERIFIED (2026-10-03): help-only |
| Enhanced | CPQ's query plus a WHERE fragment returned by getAdditionalSuggestFilters(quote, fieldValuesMap) | CPQ Plugins Guide: isSuggestCustom returning false selects Enhanced searching |
| Custom | The plugin's suggest(quote, fieldValuesMap) builds and runs the whole query and returns List<PricebookEntry> | CPQ Plugins Guide: isSuggestCustom returning true selects Custom searching |
The guided selling interface of SBQQ.ProductSearchPlugin has five methods: isInputHidden(quote, fieldName), getInputDefaultValue(quote, fieldName), isSuggestCustom(quote, fieldValuesMap), suggest(quote, fieldValuesMap), and getAdditionalSuggestFilters(quote, fieldValuesMap). CPQ calls isInputHidden and getInputDefaultValue for each input, then isSuggestCustom, then either suggest or getAdditionalSuggestFilters. Earlier versions of this skill described a search(SBQQ.ProductSearchContext ctx) method returning List<Id>; that signature is not in the guide. UNVERIFIED (2026-10-03): the claim that Enhanced mode renders multi-select questions with OR matching is help-only.
Auto Select Product
When Auto Select is on and the answers return exactly one product, CPQ adds it to the quote without showing the results list. With zero matches the wizard shows an empty result; with two or more it shows the results grid. UNVERIFIED (2026-10-03): this behavior and the field name SBQQ__AutoSelectProduct__c are help-only.
Common Patterns
Pattern: Guided Selling with Custom Classification Fields
When to use: The catalog has custom classification fields (industry, deployment model, service tier) and reps should narrow it with dropdown questions.
How it works:
- Create the custom fields on Product2.
- Create same-name, same-type fields on
SBQQ__ProcessInput__c(deployable, seereferences/metadata-examples.md). - Populate the classification fields on every product that should appear.
- Create the Quote Process for guided selling.
- Create one Process Input per question, pointing at the Product2 field API name.
- Make the Quote Process the default or assign it to the quotes that need it.
- Test from a quote with Add Products, answering every question.
Pattern: Enhanced Mode for a Business Rule the Questions Cannot Express
When to use: Reps answer the questions, but the results must also respect a rule they do not control, such as "urgent shipments only show products with inventory above 3".
How it works: Implement SBQQ.ProductSearchPlugin with isSuggestCustom returning false, and return an extra WHERE fragment from getAdditionalSuggestFilters (the guide's own example returns AND Product2.Inventory_Level__c > 3 when the "Urgent Shipment" input is "Yes"). Register the class on the Plugins tab of the CPQ package settings. UNVERIFIED (2026-10-03): the guide describes that tab for the quote calculator and recommended products plugins but does not name the product search plugin field. The full class, test, and manifest are in references/metadata-examples.md.
Decision Guidance
| Situation | Recommended Approach | Reason |
|---|---|---|
| Filter on standard Product2 fields | Point the question at the standard field API name | No mirror field needed |
| Filter on a custom Product2 field | Mirror field with the same API name on Process Input | Required for the answer to filter (help-only mechanism) |
| Extra rule the rep does not control | Plugin in Enhanced mode (getAdditionalSuggestFilters) | CPQ keeps its query; the plugin appends a WHERE fragment |
| Results need external data or ranking | Plugin in Custom mode (suggest) | The plugin owns the whole query and returns price book entries |
| Results need a post-filter the rep cannot override | Product Search Executor on the quote process | A Visualforce page that filters guided selling results |
| Answers should preselect bundle options | Product Configuration Initializer | Works only for standard product option fields |
| New implementation, no CPQ yet | Evaluate Revenue Cloud | The CPQ package has no new feature development |
Recommended Workflow
- Confirm the platform and fields. CPQ installed and staying in use; every filter field listed; custom fields flagged for mirroring; every CPQ field API name confirmed in Object Manager.
- Deploy the mirror fields. Create the same-name fields on
SBQQ__ProcessInput__cfrom metadata, with field-level security for the users who run the wizard. - Populate classification data. Every product that should appear has values on the filter fields; null values never match an equals filter.
- Create the Quote Process and Process Inputs. One input per question, pointing at Product2 field API names.
- Add plugin logic only if needed. Enhanced mode for appended filters, Custom mode for full control. Use bind variables, query any quote fields the plugin needs, and register the class on the Plugins tab of the CPQ package settings.
- Activate and test. Make the Quote Process the default or assign it, then test every question with matching, non-matching, and blank answers, and test Auto Select against every price book.
Review Checklist
- [ ] CPQ field API names confirmed in Object Manager (help-only names flagged in this skill)
- [ ] Every custom Product2 filter field has a same-name field on
SBQQ__ProcessInput__c, with field-level security granted - [ ] Filter fields populated on every product that should appear
- [ ] Plugin used only where questions cannot express the rule; mode (Enhanced or Custom) documented
- [ ] Plugin SOQL uses bind variables, not string concatenation
- [ ] Quote fields the plugin needs are queried explicitly
- [ ] Quote Process activated (default or assigned)
- [ ] Auto Select tested against every price book in use
- [ ] End-to-end wizard test completed in a sandbox
Salesforce-Specific Gotchas
The deep versions, with sources, live in references/gotchas.md.
| # | Gotcha | One-line consequence |
|---|---|---|
| 1 | CPQ package has no new feature development | Large new investments may be stranded |
| 2 | Missing mirror field returns the whole catalog | No error, just unfiltered results |
| 3 | Enhanced and Custom are plugin modes chosen by isSuggestCustom | Wrong method gets ignored |
| 4 | Plugins see only some quote fields | Logic fails on null quote values |
| 5 | The guide's sample plugin concatenates strings into SOQL | Copying it invites SOQL injection |
| 6 | Initializer sets only standard product option fields | Custom option fields stay unset |
| 7 | Auto Select needs a price book entry for the single match | Rep sees an error instead of a line |
| 8 | Null classification values never match equals filters | Valid products disappear |
Output Artifacts
| Artifact | Description |
|---|---|
| Quote Process record | Guided selling configuration, with executor and initializer if used |
| Process Input records | One per question; label, field, operator, order, required |
| Mirror custom fields on Process Input | Deployable CustomField metadata matching Product2 API names |
| Product search plugin (if needed) | Apex class implementing SBQQ.ProductSearchPlugin, with test |
| Guided selling configuration checklist | Setup decisions and test results |
Related Skills
admin/cpq-product-catalog-setup: Product2 catalog and bundles before guided sellingadmin/products-and-pricebooks: standard Product2 and price book setup that guided selling filtersadmin/cpq-pricing-rules: price rules and discount schedules applied after selectionadmin/quote-to-cash-requirements: whether guided selling is the right selection mechanismapex/cpq-apex-plugins: deeper plugin development beyond the guided selling interface
Dependencies
cpq-product-catalog-setupproducts-and-pricebooks