Configuration BOM Mapping Rules

Configuration BOM Item Mapping

BOM item mapping associates BOM items to Configuration attributes. During Configuration, whenever the configuration state is changed, the Configuration BOM Mapping Rules are invoked to map Configuration attributes to BOM items. The following image illustrates BOM item and Configuration attribute associations. For Example: When the "areYouLookingForALaptopOrDesktop" Configuration attribute is "Laptop", the root BOM item with the Variable Name "LP94777" is created.

At the next child level, if the "processor" configuration attribute is "INTEL", the child BOM item "LAPPRO1101" is created. If it is "AMD", the child BOM item "LAPPRO1109" is created. The child BOM item is created under the root BOM item. Their hierarchical relationship is defined in the BOM Item Definition table. A child BOM item is created only if its parent BOM item is created.

For more information about BOM item instances, refer to the BOM Instances section. The BOM Item Definition provides the default quantity in the BOM instance. The definition node also comes from BOM Item Definition.

Items in the BOM instance, created by BOM item mapping, must exist in the BOM Item Definition. The hierarchy of BOM item mapping is entirely based on the BOM Item Definition. As a result, a child BOM item is generated only if its parent BOM item is included.

Reconfiguration BOM Item Mapping

During reconfiguration, the Launch Configuration attributes are mapped from the BOM item instance. Refer to the JSON Representation of a BOM Item image for the following example. If “LP94777” is the BOM instance root BOM item, when the Configuration session is launched, the "areYouLookingForALaptopOrDesktop” Configuration attribute is set to "Laptop". Similarly, if the child BOM item "LAPPRO1109" exists, the "processor" Configuration attribute is set to "AMD".

If the BOM Mapping rule values conflict with sales side data, Configuration rules attempt to set the same Configuration attribute with different values. If the attribute is not a Multi Select Menu, a runtime error occurs.

It is considered a match when the sales side Configuration attribute value is "equal", or "the same as" the mapped value. However, if the Configuration attribute is a Multi Select Menu, the comparison operator is inclusively "contains". In other words, as long as the Multi Select Menu attribute contains the value required by the rule, it is considered a match.

The table-based reverse mapping sets the Configuration attributes based on which BOM items and BOM attributes exist in the BOM instance. It does not attempt to modify the Configuration attributes based on which BOM items or BOM attributes are absent in the BOM instance. Refer the "LAPPRO1109" BOM item example above for the following description. If the BOM instance contains "LAPPRO1109", the "processor" Configuration attribute is set to "AMD" accordingly. If the BOM instance does not contain "LAPPRO1109", the table-based reverse mapping does not attempt to set the "processor" attribute, even if it happens to be "AMD". If the "processor" attribute must be set to a specific value when "LAPPRO1109" is not present, advanced BML can be used to set the value, refer to From BOM Launch Configurations for more information.

When a Commerce Model line that contains a captured Sales BOM is reconfigured, mapping from BOM to Launch Configuration invokes the following actions:

1. The Configuration is restored to the values saved on the Model line
2. The Sales BOM items are validated against the current BOM Item Definition. Invalid items are removed.
3. If Table-based BOM Mapping rules exist, they are invoked first, to map the BOM instance values to the Configuration attributes.
4. If "From BOM to Configuration” advanced BML-based BOM mapping rules that are defined, they are invoked next, using the defined order.

Special attention should be paid to selector configuration attributes. If the selector (search input) value needs to be overridden via BOM Mapping, the Configuration attribute must be set to auto-locked. This is consistent with the current Configuration behavior: the selector recommended value is preferred, unless the attribute is auto-locked during reconfiguration. The auto-lock must be defined in the attribute, instead of being dynamically set by a Recommendation rule.

Similar to BOM item mapping, the BOM attribute mapping is also bidirectional. From Configuration to BOM, the target values are set based on the source types and values. From BOM to Launch Configuration, the initial Configuration attribute values are set from source to target.

BOM attribute mapping is used to set a BOM attribute, the quantity of the BOM item, or a Commerce line attribute. Under each BOM item, administrators can define many BOM attributes using attribute mapping.

Conflicting end values occur if multiple BOM attribute mappings attempt to set the same attribute to different values. Similar results can occur From BOM to Launch Configuration, if Configuration rules attempt to set the same Configuration attribute with different values. These events will generate runtime errors.

The BOM Attribute Mapping table identifies the attribute Target and Source. In the following JSON sample, the “attributes” node stores BOM attribute Target Types, and the “fields” node stores Line attribute Target Types.

{
   "partNumber": "BP3025",
   "quantity": 1,
   "variableName": "BP3025",
   "definition":         {
      "SequenceNum": 2020,
      "ItemId": "3025",
      "ItemType": "Standard Item",
      "Optional": "N"
   },
   "attributes":         {
      "BSO3901": {"value": "H~V"},
      "BSN3095": {"value": ""}
   },
   "fields" : {
       "lineActionCode", "Add"
   },
   "explodedQuantity": 1,
   "children": []
 }

During Configuration, BOM Mapping rules are invoked when changes to Configuration attribute values are saved. BOM Mapping rules run after Recommendation rules, but before Recommended Item rules. If the Configuration contains multiple nodes, BOM Mapping rules are only run in the last node, similar to Recommended Item rules.

BOM Mapping rules are invoked as follows:

• Simple Table-based BOM Mapping rules – During set up, a Configuration Model can be associated with different BOMs using multiple BOM Mapping rules. However, on the sales side, only one Table-based BOM Mapping rule should apply. In other words, a given Configuration state on the sales side can only be associated with one Sales BOM.
• Advanced BML-based BOM Mapping rules – BML-based rules are actuated in order, if they are defined. This allows administrators to revise the BOM instance using BML scripts. The BML revised result is an updated JSON BOM instance, which must conform the BOM Item Definition.

During Configuration, administrators can reference the current BOM instance by using the system Configuration attribute _bm_bom_instance. If the BOM instance is not null, it can be viewed in the Pipeline Viewer. The Pipeline Viewer displays which Configuration attributes and BOM Mapping rules were used to create the BOM instance.

If the BOM instance is not null, pricing of the BOM parts occurs. If the price is not zero, it is displayed in the Configuration Pricing section.

By default, BOM Mapping is executed at the current time. When the BOM is stored into a quote, the effective date of the BOM Mapping can be set on the line attribute “Line BOM Effective Date” field of the root BOM item line, (i.e. the Model line). This effective date is honored when:

• A Sales BOM that is extracted from a quote is validated
• A BOM instance is reconfigured

In the latter case, the effective date only applies to Configuration BOM Mapping Rules. Other Configuration rules do not honor the BOM Mapping effective date.

Beginning in Release 18B, Oracle CPQ provides BOM Mapping support for Single Select Pick Lists, which are also known as Dynamic Menus. When a Single Select Pick List option is selected, the applicable BOM Mapping rules are invoked to add parts to a Transaction based on the Single Select Pick List selection. The Single Select Pick List attribute type can be created in Configuration for Text, Integer, and Float data types.

Beginning in Release 18B, Oracle CPQ provides BOM Mapping support for Configurable Array Attributes. The options selected during Configuration can be used to populate BOM items and attributes in the BOM instance.

BOM Item Mapping for Configurable Array Attributes

When Configurable array attributes are used with BOM Item Mapping, the Array Set row items are mapped to a matching BOM item. The mapping should be one-to-one between the Array Set row and a BOM item.

For example: In the following BOM Item Mapping Data Table there are two BOM items displayed under the "SoftwareRootBOM" item:

• AntiVirusItem - Part Number "antiVirusPart", ConfigAttrVarName "softwareType", and ConfigAttrValue "Enterprise Anti-Virus"
• EncryptionItem - Part Number "encryptionPart", ConfigAttrVarName "softwareType", and ConfigAttrValue "EncryptionSoftware"

Customers can use Configurable Array Sets to define BOM items to be selected during Configuration.

For example: The following image displays an Application Software Configuration item with three items: "Enterprise Anti-Virus", "Encryption Software", and "Encryption Software".

When these BOM items are selected during Configuration, the following BOM Instance is generated:

{
  "variableName": "SoftwareRootBOM",
  "partNumber": "softwareSelectionPart",
  "quantity": 1,
  "category": "sales",
  "children": [{
      "variableName": "AntiVirusItem",
      "partNumber": "antiVirusPart",
      "quantity": 1
    }, {
      "variableName": "EncryptionItem",
      "partNumber": " encryptionPart",
      "quantity": 1
    }, {
      "variableName": "EncryptionItem",
      "partNumber": "encryptionPart",
      "quantity": 1
    }]
 }

BOM Attribute Mapping for Configurable Array Attributes

When Configurable Array Attributes are used with BOM Item Mapping, related BOM Attribute Mappings can use additional Configurable Array Attributes from the same array set. The additional Configurable Array Attributes for a BOM item are mapped to Attribute Mapping items.

For example: In the following BOM Attribute Mapping Data Table, two Configurable Attributes are displayed:

• supportType - TargetType "BOM_ATTRIBUTE", TargetVariableName "Support", and SourceType "CONFIG_ATTRIBUTE".
• softwareQuantity - TargetType "QUANTITY" and SourceType "CONFIG_ATTRIBUTE".

Customers can also use Configurable Array Sets to define BOM item attributes to be selected during Configuration.

For example: The following image displays an Application Software Configuration with three items:

• "Enterprise Anti-Virus" with "Gold" support and quantity "2"
• "Encryption Software" with "Silver" support and quantity "1"
• "Encryption Software" with "Platinum" support and quantity "3"

When these BOM items and attributes are selected during Configuration, the following BOM Instance is generated:

{
  "variableName": "SoftwareRootBOM",
  "partNumber": "softwareSelectionPart",  
  "quantity": 1,
  "category": "sales",
  "children": [{
      " variableName": "AntiVirusItem",
      "partNumber": "antiVirusPart",
      "quantity": 2,
      "attributes": {"Support": {value: "Gold"}}
    }, {
      " variableName": "EncryptionItem",
      "partNumber": " encryptionPart",
      "quantity": 1,
      "attributes": {"Support": {value: "Silver"}}
    }, {
      " variableName": "EncryptionItem",
      "partNumber": " encryptionPart",
      "quantity": 3,
      "attributes": {"Support": {value: "Platinum"}}
    }]
 }

Reconfiguration of Configurable Array Attributes

During reconfiguration, the array set is initialized to be consistent with the BOM items in the quote. For example: If a quote contains a single BOM item that maps to the array set, the size of the array set is set to one.

A more complicated use case occurs when some of the array-set attribute domain values are not mapped to BOM items. In the case, during reconfiguration the unmapped records are left unmodified. For example:

• A Configuration array set "Dessert" is defined, with an attribute called "DessertType" with three options: Coffee, Ice cream and Cake. "Ice-cream" is mapped to BOM item "BOMIcecream", "Cake" is mapped to BOM item "BOMCake", but "Coffee" is not mapped.
• On the sales side, there are only two rows in the "Dessert" menu, one is "Coffee", and the other is "Cake".
• When a user selects “Cake” during Configuration, a Sales BOM is created, containing a BOM item "BOMCake".
• When the BOM instance is saved to a quote, there is a part line corresponding to "BOMCake".
• When the quote is reconfigured, the "BOMCake" part line is replaced by "BOMIcecream".
• During reconfiguration, the BOM mapping from BOM to Launch Configuration replaces the "Cake" in the "Dessert" array set with "Ice cream", but leaves "Coffee" is unchanged, as Coffee is never involved in the BOM mapping.

Administrators create Configuration BOM Mapping rules at the Model level. BOM Mapping rules associate Configuration attributes to the BOM items. Use simple Table-Based Rules, advanced BML-Based Rules, or both for BOM Mapping.

Perform the following steps to create a Configuration BOM Mapping rule.

1. Navigate to the Model Administration List page.

   Admin > Catalog Definition > Product Families > Product Lines > Models

2. Select BOM Mapping from the Navigation drop-down menu, and click List.

   

3. Click Add to set up a new BOM Mapping Configuration rule.

   

4. Continue to one of the following procedures:

Define Simple Table-Based BOM Mapping Rules

Define Advanced BML-Based BOM Mapping Rules

//--------------------------------------------------------------
// Sample BML from Configuration to BOM
//
// Double the quantities of the direct child BOM items of the root BOM
/
// Input Attributes:
//    _bm_bom_instance: the BOM item instance in JSON
//
// Output:
//    The BOM item instance in JSON
//-------------------------------------------------------------
 
// Get the first level child BOM items
size = 0;
children = jsonget(_bm_bom_instance, "children", "jsonarray");
if (isnull(children) == false) {
    size = jsonarraysize(children);
}
 
// Loop through child BOM items.
// No-op if the children is empty or does not exist.
indices = range(size);
for index in indices {
    bomItem = jsonarrayget(children, index, "json");
    qty = jsonget(bomItem, "quantity", "integer");
    jsonput(bomItem, qty * 2);
}
 
return _bm_bom_instance;

// Sample code snippet to add a child BOM item to the root
tb1 = json();
jsonput(tb1, "variableName", "TB1");
jsonput(tb1, "partNumber", "40mb_100gb");
jsonput(tb1, "quantity", 3);
 
// Get the "children" node by reference.
// Subsequent changes to "children" directly update _bm_bom_instance
children = jsonget(_bm_bom_instance, "children", "jsonarray");
if (isnull(children)) {
    jsonput(_bm_bom_instance, "children", jsonarray());
    children = jsonget(_bm_bom_instance, "children", "jsonarray");
}
 
// Append the child BOM item.
jsonarrayappend(children, tb1);

{
  "partNumber": "telecom_package",
  "quantity": 2,
  "isModel": false,
  "explodedQuantity": 2,
  "category": "sales",
  "variableName": "TBRoot",
  "children": [  {
    "partNumber": "40mb_100gb",
    "quantity": 3,
    "isModel": false,
    "explodedQuantity": 6,
    "variableName": "TB1"
  }]
}

//--------------------------------------------------------------
// Sample BML from Configuration to BOM
// Create the root BOM from scratch when there are no table-based BOM mapping rules
//
// Input Attributes:
//    _bm_bom_instance: the BOM item instance in JSON. It starts as a skeleton as
//        {"category": "sales", "isModel": false},
//        without the part number or variable name.
// Output:
//    The BOM item instance in JSON
//-------------------------------------------------------------

// The following three fields are mandatory fields to create a BOM item
jsonput(_bm_bom_instance, "variableName", "TBRoot");
jsonput(_bm_bom_instance, "partNumber", "telecom_package");
jsonput(_bm_bom_instance, "quantity", 1);
return _bm_bom_instance;

{
   "partNumber": "telecom_package",
   "quantity": 2,
   "isModel": false,
   "explodedQuantity": 2,
   "category": "sales",
}

//--------------------------------------------------------------
// Sample BML from Configuration to BOM
// Remove the last child BOM item.
//
// Input Attributes:
//    _bm_bom_instance: the BOM item instance in JSON
//
// Output:
//    The BOM item instance in JSON
//------------------------------------------------------------- 
size = 0;
children = jsonget(_bm_bom_instance, "children", "jsonarray");
if (isnull(children) == false) {
    size = jsonarraysize(children);
}
if (size > 0) {
    jsonarrayremove(children, size - 1);
} 
return _bm_bom_instance;

//--------------------------------------------------------------
// Sample BML from Configuration to BOM
// Remove empty optional class items.
// An empty optional class item is as such:
//     - Its "definition" contains Itemtype == 'CLASS'.
//     - Its "children" is empty
//
// Input Attributes:
//    _bm_bom_instance: the BOM item instance in JSON
//
// Output:
//    The BOM item instance in JSON
//-------------------------------------------------------------   
jsonpathremove(_bm_bom_instance, "$..children[?(@.definition.ItemType=='CLASS' && @.children.length()==0)]");   
return _bm_bom_instance;

//--------------------------------------------------------------
// Sample BML from Configuration to BOM
// Set the membership card type based on the customer rating
//   If 70 <= customerRating, set cardType = Platinum
//   If 30 <= customerRating < 70, set cardType = Gold
//   else set cardType = Silver
//
// Input Attributes:
//    _bm_bom_instance: the BOM item instance in JSON
//    customerRating: an integer from 0 to 100.
//
// Output:
//    The BOM item instance in JSON
//-------------------------------------------------------------    
// Locate the membership card BOM item
membershipCard =jsonpathgetsingle(_bm_bom_instance, "$..children[?(@.variableName == 'MembershipCard')]", "json"); 
if (isnull(membershipCard) == false) {
// Create cardType BOM attribute
    cardTypeValue = "Silver";
    if (70 <= customerRating) {
       cardTypeValue = "Platinum";
    } elif ((30 <= customerRating) AND (customerRating < 70)) {
        cardTypeValue = "Gold";
    }
    cardType = json();
    jsonput(cardType, "label", "Membership Card Type");
    jsonput(cardType, "value", cardTypeValue);       
    // Attach the cardType BOM attribute
    attributes = jsonget(membershipCard, "attributes", "json");
    if (isnull(attributes)) {
        jsonput(membershipCard, "attributes", json());
        attributes = jsonget(membershipCard, "attributes", "json");
    }
    jsonput(attributes, "cardType", cardType);
}  
return _bm_bom_instance;

//---------------------------------------------------------------
// Sample BML from Configuration to BOM
// Create BOM items based-on configurable array attributes
//
// Input Attributes:
//    _bm_bom_instance:    the BOM item instance in JSON
//    softwareArraySize:   int
//    softwareType:        string[]
//    softwareQuantity:    integer[]
//    softwareSupport:     string[] 
//
// Output:
//    The BOM item instance in JSON
//-------------------------------------------------------------

// Set up the root BOM item
jsonput(_bm_bom_instance, "variableName", "SoftwareRootBOM");
jsonput(_bm_bom_instance, "partNumber", "softwareSelectionPart");
jsonput(_bm_bom_instance, "quantity", 1);

// Set up children
children = jsonarray();
indices = range(softwareArraySize);
for index in indices {
   software = softwareType[index];
   variableName = "";
   partNumber = "";
   if (software == "Enterprise Anti-Virus") {
      variableName = "AntiVirusItem";
      partNumber = "antiVirusPart";
   } elif (software == "Enterprise Anti-Spam") {
      variableName = "AntiSpamItem";
      partNumber = "antiSpamPart";
   } else {
     continue;
   } 
   // Create the child BOM item
   item = json();
   jsonput(item, "variableName", variableName);
   jsonput(item, "partNumber", partNumber);
   jsonput(item, "quantity", softwareQuantity[index]);    
   
   //Add BOM attributes
   attributes = json();
   attr = json();
   jsonput(attr, "value", supportType[index]);
   jsonput(attributes, "Support", attr);
   jsonput(item, "attributes", attributes);
   jsonarrayappend(children, item);
} 
jsonput(_bm_bom_instance, "children", children);
return _bm_bom_instance;

// No operations are performed if the BML is invoked for a manufacturing BOM.
// This check is only required when getbom is used to extract the manufacturing BOM
category = jsonget(_bm_bom_instance, "category"); //"sales" or "manufacturing"
if (category == "manufacturing") {
    return _bm_bom_instance;
}

{"<configuration variable name>":"<value>", etc.}

//--------------------------------------------------------------
// Sample BML from BOM to Launch Configuration
//
// Set the membership card type based on the customer rating if the current customer 
// rating is inconsistent with the card type
//  If cardType == Platinum and customerRating < 70, set customerRating = 85
//  If cardType == Gold and customerRating not in [30,70), set customerRating = 50
//  If cardType == Silver and customerRating not in [0, 30), set customerRating = 15
//
// Input Attributes:
//   _bm_bom_instance: the BOM item instance in json
//   customerRating: an integer from 0 to 100.
//
// Output:
// attributeOverrides, json as a name-value pair to set configuration attribute values
//-------------------------------------------------------------- 
attributeOverrides = json();  
if(isnull(_bm_bom_instance) == false){      
   cardTypeValue = jsonpathgetsingle(_bm_bom_instance, "$..children[?(@.variableName == 'MembershipCard')].attributes.cardType.value");
   if ((cardTypeValue == "Platinum") AND (customerRating < 70)) {
      jsonput(attributeOverrides, "customerRating", 85);
   } elif (cardTypeValue == "Gold" AND (customerRating < 30 OR customerRating >= 70)) {
      jsonput(attributeOverrides, "customerRating", 50);
   } elif (cardTypeValue == "Silver" AND customerRating > 30) {
      jsonput(attributeOverrides, "customerRating", 15);
   }
}
return attributeOverrides;

//--------------------------------------------------------------
// Sample BML from BOM to Launch Configuration
// This example sets software array sets based on the enterprise software BOM items.
//
// Input Attributes:
//    _bm_bom_instance: the BOM item instance in JSON
//
// Output:
// attrOverrides, json as a name-value pair to set configuration attribute values
//--------------------------------------------------------------
attrOverrides = json(); 
// _bm_bom_instance might be null. It is prudent to check.
if(isnull(_bm_bom_instance)) {
   return attrOverrides;
}
size = 0;
children = jsonget(_bm_bom_instance, "children", "jsonarray");
if (isnull(children) == false) {
    size = jsonarraysize(children);
}
softwareTypes = jsonarray();
softwareQuantities = jsonarray();
softwareSupports = jsonarray(); 
// Loop through "children". No operations are performed if children do not exist 
// or are empty.
indices = range(size);
for index in indices {
   item = jsonarrayget(children, index, "json");
   software = "";
   variableName = jsonget (item, "variableName");
   if (variableName == "AntiVirusItem") {
       software = "Enterprise Anti-Virus";
   } elif (variableName == "AntiSpamItem") {
       software = "Enterprise Anti-Spam";
   } else {
       continue;
   } 
   quantity = jsonget(item, "quantity", "integer");
   support  = jsonpathgetsingle(item, "$.attributes.Support.value");
   jsonarrayappend(softwareTypes, software);
   jsonarrayappend(softwareQuantities, quantity);
   jsonarrayappend(softwareSupports, support);
}
jsonput(attrOverrides, "softwareType", softwareTypes);
jsonput(attrOverrides, "softwareQuantity", softwareQuantities);
jsonput(attrOverrides, "softwareSupport", softwareSupports); 
// set the correct size for the array set
jsonput(attrOverrides, "softwareSize", jsonarraysize(softwareTypes));
return attrOverrides;

BOM Item Definition Tree References

The BOM Item Definition is hierarchical. The “BomItemDef.ParentVariableName” recursively points to its parent “BomItemDef's VariableName”. The BOM Item Definition hierarchy, along with its BOM Attribute Definition children, and BOM Attribute Translation grandchildren forms a BOM item definition tree.

To ease queries and migration, all BOM definition entities must include the root BOM Item Definition Variable Name:

• BomItemDef.RootVariableName

• BomAttributeDef.RootBomItemVarName

• BomAttributeTranslation.RootBomItemVarName

BOM Item Mapping Tree References

The BOM Item Map and its children BOM Attribute Maps form a BOM Item Mapping Tree, based on the BOM Item Tree. A BOM Mapping Configuration rule should only reference a single BOM Item Mapping Tree.

To ease queries and migration, all BOM Mapping entities must include the BOM Mapping rule location “productFamilyVarName:productLineVarName:modelVarName:configRuleVarName”, in the following Data Table columns:

• BomItemMap.ParenBomMapVarName

• BomAttrMap.RootBomMapVarName

In the rare case where two Configuration Models use the same BOM item mappings, as defined in the Data Tables, the wildcard rule location can be used, in the format of *:configRuleVarName. Exact BOM Mapping rule locations have a higher precedent over wildcard rule locations. A BOM Mapping Configuration rule attempts to load its BOM Item Mapping Tree that uses an exact rule location first. If there are no BOM Item Mapping Data Table records matching the exact rule location, will the BOM Mapping Configuration rule attempt to load a BOM Item Mapping Tree that uses a wildcard rule location. This means that a BOM Mapping Configuration rule loads its BOM Item Mapping Tree using either the exact rule location or the wildcard rule location, but it never loads both locations.

The following restrictions on configurable array attribute mapping are enforced, primarily to maintain one-to-one mapping between a row in the array set and a BOM item.