Skip to main content
Verify the version tags to ensure you are consuming the intended content or, complete the latest version.


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.

Rulesets in an application

Ruleset versioning

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.

Ruleset stack

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.

Application Ruleset stack

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.

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

  • Avoid having the same ruleset in multiple applications. Instead, refactor the ruleset to its own application or a common application.
  • Limit development to rulesets in the top-most application layer and keep built-on applications locked.

Versioning rulesets

  • Consider creating a major version of your application if you update 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:

This Topic is available in the following Module:

If you are having problems with your training, please review the Pega Academy Support FAQs.

Did you find this content helpful?

100% found this content useful

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice