To package rules for distribution as part of an application, you collect rules into a group called a ruleset. A ruleset identifies, stores, and manages the set of rules that define an application or a significant portion of an application. If a rule is similar to a song, a ruleset is similar to an entire album.
Just as you can copy the album to share with a friend and allow your friend to listen to your favorite song, you can share a ruleset between applications to allow several applications to use the same rules. The ability to re-use already-built rules saves development time and effort.
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.
Note: Pega Platform™ manages the creation of rules and identifies the ruleset and version in which to store rules for applications created in App Studio.
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:
Starting in 2023, Pega Infinity product versions follow the format Year.Minor.Patch. For Pega Infinity '23, the product version is 23.1.1. The Pega Ruleset semantic versioning follows the format Major-Minor-Patch. For Pega Infinity '23, the ruleset version is 08-23-02.
Note: Pega Infinity™ '23 is the latest minor release. For more information about the Pega Infinity product naming convention, see Pega software maintenance program.
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:
Ruleset best practices
Use the following best practices when creating rulesets.
- 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.
- 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.
- 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.
Note: To learn more about managing rules in rulesets, see Organizing Rules into Rulesets.
Check your knowledge with the following interaction: