Rule Versioning and Change Management

Introduction

Changing production validation rules without proper version control and testing creates significant risk. A seemingly minor logic modification can break order processing, allow non-compliant transactions, or create compliance violations. Without version history, rolling back broken changes requires recreating previous logic from memory. Without change tracking, audit trails are incomplete and troubleshooting is difficult.

Effective rule change management requires version control (maintaining snapshots of validation sets over time), comprehensive testing before deployment (unit, integration, UAT, and performance testing), documented approval workflows, and rollback capabilities for immediate recovery when issues occur.

This guide explains version numbering schemes (Major.Minor.Patch), version storage options (duplicate validation sets, file exports, Git repositories), testing processes before deployment, deployment and rollback procedures, change approval workflows categorized by risk, and audit trail requirements for compliance.

Change management components:

• Version control and numbering (Major.Minor.Patch)

• Version storage (validation set copies, exports, Git)

• Testing phases (unit, integration, UAT, performance)

• Deployment and rollback procedures

• Approval workflows by change category

• Audit trails for compliance

Part 1: Understanding Rule Versions

What is a Rule Version?

A version is a snapshot of a validation set at a specific point in time.

Version components:

• Validation set configuration

• All rules inside the set

• Conditions and formulas

• Actions and parameters

• Source References

• Timestamps

• Author information

• Change description

Version example:

Why Versioning Matters

Without versioning:

• Can't see what changed over time

• Can't roll back broken changes

• Can't compare versions to debug

• No audit trail (compliance risk)

• No change history (knowledge lost)

With versioning:

• Every change is tracked

• Instant rollback to any version

• Compare versions side-by-side

• Complete audit trail

• Team sees change history

Version Numbering Scheme

Format: Major.Minor.Patch

Major version (1.0 → 2.0):

• Significant functionality change

• New business rules added

• Behavior significantly different

• Requires retesting all scenarios

Minor version (1.1 → 1.2):

• Small improvements

• Additional conditions

• Refined logic

• Backward compatible

Patch version (1.1.1 → 1.1.2):

• Bug fixes

• Performance optimizations

• No logic changes

• Safe to deploy immediately

Examples:

✓ Checkpoint: Versions create a safety net and audit trail for every change

⏱️

Part 2: Creating and Managing Versions

Before Making Any Change: Create a Version

Version creation process:

Step 1: Document current state

Step 2: Export/Save current version

• Make a copy of the validation set

• Name it with version: "Sales Order - Credit Limit Checks - v2.0"

• Or export to file: "Sales-Order-Credit-Checks-v2.0-2024-11-15.json"

• Store in version control repository or SharePoint

Step 3: Create version log entry

Step 4: Make changes

• Modify the active validation set

• Increment version number: v2.0 → v2.1

• Update validation set description with new version

Step 5: Document changes

VERSION LOG:
v2.1 (Active)
  Created: 2024-12-01
  Author: John Smith
  Description: Added check for credit hold status
  Rules: 4 (added credit hold check)
  Status: Testing
  Changes from v2.0:
    - Added rule "Check Customer Not On Credit Hold"
    - Modified condition to include hold status [18:24]

Version Storage Options

Option 1: Duplicate validation sets

Pros: Easy to access, built into Business Central, can activate instantly Cons: Clutters validation set list

Option 2: Export to file system

File Structure:
\\

Pros: Clean BC environment, standard file versioning Cons: Must re-import to rollback

Option 3: Git repository

Git Repo: qualia-rules
  /sales/
    credit-limit-checks.json
  
Git history:
  commit 3f8a1b2 (HEAD -> main) 2024-12-01 - Added credit hold check [v2.1]
  commit 7e9c4d5 2024-11-15 - Added outstanding balance aggregate [v2.0]
  commit 2a6f8e1 2024-03-22 - Added payment terms exception [v1.1]
  commit 9d3b7c4 2024-01-15 - Initial credit limit check [v1.0]

Pros: Professional version control, diff/merge tools, collaboration Cons: Requires Git knowledge, setup overhead

Recommended approach: Combination of all three

• Use Option 1 for quick rollback (keep last 2 versions as archived sets)

• Use Option 2 for long-term storage (export all versions)

• Use Option 3 if team is technical (Git for advanced scenarios)

Version Documentation Template

Include in validation set description:

✓ Checkpoint: Every version documented, saved, and retrievable

⏱️

Part 3: Testing Before Deployment

The Testing Process

Don't deploy to production without testing:

Test Environment Setup:

1. Separate Business Central environment (sandbox)

2. Copy of production data (sanitized)

3. Test validation sets separate from production

Testing phases:

Phase 1: Unit Testing (Developer)

Phase 2: Integration Testing (Developer + Business)

Phase 3: User Acceptance Testing (Business Users)

Phase 4: Performance Testing (Developer)

Testing Checklist

Before deploying any rule change:

• Unit test each rule individually

• Integration test full validation set

• Test happy path (should work correctly)

• Test edge cases (exactly at limits, zero values, null values)

• Test exceptions (special cases that should bypass)

• Test error messages (clear and helpful?)

• UAT with actual business users

• Performance test with production data volumes

• Compare with previous version (regression test)

• Document test results

• Get business approval

• Schedule deployment

Only deploy if all tests passed.

Comparison Testing (New vs. Old)

Test both versions side-by-side:

Test Scenario: Customer with $40K limit, $25K outstanding, new $18K order

OLD VERSION (v2.0):
  Condition: [36:109] > [18:59]
  Result: Checks $18K > $40K = FALSE, allows posting
  Issue: Doesn't consider outstanding balance!
  
NEW VERSION (v2.1):
  Condition: ([36:109] + SUM(36:109)) > [18:59]

Regression testing:

• Test cases that worked in old version still work in new version

• Ensure new features don't break existing functionality

✓ Checkpoint: Thorough testing catches bugs before they reach production

⏱️

Part 4: Deployment and Rollback

Deployment Process

Production deployment steps:

Step 1: Pre-deployment checklist

• All tests passed

• Business approval obtained

• Version documented

• Previous version archived/saved

• Rollback plan ready

• Deployment window scheduled (low-usage time)

• Team notified (developers, business users, helpdesk)

Step 2: Backup current production version

Step 3: Deploy new version

Step 4: Verification testing (in production)

Step 5: Monitor initial usage

Step 6: Post-deployment

Rollback Procedures

When to rollback:

• Rule is blocking legitimate transactions

• Performance is unacceptable (>1000ms)

• Errors in Validation Log

• Business logic is incorrect

• User complaints about unexpected behavior

Immediate rollback (emergency):

Planned rollback (non-emergency):

Rollback example:

✓ Checkpoint: Smooth deployment and instant rollback minimize risk

⏱️

Part 5: Change Approval Workflow

Approval Process for Rule Changes

Change categories:

Category 1: Emergency fixes (fast-track)

• Production is broken

• Immediate business impact

• Approval: IT Manager + verbal business owner approval

• Deploy immediately, document after

Category 2: Standard changes (normal approval)

• New rules

• Modified logic

• Performance improvements

• Approval: Business owner + IT manager

• Timeline: 3-5 days (testing + approval)

Category 3: Major changes (extended approval)

• Complete redesign

• New business processes

• Affects multiple departments

• Approval: Business owner + IT manager + department heads + compliance

• Timeline: 2-4 weeks (testing + approvals + communication)

Approval Template

Change Request Form:

RULE CHANGE REQUEST

Request ID: CR-2024-137
Date: 2024-12-01
Requestor: Sarah Lee (Finance Manager)
Priority: Normal

CHANGE DETAILS:
Validation Set: Sales Order - Credit Limit Checks - BeforePost
Current Version: 2.0
Proposed Version: 2.1
Change Type: Add new rule

BUSINESS JUSTIFICATION:
Customer on credit hold status not currently checked. Finance has seen orders
posted for customers who should be on hold. Need to add this check to prevent
further occurrences.

TECHNICAL DETAILS:
Add new rule: "Check Customer Not On Credit Hold"
  Condition: [18:24]

Tracking Changes

Change log spreadsheet:

✓ Checkpoint: Formal approval process ensures controlled, documented changes

⏱️

Part 6: Audit Trail and Compliance

What to Track for Compliance

For each rule change, document:

1. Who: User who made the change

2. What: Exactly what changed (before/after)

3. When: Date and time of change

4. Why: Business justification

5. Approval: Who approved

6. Testing: What testing was performed

7. Results: Success or rollback

Audit Report Example

Compliance Audit Report: Q4 2024

Retention Requirements

Keep version history for:

• Sarbanes-Oxley (SOX): 7 years for financial controls

• GDPR: 6 years if rules process personal data

• Industry-specific: Check your requirements

• General best practice: Keep all versions indefinitely (storage is cheap)

What to retain:

• All version exports (JSON files)

• Version documentation

• Change request forms

• Approval records

• Test results

• Deployment logs

• Rollback records

• Incident reports

✓ Checkpoint: Complete audit trail meets compliance requirements

⏱️

Wrap-Up and Next Steps

What you've learned:

• ✓ Rule versioning with Major.Minor.Patch numbering

• ✓ Version storage (duplicate sets, exports, Git)

• ✓ Comprehensive testing before deployment

• ✓ Deployment process with verification

• ✓ Rollback procedures (<2 minutes to revert)

• ✓ Change approval workflow (categorized by risk)

• ✓ Audit trail for compliance

What you can do now:

• Create version backups before any change

• Test thoroughly in test environment

• Document every version with change log

• Deploy during low-usage windows

• Keep rollback version ready

• Track all changes in change log

• Maintain audit trail for compliance

Versioning workflow:

1. Document current version

2. Save backup (export or duplicate set)

3. Make changes (increment version number)

4. Test thoroughly (unit, integration, UAT, performance)

5. Get approval (business + IT)

6. Deploy during scheduled window

7. Verify and monitor

8. Document deployment

9. Keep backup for 30-day rollback window

10. Archive old versions for compliance

Emergency rollback:

1. Disable broken version (<30 seconds)

2. Enable previous version (<30 seconds)

3. Verify working (<1 minute)

4. Total time: <2 minutes

Next blog: Industry-Specific Solutions (Manufacturing Rules)

Implementation exercise: Set up versioning for one critical validation set:

1. Choose your most critical validation set

2. Document current state (version 1.0)

3. Export/save it as backup

4. Make a small test change

5. Increment to version 1.1

6. Test the change

7. Deploy to test environment

8. Practice rollback (disable 1.1, enable 1.0)

9. Document the process Goal: Complete version → change → test → deploy → rollback in <30 minutes

Pro Tips:

💡 Always save before changing: 30 seconds to backup saves hours of recovery

💡 Version in the name: "v2.1" in description makes versions instantly visible

💡 Test with production data: Development data doesn't catch real-world issues

💡 Deploy off-hours: 6 AM deployments have 90% fewer issues than 2 PM

💡 Keep last version active: Instant rollback beats re-importing from file

💡 Document rollback steps: In emergency, you won't remember the process

💡 Practice rollback: Test your rollback process before you need it

Related Resources:

• Blog 034: Rule Set Organization (organizing versions)

• Blog 033: Performance Optimization (testing performance)

• Blog 032: Testing and Debugging (testing procedures)

• Microsoft Dynamics 365 Business Central Application Lifecycle Management

• QUALIA Rule Engine Change Management Guide

Questions? Start with your most critical rule. Save a backup right now. Then practice deploying a small change. The process becomes second nature after 3-4 deployments, and you'll never fear changing rules again.

This blog is part of the QUALIA Rule Engine series for Microsoft Dynamics 365 Business Central. Follow along as we explore progressively advanced features.