CPQ Approval Workflows

Use this skill when configuring or troubleshooting the CPQ Advanced Approvals managed package (namespace SBAA__): creating approval rules that evaluate fields across quote line items using Approval Variables, building sequential or parallel Approval Chains, enabling Smart Approvals to skip re-approval on unchanged requote fields, configuring escalation timeouts, and assigning the required permission sets. This skill does not cover standard Salesforce approval processes or CPQ pricing configuration.

---

Before Starting

Gather this context before working on anything in this domain:

• Confirm the CPQ Advanced Approvals managed package (SBAA__) is installed separately from the base Salesforce CPQ package (SBQQ__). Both must be present. Check via Setup > Installed Packages.
• Confirm users who submit, approve, and administer approvals have the "CPQ Advanced Approvals" permission set assigned — this is a separate permission set from the base "Salesforce CPQ" permission set. Missing this permission set causes silent failures where approval buttons or records do not appear.
• Identify whether the approval trigger must evaluate quote-level fields (e.g., total quote discount), single quote-line fields (e.g., line discount), or aggregated values across all lines (e.g., maximum discount across all line items). Line-level aggregation requires SBAA__ApprovalVariable__c, not a direct field reference.
• Understand the most common wrong assumption: standard Salesforce approval processes cannot evaluate across quote line items. A standard approval process evaluates a single record; it cannot compute "the maximum discount across all lines." SBAA__ApprovalVariable__c is the only mechanism that solves this.
• Identify whether Smart Approvals should be enabled. When enabled, a requote that changes only non-approval-relevant fields will not require re-approval; if any approval-relevant field changes, all previous approvers must re-approve.

---

Core Concepts

CPQ Advanced Approvals Package and Namespace

CPQ Advanced Approvals is a separate managed package with the namespace SBAA__. It extends Salesforce CPQ (SBQQ__) and adds objects specifically for quote-level approval workflows. Installing CPQ does not install Advanced Approvals — they require separate installation steps and separate AppExchange listings.

Core objects introduced by the package:

Object	Purpose
SBAA__ApprovalRule__c	Defines when an approval is required (conditions, approver, escalation)
SBAA__ApprovalCondition__c	A single condition on a rule (field, operator, value)
SBAA__ApprovalVariable__c	Aggregates a value across all quote line items (e.g., max discount)
SBAA__ApprovalChain__c	Defines a sequential or parallel ordered list of approvers
SBAA__Approver__c	Represents a single approver step within a chain

Permission set: "CPQ Advanced Approvals" must be assigned to every user who interacts with approvals (submitters, approvers, administrators). This permission set is separate from the CPQ base permission sets.

Approval Rules and Approval Variables

An SBAA__ApprovalRule__c record is the core unit: it defines the threshold condition and the approver to route to when that threshold is met.

Approval Conditions (SBAA__ApprovalCondition__c) reference a field on the Quote (SBQQ__Quote__c) or an Approval Variable. Operators include: equals, not equals, greater than, less than, contains. Multiple conditions on a single rule are ANDed together. OR logic across separate conditions requires separate approval rules.

Approval Variables (SBAA__ApprovalVariable__c) solve a problem that standard approval processes cannot: computing an aggregated value across all quote line items. For example, a rule that fires when "any single line discount exceeds 30%" requires knowing the maximum discount value across all lines. An Approval Variable is configured to aggregate a specific field on SBQQ__QuoteLine__c using a function (Max, Min, Sum, Average) and the result is then available as a field reference in an Approval Condition. Without Approval Variables, cross-line discount approvals cannot be implemented.

Approver assignment on a rule can be:

• A specific user (User lookup on SBAA__ApprovalRule__c)
• A field on the quote that contains a user ID (dynamic user reference, e.g., the Account Owner)
• Routed through an Approval Chain for sequential or parallel multi-approver scenarios

Approval Chains

SBAA__ApprovalChain__c defines an ordered sequence of approvers. Each step is an SBAA__Approver__c record referencing the chain. Steps can be:

• Sequential: each approver must approve before the next is notified. This is the default and the most common pattern for escalating approval hierarchies (line manager to VP to CFO).
• Parallel within a step: multiple SBAA__Approver__c records with the same step number require all to approve before the chain advances.

An approval rule is linked to an approval chain rather than a single user when multi-step approval is required. The chain handles routing; the rule handles the trigger condition.

Smart Approvals

Smart Approvals is a feature of CPQ Advanced Approvals that avoids requiring full re-approval when a quote is re-submitted after changes. The behavior:

• If the re-submitted quote changes only non-approval-relevant fields (e.g., the quote description or expiration date), existing approvals are carried forward and the quote does not go back through the approval process.
• If the re-submitted quote changes any approval-relevant field (any field referenced in an active approval condition), all approvers must re-approve — even if their specific condition was not affected by the change.

Smart Approvals is enabled per rule. It does not reduce the approval requirement when relevant fields change — it only eliminates unnecessary re-approval cycles for cosmetic changes.

Escalation

Each SBAA__ApprovalRule__c can have an escalation policy: a timeout period (in days) after which, if the approver has not acted, the approval is routed to a designated escalation approver. Escalation is configured directly on the approval rule record via SBAA__EscalationDays__c and SBAA__EscalationUser__c. Escalation requires the SBAA.EscalateApprovals scheduled Apex job to be active in Setup > Scheduled Jobs — without this job, escalation timeouts never fire regardless of the rule configuration.

---

Common Patterns

Pattern: Line-Level Discount Threshold via Approval Variable

When to use: A quote must be approved when any single line item has a discount exceeding a threshold (e.g., 30%), which requires knowing the maximum discount across all lines.

How it works:

1. Create an SBAA__ApprovalVariable__c record:
   • Name: Max Line Discount
   • Object: SBQQ__QuoteLine__c
   • Aggregation Function: Max
   • Field: SBQQ__Discount__c
2. Create an SBAA__ApprovalRule__c record with the designated approver user or lookup field, and Active checked.
3. Create an SBAA__ApprovalCondition__c record referencing the rule:
   • Variable: the Max Line Discount variable
   • Operator: Greater Than
   • Value: 30
4. Test by creating a CPQ quote with a line at 31% discount and verifying the approval is triggered; test a quote with all lines at 29% and verify no approval is required.

Why not a standard approval process: Standard approval processes evaluate a single record. There is no native mechanism to evaluate a field across multiple child records (quote lines) within a standard approval process. SBAA__ApprovalVariable__c is the only correct solution for cross-line aggregation.

Pattern: Sequential Approval Chain for Tiered Authority

When to use: Different discount thresholds require different approver levels in sequence — for example, discounts above 20% need manager approval, and discounts above 40% additionally require CFO approval.

How it works:

1. Create an SBAA__ApprovalChain__c record: High Discount Chain.
2. Create SBAA__Approver__c records for each step:
   • Step order 1: Sales Manager user reference
   • Step order 2: CFO user reference
3. Create an SBAA__ApprovalRule__c with condition Max Line Discount > 40% and link it to High Discount Chain.
4. Create a second SBAA__ApprovalRule__c with condition Max Line Discount > 20% and assign the Sales Manager directly (no chain needed for single-approver rules).

Why not a flat rule per approver: Without a chain, triggering two rules separately does not enforce ordering — both approvers could be notified simultaneously, which does not match the escalating authority model. Chains enforce the sequential constraint so the CFO is only notified after the Sales Manager approves.

Pattern: Smart Approvals for Requote Scenarios

When to use: Sales reps frequently adjust non-commercial fields on requotes (e.g., quote name, expiration date) and should not be blocked by the full approval cycle for changes that do not affect pricing or discounts.

How it works:

1. Enable Smart Approvals on each applicable SBAA__ApprovalRule__c using the Smart Approvals checkbox in the rule record.
2. Document which fields are "approval-relevant" (those referenced in conditions). Any change to these fields on a requote forces full re-approval.
3. Communicate to sales reps that changing discount, quantity, or price-impacting fields always triggers re-approval; changing only administrative fields does not.

Why not disable re-approval entirely: Skipping re-approval when discount-relevant fields change would allow a rep to obtain approval at 20% discount and then change it to 40% without additional approval. Smart Approvals enforces re-approval exactly when the trigger conditions could be affected.

---

Decision Guidance

Situation	Recommended Approach	Reason
Approval triggered by a field on the quote (not lines)	SBAA__ApprovalRule__c with condition on Quote field	Direct field reference; no variable needed
Approval triggered by maximum or total discount across all lines	SBAA__ApprovalVariable__c (Max/Sum) + Approval Condition	Standard approvals cannot aggregate across child records
Multiple approvers required in a fixed sequence	SBAA__ApprovalChain__c with ordered SBAA__Approver__c steps	Enforces sequential routing; parallel steps possible within a step number
Re-approval required only when pricing fields change on requote	Smart Approvals enabled on each rule	Skips re-approval for non-relevant field changes; still re-approves when conditions could be affected
Approver has not responded after N days	Escalation config on SBAA__ApprovalRule__c	Routes to escalation user after timeout; requires scheduled job active
OR logic across two separate conditions	Two separate Approval Rules each with one condition	Conditions within one rule are ANDed; separate rules cover OR scenarios
Standard Salesforce approval process for a CPQ discount approval	Do NOT use — use CPQ Advanced Approvals instead	Standard processes cannot evaluate across quote line items

---

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Verify package installation and permission sets. Confirm SBAA__ namespace is present under Setup > Installed Packages. Confirm the "CPQ Advanced Approvals" permission set exists and is assigned to all users who will submit or approve quotes. Without this permission set, approval buttons and records will not appear — this is the most common cause of "approvals not working" reports.

2. Design the approval matrix before configuring records. Document each approval threshold: the triggering condition (field, operator, value), whether it requires a quote-level field or a line-level aggregation, the approver or approver chain, whether Smart Approvals should be enabled, and the escalation timeout. This design document becomes the canonical reference for all rule records.

3. Create Approval Variables for any line-level aggregations. For each threshold that depends on a value aggregated across quote lines (e.g., max discount, total discount amount), create an SBAA__ApprovalVariable__c record specifying the child object (SBQQ__QuoteLine__c), the field, and the aggregation function. Verify the variable resolves against test quote line data before building rules that reference it.

4. Create Approval Rules and Conditions. For each approval threshold, create one SBAA__ApprovalRule__c record. Attach SBAA__ApprovalCondition__c records referencing either quote fields or Approval Variables from step 3. If multiple approvers are needed in sequence, link the rule to an SBAA__ApprovalChain__c rather than a single user. Enable Smart Approvals on each rule where requote skip logic is desired.

5. Configure Approval Chains for multi-step approvals. Create SBAA__ApprovalChain__c and SBAA__Approver__c records for any rules requiring sequential or parallel multi-step routing. Assign step order numbers to enforce sequence; use the same step number for approvers that should act in parallel within a step.

6. Verify escalation setup. If escalation is required on any rule, set SBAA__EscalationDays__c and SBAA__EscalationUser__c on the rule. Then confirm the SBAA.EscalateApprovals scheduled Apex job is active in Setup > Scheduled Jobs. Without this job, escalation timeouts never fire.

7. Test end-to-end in a sandbox. Create CPQ quotes that cross each threshold and verify the correct approver is notified. Test below-threshold quotes to confirm no spurious approvals fire. Test a requote with Smart Approvals enabled: change only a non-relevant field and confirm approval is carried forward; then change a discount field and confirm re-approval is required. Document test results before promoting to production.

---

Review Checklist

Run through these before marking work in this area complete:

• CPQ Advanced Approvals managed package (SBAA__) is installed and version is compatible with the installed CPQ version
• "CPQ Advanced Approvals" permission set is assigned to all submitters, approvers, and administrators
• All SBAA__ApprovalRule__c records are Active and have at least one SBAA__ApprovalCondition__c
• All SBAA__ApprovalVariable__c records reference the correct child object (SBQQ__QuoteLine__c), field, and aggregation function
• Approval Chains have SBAA__Approver__c records with explicit step order numbers; no two sequential approvers share the same step number unintentionally
• Smart Approvals is enabled on each rule where requote skip logic is desired; approval-relevant fields are documented
• Escalation rules have both SBAA__EscalationDays__c and SBAA__EscalationUser__c set; SBAA.EscalateApprovals scheduled job is active in Setup > Scheduled Jobs
• End-to-end approval test passed in sandbox: above-threshold quote triggered approval, below-threshold quote did not
• Smart Approvals requote test passed: non-relevant field change skipped re-approval; discount field change required re-approval
• Approval workflow design document is complete and all rule records match the documented design

---

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Standard approval processes cannot aggregate across quote line items — A standard Salesforce approval process evaluates a single record at submission time. It cannot evaluate a field value across all child SBQQ__QuoteLine__c records. SBAA__ApprovalVariable__c with a Max/Sum/Min/Average function is the only supported solution for cross-line aggregation logic.

2. Smart Approvals re-approves all approvers when any relevant field changes — A common misconception is that Smart Approvals re-approves only the approver whose specific condition was affected by the field change. The actual behavior: if any approval-relevant field changes on a requote, every approver in every rule that previously approved must re-approve. There is no selective re-approval by rule.

3. Escalation requires the SBAA.EscalateApprovals scheduled Apex job — Setting SBAA__EscalationDays__c on a rule does not by itself cause escalation. The escalation is only evaluated when the scheduled job runs. If this job is not scheduled or has been deactivated, no escalations will ever trigger. Always verify the job is active in Setup > Scheduled Jobs when configuring escalation.

4. The "CPQ Advanced Approvals" permission set is separate from CPQ base permission sets — Installing CPQ Advanced Approvals creates a new permission set. Users who already have "Salesforce CPQ" or "Salesforce CPQ Admin" permission sets do not automatically receive Advanced Approvals permissions. Forgetting this assignment causes approval buttons to be invisible or approval record access to fail silently with no error message.

5. All conditions on a single approval rule are ANDed — OR logic requires separate rules — All SBAA__ApprovalCondition__c records on a single SBAA__ApprovalRule__c are evaluated with AND logic. If OR logic is required (e.g., trigger approval if discount > 30% OR total revenue > $100K), two separate approval rules must be created, each with its own condition.

---

Output Artifacts

Artifact	Description
SBAA__ApprovalRule__c records	Active rules defining each approval threshold, approver, and escalation policy
SBAA__ApprovalCondition__c records	Individual conditions on each rule referencing quote fields or Approval Variables
SBAA__ApprovalVariable__c records	Aggregation definitions for cross-line metrics (max discount, sum of revenue, etc.)
SBAA__ApprovalChain__c + SBAA__Approver__c records	Sequential or parallel approver chains for multi-step routing
Permission set assignment list	Record of which users have the CPQ Advanced Approvals permission set
Approval workflow design document	Design matrix: each rule's threshold, approver, chain, Smart Approvals flag, escalation timeout
Completed review checklist	Signed-off checklist confirming all rules, variables, and chains are correctly configured

---

Related Skills

• cpq-pricing-rules — Configure the price waterfall and discount mechanisms that approval thresholds evaluate against
• cpq-product-catalog-setup — Set up product bundles and options before approval rules that reference product-level fields
• approval-processes — Use for standard Salesforce approval processes on non-CPQ objects; do not use for cross-line CPQ discount approvals
• quote-to-cash-requirements — Use during requirements gathering to map approval policies to CPQ mechanisms