Editing Configuration Attributes in Salesforce CPQ

When integrating with Salesforce CPQ, your configurator price items (in Epicor CPQ) are converted into CPQ line items (in Salesforce) when the configuration is saved.  These price items in Epicor CPQ are created through Pricing Rules. 

Three pricing blocks, and how they create Salesforce CPQ data

Three different Snap blocks available in Epicor CPQ pricing rules help you create the product options you want to see in Salesforce CPQ.

• The "Set Price Object" Snap block is used to set attributes of the top level configurable product in Salesforce CPQ.
• The "Add Price Item" Snap block is used to set attributes on a first-level product option within that product.
• The "Add Price Item as child of" Snap block is used to create a hierarchical set of product options within that product.  

While Epicor CPQ allows unlimited levels of price item hierarchy, only the first 3 levels will be accepted by Salesforce CPQ versions 240 and higher: levels 4 and above will not be passed.  No levels will be accepted by Salesforce versions lower than 240.  To use nested bundles in Salesforce CPQ, ensure the Salesforce CPQ setting "Nested Bundles for External Configurator" is turned on.

Example Snap code in Epicor CPQ

Here in an example configurator named A, the pricing rules inside it create Price Items B, C, D, and D2.

• Note the simple logic to determine if a price item is added: your product logic will likely be more interesting.
• Note that each Snap block that matches a Salesforce product option must have a metadata setting "External ID" set to that product option's unique ID, starting with "a0r".
• Note the Salesforce ID is accepted, but not required, for the "add price item" Snap block.  At this root level, the SKU name is used to match to a Salesforce product option, not the ID.
• In this simple hello-world example, the IDs are hard-coded.  If you have more than just a few matching product options, you'll probably store all these product option IDs in a table and use an option filter or query to gather that table data.  Such a setup would be easier to maintain.

Resulting Epicor CPQ price object with price items

When viewing the Epicor CPQ configurator embedded within the Salesforce interface, your user would see this when they click the "details" button:

While viewing the entries within product A, we see the hierarchical tree built in the Snap rules showing items B, C, D, and D2.

Resulting Salesforce CPQ bundle with product options

Here, in a salesforce quote, we see the product A (from the price object of a configurator) along with the hierarchical options B, C, D, and D2 below it (from the price items within that configurator.)

Two Options for Setting Configuration Attributes in Salesforce CPQ

Each of these pricing Snap blocks can store information that will appear as a configuration attribute in Salesforce CPQ in one of two ways: either as a price column, or as metadata. Which should you use?

• Price columns give consistency. If you have many Epicor CPQ configurators connecting with Salesforce CPQ, you can ensure consistency by using price columns.  Price columns are shared across your entire environment, so you know the spelling and datatype will always be consistent across all configurations.
• Price columns give visibility.  They can be made visible or hidden to different Epicor CPQ users when they view an Epicor CPQ quote.  This can help with troubleshooting or daily tasks.
• Price columns allow easier analysis. By storing information in price columns, it's easier for you to extract and analyze that data from Epicor CPQ. 
• Metadata is easier to set up.  It doesn't rely on any other shared objects. But it cannot be displayed to your users in the CPQ interface.

By using price columns

1. If the price column doesn't already exist, create it with the exact same API name and data type as the Salesforce CPQ configuration attribute.  Remember, the API name usually ends in "__c".   So if the API name of your SFDC configuration attribute is Width__c, then the matching Epicor CPQ price column should have the name Width__c as well.
2. Optionally, change the label of the price column to whatever you want your users to see in Epicor CPQ.  Note that this label is also what is displayed in the Snap block when you write your pricing rules.  For easier debugging, you can leave the label blank.
3. Optionally, choose to show or hide this price column, or set which users can see it.
4. Once you have created a price column, you can set the value of it in your pricing rule.  
   
   
   
   

By using metadata

You can also use the price object metadata to set configuration attributes.  If the metadata name in your Epicor CPQ rule matches the API name of the configuration attribute in Salesforce CPQ, then information flows.  For example, instead of selecting a price column as above, you can type in metadata as below:

Clearing Configuration Attributes in Salesforce CPQ

Configuration attributes in Salesforce CPQ are not automatically cleared on every save of the configurator.  New values set in the configurator will overwrite old values saved previously, but if a configuration attribute was set in a previous save it will stay that way if new values aren't passed to it.

For reliable operation, a best practice is to ensure you not only write data to a price object column or metadata, but also clear that data by writing an empty string.  

To continue the example above, let's say that the user had previously edited her configured product and saved it, so the rules caused the "Width__c" attribute of the Price Object to be set to 5. This caused the Salesforce CPQ configuration attribute called "Width" to be set to 5.  But now, after returning to the configured product and continuing her edits, the user has made changes so that "Width__c" is no longer defined.  Even though that PriceObject attribute is null (not defined) in Epicor CPQ, the old information of "5" is still in Salesforce CPQ, and will remain there until overwritten.

There are two easy ways to follow our best practice of clearing out any old attributes:

If you have...	...then clear attributes with this technique
A manageable number of rules / Price Columns or metadata	Always remember to clear any values you set.  For example, instead of simply setting the "Width__c" field as in this code block: You must add an else clause, so that Width__c is always set to either "5" or "" (the empty string).  Here is the replacement code:
A very large number of rules, or many PriceColumns/metadata	Adding an "else" to every "if" statement you write can be hard to manage and can make your code bulky.  Instead, set them all to the empty string first.  Create a table to store that collection of attributes you want to clear, which makes it easy to manage. Create a new pricing rule. Drag it above all other pricing rules, so it will always run as the first rule. In that rule, query the table using Snap and, for each row returned, use the resulting text as the name of an attribute that you want to clear. Clear it by writing the empty string to it.

How to have Salesforce CPQ configuration attributes write to a custom field on the Quote Line object in Salesforce

While this technique is not specific to Epicor CPQ, it is a common need for the configuration attributes being set to propagate to custom fields in the Salesforce CPQ quote line objects.  To do so, follow these steps:

1. In Salesforce Setup > Create > Object, navigate to the ProductOption object and edit it.  Add a custom field with your chosen name and data type.
   
   
   
   
2. In Salesforce Setup > Create > Object, navigate to the QuoteLine object, and add the same custom field with identical settings.
3. If you haven't already created the configuration attribute, then navigate to the top level Product that represents your configurator.  Scroll down to the 'Configuration Attributes' section and press the 'Add' button.
4. Fill in the form about the configuration attribute, making sure to set the 'Target Field' to the API name of the custom field you created in steps #1 and #2 (they should have the same API name).  Ensure 'Auto-Select' is set to false, otherwise it will overwrite the values coming from Epicor CPQ!
   
   

Now when you set configuration attributes through Epicor CPQ, they will propagate through to the custom field in the Quote Line object.