Within an organization or a development team, standard naming conventions help to ensure a uniform understanding of an application and its components. Careful consideration of naming conventions at the outset of a project reduces the risk of duplicated effort and rework. Additionally, many of the names employed in development are visible on the user forms and portals, so clear, meaningful labels enhance user experience and improve productivity.

This article presents recommended naming conventions for:

• Case lifecycle design constructs (such as stages and steps) and related components (such as case types, data object types, flow actions, and assignments).
• Rule and data records (for example, class names, purpose names, and property names).

Case Lifecycle Management naming conventions

Implemented in Pega 7, Case Lifecycle Management use a process-design paradigm based on stages and steps. The design provides a holistic view of a business transaction, such as a purchase request or a vendor inquiry, from beginning to end.

You build your application on the Pega 7 Case Designer landing page. Here is where you add your stages and steps and configure your processes. The naming conventions that you employ are key to conveying the application's purpose to developers and business analysts.

The conventions presented here are suggestions; adopt or adapt the ones you want based on your application and organizational requirements. In any event, make your conventions uniform and apply them consistently.

Stages

Stages describe the phases of a case transaction. For example, an auto loan case might have the following stages: Submission, Review, Underwriting, and Financing. Collectively, stages show the sequence in which these phases occur. As a best practice, every case should have at least three stages – assume that, at minimum, every case is submitted, gets some level of review or validation, and is finalized.

From the Case Designer, you name stages by entering text in the shape's text field. The text is also used as labels on stage shapes on user forms.

Use nouns or gerunds (verbs ending in “ing”) as a naming convention. Avoid using verbs that describe an action or a status; for instance, Order Placed, Shipped, Account Paid, and Closed.

Steps

Steps represent a process, an assignment, or another case. Steps are actionable “things to do”, whether the action is a single assignment, a process that contains multiple assignments, or the automatic creation of new case.

You create steps by entering a name in a step shape, which is located beneath a stage shape. Use a verb + noun naming convention. The name should describe the step’s overall purpose. For example, an auto loan case might have a step named Submit Loan Application, which can be either a single-step assignment or a multi-step process (because it uses a screen flow).

When you add a step on the landing page, the system creates a flow record and uses the name you entered as the record’s Short Description. For single and multi-step processes, the system uses the text for the first assignment’s label. The step names also appear on the user portal dashboard beneath the stage chevrons.

Case types and cases

Case types represent business transactions (cases). For example, a lending application might have auto loan, personal loan, home equity loan transactions. In other words, a case represents what must be processed, not how it is processed, which is described by stages and steps.

Typically, you create case types in the Cases Explorer or Application Express by entering their names in a field. Use a noun convention. Avoid using vague, non-specific names such as Auto or Personal, which do not provide enough context. For instance, in a financial services organization, there may be Auto Loan cases and Auto Accident cases. Getting immediate context from the transaction name is crucial.

The system uses the names as Short Descriptions for the new class records. On the user interface the names appear in locations that include user form headers, case lists, and the Create menu.

Data object types

Data object types are classes that contain the information such as properties and data pages that are necessary for a case to accomplish its actions or achieve its business outcome. In other words, they represent “things.”

Typically, you create data object types in the Data Explorer or Application Express by entering their names in a field. The system uses the names as Short Descriptions for the new class records. The names appear in the Data Explorer, which serve to logically organize the application's data objects.

Use a noun convention; for example, Cost Center, Country, and Exchange Rate.

Flow actions and assignments

Like steps, use a verb + noun convention. It is important that the names are meaningful to users – the text appears in many locations on the end user interface, including work lists and menus on user portals and forms.

More about flow action names

A flow action can reference other records. When associated with certain activities and validation records, prefix the flow action name with:

• Pre if used with a pre-activity; for example, PreApproveCorrespondence
• Post if used with a post-activity; for example, PostApproveCorrespondence
• Val if used with a validate record; for example, ValApproveCorrespondence

When naming other records related to the flow action, follow these guidelines:

• Section – use the same name as the flow action, for example Approve Correspondence
• Privilege – use the same name as the flow action

Naming conventions for records, classes, tables, and other objects

The PRPC development environment includes a large set of rule and data records, classes, tables, and design features that are ready for immediate use. You can quickly get a basic, working application – not just a prototype – up and running by slightly modifying the standard capabilities to suit your business needs.

As you create new items in your application, it is important to label them consistently and in a logical manner. This approach makes it easier for members of an organization or a development team to:

• Find and identify records as you build out applications and configure changes and enhancements.
• Convey the meaning of the process and understand the application’s structure.
• Avoid record duplication thus enhancing processing efficiency and developer productivity.

Refer to the following sections for guidelines on appropriate naming conventions:

• Rule and data records
• Classes
• Tables
• Design features

General guidelines for record naming conventions

Before creating a record:

• Look for an existing record (standard or in your application) that either delivers the required capability or that you can copy and modify to reduce development time.
• Assess the likely reusability of the record, as this will help you determine where to place it in the class and ruleset hierarchies.

The general guidelines for all records are:

• Choose names that reflect the purpose of the record.
• Keep names short, but not so short that the purpose of the record is not evident.
• Start all names with a capital letter. Start words within names with capital letters. Capitalize any acronyms within names.
• Do not include underscores or other special characters, except as noted.
• When creating rules in PRPC 7.1+, the system automatically generates the record identifier using text you enter in the Label field. You can include spaces and special characters; the system removes them and capitalizes the first letter of each word when it creates the identifier.
• Names of records that are part of specific functional groups can start with the function name (or an abbreviation of the name), followed by an underscore, and then a record name. Do not do this for rules from which other rules inherit.
• Start the names of active rules, such as activities and flows, with a verb indicating the main action of the rule. Usually, include a noun or noun phrase indicating what the rule operates on.
• For passive or object records, such as parameters, properties, work parties, libraries, and roles, choose nouns or noun phrases indicating the use of the rule. For example, ProjectGoalDate, ClaimID, DefenseAttorney.
• Use dashes (hyphens) in Class names to control pattern inheritance.

Limitations on name lengths for rule types and objects

Length limitations exist for names of certain rule types and objects:

• A ruleset name (pyRuleSet property) may be up to 128 characters long.
• An Operator ID value (pyUserName property) may be up to 128 characters long.
• The internal key of an object (pzInskey property) may be up to 255 characters for most tables. Longer file names cause compilation issues in Windows environments.
• A class name (pxObjClass property) for a class you create may be up to 56 characters long. (The system generates parallel History- classes for most classes that you create, thus reaching the 64 character limit for class names.)
• The visible key (pxInsName property) may be up to 128 characters long.
• The short description for a record (pyLabel property) may be up to 64 characters long; as a best practice, enter no more than 30.
• A property name may be up to 64 characters long.
• The system name (key of the Data-Admin-System data instance) may be up to 32 characters long.
• The pzPVStream column or Storage Stream has a maximum of 2 gigabytes. This column typically has a data type of BLOB.
• A node name may be up to 32 characters long.
• Assignments may be up to 32 characters long.

Naming conventions for records

Access roles

Choose a name that is unique system-wide, both in the current system and in other PRPC systems that may later host this application, and that contains one colon character.

Use the format ApplicationName:RoleName; for example, Thorr:Administrator or Purchasing:Buyer. This allows you and others to ensure the name is unique across multiple applications.

Begin the name with a letter and use only alphanumeric, ampersand, dash characters, and a single colon.

Data transforms

Name the data transform (in each case type) that is most often used to initialize cases pyDefault.

Check the Call superclass data transform? checkbox. Only set values that will override or supplement those set in the superclass pyDefault data transforms.

Declaratives

For declarative expressions and constraints, use logical descriptive naming conventions. Since these records extend the definition of a property value, use nouns to distinguish them from activities.

Files

For records in any of the rule types derived from Rule-File-, select a name that uses only lowercase characters. This avoids confusion between systems like UNIX (which have case-sensitive file names) and Windows systems, which do not have case-sensitive file names.

Begin the names of files for related functions with a common prefix character so they appear grouped together in listings.

Flows

Follow the noun + verb convention as described above for Case Lifecycle steps.

Functions

Follow Java naming standards (initial lower case, then mixed case) for the Function Name key part of a function record, since these define Java functions.

HTML streams

For an HTML stream, choose a noun or noun phrase that indicates the main data displayed by the stream. If possible, this name should relate to the name of the activity or action that displays the stream. For example, WorkSummary.

Properties

For the names of a property, choose nouns or noun phrases that describe the property. Use names that are descriptive and meaningful so the contents of the property are obvious.

For example, LoanNumber is a good choice for a numeric account number, while LoanID is a better choice for an alphanumeric account number. Enter the name in mixed case with the first letter in uppercase and the first letter of each internal word also capitalized.

• Names of lists (Page List) should end in list.
• Name of groups (Page Group) should end in group.
• Property names are case-sensitive — use only letters and digits.
• Do not start property names with an underscore ( _ ) or dollar sign ($).

Standard property names are prefixed with px, py, or pz. Your property names must not start with these prefixes. The table below describes each of these prefixes.

When defining properties, complete all of the data format and typing options to ensure the integrity and formats of the data within the application. Therefore, when defining new properties within an application, use all the validation and format features available. Complete these fields on the Property form:

For properties with type Text:

• Max Length to enforce the maximum number of characters that can be stored in the field
• Expected Length to control the width of the display input box (using standard text display)
• Edit Input to convert text to upper or lower case
• Use Validate to validate Alpha or Alpha Numeric
• UI Control to show a common look and feel for the property when it appears on a form

For properties of type Decimal:

• Use Validate to validate positive / negative amounts
• Property Qualifiers to enforce minimum length (pyMinimumLength) or decimal precision (pyDecimalPrecision)
• UI Control to show a common look and feel for the property when it appears on a form

For properties of type Integer:

• Edit Validate to validate positive / negative amounts
• Property Qualifiers to enforce minimum length (pyMinimumLength) or decimal precision (pyDecimalPrecision)
• UI Control to show a common look and feel for the control when it appears on a form

Privileges

Begin the name with a letter and use only alphanumeric, ampersand, and dash characters. As a best practice, start the name with a capital letter. In compound names such as ReconcileProblemWork, capitalize the first letter of each word.

Rulesets

When creating a new ruleset, follow these naming conventions:

• Create a new ruleset with a top-level class that inherits directly from @baseclass.
• Use names that are easy to remember and are short and catchy.
• Use names that make sense; avoid using obscure acronyms.
• Choose a name that clearly describes the ruleset. For example, use CitiMortgage as opposed to CGMLS (short for CitiGroup Mortgage Loan System).
• Always begin your ruleset name with something that uniquely identifies your company and the business purpose. This convention also prevents potential ruleset collisions.
• Do not use Pega or Pega- as a prefix for your ruleset names. They are restricted to Pegasystems use and could cause unexpected behavior.
• Names can be a maximum of 32-characters and cannot contain spaces.
• Avoid the use of special characters such as dashes, underscores, plus signs, or quotes. The system prevents entry of rules with these attributes.
• The Version field defaults to 01-01-01 which is the standard value for a new ruleset.

Ruleset versions

Ruleset versions follow the pattern 01-01-01 (MJ-MN-PT); where:

• MJ (Major Version) – incremented for major changes or new releases
• MN (Minor Version) – incremented for enhancements or medium-size changes
• PT (Patch Version) – incremented for bug fixes or very minor changes

Tickets

For a ticket names, describe the condition to be met before processing continues from the ticket. For example:

• AllCoveredResolved
• WorkWithdrawn

When conditions

The names of when condition records should have names that could logically follow the word when.

Each of these names conform:

• IsBlank
• StepStatusGood
• NotThisClass
• Contains
• MyOrgDivOwner

For each of these, the meaning is unclear when preceded by the word when:

• AdministratorID
• Unlock

Organization

Use the organization's short name, ticket symbol, or internet domain name; for example: Pega, PEGA, or pega.com.

Operator ID

Use an email address. The maximum length should be 20 characters.

Workbaskets and work groups

Use a name that clearly identifies the purpose of the workbasket followed by the suffix WB. For example:

• AnalystsWB
• UnderwritingWB

Work groups usually identify a group of workers that have similar process responsibilities. Use a name that clearly identifies the purpose of the group followed by the suffix Group. For example:

• HelpDeskGroup
• BenefitsGroup

Work item status values

The property Work-.pyStatusWork defines whether a case is open or resolved. Values for this property are restricted to a set defined by field value rules. Changes to this property value convey important information about the progress of the work object towards completion. In addition, the system uses this property value to control automatic case instantiation, and mid-process dependencies.

The following values are typical for this property:

Instead of adding completely new statuses, extend the four existing statuses so that you can use the existing reports without having to localize and modify them. Start each value with one of the words New, Open, Pending, or Resolved, using initial capitals as indicated.

Values for this property are defined through field value records; several standard values are defined. The HTML property rule WorkStatus supports localization of the status value on displays, through field value records.

Naming conventions for classes

Follow these guidelines when naming classes:

• Use a noun for a class name (such as Customer or Address). Use mixed case with the first letter of each word capitalized.
• Make class names simple and descriptive.
• Use whole words. Avoid acronyms and abbreviations (unless the abbreviation is much more widely used than the long form, such as URL or HTML).
• Do not include underscores in class names.
• In general, application developers never need to create top-level classes (Work-, Rule-, Data-, Assign-, and so on.) Create new classes only underneath the organization class, for example. MyCo-.
• Use logical, descriptive names for your class structure. Classes represent units of work, so use nouns to name classes, which helps distinguish classes from actions and processes.
• By convention in PRPC 6.x and earlier, abstract class names end with a dash, while concrete class names do not. Starting with PRPC 7.1, abstract class names do not end with a dash.
• Class names are visible labels in some forms, worklists, reports, and other areas of an application. The Short Description is also visible. Therefore, be sure to use class names that are self-explanatory and reflect the purpose of the work. Avoid using class names that reflect status or action, instead of a unit of work.
• Choose class names that support pattern inheritance, as well as directed inheritance.
• Name related objects similarly, with consistent prefixes, so you can quickly locate similar classes in an alphabetical list.
• To indicate class behavior, include something that describes whether it is a work object, a cover, or a folder. For example, PegaRP-Work-Object- (parent class for work objects) and PegaRP-Work-Project- (parent class for covers).
• To distinguish hierarchy position and inheritance, use class names that visually reflect pattern inheritance. For subclasses, include the names of all parent classes (including your top-level class), separated by dashes. For example, if the parent class YourCoLoan-Request has child classes for mortgage and car loan applications, name them YourCoLoan-Request-Mortgage and YourCoLoan-Request-Auto.
• Use the same naming conventions for class groups as for classes.

Naming conventions for database objects

This section defines the naming standards for objects such as tables, views, indexes, and so on created in the PegaRULES database or other databases used by a Process Commander application.

In general, database tables should be named in accordance with the location of the respective work or data class in the <Customer> Enterprise Class Structure (ECS).

Names of standard PegaRULES database tables begin with pr_, pc_, or pi_. Often it is necessary to create your own tables to supplement the standard ones. It is convenient to use the application/ruleset name as a suffix (MyApp_), and to try to resemble the existing name (MyApp_work would be the work table).

For database objects, use the same name as the class or class group. Ending suffixes are:

• TB – a table
• IN – an index
• SY – synonyms
• SQ – a sequence

Work tables

Should be mapped on the implementation layer so as to allow multiple lines of business using the same framework application to map to different database tables. The name of a work table should be:

<LOB-name>_work_<work-pool-name>

Abbreviations of line of business name and work pool name should match the abbreviations in the <Customer> ECS. (Case does not matter for DB2 table names.)

For example:

Line of business = VSHP; Work Pool = Order Intake
Database table name: vshp_work_orderintake

Line of business = Claims; Work Pool = Contracts
Database table name: claims_work_contracts

Work history tables

Should be named as follows:

<LOB-name>_history_work_<work-pool-name>

Abbreviations of line of business name and work pool name should match the abbreviations in the <Customer> ECS.

For example:

Line of business = VSHP; Work Pool = Order Intake
Database table name: vshp_history_work_orderintake

Data tables

Data tables that represent division-wide or enterprise-wide data tables or reference data should be named as follows:

Division- wide: <LOB-name>_data_<domain-name>

Enterprise-wide: ent_data_<domain-name>

Abbreviations of line of business name and domain name should match the abbreviations in the <Customer> ECS.

For example:

Division-wide wide reference table for Claims; Domain Name = Provider
Database table name: claims_data_provider

Enterprise-wide data table; Domain Name = Networks
Database table name: ent_data_networks

Constraints

Constraints on a database tables containing work or data should be named using the table name suffixed by _PK.

For example:

Database table name = claims_work_contracts
Primary key name: claims_work_contracts_pk

Naming conventions for other objects

For indexes, views, triggers, and stored procedures, use the same naming criteria as for activities. Start with a verb indicating what the database object does, followed by a noun or a noun phrase indicating what the view does. End the name with the appropriate suffix. Maximum length should be 15.

• vw – View
• tr – Trigger
• in – Index
• rp – Report
• te – Trigger events
  • te_ai – After Insert
  • te_bi – Before Insert
  • te_au – After Update
  • te_bu – Before Update
  • te_bd – Before Delete
• sp – Stored procedure

For example, database view to retrieve employee data records has the name get_employee_data_vw.

Service packages

A service package supports the development of services offered by your application. A service package name becomes the first key part of a set of service records that are packages and deployed together.

Create a service package data instance for each service. As a naming convention, use the following format:

<application name><service type><optional deployment type><optional unique part>

For example:

• LOANSSOAP
• LOANSEJBV2
• LOANSEMAIL
• LOANHTTPA, LOANHTTPB, LOANHTTPC

Activities

When creating new activities, ensure that the steps are specific to the functionality being developed. If the steps can logically be broken into multiple records, this may provide for greater reuse opportunities in the overall application. Also, look for opportunities for parameterization, which supports reuse.

• Start activity names with a verb that indicates what the activity does. In most cases, follow the verb with a noun or noun phrase indicating what the activity operates on.
• Enter the name using mixed case, with the first letter of the name and the first letter of each internal word in uppercase.

These examples follow the best practice guidelines:

• CreateClassPage, GetHTMLFilePath, AddPageIndex – these indicate what the activity is doing
• Toolbar_ChangeAvailability – demonstrates leading functional group names

These examples do not follow the best practice guidelines:

• Create, Delete – too generic
• HarnessShow – does not start with a verb
• New – not a verb and does not provide sufficient information
• AllCompleted ​– does not say what it does

Router activities

Start the name of a router activity with To and end in a noun phrase indicating the route destination, such as ToWorkbasket. The table below contains examples.