Choosing good rule and data instance names

As you complete a New instance 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, easy to debug, and easy to maintain. For best results, note these guidelines and write down — and enforce — your own 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, digits, ampersand, and hyphens (also called a dash character) in the name. Don't include spaces, special characters (quotes, dollar signs, percent signs, punctuation, parentheses, brackets, 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: As noted in other help topics, the names of many rule types, service packages, and group subscript values must be valid Java identifiers, consisting only of letters, digits, and dash characters (converted to underscores). See How to enter an identifier.

Guideline 4: For a few rule types or data classes, additional characters are allowed or required in keys. You can use:

• One at-sign character (@) and one or more periods in names for data objects involved with an organization, such as Operator IDs, organizations, divisions, organization units, work groups, and access groups.
• One colon (:) character in access role names
• Any character in a field value or skill rule name
• A single quote character in Operator ID names.

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 dash character to an underscore character. Accordingly, you cannot create two objects with names that differ only by letter case. If you try, the system message appears.

For example:

• If your system contains a Database data object named CusMaster, you cannot create another named CUSMASTER, cusmaster, or CusMaster.
• If your system contains an activity rule named Data-Account.Summarize, you cannot create another named Data-Account.summarize or Data-Account.SUMMARIZE (with the same values for the RuleSet, Version, Start Time, End Time, Circumstance Property and Circumstance Value). You can create an activity named Data-Account.Summarize if it has a different RuleSet or Version from the first.

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, often with sophisticated and powerful algorithms.

References to rule or data instances must match the exact case of the name. (That is, 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:

• Names of classes (Rule-Obj-Class) and RuleSets (Rule-RuleSet-Name) must be unique system-wide.
• If the name of a class rule ends in a dash character, the class must be an abstract class.
• You cannot create properties with names that start with the reserved prefixes px, py, orpz unless they override existing standard properties.
• Keys are limited in length. See System limits and maximums.