BOM Instance

Overview

A Configuration BOM instance is represented by a JSON object. This BOM instance is referenced during reconfiguration and is used to generate Sales BOMs and Manufacturing BOMs, which can be sent to a back-end system for order fulfillment.

Sales and Manufacturing BOMs

BOM items can be classified as sales items, manufacturing items or both. These items are defined in the BOM Item Definition table.

Oracle CPQ uses sales items to create a BOM instance during Configuration, sales items are used for quotes, and the BOM instance used during reconfiguration contains sales items. In other words, only sales items are used inside CPQ.

Note: Sales Items and Manufacturing Items must have corresponding Part Numbers defined in the Oracle CPQ Parts Database.
Manufacturing items are only used when Oracle CPQ submits a Manufacturing BOM to a back-end Fulfillment system. Administrators use the BML getbom function to create a Manufacturing BOM from the saved Configuration in a quote.

Capture a BOM Instance in Commerce Transactions

The BOM instance is stored in a quote when the end user saves the Configuration to a quote.

Structure

The root BOM item is equivalent to a Model line, and it will be processed as Model line within CPQ. Model lines do not use part fields; therefore, the root BOM item Part Number is stored in the “Line BOM Part Number” field. The other part fields of the root BOM item are not saved into the Model line. As a result, part-based pricing is not executed on the root BOM item. Customers should not define part pricing for the root BOM item.

All child BOM items are stored as child Part lines of the Model line. All child and grandchild BOM items are stored as the direct children of the Model line. Hierarchical relationships are stored the “Parent Line Item BOM ID” field.

When a BOM tree is saved into a quote, the item Variable Names are not stored. During reconfiguration, the getBOM BML function performs the following actions:

Extracts the Sales BOM from the saved BOM instance
Validates items against the current BOM Item Definition
Resolves the BOM item Variable Names

Oracle CPQ uses the following system fields to capture a BOM instance into a quote:

Name	Variable Name	Type	Description / Notes
Line Item BOM ID	_line_bom_id	Text	The BOM item instance id.
Line Item BOM ID	_line_bom_id	Text	When ABO is enabled, this field is used to store the asset key.
Parent Line Item BOM ID	_line_bom_parent_id	Text	The parent BOM item instance id.
Part Number	_part_number	Text	The part number of the BOM item
Part Number	_part_number	Text	Used for child BOM items, not applicable to root BOM items.
Line BOM Part Number	_line_bom_part_number	Text	The part number of the root BOM item.
Line BOM Part Number	_line_bom_part_number	Text	Stores the root BOM Item Part Number in the Model line. Applicable to the root BOM item only.
Line Item BOM Attributes	_line_bom_attributes	Text Area	BOM attributes, stored as a JSON string.
Line Item BOM Attributes	_line_bom_attributes	Text Area	Refer to BOM Attributes for the format of the JSON object.
Quantity	_price_quantity	Integer	Quantity of the line item.
Quantity	_price_quantity	Integer	The exploded line quantity. This item is part of the "Price Attributes" attribute set.
Line BOM Item Quantity	_line_bom_item_quantity	Integer	The BOM item line quantity. This is the unexploded line quantity, whereas _price_quantity stores the exploded quantity.
Line BOM Item Quantity	_line_bom_item_quantity	Integer	BOM Item line quantity. This is the unexploded line quantity. The _price_quantity stores the exploded, effective quantity of the line.
Line BOM Level	_line_bom_level	Integer	The BOM item depth (level) in the quote.
Line BOM Level	_line_bom_level	Integer	Add a new system attribute _line_bom_level, of integer type. The value is "0" for the root BOM item, i.e. the Model line. The value is "1" for first level child BOM items The value is "2" for second level child BOM items, etc. The value is empty for non-BOM quote lines The value is "0" for BOM and non-BOM items when the Commerce setting "Enable Subscription Ordering for Simple Products" is set to "Yes"
Line BOM Effective Date	_line_bom_effective_date	Date	BOM Effective Date. If null, the current time is used.
Line BOM Effective Date	_line_bom_effective_date	Date	Stores the system attribute in the Model line Effective Date to enforce date effectivity in all BOM mappings. Enforces date effectivity data in the BOM Item Definition and BOM Item Mapping Data Tables. Enforced at runtime for Model to BOM, Get BOM from quote, and BOM to Configuration.
Is Line Item Mandatory?	_is_line_item_mandatory	Boolean	Used to identify if the line item is a mandatory part.
Is Line Item Mandatory?	_is_line_item_mandatory	Boolean	True if the BOM item is not optional. The default logic can be overridden by BOM attribute mapping.

Quantity

BOM Mapping makes it possible to set the Model line “Quantity" to numbers greater than one, by using “Quantity” and “Line BOM Item Quantity” fields. The child “Line BOM Item Quantity” value is multiplied by the parent “Quantity” value, and the sum is stored in the child “Price Quantity” field.

Quantity - the effective or exploded quantity, i.e. multiplied by the parent Quantity.
This field is used to calculate pricing.
Line BOM Item Quantity - the BOM item quantity before explosion.

For example: If the BOM Model line “Line BOM Item Quantity” is 2, and the child line “Line BOM Item Quantity” is 3; the BOM Model line “Quantity” will be 2, and the child line “Price Quantity” will be 6 (3*2).

Model Quantity and Pricing

Since the Model line quantity can be more than one, the total price of the quote uses this quantity when calculating the Model line subtotal. This is different from the standard Configuration total price, where the unit price assumes the Model quantity is one.

Save a BOM Instance to a Quote

When the Configuration is saved to a quote, the BOM instance is saved as item lines in the quote. Before the BOM instance is saved to a quote, any defined BOM attributes and BOM attribute translations are added to the BOM instance.

If a BOM item instance contains a "fields" node, it is used to populate the Commerce line attribute. BOM attribute mapping creates a "fields" node when an attribute Target is Line Attribute. Administrators can also use advanced BML-based rules to populate Commerce lines.

When quote line items are initially created, defined line attribute default values take precedence over BOM Mapping attempts to set the line attribute. This is consistent with the current Commerce behavior.

The Configuration date attribute does not have a “time” component. If a Configuration date attribute is mapped to a Commerce date attribute that includes time, the time portion of the Configuration date attribute is set to 00:00 AM on the date in the default time zone, set up on the Oracle CPQ server.

BML Functions to Extract Sales and Manufacturing BOMs

When a Sales BOM is extracted from a quote, the return result is based on the root BOM line (i.e. the root Model line) as its children BOM part lines. If the "validateBomModel" flag is true, the last saved BOM instance is validated, and normalized, against the latest BOM item definition.

When a Manufacturing BOM is extracted from a quote, it starts with the saved configuration state on the model line, and executes a BOM mapping from configuration to BOM. The execution fires both the table-based BOM mapping, as well as advance BML mapping. Table-based mapping automatically generates a Manufacturing BOM, based on the BOM item mappings and the BOM item definitions. The BML-based BOM mapping, if defined, is more complicated. The same BML-based BOM mapping rules are invoked to create both a Sales BOM and Manufacturing BOM. Inside the BML script, administrators indicate whether the BML-based rule creates a Sales BOM or a Manufacturing BOM using the "category" field of the input _bm_bom_instance. If the category is "manufacturing", the BML script is invoked to create a Manufacturing BOM.

Administration

BOM Item JSON Object and Examples

BOM Item JSON Object

The following table describes BOM Item fields in the JSON object.

Field	Data Type	Required	Description
id	String	N	The instance id of the BOM item.
variableName	String	N	The variable name of the BOM Item Definition. Required when BML-based rules are used to create the BOM instance during Configuration.
category	String	N	Legal values: sales, manufacturing. Designates if a BOM is a Sales BOM or a Manufacturing BOM. Applicable to the root BOM item only.
effectiveDate	String	N	The effective date. In ISO format `yyyy-MM-ddTHH:mm:ssZ`. Applicable to the root BOM item only.
parentId	String	N	The parent BOM item instance id. The field is not defined unless children items are flattened.
partNumber	String	Y	The Part Number of the item. A sales item exists in the Oracle CPQ Parts Database and the back-end fulfillment system with the same Part Number. A manufacturing item only exists in the back-end fulfillment system; it is not required in the Oracle CPQ Parts Database.
quantity	Long	Y	The line item quantity
isModel	Boolean	N	Specifies if the BOM item is a model item. Used in the output BOM item instance for system configuration. The flag does not need to be explicitly set in BOM mapping BML.
explodedQuantity	Long	N	The exploded line quantity
children	Array	N	The child BOM items. A JSON array of BOM items.
attributes	Object	N	A JSON object that stores the BOM attributes. The format is defined in the BOM Attributes section.
definition	Object	N	Additional BOM Item Definition items required when submitting BOMs to back-end fulfillment systems, including `SequenceNum`, `ItemId`, `ItemType`, `Optional`, and `IncludedInBasePrice`. The node is populated in the output BOM instance for BOM item mapping and the `getBOM` BML function when either `validateBomModel` is true or `isSalesBom` is false. Do not explicitly populate this node in the BOM mapping BML.
fields	Object	N	Optional fields for ABO. The JSON object stores fields as key-value pairs. If a BOM is saved to a quote, the fields are mapped to line attributes. Field names must be line attribute variable names.

BOM Item Attribute JSON Object

The attributes of BOM items are represented by a single JSON object. Commerce sub document lines also use this format to store the BOM attributes in the line attribute (_line_bom_attributes).

The field name is the BOM attribute Variable Name. The following table defines the BOM attribute values

Field	Data Type	Required	Description
value	String Integer Number Boolean Date null	N	If the data type is String, the value is in the site base language. If the data type is Date, the value is stored in the JSON object as a as a String using the ISO date time format `yyyy-MM-ddTHH:mm:ss`Z.
displayValue	String	N	The display value of the attribute, in the site base language
label	String	N	Attribute (display) name, in the site base language.
translations	Object	N	A JSON object represents the translation of attributes in the site non-base language. The language code is the field name. `{"de": {"label": xxx, "displayValue": xxx}, "fr":{"label": xxx, "displayValue":xxx}}` Oracle CPQ provides translation of values when the attribute is a menu type and the data type is a String. Other data types are not translated.

BOM Instance JSON Example

The following example displays the JSON object for a sample BOM instance.

{ 
   "id": "7345ABCDE", 
   "variableName": "BM54888-0", 
   "partNumber":  "BM54888", 
   "quantity": 1, 
   "definition": {"SequenceNum": 20, "ItemId": "EBS56321", "ItemType": "Optional Class"},   
   "fields": {"_price_list_price_each": 99.12, "line_action_code":  "Update"},
   //Optional fields injected 
   
    "attributes": { 
        "size": {  //The attribute variable name 
           "value": "L", //The attribute value in the site base language 
           "displayValue": "Large", //The attribute display value in the site base language 
           "label": "Size", //The attribute display name in the site base language 
           "translations": { 
              "de": { "label": "Größe", "displayValue":  "groß" }, 
              "en": { "label":  "Size",  "displayValue":  "Large" }   
            } 
        }, 
   
        "instruction": { 
           "value": "Leave the package at the door.", 
           "label": "Special Instruction", 
           "translations": { 
              "de": {"label": "Spezialanweisung"},
          // Only the label is translated, as the attribute is not a menu type. 
              "en": { "label": "Special Instruction" }  
            } 
        } 
    }, 
   
    "children": [ 
       { 
         "variableName": "BM54888-1", 
         "partNumber": "PT13345"  
         "quantity": 1, 
         "children": [] 
       }, 
   
       { 
         "variableName": "BMDSK781-4", 
         "partNumber": "DSK781-4", 
         "quantity": 1 
       } 
    ] 
}

Note: // is used to add comments in the JSON object for explanation only. JSON does not formally support comments.

Notes

Refer to the BOM Pricing topic for Configurable Price Item examples.