Fields
Summarize
Summary of Fields in CPQ Configurations
Fields are the fundamental data elements in the CPQ configuration model, representing single pieces of data like quantities, choices, or notes. They power the user experience, logical rules, and downstream outputs such as bills of materials or external system integrations. Fields are global within an environment, enabling reuse across blueprints, rules, and layouts to maintain consistency and reduce duplication. A field becomes part of a configuration only when associated with a blueprint, and rules automatically link to blueprints if their referenced fields are associated.
Show less
How Fields Integrate with CPQ Components
- Blueprints: Specify which global fields are included in a configuration, enabling reuse without cloning.
- Rules: Use field values as inputs and perform actions like setting values, controlling visibility, validation, filtering options, or adding products.
- Layouts: Define the visual placement and user interaction type (Component display) for fields.
- BOM/Product List: Map field values to product attributes or extended properties for downstream processing.
Field Scope and Lifecycle
Fields are created once with a global identifier and are available for reuse. Their lifecycle includes:
- Create: Define field type, name, and unique variable name.
- Associate: Link fields to one or more blueprints.
- Place Display: Choose an appropriate Component display type in layouts (e.g., grid, slider, read-only).
- Orchestrate: Use rules to read/set field values, control visibility, show messages, and drive product actions.
Choosing the Right Field Type
Selecting the correct field type ensures valid data and simplifies rule logic. Types include:
- Text: Free-form input up to 2000 characters, with optional constraints.
- Number: Numeric input with min/max limits and formatting options like currency or percent.
- Boolean: True/False with customizable labels and defaults.
- Picklist: Single or multi-select constrained choices with options and extensions for richer data and filtering.
- Product Picker: Specialized picker for products that can add items to BOM and map to product list fields, often reducing rule complexity.
- Sets: Tabular collections ideal for line-item or calendar-like data, where subfields interact locally per row.
Tip: Prefer constrained types like number, picklist, and product picker to reduce validation and improve user guidance.
Data Model vs. Display Model
The field type defines the data structure and valid values, whereas the Component display type controls user interaction in layouts. A single field can have different visual representations (e.g., slider, grid, radio buttons) across layouts while maintaining consistent data integrity.
Association and Reuse
Fields are global and reusable. Associating a field with a blueprint makes it available for that configuration’s layouts and rules. Rules automatically relate to blueprints if their fields are associated, preventing cloning, reducing configuration drift, and simplifying maintenance.
Governance and Naming Best Practices
- Use clear, stable variable names with underscores (e.g., shippingmethod) for maintainable rule scripting.
- Document field intent, valid ranges, and semantics in descriptions to support future reuse.
- Set default values only when a starting state is required; otherwise, use contextual rule logic.
Accessibility and Internationalization
- Choose display types that clearly show choices, such as radio buttons or tiles, especially when options are few.
- Provide human-readable labels and help text; use read-only Markdown text for structured guidance.
- Apply locale-aware formatting for numbers and currency in layouts.
Performance and Reliability
- Use the simplest field type that meets requirements to minimize rule complexity and improve runtime performance.
- Leverage picklist extensions and product pickers to encapsulate option data and reduce rule counts.
- Reserve always-on determination rules for system defaults; prefer context-driven conditions elsewhere.
Bulk Operations
For large-scale changes or environment migrations, use the Matrix Loader tool to bulk-create and edit fields and their options. This approach streamlines development workflows and serves as documentation across environments.
Learn how fields provide the foundational data model for CPQ configurations—what they are, how they relate to blueprints, rules, and layouts, and how to choose the right type and display for reliable, reusable experiences.
Fields are the smallest unit of the CPQ configuration model and represent a single piece of data (for example, a quantity, a choice, or a note). They power the user experience (what the user sees and edits), the logical model (what rules read and act on), and downstream outputs (what is written to the bill of materials or passed to external systems). Because fields are global in an environment, the same field can be reused across blueprints, rules, and layouts to ensure consistency and reduce duplication.
Fields become part of a specific configuration only when they are associated with a blueprint. When all fields referenced by a rule are associated to a blueprint, the rule is intrinsically related to the blueprint—no extra linking step is required.
How fields fit into the configuration model
- Blueprints: Declare which global fields participate in a configuration. Association enables reuse without cloning.
- Rules: Read field values as inputs and perform actions on fields (determine values, show/hide, validate, filter options, add products).
- Layouts: Place fields visually and select a Component display type to control how the user interacts with each field.
- BOM/product list: field values can be mapped to product attribution or extended properties for downstream processing.
Field scope and life cycle
- Create: Define the field type, name, and unique variable name (global identifier).
- Associate: Add the field to one or more blueprints to make it available in those configurations.
- Place Display: Choose the appropriate Component display type in a layout (for example, grid, visual picker, slider, read-only).
- Orchestrate: Apply rules to read or set field values, control visibility, present messages, and drive product actions.
Choosing the right field type
- Text: Free-form string input (up to 2000 characters), with optional length constraints and default.
- Number: Numeric input with optional min/max; layout-level options can enforce step or precision and formatting (currency/percent/read-only currency).
- Boolean: True/False with customizable labels and default state.
- Picklist (single or multi-select): Constrained choices with definable options, defaults, and picklist extensions for rich, columnar option data and implicit filtering.
- Product Picker: A picker specialized for products that can add items to the BOM and map additional data to Product List fields—often removing the need for separate rules.
- Sets: Tabular collections where each row’s subfields interact row-locally (ideal for calendar-like or line-item scenarios).
Data model vs. display model
The field type defines the data model and specifies what values are valid. The Component display type defines how users interact with the field in a layout (for example, radio, menu, or grid). A single field can be rendered differently across layouts while preserving a consistent data model.
- Number: shown as number input, number-with-submit, slider, read-only text/currency, or formatted number.
- Picklist: shown as traditional menu, vertical radio buttons or check boxes, visual tiles, or grid (with picklist extension columns).
- Product Picker: shown as a grid or visual tile experience with subfields and aggregates.
Association and reuse
Because fields are global, reuse is the default. Associate a field with any blueprint that needs it; the field is then available to the blueprint’s layouts and rules. If all referenced fields in a rule are associated with the blueprint, the rule is automatically considered related to the blueprint.
This model avoids cloning, reduces drift, and simplifies maintenance across products and experiences.
Governance and naming
- Variable names: Use clear, stable, names (with words separated by underscores, as in shipping_method) to make rule scripts expressive and durable.
- Descriptions: Document intent and valid ranges (minimum and maximum, semantic meaning) to aid future reuse.
- Defaults: Set only when the business logic expects a starting state; otherwise, let rules determine values contextually.
Accessibility and internationalization
- Prefer display types that make choices obvious (radios/tiles) when option sets are small.
- Provide human-readable labels and help text; use read-only text with Markdown for structured guidance.
- Use layout-level formatting for numbers and currency to respect locale conventions.
Performance and reliability tips
- Choose the simplest field type that satisfies the requirement. Fewer rules and validations mean faster run times.
- Use picklist extensions or product pickers to encapsulate rich option data and reduce rule count.
- Reserve “always-on” determination rules for true system defaults; prefer contextual conditions elsewhere.
When to use bulk operations
For larger changes or environment migrations, use Matrix Loader to bulk-create and edit fields and field options. The spreadsheet artifact doubles as documentation and accelerates flow from dev to test to production.