System Configuration

A BOM (Bill of Material) is a multi-level hierarchical structure of parent and child items that defines the components needed to sell or manufacture a complex product. Model BOMs define the options displayed in an Oracle CPQ Configuration session and the set of Commerce line items that result from users’ Configuration choices.

Using Oracle CPQ System Configuration, model BOMs can now be reused as children of other, parent model BOMs or system model BOMs, which then allow the child models to be sold separately and as part of a bundle.

In order to reuse a child model BOM as part of a system BOM, Oracle recommends configuring BOM Mapping Rules for the child model BOM by defining it as its own root BOM item with a corresponding BOM Mapping Rule. The parent system model BOM is then also defined with its own root BOM item and corresponding BOM Mapping Rule, but with the child model BOM associated as a child.

Administrators may choose one of two different behaviors for the child model BOM within a system when setting up the system model BOM in the Oracle CPQ BOM Item Definition table.

1. Default BOM items can be defined for the child model. Each default BOM item is listed as a child of the child model within the system model BOM. Customers leverage the system-level BOM definition to model the default BOM they wish to sell, allowing sales users to complete their order without needing to configure each of the child items. If the sales user chooses to configure the child model and override the defaults, the child model’s BOM Mapping Rules execute, avoiding duplication of the complete hierarchy definition in the system-level BOM. While the parent model defines the default contents of the child model, the child model will override the parent’s definition.
2. No default BOM items are defined for the child model. The child model BOM alone is listed as the child of the system model BOM. Sales users must configure the child model as if they were buying that model on its own.

For example: A customer wants to sell a promotional back-to-school bundle for their laptop, printer, and smartphone products and sell software and data plans as child items under the laptop and the smartphone items. To accomplish this, the administrator would represent the promotional bundle, the laptop, the printer, and the smartphone products as separate models in the system. As a result, each of the child models can then be purchased or sold separately or as part of the bundle.

The administrator creates a bundle level root BOM in the BOM data tables, which defines the default set of BOM items for all these products. A specific laptop, software, printer, smartphone, and a specific data plan are defined as child items under the bundle’s root BOM item. If users do not configure laptop, printer, and smartphone models, they purchase the default promotion bundle. Alternatively, the sales user can choose to configure the smartphone model and select a different data plan than that defined as the default under the promotion. Administrators can model the different options available for the data plans in the BOM data table under the Smartphone model. In this example, the administrator does not need to duplicate all possible data options under the promotional bundle. By configuring the smartphone model, the buyer could select an option other than the one selected by default under the promotion.

The following image illustrates the setup of the BOM items for the example described. The left side illustrates the logical model BOMs that are reused as children of the system-level model BOM. The Laptop, Printer, and Smartphone are root BOM items for their model definitions. For the promotional bundle, the laptop, printer, and smartphone are child models and the promotional bundle is the root BOM item. The right side illustrates the corresponding entries in the BOM Item Definition Table for the standalone models (white background) and for the system-level model containing these same models as children (yellow background). Default values have been specified for the child models in the system-level model BOM.

The following image displays a sample System Configuration JSON Structure along with a hierarchy diagram and a corresponding Line Item Grid. The System Configuration Hierarchy provides a visual representation of the items in the JSON Structure. This image also shows the relationship between the JSON Structure "documentNumber" field and the Line Item Grid "Doc #" attribute.

Administrators can now view folders for each model in a BOM hierarchy when adding attribute references to an advanced BML function. The System Configuration folder is available when there is at least one root item defined in an active BOM Item Definition Table, and will be shown when an administrator selects Add Attributes from within an advanced BML function. The root items for defined systems are shown within the System Configuration folder. Administrators can navigate through the folder structure to select and add attributes.

Configurable Attributes

System Configuration Document Number

System Configuration Variable Names

Invalid BOM Item Definition Folders

The System Navigation Panel contains model and part icons to show the hierarchy of a system and status icons to identify models requiring user action.The system navigation panel will display items that are valid, incomplete, and invalid. It will also indicate if models have warnings or errors. The following table describes possible states for models within the system navigation panel and identifies if invocation is allowed for each state.

System Navigation Panel Example

Status Order of Precedence

System Path Warnings for Favorites and Pending Configurations

In prior releases the child models were not configured until the Configuration UI was launched for each child model. Beginning in Oracle CPQ 19D, when customers launch system configurations a defined collection of child models can have an initial configuration applied. The initial configuration will consist of attribute default values, layout default values, and the result of configuration rules. New system configuration options allow administrators to define the number of models and the depth of descendant models to initialize.

For example, a cellular provider offers a Family Connect Plan that comes standard with four lines. Each line comes with an xPhone S with a 2 year warranty, and an Unlimited Nation-wide Plus plan that has unlimited nation-wide calls, text, and data.

Without system configuration initialization the child models are not configured when the Configuration UI for the root model is launched. The following image shows the Family Connect Plan system with the un-configured child models. This is the same behavior when system configuration initialization is disabled.

When system configuration initialization is enabled the child models can be configured when the Configuration UI for the root model is launched. The following image shows the Family Connect Plan system with all of the child models initialized and configured.

There are initialization scenarios when the system will be partially configured. This can occur when the depth of descendant models setting is lower than the number of descendant levels in the system. For example, the following image shows a system where the depth of descendant models is set to "1", the number of models is set to "20", and the system configuration has two descendant levels. Notice only the level one child models are configured (Line 1, Line 2, Line 3, and Line 4).

Another scenario that can cause partial configuration is when the when the number models setting is lower than the number of models in the system. The system will initialize all of the first level children and then continue to the next enabled level until it reaches the limit set for the number of models. For example, the following image shows a system where the depth of descendant models is set to "3", the number of models is set to "3", and the system configuration has two descendant levels and twelve descendant models. Notice only the first three level one child models are configured (Line 1, Line 2, and Line 3).

Previously, system configuration initialization would add child models during the initial configuration. Oracle CPQ 24C provides the ability to invoke rules for child models during system configuration. Unlike system configuration initialization which only occurs during the initial configuration, the cascading configuration of descendant models will automatically apply default values during reconfiguration and from favorites. New models added to a System Configuration are immediately configured using default and rule-defined values.

• Automatic configuration will continue for descendant models added by the new model’s rules.

• Each configured System Model is marked with the appropriate status icon in the System Navigation Panel.

  

Beginning in Release 18C, users can access incomplete system configurations from the existing Pending Configurations page. An incomplete system configuration is the result of configuring a system in the Model Configuration page and navigating away from the page. An incomplete system configuration can also occur when users are configuring a system and are accidentally logged out of their session or lose a network connection. When any of these scenarios occur, the entire system is saved as a draft on the Pending Configurations page.

Access Incomplete System Configurations from the Pending Configurations Page

Resume Work on Incomplete Configurations

Beginning in Release 18B, administrators can create Configuration rules that reference Configuration attributes from different Product Families. The System Configuration folder is available when there is at least one root item defined in an active BOM Item Definition Table, and will be shown when an administrator selects Add Attributes from within an advanced BML function.

The System Configuration folder shows all available root items on the site. Upon expanding a folder, the model and its associated attributes are displayed. In prior releases, only the models within the same product family as the rule being defined had the Configurable Attributes folder. Administrators select attributes from the Configurable Attributes folder to populate the advanced BML function.

For example: The following image shows a Constraint Rule for a cable modem within the Internet model, that references the phoneServiceType attribute within the Phone model.

When users select a model from the system navigation panel and proceed to configure the model, the full system to which the model belongs is visible in the Bill of Materials panel. In the below example, the user is configuring room models. As each room is configured, the associated BOM parts are added to the Bill of Materials panel to denote the configuration status, or selected settings, for the model. This enhancement allows users to track the progress of the entire system.

Prior to Oracle CPQ Release 18D, only the Bill of Materials for the current model were displayed in the Bill of Materials panel.

As a prerequisite to users’ ability to reconfigure a child model from the line item grid, administrators would first define a BOM hierarchy for each BOM-enabled configurable model in the system. As in prior releases, administrators can build the System Configuration from the Oracle CPQ Home page. The same Reconfigure icon that displays next to the root model also displays next to the child models in the line item grid.

Complete the following steps to reconfigure a child model from the line item grid:

1. Log in to CPQ.

2. Open a quote containing child models, which will display in hierarchical order under the root model in the line item grid.

   

Administrators can capture the BOM hierarchy of a child model by calling the “getbom” BML function using the document number of any BOM element. Administrators can use this functionality to retrieve details of the parent or child BOM items while configuring a given model. They can then choose to apply rules for the current child configuration, allowing the application of system level constraints or recommendations to the current model.

Administrators can create a read-only HTML attribute and use the attribute to display a hierarchical representation of BOM-derived elements from the line item grid. Once created, the populated attribute displays a multi-level structure of BOM-derived root and child items in a Transaction.

Example of BOM Hierarchy Display Attribute in a Transaction

Complete the following steps:

1. Navigate to the Admin Home page.

2. Under Commerce and Documents, click Process Definition.

   The Processes page opens with Documents displaying by default in the Navigation drop-down menu for each Commerce process listed.

3. Next to the process name for which you are creating the attribute, click List.

   The Document List page opens with Attributes displaying by default in the Navigation drop-down menu for each document listed.

4. Click List next to the main document for which you are creating the attribute.

   The Attribute List page opens.

5. Click Add.

   The Attribute Editor opens.

6. In the Label field, enter a name for the attribute, such as BOM Hierarchy Display.
7. Click in the Variable Name field to auto-populate the field.

8. In the Attribute Type drop-down menu, select Read-only text or HTML.

   

9. Click Add.

   The Read-only text or HTML Attribute Editor opens with the Exclude from XML checkbox selected by default. Keep the checkbox selected.
   
   

10. In the Default tab, select the BOM Hierarchy Display option.
    
    

11. Click the Save and Edit Desktop Layout button or the Save and Edit Mobile Layout button to open the layout.

12. Add the attribute to the layout using the standard drag and drop functionality available in prior releases. For additional information, refer to the Layout Editor Overview topic.

13. Click Save.

14. Click Apply.

15. Use the Mapping tab if you want to hide the attribute on Transactions.

16. Click Apply.

17. Click Update to return to the Attribute List page.

Beginning in Release 18B administrators can migrate Configuration rules that reference System Configuration attributes even if they do not exist on the target site. Upon opening a migrated Configuration rule with references to an attribute that does not exist on the current site, administrators are given a warning message stating a reference is missing. During Configuration, an empty result value is returned when a referenced attribute does not exist.

For example: The following image shows a warning message that is displayed when an administrator opens a migrated rule where the attribute does not exist on the current site.

Administrators can close the rule, but no changes to the rule can be saved until the reference is removed or the corresponding attribute exists on the current site. The warning message will change to an error message if the administrator attempts to validate or save a rule with a missing reference warning. Warning and error messages are also displayed in the BML Editor when the administrator views the advanced BML function.

For example: The following image shows a warning message that is displayed when an administrator attempts to validate or save the advanced BML function for a migrated rule where an attribute does not exist on the current site.

A Transaction ID and the document number of the root system can be used to debug system configuration inter-model rules. The Context Parameters field has been added to Debugger tab for BML Function Editor.

To debug system configuration inter-model rules, enter the bsId and documentNumber, and then run the script using the Debugger's Run action. This will automatically pull the specified system into memory and evaluate the attributes based on the specified system's data.

Syntax: bsId=#######,documentNumber=#

The BOM Item Definition table stores the BOM hierarchical relationships used in the fulfillment system along with item variable references that link child items to parent items. The table also stores fulfillment system IDs, default quantities, and BOM item effective dates for the fulfillment BOM.

In Oracle CPQ Release 18C, a ModelPath column is also available in the BOM Item Definition table. This is an optional column that allows administrators to define the path to a model for a BOM item. The model at the path specified is added to the BOM hierarchy, allowing users to configure or reconfigure the model from the system navigation panel. When entering a value in the ModelPath column, administrators must use the following format: productFamilyVariableName:productLineVariableName:modelVariableName.

Complete the following steps to enable system configuration initialization.

1. Navigate to the Configuration Options page.

   Admin Home > Products > Configuration Settings

2. Set the Number of descendant models to initialize.

3. Set the Depth of descendant models to initialize.

   

4. Click Update to save your changes and return to the previous page.

Complete the following steps to initialize rules for child models during system configuration initialization.

1. Navigate to the Admin Home Page.

2. Click Configuration Settings in the Products section.

3. Set the Enable cascading configuration of newly added descendant models option to Yes.

4. If applicable, set the Total number of descendant models to configure value. *default value is 20

5. If applicable, set the Limit number of cascaded descendant models (depth) value. *default value is 6

6. Click Apply or Update.

Oracle CPQ 19C introduces the new System Configuration Model Path (_system_config_model_path) system attribute to return a JSON path with the exact location of the current model in the system. "_system_config_model_path" returns a path that includes all of the current model's parent models and the array index associated with the current model.

The indices provided in the JSON path system attribute leverage the absolute position of the elements. They describe the BOM hierarchy path to get to the current model. Even though system configuration model paths are only returned for models, all BOM items (i.e. models and parts) get their own index in the list of children at each level of the hierarchy. The following example shows the system configuration model paths for a basic system configuration.

Administrators can use "_system_config_model_path" in inter-model rules to retrieve a path that includes all of the current model's parent models and the array index associated with the current model. For example, a customer wants to retrieve the "color" attribute value from its direct parent model. The following code sample uses "_system_config_model_path" to retrieve the path for the parent model.

parentPath = stringbuilder();
pathElementSeparator = ".";
pathElementArray = split(_system_config_model_path, pathElementSeparator);
pathElementArraySize = sizeofarray(pathElementArray);
pathElementIndex = 1;
for pathElement in pathElementArray {
  if (pathElementIndex < pathElementArraySize) {
    sbappend(parentPath, pathElement, pathElementSeparator);
  }
  pathElementIndex = pathElementIndex + 1;
}
sbappend(parentPath, "configAttributes", pathElementSeparator, "color");
parentAttrVals = string[];
parentAttrVals = getsystemattrvalues(parentPath);
return parentAttrVals[0];

The default system navigation panel elements can be customized using a CSS file. The root item model has a unique class. The status icons are not applied to the root model. The child models are represented by four different classes to indicate the status of the model configuration. When warnings or errors exist, the applicable class is applied to the relevant model. If desired, administrators can use an alternate CSS file to customize the system navigation panel styles and assign different styles or icons for the specific warning or error classes.

The following table shows the default icons and identifies the CSS class names for the status, warning, and error classes.

A new system attribute is available in Release 18D for use in all Configuration rules to facilitate punch in to Oracle CPQ for ABO and System Configuration operations. The system attribute "_config_upgrade_name" is supported as a Simple Condition in a Configuration rule or as an Advanced Condition in a Configuration rule, where an action references the system attribute. For example: Administrators can use the "_config_upgrade_name" system attribute in a "Bulk Table Lookup" recommendation rule condition. When users punch-in to the Model Configuration page, the URL parameter populates the value of "_config_upgrade_name" across all models in a system.

Administrators can use Advanced Conditions and the new BML functions to retrieve System Configuration attribute values from other configured system models. They can set the configuration flow and build rules to constrain, hide, recommend, and price sub model values.

Cross-model Constraint Rules

Cross-model Hiding Rules

Cross-model Recommendation Rules

Cross-model Recommended Item Rules

Cross-model Pricing Rules

Cross-model Configuration Flows

Customers can use BML to select attributes from other product families. Advanced rule attributes from the "System Configuration" folder are always an Array of the type of the referenced attribute. Since the specified path can contain multiple models, the value for the each model is placed in a different index in the provided array. No assumptions should be made about the index at which a specific model's attribute value will be found. If the referenced attribute is an array, each model's attribute value will be a delimited collection of all of the array values for that attribute.

For example: the customer has a system with a Package Bundle as the system root. Under the root level, there are three child systems: internet, cable, and telephone. The cable system contains a premium channels model. The following image displays the BML code to capture the value of "premiumSelection" under premium channels. In this example, "selectedChannels" contains the value of the attribute.

The getSystemMultipleAttrValues BML function can also be used to return dictionary key and value string arrays containing attribute values from a system configuration.

In Oracle CPQ Release 18D, customers can use System Configuration in conjunction with the ABO and Oracle CX Commerce integrations. The 18D ABO Implementation Package provides support for system assets, allowing customers to use ABO flows on System Configuration models in Oracle CX Commerce order scenarios.

For example: Oracle CX Commerce self-service users can securely access the Model Configuration page via an iFrame that displays within Oracle CX Commerce. They can then use the system navigation panel to choose a system model or child model to configure or reconfigure. Using the Add to Cart action, the Oracle CX Commerce shopping cart is then updated.

Add System Data to Integration Action BML

Request for Quote Flow