Rulesets

Developers collect individual Rules into an instance of a Ruleset, called a Ruleset version. To update the contents of the Ruleset, you create a new Ruleset version. The new Ruleset version is available — or unlocked — for the developer to make Rule updates and add new Rules. It is a best practice to lock older versions of the Ruleset. Ruleset versioning helps developers identify and manage changes to an application.

Pega Platform identifies Rulesets by names and version numbers. For example, an application to process expense reports includes a Ruleset named Expense. Pega Platform appends the version number to the Ruleset name. Expense:01-02-03 is version number 01-02-03 of the Expense Ruleset.

The version number is divided into three segments: a major version, a minor version, and a patch version. Each segment is a two-digit number starting at 01 and increasing to 99. Ruleset version numbering starts at 01-01-01 and increments upward.

In the following image, click the + icons to learn more about the segments of Ruleset versions:

Each application consists of a sequence of Rulesets called a Ruleset stack. The Ruleset stack determines the order in which Pega Platform looks through Rulesets to find the Rule that is in use. Each entry in the Ruleset stack represents all the versions of the specified Ruleset, starting with the listed version and working down to the lowest minor and patch version for the specified major version.

Each version of an application contains a unique Ruleset stack. The Ruleset stack allows an updated application to reference new Ruleset versions that contain updates and new features.

For example, Bob is a developer working on the first version of an application to manage expense reports. Bob creates Rules for the first version of the application, such as Processes, UIs, and Notifications. Bob collects these Rules into the first version of the Expense Ruleset, Expense:01-01-01. After several iterations of deploying to a QA environment and bug fixes, the Expense Ruleset is versioned multiple times up to 01-01-05 before being deployed to production.

Months later, Tanya receives an enhancement request to update the UI in the application to collect extra information from employees due to a policy change. This update enhances the Rules created earlier by Bob. Tanya creates Rules to model this new behavior in a second version of the Ruleset, Expense:01-02-01. She then uses the Expense:01-02-01 Ruleset in the updated expense reporting application.

In the following image, click the + icons to learn more about the Ruleset stacks: 

Use the following best practices when creating Rulesets.

Naming conventions

• For application Rulesets, use unique names that are meaningful in a business context and easy to remember to clearly convey the purpose of the Ruleset. For example, in a Banking application, name your Ruleset as Accounts to store Rules related to accounts.
• For organization, division, and shared Rulesets, begin your Ruleset name with a phrase that clearly identifies your company and the business purpose, and avoid using acronyms that might be difficult to decode. For example, name your Ruleset UPlusTelcoContracts instead of UPTC. This convention also prevents potential Ruleset conflicts.
• Do not use Pega or Pega- as a prefix for your Ruleset names. These prefixes are restricted to internal use in the Pega Platform and can cause unexpected behavior.
• Avoid using spaces in Ruleset names. The maximum length of a Ruleset name is 32 characters.
• Avoid the use of special characters such as dashes (-), underscores (_), plus signs (+), or quotes (" "). The system does not permit the saving of Rules with these attributes.

Saving Rulesets

• Refactor the Ruleset to its own application or a common application. Only share the base Rulesets when sharing Rulesets across multiple applications.
• Limit development to Rulesets in the topmost Application Layer and keep built-on applications locked.

Versioning Rulesets

• Consider creating a major version of your application if you upgrade your application server or database server to a major new version.
• Increment Ruleset versions frequently to easily track updates to your application over time.
• Create a new Ruleset with a top-level class that inherits directly from @baseclass.

Check your knowledge with the following interaction: