Naming Conventions for Rules, Attributes, and Variables
Overview
Engineers, architects, and admins have free reign over what they name rules, functions, documents, attributes, and internal variables. However, it is imperative that all of these aspects of an implementation are given clear, useful, and at least semi-standardized names. Consistent and clear naming supports maintenance and add-on activities. Well-named Rules and Attributes are easier to identify, and code that uses well-named variables and functions is self-documenting.
Naming opportunities are ubiquitous across CPQ:
- Rule naming applies to anywhere rules can be created; configuration rules are generally the focus.
- Functions are usually found in the form of utility or Commerce libraries. Though they may only be called in few places, it is still important that they have meaningful names.
- Documents refer mainly to XSL integration files and Document Designer or Document Engine documents. As sites become larger and more complex, it is imperative that admins and engineers can quickly and easily identify what an integration file or DocEngine doc is for without having to open it up and study its components.
- Attributes are extremely important because they are the link to the user and his or her experience with the product. They are found in Configuration and Commerce.
- Variables are contained in all of the above items. If they are poorly named, maintenance and add-ons become difficult.
Administration
Naming Convention Rules
The name of a configuration rule should give an admin some insight as to what the rule does. Wherever possible, use names that evoke the business rules being implemented, using the terminology and language that the customer is familiar with. Remember, there are a number of attributes of rules stored as metadata, so it is not necessary to recapitulate them in the naming and it can clutter the UI if you do:
- Rule Type
- Related Attributes
- Description
- Status (Active/Inactive/Internal)
- Model/Product Line/Product Family
Recommendation Rules
Recommendation Rules are generally used in order to “set” values based on other values, or specify “default” values conditionally based on the initial state. This is useful if multiple flows inherit a collection of attributes. Examples:
Constraint Rules
Constraint rules “limit”, “filter” or “remove” options that the user can select. Examples:
- “Filter Model by Product Line” might implement a hierarchical relationship between Product Line and Model.
- “Restrict Support Term by Support Type” might apply a table-based limit to the Support Term attribute which takes the Support Type attribute as input.
Hiding Rules
Similar to other types of rules, name Hiding Rules based on the business rules they represent. In most cases, the rule should describe “what” is hidden (and optionally “why”):
- “Hide Advanced Rack Configuration” might hide an array set of customized options if an “Advanced Rack Configuration” option is set to
No.
- “Hide Support Option if Subscription” might hide a Support Option attribute (or set) if a given item represents a Subscription (in which support is included).
Recommended Item Rules
Most sites have few enough recommended item rules (some have just two or one) that it's okay to just refer to the output. It's generally understood that the rule is probably either always true, or fires when the user starts to provide the input that generates the recommended items. Examples include:
- Spares – Optional
- Main Units – Mandatory
-
Software – Mandatory
Consider including whether or not the rule type is Mandatory or Recommended. Since the word “Recommended” can be confusing, since all of these rules are of the “Recommended Item” type, the word “Optional” is a good substitute.
- Keep names short and simple.
- If you have a large number of rules at a high level (for example, Product Family) try a prefix naming system to group them together, such as “Support - Options”, “Support - Term”, or “Hardware - Advanced Config”.
- Do not use phrases like “greater than”, “less than”, or “equal to”. When there is a large list of rules it is hard to tell which words are attributes and which words are operators.
- The exception to the above rules is “CONTAINS”. Use it and its negative ”!CONTAINS” in all caps so that you can differentiate them from the operands in the rule name.
Naming Functions
Each function should have a meaningful name that accurately conveys what it does. Function/method names should start with a strong action verb, such as convert, divide, build, and so on. Get and set are often used in function names. The rest of the name should reference what the function is acting on or perhaps what it is returning. Examples include:
divideProductIntoBuckets
buildSupportTypeQuery
getXMLNode
setSupportPrice
Naming Documents
There are two primary types of documents in CPQ:
Document Designer (or DocEngine)/Printer Friendlies
The names for Printer Friendlies should simply reflect the contents of the document. If the document is a Schedule A, the name 'Schedule A' is fitting. If it consists solely of a financial analysis then 'Financial Analysis' fits. The rule of thumb is that each document should be easily distinguished from all of the other documents. Because of this, the more documents a site has the more important the names become.
XSL Integration Docs
Integration Docs are a bit harder to name. Luckily, QuickStart comes with well-named Documents.
- The QuickStart Template:
- Examples:
- Salesforce Opportunity - Import
- Salesforce Quote - Upsert
The Object refers to the CRM Object that is being queried or updated. The Action explains what is being done with that Object.
The most common Actions for an integration are:
- Create
- Delete
- Upsert
- Import
- Get IDs
Naming BML Variables
Often the sheer number of variables in BML scripts causes admins to give little thought to the variable names. Poorly chosen names can make code difficult or impossible to read.
The following table describes types of BML variables:
| Constant |
Values never change through the entire script. |
They should be in all capital letters. Separations in words should be replaced by an underscore (for example, LIKE_THIS)
They should be included at the top of the BML script in which they are contained.
They should be used for commonly-used strings and numbers. A pricing script might have the literals:
ITEM_DELIM = "|";
FIELD_DELIM = "~";
MAIN_LEVEL_INDEX = 3;
If the field delimiter changes from a tilde to another, an admin needs only to change the initialization of the variable instead of searching through the code for every single instance of a tilde.
Try to use these literals when pulling values from an array.
Example: Write listPrice = pricingInfoArray[LIST_PRICE_INDEX] instead of referring to pricingInfoArray[2]
|
| True Variable |
Any variable whose value can change as the script runs. |
They should be in camelCase. The first letter is lowercase, while the first letter of each element in the name is upper case, for example, listPriceAfterStandardDiscount
Avoid acronyms when possible, unless they are standard acronyms like XML, HTML, and so on.
When acronyms are included, they must also follow the camelCase rule (for example, parsedXmlHtml)
Make your variable names "information dense" so that the admin will have an idea of what the variable represents, without context.
Keep variable names short, but not so short that they are not useful.
|
Naming Attributes
Follow the preceding recommendations for variables when naming Configuration and Commerce attributes. In addition, you should follow a naming convention that makes it easier to distinguish between Attributes and regular variables in a script, since they behave differently. For example, you cannot set the value of an Attribute in a script.
The following examples show "_object" convention used in QuickStart:
- Quote:
quoteNumber_quote, submittedDate_quote
- Line:
listPrice_line, isOptional_line
- Model “Rack”:
server_rack, memory_rack, (or simply server_m, server_pl, server_f, and so on.)
Naming Data Tables
To more easily distinguish between variables, use Capitalized CamelCase when naming Data Tables. Example:
- Table Name:
ContractPricing
- Table Columns:
Product, Username, StartDate
Related Topics
See Also
