ExamFinch.com My Study

Study guide

7.1 Rulesets, Versioning & Ruleset Stack Hierarchy

Practice this exam

Pegasystems Certified Pega System Architect CSA

Track your progress as you read

Finished sections get a check mark.

1 Chapter 1: Exam Overview & Architecture Foundations

1.1 Certified Pega System Architect Exam Format, Blueprint & Strategy 1.2 Pega Architecture & Enterprise Class Structure (ECS) 1.3 Studio Environments: App Studio, Dev Studio, Admin Studio & Prediction Studio

2 Chapter 2: Case Lifecycle Design & Core Workflows

2.1 Case Types, Stages, Processes, and Steps 2.2 Routing Strategies: Worklists, Work Queues, and Teams 2.3 Service Level Agreements (SLAs) & Urgency Calculations

3 Chapter 3: Advanced Case Management Patterns

3.1 Multi-Step Processes, Parallel Processing & Sub-processes 3.2 Child Cases, Data Propagation & Wait Steps 3.3 Optional Actions, Approvals & Case Resolution 3.4 Duplicate Case Detection, Automation Shapes & Automated Correspondence

4 Chapter 4: Data Modeling & Data Page Architecture

4.1 Data Objects, Property Modes & Page Types 4.2 Data Pages: Scope, Types & Refresh Policies 4.3 Data Transforms & Object Mapping

5 Chapter 5: Business Logic, Calculations & Decisioning

5.1 Declare Expressions & Declarative Network Chaining 5.2 Decision Tables & Decision Trees 5.3 Integration Connectors, Systems of Record & Error Handling

6 Chapter 6: User Interface & User Experience Design

6.1 Traditional UI vs Constellation Architecture 6.2 Views, Dynamic Layouts, Design Templates & Action Sets 6.3 Form Validation, Edit Validate & WCAG Accessibility 6.4 Form Views: Default vs Hierarchical Forms, Field Groups & Primary Fields

7 Chapter 7: Rule Architecture & Rule Resolution

7.1 Rulesets, Versioning & Ruleset Stack Hierarchy 7.2 The Rule Resolution Algorithm 7.3 Circumstancing & Rule Specialization

8 Chapter 8: Security & Access Control

8.1 Authentication, Operator Records & Access Groups 8.2 Role-Based Access Control: Access Roles, ARO & Privileges 8.3 Attribute-Based Access Control (ABAC), Encryption & Audit Trails 8.4 The Security Checklist & Secure Deployment

9 Chapter 9: DevOps, Testing & Application Quality

9.1 Guardrail Compliance, Best Practices & Performance Profiling 9.2 Automated Testing: Pega Unit Test Cases & Scenario Testing 9.3 Packaging, Branching & Deployment Manager CI/CD

10 Chapter 10: Reporting & Operational Analytics

10.1 Report Definitions: Querying, Columns, Summaries & Joins 10.2 Filtering, Parameters & Column Exposure Optimization 10.3 Insights, Visual Dashboards & Business Metrics

11 Chapter 11: Mobility, Digital Channels & Portals

11.1 Mobile Channel Configuration & Offline Processing 11.2 Web Mashup, Digital Channels & Constellation Embed 11.3 Channels, Personas, Portals & Landing Pages

12 Chapter 12: Center-out Architecture, Enterprise Reuse & Agile Delivery

12.1 Center-out Business Architecture & the Case for Pega 12.2 The Situational Layer Cake, Modules & Enterprise Reuse 12.3 Agile Workbench, Workspaces, Branches, Delivery Roles & the Estimator

13 Chapter 13: Pega GenAI for System Architects

13.1 Pega Blueprint: Creating, Importing & Modifying an Application Design 13.2 Pega GenAI Autopilot & Pega GenAI Coach 13.3 Pega GenAI Connect Rules, Knowledge Buddy, Agents & Tool Rules

7.1 Rulesets, Versioning & Ruleset Stack Hierarchy

Key Takeaways Explain This Topic AI

In Pega, a rule is an object-oriented building block defining application behavior, data structures, and user experiences, stored as an XML/BLOB record with exposed index columns in the PegaRULES database.

Rulesets function as versioned business containers using a three-segment versioning structure (Major-Minor-Patch: NN-NN-NN), secured through version locking and streamlined via Skimming.

Application Validation (AV) eliminates cyclical dependency deadlocks inherent in Ruleset Validation (RV) by validating rules against the complete application ruleset stack rather than hardcoded prerequisite chains.

The runtime Ruleset Stack is assembled at authentication from the Operator ID, Access Group, and Application records and evaluated top to bottom, while production rulesets let delegated business users change operational rules such as decision tables and SLAs without a deployment.

Relevant records mark the properties, views, processes, and user actions that matter for a case type; App Studio marks records it creates automatically, and Dev Studio can mark a record manually with Actions > Mark as relevant record.

Last updated: September 2026

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 |
  • +-------------------------------------------------------------------------+

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.

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.

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:

Ruleset Type Purpose & Scope Environment / Lifecycle

Standard Application Ruleset Contains core business processes, case types, UI views, data models, and logic specific to an application. Configured on the Application rule; promoted across Dev -> Stage -> Prod.

Shared / Enterprise Ruleset Contains reusable enterprise assets (e.g., corporate data types, enterprise integration connectors, compliance logic) shared across multiple lines of business in the Enterprise Class Structure (ECS). Lives in the Organization or Division layer; governed centrally by an enterprise architecture team.

Production Ruleset Contains rules that authorized business users or system administrators must modify directly in a Production environment without requiring a code deployment or server restart. Configured on the Application rule and Access Group; left unlocked in production for dynamic operational rules (e.g., Decision Tables, SLAs, Correspondence).

Branch Ruleset A lightweight, sandboxed container used by agile development teams to isolate work on specific user stories or defects without impacting the base ruleset. Created temporarily in Dev; merged into the base ruleset version upon code review and guardrail verification, then deleted.

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.

Dimension Ruleset Validation (RV) Application Validation (AV)

Prerequisite Definition Explicitly declared on each ruleset version record Implicitly derived from the Application record's ruleset stack

Circular Dependencies Strictly forbidden; causes save-time validation errors Supported seamlessly among sibling rulesets in the same application

Maintenance Overhead High; manual version bumping required on prerequisite lists Low; managed centrally through the Application rule definition

Primary Recommended Use Shared component rulesets, libraries, and core Pega engine All enterprise line-of-business application rulesets

Rule Reference Scope Only itself, lower versions, and listed prerequisites Any ruleset at or below its position in the application stack

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):

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.

Branch Rulesets: Active branch rulesets associated with the developer's current application and access group appear immediately below the personal ruleset.

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.

Application Rulesets: Rulesets explicitly listed on the user's primary Application rule, evaluated from the top of the application list to the bottom.

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.

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.

Loading diagram... Ruleset Stack Assembly and Validation Hierarchy

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

Path Mechanism Typical use

Automatic Pega Platform automatically marks records you create in App Studio — properties, for example — as relevant to the appropriate context Ordinary low-code authoring; no action required

Manual In Dev Studio, open the record, open the Actions menu, and click Mark as relevant record Promoting a rule an architect built in Dev Studio so App Studio authors can reuse it

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.