bc-code-intelligence-mcp 1.1.1

package/embedded-knowledge/domains/dean-debug/no-series-validation-module-bc24.md

@@ -0,0 +1,246 @@
+---
+title: "No. Series Validation Module Patterns (BC24+)"
+domain: "dean-debug"
+difficulty: "intermediate"
+bc_versions: "24+"
+tags: ["no-series-validation", "business-foundation", "module-validation", "bc24-migration", "data-integrity"]
+prerequisites: ["no-series-module-patterns-bc24", "validation-frameworks", "business-foundation-architecture"]
+samples: "samples/no-series-validation-module-bc24.md"
+related_topics: ["no-series-module-patterns-bc24", "no-series-validation-patterns", "bc24-migration-patterns"]
+---
+
+# No. Series Validation Module Patterns (BC24+)
+
+## Overview
+
+The new No. Series module in BC24+ provides enhanced validation capabilities through the Business Foundation layer. These patterns leverage the improved validation methods and modular architecture to ensure number sequence integrity with better performance and clearer error handling.
+
+**Key Benefit**: Utilizes the new No. Series module's built-in validation capabilities for more reliable and maintainable number sequence validation with enhanced error reporting.
+
+## New Validation Architecture
+
+### Business Foundation Integration
+The No. Series module provides native validation methods that integrate seamlessly with the Business Foundation layer's error handling and logging systems.
+
+### Enhanced Validation Methods
+New dedicated validation methods replace complex custom validation logic:
+- Built-in format validation
+- Automatic relationship validation
+- Improved error messaging and diagnostics
+
+### Modular Validation Design
+Validation is now distributed across focused codeunits rather than centralized in legacy NoSeriesManagement.
+
+## Essential Validation Patterns
+
+### Number Format Validation
+**Legacy Pattern (BC14-23)**:
+```al
+// Custom validation logic required
+if not NoSeriesMgt.CheckFormat("No.", "No. Series") then
+    Error('Invalid format');
+```
+
+**New Pattern (BC24+)**:
+```al
+if not NoSeries.IsValidNo("No.", "No. Series") then
+    Error('Number %1 is not valid for series %2', "No.", "No. Series");
+```
+
+### Series Existence Validation
+**New Pattern (BC24+)**:
+```al
+NoSeries.VerifySeriesExists("No. Series");
+```
+
+### Manual Number Validation
+**Legacy Pattern**:
+```al
+NoSeriesMgt.TestManual("No. Series");
+if not NoSeriesMgt.ManualNoAllowed("No. Series") then
+    Error('Manual numbers not allowed');
+```
+
+**New Pattern**:
+```al
+NoSeries.TestManual("No. Series");
+// Built-in error handling provides clear messaging
+```
+
+### Series Relationship Validation
+**New Pattern (BC24+)**:
+```al
+if not NoSeries.AreRelated(CurrentSeries, NewSeries) then
+    Error('Series %1 and %2 are not related', CurrentSeries, NewSeries);
+```
+
+## Advanced Validation Integration
+
+### Batch Validation
+Utilize NoSeriesBatch for validating multiple number allocations:
+```al
+// Validate batch allocation feasibility
+if not NoSeriesBatch.CanAllocateNumbers("No. Series", RequiredCount) then
+    Error('Cannot allocate %1 numbers from series %2', RequiredCount, "No. Series");
+```
+
+### Date-Based Validation
+Leverage enhanced date validation in the new module:
+```al
+if not NoSeries.IsValidForDate("No. Series", "Posting Date") then
+    Error('Series %1 is not valid for date %2', "No. Series", "Posting Date");
+```
+
+### Cross-Series Validation
+```al
+// Validate consistency across related series
+NoSeries.ValidateRelatedSeries("Primary Series", "Related Series");
+```
+
+## Migration from Legacy Validation
+
+### Obsolete Validation Patterns
+**Remove Legacy Patterns**:
+- Custom format checking logic
+- Manual series relationship validation
+- Complex date range validation
+- Direct table validation queries
+
+**Replace with Module Methods**:
+- Use built-in `IsValidNo()` for format validation
+- Use `AreRelated()` for relationship checking
+- Use `TestManual()` for manual number validation
+- Use `VerifySeriesExists()` for existence checking
+
+### Event Migration Strategy
+**Obsolete Events** (no direct replacement):
+- OnBeforeGetNextNo events
+- OnAfterGetNextNo events
+- Custom validation events in NoSeriesManagement
+
+**New Approach**:
+```al
+// Implement validation through direct method calls
+// Use error handling for validation failures
+// Leverage module's built-in logging capabilities
+```
+
+## Enhanced Error Handling
+
+### Improved Error Messages
+The new module provides more descriptive error messages with context:
+```al
+// Automatic error context from module
+NoSeries.GetNextNo("No. Series", WorkDate());
+// Provides detailed error if series is invalid, exhausted, or misconfigured
+```
+
+### Structured Exception Handling
+```al
+if not NoSeries.TryGetNextNo(NextNo, "No. Series", WorkDate()) then begin
+    // Handle specific validation failure scenarios
+    HandleNumberGenerationError("No. Series");
+end;
+```
+
+### Validation Result Processing
+```al
+ValidationResult := NoSeries.ValidateSeriesConfiguration("No. Series");
+if not ValidationResult.Success then
+    ProcessValidationErrors(ValidationResult);
+```
+
+## Performance-Optimized Validation
+
+### Reduced Database Queries
+The new module optimizes validation with fewer database round-trips:
+```al
+// Single call validates multiple aspects
+if NoSeries.IsReadyForGeneration("No. Series", WorkDate()) then
+    ProcessNumberGeneration();
+```
+
+### Cached Validation Results
+```al
+// Module handles caching internally
+// Repeated validation calls are optimized
+for i := 1 to DocumentCount do
+    NoSeries.GetNextNo("No. Series", WorkDate()); // Cached validation
+```
+
+### Batch Validation Optimization
+```al
+// Validate entire batch before processing
+ValidationResults := NoSeriesBatch.ValidateBatchAllocation("No. Series", BatchSize);
+if ValidationResults.AllValid then
+    ProcessBatch();
+```
+
+## Integration with Business Processes
+
+### Transaction Validation
+```al
+// Validate number series within transaction context
+NoSeries.ValidateForTransaction("No. Series", TransactionDate);
+```
+
+### Multi-Company Validation
+```al
+// Enhanced support for multi-company scenarios
+NoSeries.ValidateAcrossCompanies("No. Series", CompanyList);
+```
+
+### Audit Trail Integration
+```al
+// Built-in audit trail support
+NoSeries.LogValidationActivity("No. Series", ValidationAction::Validate);
+```
+
+## Best Practices for BC24+
+
+### Leverage Built-In Validation
+- Use module's native validation methods instead of custom logic
+- Trust the module's error handling and messaging
+- Utilize built-in logging and audit capabilities
+
+### Simplify Validation Logic
+- Remove complex custom validation patterns
+- Focus on business-specific validation requirements
+- Let the module handle technical validation aspects
+
+### Error Handling Strategy
+- Implement graceful degradation for validation failures
+- Provide business-friendly error messages
+- Use try-methods for scenarios where validation failure is expected
+
+## Common Migration Pitfalls
+
+### Over-Validation
+Avoid duplicating validation that the new module already performs internally.
+
+### Event Dependency
+Don't rely on obsolete events - redesign validation logic using direct method calls.
+
+### Custom Table Access
+Avoid direct table manipulation - use module methods for all series operations.
+
+## Testing Validation Migration
+
+### Functional Validation Testing
+- Verify all validation scenarios work with new module methods
+- Test error handling and messaging improvements
+- Validate performance improvements in validation-heavy scenarios
+
+### Integration Testing
+- Test validation integration with existing business processes
+- Verify compatibility with custom validation requirements
+- Test cross-series validation scenarios
+
+### Regression Testing
+- Ensure existing validation behavior is preserved
+- Test edge cases and error conditions
+- Validate performance under load
+
+*Complete BC24+ validation examples: samples/no-series-validation-module-bc24.md*
+*Core module patterns: no-series-module-patterns-bc24.md*
+*Migration guidance: bc24-no-series-conversion-guide.md*

package/embedded-knowledge/domains/dean-debug/no-series-validation-patterns.md

@@ -0,0 +1,107 @@
+---
+title: "No Series Validation Patterns"
+domain: "dean-debug"
+difficulty: "intermediate"
+bc_versions: "14..23"
+tags: ["no-series-validation", "data-validation", "integrity-checking", "error-prevention"]
+prerequisites: ["no-series-implementation-patterns", "validation-frameworks", "error-handling"]
+samples: "samples/no-series-validation.md"
+related_topics: ["no-series-implementation-patterns", "data-integrity-patterns"]
+---
+
+# No Series Validation Patterns
+
+## Overview
+
+No Series Validation Patterns provide comprehensive approaches for validating number sequences, ensuring data integrity, and preventing common numbering issues in Business Central applications. These patterns help maintain sequence integrity and compliance with business rules.
+
+**Key Benefit**: Ensures number sequence integrity and compliance through systematic validation that prevents data corruption and maintains business rule adherence.
+
+## Core Validation Architecture
+
+### Multi-Layer Validation Strategy
+Implement validation at multiple layers including input validation, business rule validation, and integrity validation to ensure comprehensive coverage.
+
+### Real-Time vs. Batch Validation
+Design validation strategies that balance real-time validation for immediate feedback with batch validation for comprehensive integrity checking.
+
+### Validation Result Management
+Create systems for managing validation results, tracking issues, and coordinating resolution efforts across different validation scenarios.
+
+## Essential Validation Patterns
+
+### Format Validation
+Implement validation patterns that ensure generated numbers conform to expected formats, character sets, and length requirements.
+
+### Uniqueness Validation
+Design uniqueness checking that can efficiently validate number uniqueness across large datasets while maintaining performance.
+
+### Sequence Integrity Validation
+Create validation patterns that check for sequence continuity, gap detection, and sequence corruption issues.
+
+## Advanced Validation Techniques
+
+### Cross-Reference Validation
+Implement validation that checks number consistency across related tables and ensures referential integrity in number usage.
+
+### Business Rule Validation
+Design validation patterns that ensure number generation and usage comply with specific business rules and policies.
+
+### Historical Validation
+Create validation capabilities that can check historical number usage and detect retroactive integrity issues.
+
+## Validation Framework Architecture
+
+### Configurable Validation Rules
+- Design validation frameworks that support configurable rules for different numbering scenarios
+- Enable business users to configure validation criteria through setup interfaces
+- Support dynamic validation rule changes without code modification
+- Provide validation rule testing and simulation capabilities
+
+### Validation Pipeline
+Implement sequential validation checks with conditional execution and performance monitoring.
+
+## Core Implementation
+
+### Error Detection & Reporting
+Categorize errors by severity, provide detailed reports, and implement automated issue detection.
+
+### Performance Optimization
+Design efficient algorithms, incremental validation, and intelligent caching for optimal performance.
+
+### Business Process Integration
+Integrate with workflows, support transaction validation, and provide real-time feedback.
+
+## Advanced Capabilities
+
+### Monitoring & Compliance
+Implement metrics collection, health monitoring, and audit trail validation to ensure system reliability and regulatory compliance.
+
+### Regulatory Compliance
+Design validation that supports regulatory compliance requirements for number sequence management and documentation.
+
+### Compliance Reporting
+Create reporting capabilities that demonstrate compliance with numbering policies and regulatory requirements.
+
+## Recovery and Remediation
+
+### Validation Failure Recovery
+Design recovery procedures for scenarios where validation failures indicate data integrity issues requiring correction.
+
+### Automated Remediation
+Implement automated remediation capabilities for common validation issues that can be safely resolved automatically.
+
+### Manual Intervention Support
+Provide tools and procedures for manual intervention in complex validation scenarios requiring human judgment.
+
+## Implementation Guidelines
+
+### Testing & Best Practices
+Design comprehensive testing strategies, implement early validation, provide actionable feedback, and maintain clear documentation.
+
+### Common Pitfalls
+Avoid over-validation, validation gaps, and false positives through balanced design and comprehensive coverage.
+
+*Complete validation implementation examples: samples/no-series-validation.md*
+*No series implementation: no-series-implementation-patterns.md*
+*Data integrity frameworks: data-integrity-patterns.md*

package/embedded-knowledge/domains/dean-debug/odata-query-optimization.md

@@ -0,0 +1,105 @@
+---
+title: "OData Query Performance Optimization"
+domain: "dean-debug"
+difficulty: "advanced"
+bc_versions: "14+"
+tags: ["odata", "query-performance", "api-optimization"]
+samples: "samples/odata-query-optimization.md"
+---
+# OData Query Performance Optimization
+
+## Overview
+
+OData query performance in BC API Pages requires understanding how OData expressions translate to SQL queries and how table structure affects execution performance. Proper optimization techniques can dramatically improve API response times and reduce resource consumption.
+
+The BC platform automatically translates OData queries into SQL operations against the underlying database. Understanding this translation process helps identify optimization opportunities and avoid performance anti-patterns in API implementations.
+
+Query performance varies significantly based on data volume, table structure, indexing strategy, and query complexity. Systematic optimization approaches address these factors to achieve predictable performance characteristics.
+
+## Query Translation Mechanisms
+
+OData filter expressions map to SQL WHERE clauses with varying efficiency depending on filter complexity and available table keys. Simple equality filters on indexed fields provide optimal performance.
+
+Complex filter expressions involving multiple fields, functions, or nested conditions may result in less efficient SQL queries. Understanding the translation patterns helps structure OData queries for optimal database execution.
+
+The BC platform may choose different execution strategies based on available indexes and query complexity. Monitoring actual SQL execution provides insight into optimization opportunities.
+
+## Filter Optimization Strategies
+
+Structure OData filters to leverage available table keys and indexes. Leading filter conditions should target the most selective indexed fields to minimize result set size early in query execution.
+
+Avoid complex expressions in filter conditions that prevent index usage. Simple comparisons perform better than function calls or complex logical combinations that cannot be optimized by the query engine.
+
+Consider the order of filter conditions in complex expressions. The BC query optimizer may not reorder conditions for optimal performance, making condition ordering an important performance factor.
+
+## Projection and Field Selection
+
+Use OData $select queries to limit returned fields to only those required by the API consumer. This reduces network transfer overhead and can improve query performance by avoiding unnecessary field retrieval.
+
+Avoid selecting large text fields, BLOB fields, or complex calculated fields unless specifically required. These field types consume significant resources and can dramatically impact query performance.
+
+Strategic field selection can sometimes influence query execution plans by reducing the data volume processed during query execution and result set construction.
+
+## Sorting and Pagination Performance
+
+OData $orderby operations require careful optimization to avoid performance issues with large result sets. Ensure sort fields have appropriate indexes or are part of existing table key structures.
+
+Implement proper pagination using $skip and $top parameters to limit result set size. Large result sets without pagination can cause timeout issues and resource exhaustion in both BC and API consumers.
+
+Consider the impact of sort operations on temporary storage requirements. Complex sorts on large datasets may require significant temporary storage allocation during query execution.
+
+## Aggregation Query Optimization
+
+OData aggregation queries using $apply operations require special consideration for performance optimization. These queries can be particularly resource-intensive and may benefit from specialized indexing strategies.
+
+Consider using SIFT technology for frequently executed aggregation operations. SIFT provides pre-calculated aggregations that can dramatically improve performance for common aggregation patterns.
+
+Monitor aggregation query performance closely as these operations can consume significant CPU and memory resources, especially with large datasets and complex grouping requirements.
+
+## Expansion and Navigation Performance
+
+OData $expand operations that traverse table relationships require optimization to prevent performance issues. Each expansion level adds complexity and resource requirements to query execution.
+
+Limit expansion depth and scope to only required related data. Deep expansions across multiple table relationships can result in cartesian product scenarios that consume excessive resources.
+
+Consider the performance impact of expanding one-to-many relationships which can dramatically increase result set size and processing requirements.
+
+## Caching and Performance Patterns
+
+Understand BC platform caching behavior for API queries to optimize for cache effectiveness. Repeated queries with identical parameters may benefit from platform-level caching mechanisms.
+
+Design API query patterns that align with BC caching strategies. This may involve structuring queries to maximize cache hit ratios and minimize cache invalidation scenarios.
+
+Consider implementing application-level caching for expensive queries that don't require real-time data. This can significantly reduce database load and improve overall system performance.
+
+## Resource Management
+
+Monitor resource consumption for API queries including CPU utilization, memory usage, and database connection requirements. High-resource queries can impact overall system performance.
+
+Implement appropriate timeout settings for API queries to prevent resource exhaustion from long-running operations. Balance timeout values with legitimate query execution requirements.
+
+Consider connection pooling and resource allocation strategies for high-volume API scenarios. Resource contention can significantly impact query performance under load.
+
+## Performance Testing and Validation
+
+Establish performance baselines for critical API queries under realistic data volumes. Performance characteristics often change dramatically as data volumes increase.
+
+Test query performance with production-like data distributions and volumes. Development environment testing may not reveal performance issues that occur with production data characteristics.
+
+Implement automated performance monitoring for critical API endpoints to detect performance degradation early and enable proactive optimization efforts.
+
+## Troubleshooting Performance Issues
+
+Use BC telemetry and database performance monitoring tools to identify slow-performing queries and understand root cause performance issues.
+
+Analyze actual SQL query execution plans generated from OData queries to identify optimization opportunities and understand query execution characteristics.
+
+Monitor for common performance anti-patterns including table scans, excessive temporary storage usage, and resource contention issues that impact query execution.
+
+## Best Practices
+
+Design OData query patterns based on available table structures and indexing strategies rather than generic OData capabilities. Align query design with underlying database optimization principles.
+
+Balance query functionality with performance requirements. Complex OData queries provide flexibility but may sacrifice performance compared to simpler, more targeted query approaches.
+
+Document performance assumptions and optimization decisions for critical API endpoints. This documentation supports ongoing performance management and troubleshooting efforts.

package/embedded-knowledge/domains/dean-debug/samples/bc24-no-series-conversion.md

@@ -0,0 +1,186 @@
+# BC24 No. Series Conversion Examples
+
+## Complete Conversion Examples
+
+### Sales Document Conversion
+```al
+// BEFORE (BC14-23): Legacy NoSeriesManagement approach
+table 50100 "Sales Document"
+{
+    trigger OnInsert()
+    var
+        NoSeriesMgt: Codeunit NoSeriesManagement;
+    begin
+        if "No." = '' then
+            NoSeriesMgt.InitSeries(GetNoSeriesCode(), xRec."No. Series", 0D, "No.", "No. Series");
+    end;
+
+    procedure GetNoSeriesCode(): Code[20]
+    begin
+        exit('SALES-DOC');
+    end;
+}
+
+// AFTER (BC24+): New No. Series module approach
+table 50100 "Sales Document"
+{
+    trigger OnInsert()
+    var
+        NoSeries: Codeunit "No. Series";
+    begin
+        if "No." = '' then
+            "No." := NoSeries.GetNextNo("No. Series", WorkDate());
+    end;
+
+    procedure GetNoSeriesCode(): Code[20]
+    begin
+        exit('SALES-DOC');
+    end;
+}
+```
+
+### Manual Number Testing Conversion
+```al
+// BEFORE (BC14-23): Multiple method calls for manual testing
+procedure ValidateManualEntry()
+var
+    NoSeriesMgt: Codeunit NoSeriesManagement;
+begin
+    NoSeriesMgt.TestManual("No. Series");
+    if not NoSeriesMgt.ManualNoAllowed("No. Series") then
+        Error('Manual numbers not allowed for series %1', "No. Series");
+end;
+
+// AFTER (BC24+): Single method with built-in logic
+procedure ValidateManualEntry()
+var
+    NoSeries: Codeunit "No. Series";
+begin
+    NoSeries.TestManual("No. Series");
+    // Built-in error handling provides comprehensive validation
+end;
+```
+
+### Number Peek vs Allocation Conversion
+```al
+// BEFORE (BC14-23): Boolean parameter controls behavior
+procedure GetNumberPreview(): Code[20]
+var
+    NoSeriesMgt: Codeunit NoSeriesManagement;
+begin
+    exit(NoSeriesMgt.GetNextNo("No. Series", WorkDate(), false)); // Peek only
+end;
+
+procedure AllocateNumber(): Code[20]
+var
+    NoSeriesMgt: Codeunit NoSeriesManagement;
+begin
+    exit(NoSeriesMgt.GetNextNo("No. Series", WorkDate(), true)); // Allocate
+end;
+
+// AFTER (BC24+): Explicit method names for clear intent
+procedure GetNumberPreview(): Code[20]
+var
+    NoSeries: Codeunit "No. Series";
+begin
+    exit(NoSeries.PeekNextNo("No. Series", WorkDate())); // Explicit peek
+end;
+
+procedure AllocateNumber(): Code[20]
+var
+    NoSeries: Codeunit "No. Series";
+begin
+    exit(NoSeries.GetNextNo("No. Series", WorkDate())); // Explicit allocation
+end;
+```
+
+## Event Migration Examples
+
+### Replacing Obsolete Events
+```al
+// BEFORE (BC14-23): Event subscriber approach
+[EventSubscriber(ObjectType::Codeunit, Codeunit::NoSeriesManagement, 'OnBeforeGetNextNo', '', true, true)]
+local procedure OnBeforeGetNextNo(NoSeriesCode: Code[20]; var NoSeriesLine: Record "No. Series Line"; var IsHandled: Boolean)
+begin
+    // Custom logic before number generation
+    if NoSeriesCode = 'SPECIAL-SERIES' then begin
+        PerformCustomValidation(NoSeriesCode);
+        IsHandled := true;
+    end;
+end;
+
+// AFTER (BC24+): Direct method call with wrapper
+procedure GetNextNoWithCustomLogic(SeriesCode: Code[20]): Code[20]
+var
+    NoSeries: Codeunit "No. Series";
+begin
+    // Pre-processing logic (replaces OnBeforeGetNextNo)
+    if SeriesCode = 'SPECIAL-SERIES' then
+        PerformCustomValidation(SeriesCode);
+
+    // Get number using new module
+    exit(NoSeries.GetNextNo(SeriesCode, WorkDate()));
+end;
+```
+
+### Complex Event Replacement
+```al
+// BEFORE (BC14-23): Multiple event subscriptions
+[EventSubscriber(ObjectType::Codeunit, Codeunit::NoSeriesManagement, 'OnAfterGetNextNo', '', true, true)]
+local procedure OnAfterGetNextNo(NoSeriesCode: Code[20]; NextNo: Code[20])
+begin
+    LogNumberAllocation(NoSeriesCode, NextNo);
+    UpdateRelatedSeries(NoSeriesCode, NextNo);
+end;
+
+// AFTER (BC24+): Integrated procedure with post-processing
+procedure AllocateNumberWithLogging(SeriesCode: Code[20]): Code[20]
+var
+    NoSeries: Codeunit "No. Series";
+    AllocatedNumber: Code[20];
+begin
+    // Allocate number
+    AllocatedNumber := NoSeries.GetNextNo(SeriesCode, WorkDate());
+
+    // Post-processing logic (replaces OnAfterGetNextNo)
+    LogNumberAllocation(SeriesCode, AllocatedNumber);
+    UpdateRelatedSeries(SeriesCode, AllocatedNumber);
+
+    exit(AllocatedNumber);
+end;
+```
+
+## Complete Migration Checklist
+
+### Step 1: Variable Declaration Updates
+```al
+// Remove these legacy declarations
+var
+    NoSeriesMgt: Codeunit NoSeriesManagement;
+
+// Replace with new module references
+var
+    NoSeries: Codeunit "No. Series";
+    NoSeriesBatch: Codeunit "No. Series - Batch";
+```
+
+### Step 2: Method Call Replacements
+```al
+// Replace all instances of these patterns:
+NoSeriesMgt.InitSeries(...) → NoSeries.GetNextNo(...)
+NoSeriesMgt.TestManual(...) → NoSeries.TestManual(...)
+NoSeriesMgt.SelectSeries(...) → NoSeries.LookupRelatedNoSeries(...)
+NoSeriesMgt.GetNextNo(..., false) → NoSeries.PeekNextNo(...)
+NoSeriesMgt.GetNextNo(..., true) → NoSeries.GetNextNo(...)
+```
+
+### Step 3: Error Handling Migration
+```al
+// BEFORE: Custom error handling required
+if not NoSeriesMgt.TryFunction(...) then
+    Error('Custom error message');
+
+// AFTER: Built-in error handling with try methods
+if not NoSeries.TryGetNextNo(ResultNo, SeriesCode, WorkDate()) then
+    HandleSpecificFailureScenario();
+```