When you create new rules or new data instances, it is important to understand how Pega Platform uses names and keys. If your development team has established naming conventions to avoid confusion and wasted time, it is important to observe them as well.
As you complete a Create form or Save As form, you choose the name of a new rule or data instance. Careful attention to the spelling and capitalization of the names you enter contributes to applications that are easy to learn, debug, and maintain. For best results, note these guidelines and establish — and enforce — team naming conventions.
Many rules and data objects have a visible key that contains multiple fields — key parts. Generally, the guidelines here apply to each part. The total length of all key parts added together cannot exceed 128 characters.
Guideline 1: Start a name in a rule with a letter (A-Z, a-z). Start a name in a data instance with a letter or digit. Use only characters from a single Latin-1 character set.
As a best practice, start the name with a capital letter.
Guideline 2: Use only letters, numbers, underscores, and hyphens in the name. Do not include spaces, special characters (quotation marks, dollar signs, percent signs, punctuation, parentheses, brackets, ampersands, and so on) in a name, except as noted below. If you include spaces, the system forms the name by deleting the space characters.
Guideline 3: The names of many rule types, service packages, and group subscript values must be valid Java identifiers, consisting only of letters, numbers, and hyphens (converted to underscores). See How to enter a Java identifier.
Guideline 4: For some rule types or data classes, additional characters are allowed or required in keys. You can use:
Internally, the system forms a property pxInsName, known as the visible key, from the name or key parts you enter. It converts letters into uppercase and concatenate the parts with an exclamation point character between parts. In addition it converts a hyphen to an underscore character. Accordingly, you cannot create two objects with names that differ only by letter case. If you try, the system message "This instance already exists" appears.
For example:
The three activities named Data-Account.Summarize in Ruleset Version Alpha:01-01-01, Data-Account.SummaRize in Alpha:01-02-07 and Data-Account.SUMMARIZE in RuleSet Gamma have the same visible key, and so are known as sibling rules.
After you save a rule or data instance, you or other developers can reference it elsewhere by name. Many references identify only one name or key part. The system determines any other key parts from context.
References to rule or data instances must match the exact case of the name; references are case-sensitive. You cannot reference the object named FOO with the value foo, Foo, or fOO.
For many rule types, the standard property .pyRuleName contains the exact case of the Name or Purpose key part; this is useful in reporting on rules or presenting a selection list of rules. In contrast, the handle or internal key (pzInsKey property) and the visible key (pxInsName property) present this key part in uppercase.
For certain rule types, additional restrictions apply to names:
px, py, orpz unless they override existing standard properties.