Introduction

Pega rules are broadly categorized into two types: Versioned and Non-Versioned. While most of the application's core logic resides in Versioned Rules (which are safely managed through RuleSet versions and controlled deployments), a critical set of configuration and security settings are managed by Non-Versioned Rules. These rules are not tied to a specific version number.

Rules and Best Practices: The Non-Versioned Landscape

Terminology Note: In Pega terminology, these are primarily called 'data instances' rather than 'non-versioned rules,' though this article uses the term 'non-versioned rules' colloquially to distinguish them from versioned rules.

Non-versioned rules are essentially the configuration backbone of a Pega application. They define how the application connects to external systems, who can access it, and what system-wide parameters control its behavior. Because they bypass the standard versioning and rule resolution process, they are ideal for environment-specific settings but pose a higher risk if managed carelessly.

The Critical Distinction: Versioned vs. Non-Versioned

Understanding the distinction between these two types is crucial for effective system architecture and deployment planning.

Common Types of Non-Versioned Rules

Non-versioned rules primarily belong to the `Data-Admin-` class hierarchy and manage the administrative and operational aspects of the Pega application.

1. Security and Access Configuration:

• Operators (Data-Admin-Operator-ID): User accounts that access the Pega application.
• Access Groups (Data-Admin-Security-AccessGroup): Define user permissions and access rights.
• Access Roles (Data-Admin-Security-AccessRole): Define sets of privileges.

2. Organizational Structure:

• Organizations (Data-Admin-OrgUnit): Organizational hierarchy for work routing and access control.
• Organizational Units: Subdivision of organizational structures.

3. System Configuration and Integration:

• Dynamic System Settings (DSS): Application-wide configuration values.
• Database Instances (Data-Admin-DB-Name): Database connection configurations.
• Data Instances for Connectors/Services (Data-Admin-Connect- types): Hold environment-specific details like endpoint URLs and authentication profiles.

4. Operational Configuration:

• Job Schedulers (Data-Admin-JobScheduler): Scheduled background processes.
• Queue Processors (Data-Admin-Queue-Processor): Asynchronous processing configurations.

Core Best Practices for Governance and Stability

The primary goal of managing non-versioned rules is to ensure stability and traceability. This requires a disciplined approach that treats these rules as operational configuration rather than application code.

1. Treat Non-Versioned Rules as "Live" Production Data

Since changes to these rules are immediate and global, they must be managed with the highest level of caution.

• Development Focus: Implement the highest level of change control for these rules, especially in Staging and Production environments. This includes mandatory peer review, formal approval, and a documented rollback plan for every change.
• Stakeholder Focus: Understand that a change to a non-versioned rule is akin to changing a live database setting—it affects the system immediately. This necessitates a more rigorous approval process than a standard code deployment.
• Use Restore Points: Before making significant configuration changes, always create a restore point. This provides an easy rollback option if the change introduces unexpected issues, minimizing system downtime.

2. Decouple Configuration from Code (Parameterization)

This practice ensures that the core application logic remains consistent across all environments, with only the configuration layer changing.

• Development Focus: Never hardcode environment-specific values (like URLs, passwords, or thresholds) directly into versioned rules. Instead, use non-versioned rules (like DSS or GRS) as a centralized configuration layer.
• Stakeholder Focus: This drastically reduces the risk of environment-specific bugs and simplifies the deployment pipeline, as the application code itself does not need to change for different environments

3. Implement a Separate Deployment Strategy

Non-versioned rules should not be migrated alongside versioned rules in the standard application Product Rule.

• Separate Packaging: Create separate Rule Archive Package (RAP) files for application rules and environment-specific configurations (e.g., operators, access groups). This allows the migration of application logic without overwriting environment-specific settings.
• Dedicated Tools: Non-versioned rules should be managed using dedicated tools like Deployment Manager's Application Configuration feature or Global Resource Settings (GRS). Avoid relying on manual imports or the main Product Rule for these critical settings.
• Careful Import: When using the Import wizard, pay meticulous attention to the manifest to ensure you are not accidentally overwriting production-specific data instances, such as Operator IDs, with development settings.

4. Document All Changes and Use Availability Settings Strategically

Since non-versioned rules do not maintain version history in the same way as application rules, documentation and lifecycle management are crucial.

• Thorough Documentation: Maintain documentation of what was changed, when it was changed, who made the change, and why the change was necessary. This is vital for troubleshooting and auditing.
• Leverage Availability Settings: Use rule availability settings (Available, Not Available, Blocked, Final, Withdrawn) to control the lifecycle:
  • Use Final status for core configurations that should never be overridden.
  • Mark deprecated configurations as Withdrawn rather than deleting them immediately, allowing dependent rules to continue functioning until they are updated.
• Use Availability Dates for Controlled Rollout: For configuration changes that need to take effect at a specific time (e.g., scheduled maintenance or phased feature enablement), use availability dates rather than versioning.

Detailed Best Practices for Key Non-Versioned Rule Types

1. Dynamic System Settings (DSS)

DSS rules are the most flexible mechanism for storing system-wide configuration values.

• Purposeful Naming: Use a clear, hierarchical naming convention: OwningRuleset.SettingName. This prevents conflicts and clearly identifies the owner. Example: MyCo-FW-App.MaxCaseAttachmentSize.
• Environment-Specific Values: Utilize the System Name key part to define different values for the same setting across environments (e.g., Dev, QA, Prod). This is essential for managing environment-specific configurations without changing the rule itself.
• Minimize Usage: Over-reliance on DSS can lead to "configuration sprawl." Prefer System Settings (versioned rules) for values that do not change across environments or Data Pages for data that is frequently accessed and cached.

2. Security and Access Rules (Operator IDs and Access Groups)

These rules are the foundation of the application's security model. Ignoring access control or managing these manually is a major security risk.

• Automated Provisioning: In higher environments, Operator IDs should be managed by an external system (e.g., LDAP, SAML, or an HR system) and provisioned/updated via an automated process. Manual creation is slow, error-prone, and creates security gaps.
• Role-Based Access Control (RBAC): All permissions must be managed through Access Roles (versioned rules) and assigned to a minimal set of Access Groups. The Operator ID should only link the user to the appropriate Access Group. Avoid creating one-off Access Groups for individuals.
• Regular Audits: Regularly audit access groups and operator permissions to ensure compliance and remove stale or excessive privileges.
• Decouple Routing from Users: Use Work Groups (Data-Admin-WorkGroup) for routing and reporting purposes, and link them to the Operator ID. This improves business agility, as changes to team structure only require updating the Work Group, not individual user accounts.

3. Data Instances for Integration (Data-Admin-Connect- types)

These rules hold environment-specific details for connecting to external systems.

• Parameterize Endpoints: Never hardcode URLs or credentials directly in the Data Instance. Use Global Resource Settings (GRS) or Dynamic System Settings (DSS) to store the environment-specific values. This ensures the application automatically connects to the correct endpoint in each environment.
• Use Authentication Profiles: Decouple authentication details from the connector/service instance by using Authentication Profiles (Data-Admin-Security-AuthenticationProfile). This allows for centralized, secure management of credentials, often referencing a secure credential store (e.g., Pega's built-in Keystore).
• Prioritize GRS: For modern Pega versions (Pega 24/Constellation), prioritize Global Resource  Settings over DSS for integration endpoints, as GRS is specifically designed for this purpose and offers better governance.

Migration and Deployment Considerations

Non-versioned rules require special handling during application migration to avoid overwriting critical environment-specific configurations.

What to Migrate (Application-Specific)

These are data instances that should be consistent across all environments:

• Application-specific data instances that are consistent across environments.
• Reference data and lookup tables that support business logic.
• Organizational structures that are standardized.

What NOT to Migrate (Keep Environment-Specific)

These configurations must be managed separately for each environment:

• Operator IDs and passwords.
• Environment-specific access groups.
• Database connection strings.
• Job scheduler configurations (timing may differ by environment).
• Queue processor settings.
• Environment-specific dynamic system settings.

Migration Strategy

1.  Export application rules and shared data instances as one package.

2.  Export environment-specific configurations as separate packages.

3.  Import application package to the target environment.

4.  Manually configure or selectively import environment-specific settings.

5.  Validate that environment-specific settings are correct after import.

6.  Test thoroughly in lower environments before production deployment.

Common Pitfalls to Avoid

Ignoring these common mistakes can lead to significant deployment failures, security vulnerabilities, and system instability:

• Accidentally Overwriting Production Operators: This is a frequent mistake when importing a RAP file. Always review the import manifest carefully to prevent overwriting live operator records with development settings.
• Ignoring Access Control: Allowing too many users to modify critical non-versioned rules like access groups and security settings without proper governance. This is a major security and compliance risk.
• Forgetting Dependencies: Non-versioned rules often reference each other (e.g., operators reference access groups). Breaking these dependencies during migration causes immediate access issues.
• Lack of Documentation: Since non-versioned rules don't maintain the same version history, failing to document changes makes troubleshooting difficult and time-consuming.
• Not Accounting for Environment Differences: Assuming that database connections, queue processors, and other configurations can be migrated as-is between environments.

Conclusion

Non-versioned rules are the nervous system of a Pega application. They are the essential link between the application's code and its operating environment. For both the development team and business stakeholders, a shared understanding of these rules is crucial.

By adopting best practices centered on strict governance, parameterization, and decoupled deployment, organizations can harness the power of non-versioned rules to create Pega applications that are not only robust and secure but also highly agile and adaptable to the ever-changing demands of the business. This disciplined approach is the foundation for a successful, low-risk Pega deployment strategy in any environment, across all recent Pega Platform versions.

References

• Pega Documentation: Rule resolution - https://docs.pega.com/bundle/platform/page/platform/app-dev/rule-resolu…
• Pega Documentation: Organizing Rules into classes - https://docs.pega.com/bundle/deployment-manager/page/platform/app-dev/o…
• Pega Documentation: Database data instances - https://docs.pega.com/bundle/platform-23/page/platform/system-administr…
• Pega Documentation: Moving applications between systems - https://docs.pega.com/bundle/deployment-manager/page/platform/system-ad…
• Pega Academy: Setting rule status and availability - https://academy.pega.com/topic/setting-rule-status-and-availability/v2
• Pega Documentation: Global Resource Settings (GRS) and Authentication Profiles - https://docs.pega.com/bundle/deployment-manager/page/platform/reference…
• Pega Documentation: System administration overview - https://docs.pega.com/bundle/platform/page/platform/system-administrati…