Return to main navigation Page
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 Cloud:
Naming Convention Rules
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
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 “limit”, “filter” or “remove” options that the user can select. Examples:
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”):
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:
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:
There are two primary types of documents in CPQ Cloud:
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.
Integration Docs are a bit harder to name. Luckily, QuickStart comes with well-named Documents.
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 ALL CAPS. 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:
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.
|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,
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,
Keep variable names short, but not so short that they are not useful.
Follow the preceding recommendations for variables when naming Configurable 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:
server_rack, memory_rack, (or simply
server_f,and so on.)
Naming Data Tables
To more easily distinguish between variables, use Capitalized CamelCase when naming Data Tables. Example:
Product, Username, StartDate