7.1 Rulesets, Versioning & Ruleset Stack Hierarchy

Rulesets, Versioning & Ruleset Stack Hierarchy

The fundamental philosophy of the Pega Platform is built on a declarative, model-driven architecture where "everything is a rule." Rather than writing procedural code in monolithic files, System Architects assemble enterprise applications by creating discrete, reusable, and version-controlled configuration artifacts called Rules. Rules define every facet of an application—from case lifecycles and business logic to data integration, user interfaces, and role-based security.

To manage these rules across enterprise teams, environments, and application layers, Pega provides a rigorous organizational framework centered around Rulesets, Ruleset Versions, and the Ruleset Stack. Understanding how rulesets are versioned, validated, and stacked at runtime is critical for Certified System Architects (CSAs) responsible for designing scalable, maintainable enterprise solutions.

---

1. What is a Rule in Pega?

A Rule is a named business instruction or data definition that governs how a Pega application operates. In object-oriented terms, a rule is an instance of a concrete rule class that inherits from the abstract base class Rule-.

Rules vs. Data Instances

It is vital to distinguish between Rules and Data Instances:

• Rules (Rule-): Define application behavior, logic, and presentation. Examples include Properties (Rule-Obj-Property), Sections (Rule-HTML-Section), Flows (Rule-Obj-Flow), Data Transforms (Rule-Obj-Model), and Declare Expressions (Rule-Declare-Expressions). Rules are subject to versioning, ruleset packaging, check-out/check-in security, and the Rule Resolution Algorithm.
• Data Instances (Data-): Represent concrete business or system entities created during application runtime or environment setup. Examples include Operator IDs (Data-Admin-Operator-ID), Work Queues (Data-Admin-WorkBasket), Access Groups (Data-Admin-Operator-AccessGroup), and Database records (Data-Admin-DB-Table). Data instances are stored in operational database tables (such as pr_operators), do not belong to ruleset versions, and are not evaluated by rule resolution.

Database Storage & Rule Anatomy

Every rule created in Pega is stored in the PegaRULES database schema (primarily within the pr4_base table or rule-type-specific views):

• The Storage Stream (BLOB): The complete internal definition of the rule is serialized as an XML/BLOB (Binary Large Object) into the pzPVStream column. This encapsulates all properties, parameters, and metadata.
• Exposed Columns: Essential identification keys—such as pyRuleName, pxObjClass, pyClassName (Applies-To class), pyRuleset, and pyRulesetVersion—are exposed as distinct relational database columns. These exposed columns allow the Pega engine to execute rapid SQL indexing queries during rule resolution without having to deserialize the heavy BLOB.

---

2. Rulesets and Ruleset Versions

A Ruleset is an administrative container used to group related rules together for packaging, versioning, deployment, and security. Think of a ruleset as a cohesive software module or library.

The Three-Segment Versioning Scheme (NN-NN-NN)

Rulesets use a standardized three-segment version format: Major-Minor-Patch (represented as NN-NN-NN, where each segment is a two-digit integer):

+-------------------------------------------------------------------------+
|                   RULESET VERSION FORMAT: NN-NN-NN                      |
+-------------------------------------------------------------------------+
|   [ 01 ]                 -       [ 02 ]          -       [ 03 ]         |
|   Major Version                  Minor Version           Patch Version  |
+-------------------------------------------------------------------------+
| - Fundamental redesign         - New features          - Bug fixes      |
| - Architectural overhaul       - Sub-releases          - Small patches  |
| - May break compatibility      - Backward compatible   - 100% stable    |
+-------------------------------------------------------------------------+

1. Major Version (NN-xx-xx):
   • Represents a substantial architectural redesign, major platform version upgrade, or fundamental overhaul of business capabilities.
   • Changes in a major version are not guaranteed to be backward-compatible with earlier major versions. When an organization moves from 01-xx-xx to 02-01-01, downstream applications must undergo comprehensive regression testing.
2. Minor Version (xx-NN-xx):
   • Represents significant new functionality, enhanced business workflows, or intermediate project milestones.
   • Minor versions preserve backward compatibility with preceding minor versions within the same major release.
3. Patch Version (xx-xx-NN):
   • Represents defect corrections, hotfixes, performance tweaks, and minor maintenance adjustments.
   • Patch versions maintain 100% interface stability and backward compatibility.

Version Maintenance: Skimming

As teams iterate across numerous sprints, an application ruleset may accumulate dozens of patch versions (e.g., 01-01-01 through 01-01-45). In these intermediate versions, the same rule may have been modified multiple times. To clean up rule clutter, reduce database storage, and improve rule resolution efficiency, Pega provides Skimming:

• Minor Skim: Gathers the highest, most recent version of each rule across all patch versions within a minor release and compacts them into a new minor version (e.g., skimming 01-01-01 through 01-01-30 into 01-02-01).
• Major Skim: Gathers the highest version of each rule across all minor and patch versions within a major release and promotes them into a new major release (e.g., skimming 01-01-01 through 01-05-20 into 02-01-01). Rules that were superseded or marked as Not Available in historical versions are purged during the skim.

---

3. Taxonomy of Ruleset Types

Pega classifies rulesets into specific functional roles to manage enterprise governance and multi-team collaboration:

Branch Rulesets and Parallel Development

In large enterprise implementations where dozens of architects collaborate simultaneously, editing base rules directly causes collisions, lock contention, and regression defects. Pega uses Branch Rulesets to facilitate parallel development:

• A branch ruleset is linked to an underlying base ruleset (e.g., Branch Feature-LoanAutoApproval branching from Loans:01-01).
• Developers check out and modify rules strictly within the branch.
• Other team members continue working in their own independent branches or against the stable base ruleset without seeing uncommitted branch edits.
• Before merging, Pega provides a Merge Branch wizard that analyzes conflicts, validates guardrail scores, runs Pega Unit test suites, and flags duplicate rule modifications. Once approved, the branch rules are merged into the target base ruleset version, and the branch is deleted.

---

4. Ruleset Validation Modes: Ruleset Validation (RV) vs. Application Validation (AV)

When a developer creates or modifies a rule, Pega validates that all referenced rules (such as properties, data transforms, or sections) actually exist and are accessible. Pega supports two distinct validation modes configured on the ruleset version record:

+-------------------------------------------------------------------------+
|            RULESET VALIDATION (RV) vs APPLICATION VALIDATION (AV)       |
+-------------------------------------------------------------------------+
| RULESET VALIDATION (RV):                                                |
|   - Hierarchical, explicit prerequisite chain                           |
|   - Strict: Ruleset B can only reference Ruleset A if A is listed       |
|   - Risk: Cyclical dependencies (A needs B, B needs A) cause DEADLOCKS  |
|                                                                         |
| APPLICATION VALIDATION (AV):                                            |
|   - Governed by the Application Ruleset Stack                           |
|   - Flexible: Any AV ruleset can reference sibling AV rulesets          |
|   - Solution: Eliminates cyclical deadlocks in multi-team apps          |
+-------------------------------------------------------------------------+

Ruleset Validation (RV)

• Mechanics: Under RV, the ruleset version form explicitly lists a set of prerequisite ruleset versions. A rule in an RV ruleset can only reference rules residing in its own ruleset version, lower versions of the same ruleset, or rulesets explicitly listed in its prerequisite hierarchy.
• The Cyclical Dependency Problem: If Team A working on Claims:01-01 needs to reference a property in Customer:01-01, Customer:01-01 must be added as a prerequisite to Claims:01-01. However, if the Customer module later needs to invoke a flow action in Claims:01-01, RV prohibits adding Claims:01-01 as a prerequisite to Customer:01-01 because circular prerequisites are illegal. This causes development deadlocks.
• Appropriate Use Cases: RV is mandatory for platform base rulesets (e.g., Pega-ProcessEngine), reusable component rulesets, and marketplace libraries intended for export and distribution across independent client environments that have different application definitions.

Application Validation (AV)

• Mechanics: Modern Pega application development uses Application Validation by default. Under AV, ruleset versions do not require manual prerequisite lists. Instead, the validation engine evaluates rule references against the entire Application ruleset stack defined in the Application record.
• Cyclical Freedom: Any ruleset set to AV can reference any rule present in any ruleset that appears at the same level or lower in the application's ruleset stack or its built-on application hierarchy. Sibling rulesets in the same application layer can reference each other bidirectionally without circular dependency errors.
• AV-to-RV Rules: An AV ruleset can freely reference rules in RV rulesets. However, an RV ruleset cannot reference rules in an AV ruleset because the RV ruleset cannot establish an explicit version prerequisite against an AV ruleset.

---

5. Assembling the Runtime Ruleset Stack

When an authenticated user logs into a Pega application, the platform dynamically constructs an ordered list of rulesets called the Ruleset Stack (or Ruleset List). This stack represents the complete universe of rules available for execution during that operator's session.

+-------------------------------------------------------------------------+
|                     RUNTIME RULESET STACK ASSEMBLY                      |
+-------------------------------------------------------------------------+
| 1. Operator ID (Data-Admin-Operator-ID)                                 |
|    └─ Specifies default Access Group                                    |
|                                                                         |
| 2. Access Group (Data-Admin-Operator-AccessGroup)                       |
|    ├─ Specifies Production Rulesets                                     |
|    └─ Specifies Active Application Rule & Version                       |
|                                                                         |
| 3. Application Rule (Rule-Application)                                  |
|    ├─ Application Rulesets (ordered highest priority to lowest)         |
|    ├─ Production Rulesets                                               |
|    └─ Built-On Application (Recursive descent)                          |
|                                                                         |
| 4. Built-On Applications (Framework -> Core -> PegaRULES)               |
|    └─ Traversed downward to populate underlying enterprise rulesets     |
+-------------------------------------------------------------------------+

The Assembly Precedence Order

The engine orders the ruleset stack from highest priority (top of stack) to lowest priority (bottom of stack):

1. Personal Ruleset (Check-out): If an operator has developer check-out privileges enabled, their personal ruleset (OperatorID@Company.com) sits at the absolute top of the stack. Rules checked out to this private sandbox override all other versions.
2. Branch Rulesets: Active branch rulesets associated with the developer's current application and access group appear immediately below the personal ruleset.
3. Production Rulesets: Production rulesets specified on the operator's Access Group and Application rule are placed above standard application rulesets. This ensures that runtime overrides authored in production take precedence over standard deployment versions.
4. Application Rulesets: Rulesets explicitly listed on the user's primary Application rule, evaluated from the top of the application list to the bottom.
5. Built-on Application Rulesets: Pega traverses the application hierarchy recursively. If the primary application is built on a Framework application, the framework rulesets are added next, followed by any underlying core applications.
6. Pega Platform Core Rulesets: At the base of every stack sit the out-of-the-box system rulesets (e.g., Pega-ProcessEngine, Pega-UIEngine, Pega-Rules, Pega-IntEngine).

Design-Time vs. Runtime Visibility

• Runtime Visibility: Any rule residing anywhere in the user's assembled ruleset stack can be executed by the Pega engine, subject to the Rule Resolution Algorithm.
• Design-Time Visibility: In Dev Studio and App Studio, developers can only create or edit rules in rulesets that are explicitly listed in the current Application's edit list, are unlocked, and belong to the user's active branch or application development profile.

6. Ruleset Locking and Password Protection

To preserve software integrity across enterprise development and deployment cycles, ruleset versions must be systematically secured against unauthorized modifications.

Version Locking

Once a ruleset version has completed testing and is packaged for deployment to staging or production environments, the version must be Locked:

• In Dev Studio, a system architect opens the ruleset version rule form and selects the Lock and Save option.
• Locking a ruleset version renders every rule within that version immutable. No new rules can be added, and existing rules cannot be modified, checked out, or deleted.
• If defect fixes or enhancements are required post-deployment, architects must create a new ruleset version (e.g., incrementing from 01-01-01 to 01-01-02) in which to save the updated rules.

Password Protection

When locking a ruleset version, architects have the option to assign a Password:

• A password-protected ruleset version cannot be unlocked by unauthorized developers.
• This prevents team members from accidentally unlocking a frozen release version in lower environments and introducing unapproved changes into a golden release build.

Check-in and Check-out Governance

Ruleset versions can enforce the Rule Check-Out security facility:

• When check-out is enabled on a ruleset, developers cannot edit rules directly in the shared version.
• A developer must check out the rule, which copies the rule to their private personal ruleset (OperatorID@Company.com).
• While checked out, other developers can see that the rule is locked by that operator and cannot overwrite it.
• Once edits and unit testing are complete, the developer performs a Check-in, supplying a mandatory audit note explaining the business rationale. The engine merges the changes back into the unlocked target ruleset version, making the updated rule visible to the entire team.

---

7. Relevant Records

The Application Development objectives pair "create and maintain rules, rulesets, classes, inheritance" with relevant records, and the two belong together: rulesets and classes decide where a rule lives, while relevant records decide which rules a low-code author is offered when they build.

What a Relevant Record Is

Relevant records for a case type are references to the rules that are explicitly important to that case — fields (properties), views (sections), processes (flows), and user actions (flow actions). Marking a rule relevant does not change what it does; it changes its discoverability in the guided, low-code authoring experience.

Without relevant records, a case type in a mature application exposes every inherited property and section in the class hierarchy, and an App Studio author picking a field to add to a form has to choose from hundreds of candidates. With them, the author sees the curated set the architect intended for reuse.

How Records Become Relevant

To review what is currently relevant for a class, in Dev Studio click Configure > Application > Inventory > Relevant Records and enter the class of a case type or data type in the Class Name field.

Why It Matters at Run Time of the Project

• Processes and user actions marked as relevant appear in prompts for case-type settings, which is how the platform steers authors toward reuse rather than toward a new copy.
• Views marked as relevant appear as reusable views when an author configures a step.

That is the practical connection to Section 12.2: the Reuse Library and the modular layer cake decide what should be reused, and relevant records are one of the mechanisms that make the reusable asset show up at the moment of choice.