bc-code-intelligence-mcp 1.1.1

package/embedded-knowledge/domains/eva-errors/samples/fielderror-syntax.md

@@ -0,0 +1,256 @@
+# FieldError Method Syntax - AL Code Sample
+
+## Basic FieldError Syntax
+
+```al
+// Basic FieldError syntax with automatic message
+table 50100 "Sales Document"
+{
+    fields
+    {
+        field(1; "Document Type"; Enum "Sales Document Type") { }
+        field(2; "Document No."; Code[20]) { }
+        field(3; "Sell-to Customer No."; Code[20]) { }
+        field(10; "Currency Code"; Code[10]) { }
+        field(20; "Amount"; Decimal) { }
+    }
+    
+    trigger OnInsert()
+    begin
+        // Validate required fields before insert
+        ValidateRequiredFields();
+    end;
+    
+    local procedure ValidateRequiredFields()
+    begin
+        // FieldError assumes validation already failed - no testing performed
+        if "Sell-to Customer No." = '' then
+            FieldError("Sell-to Customer No.");  // Generates: "Sell-to Customer No. must have a value in Sales Document Document Type='Order', Document No.='SO001'."
+            
+        if Amount <= 0 then
+            FieldError(Amount);  // Generates: "Amount must not be 0 in Sales Document..."
+    end;
+}
+```
+
+## FieldError vs TestField Comparison
+
+```al
+codeunit 50100 "Validation Examples"
+{
+    procedure DemonstrateFieldErrorVsTestField()
+    var
+        SalesHeader: Record "Sales Header";
+        Customer: Record Customer;
+    begin
+        SalesHeader.Get(SalesHeader."Document Type"::Order, 'SO001');
+        
+        // TestField approach - tests condition AND throws error if failed
+        SalesHeader.TestField("Sell-to Customer No.");  // Tests if empty, then errors
+        SalesHeader.TestField(Amount);  // Tests if zero, then errors
+        
+        // FieldError approach - assumes you already validated the condition
+        if SalesHeader."Sell-to Customer No." = '' then
+            SalesHeader.FieldError("Sell-to Customer No.");  // Only errors, no testing
+            
+        if SalesHeader.Amount <= 0 then
+            SalesHeader.FieldError(Amount, 'must be positive');  // Custom message
+            
+        // Practical usage: FieldError for complex validation logic
+        if not Customer.Get(SalesHeader."Sell-to Customer No.") then
+            SalesHeader.FieldError("Sell-to Customer No.", 'customer does not exist');
+            
+        if Customer.Blocked <> Customer.Blocked::" " then
+            SalesHeader.FieldError("Sell-to Customer No.", 
+                StrSubstNo('customer is blocked (%1)', Customer.Blocked));
+    end;
+}
+```
+
+## Custom Message Examples
+
+```al
+table 50101 "Purchase Document"
+{
+    fields
+    {
+        field(1; "Document Type"; Enum "Purchase Document Type") { }
+        field(2; "Document No."; Code[20]) { }
+        field(3; "Buy-from Vendor No."; Code[20]) { }
+        field(10; "Expected Receipt Date"; Date) { }
+        field(20; "Amount Including VAT"; Decimal) { }
+    }
+    
+    procedure ValidateBusinessRules()
+    var
+        Vendor: Record Vendor;
+    begin
+        // Custom message examples - note lowercase first word convention
+        if "Expected Receipt Date" < WorkDate() then
+            FieldError("Expected Receipt Date", 'cannot be in the past');
+            
+        if "Amount Including VAT" > 10000 then
+            FieldError("Amount Including VAT", 'exceeds approval limit');
+            
+        // Complex validation with detailed custom message
+        if Vendor.Get("Buy-from Vendor No.") then begin
+            if Vendor.Blocked <> Vendor.Blocked::" " then
+                FieldError("Buy-from Vendor No.", 
+                    StrSubstNo('vendor is blocked for %1', Vendor.Blocked));
+                    
+            if (Vendor."Payment Terms Code" = '') and ("Amount Including VAT" > 1000) then
+                FieldError("Buy-from Vendor No.", 
+                    'requires payment terms for amounts over 1000');
+        end else
+            FieldError("Buy-from Vendor No.", 'vendor does not exist');
+    end;
+}
+```
+
+## Real-World Posting Codeunit Pattern
+
+```al
+codeunit 50102 "Sales Document Validation"
+{
+    // Pattern used in standard BC posting codeunits (12, 80, 90)
+    
+    procedure ValidateSalesDocument(var SalesHeader: Record "Sales Header")
+    begin
+        // Comprehensive validation before posting
+        with SalesHeader do begin
+            // Required field validation
+            if "Sell-to Customer No." = '' then
+                FieldError("Sell-to Customer No.");
+                
+            if "Document Date" = 0D then
+                FieldError("Document Date");
+                
+            // Business logic validation with custom messages
+            if "Posting Date" < "Document Date" then
+                FieldError("Posting Date", 'cannot be before document date');
+                
+            if Status <> Status::Released then
+                FieldError(Status, 'must be Released before posting');
+                
+            // Complex validation scenarios
+            ValidateCustomerCredit(SalesHeader);
+            ValidateDimensions(SalesHeader);
+        end;
+    end;
+    
+    local procedure ValidateCustomerCredit(var SalesHeader: Record "Sales Header")
+    var
+        Customer: Record Customer;
+        CustLedgerEntry: Record "Cust. Ledger Entry";
+        RemainingAmount: Decimal;
+    begin
+        Customer.Get(SalesHeader."Sell-to Customer No.");
+        
+        // Calculate customer's remaining credit
+        CustLedgerEntry.SetRange("Customer No.", Customer."No.");
+        CustLedgerEntry.SetRange(Open, true);
+        CustLedgerEntry.CalcSums("Remaining Amt. (LCY)");
+        RemainingAmount := CustLedgerEntry."Remaining Amt. (LCY)";
+        
+        // Validate credit limit
+        if (Customer."Credit Limit (LCY)" > 0) and 
+           (RemainingAmount + SalesHeader."Amount Including VAT" > Customer."Credit Limit (LCY)") then
+            SalesHeader.FieldError("Sell-to Customer No.", 
+                StrSubstNo('credit limit exceeded. Available credit: %1', 
+                          Customer."Credit Limit (LCY)" - RemainingAmount));
+    end;
+    
+    local procedure ValidateDimensions(var SalesHeader: Record "Sales Header")
+    var
+        DimMgt: Codeunit DimensionManagement;
+        DimSetID: Integer;
+    begin
+        DimSetID := SalesHeader."Dimension Set ID";
+        
+        // Validate required dimensions
+        if not DimMgt.CheckDimIDComb(DimSetID) then
+            SalesHeader.FieldError("Dimension Set ID", 'invalid dimension combination');
+            
+        // Validate dimension values against posting rules
+        if not DimMgt.CheckDimValuePosting(DimSetID, DATABASE::"Sales Header", SalesHeader."No.") then
+            SalesHeader.FieldError("Dimension Set ID", 'dimension values not allowed for posting');
+    end;
+}
+```
+
+## Advanced FieldError Patterns
+
+```al
+codeunit 50103 "Advanced Validation Patterns"
+{
+    // Pattern: Conditional validation with detailed context
+    procedure ValidateItemAvailability(var SalesLine: Record "Sales Line")
+    var
+        Item: Record Item;
+        AvailableQty: Decimal;
+    begin
+        if SalesLine.Type <> SalesLine.Type::Item then
+            exit;  // Only validate items
+            
+        Item.Get(SalesLine."No.");
+        Item.CalcFields(Inventory, "Reserved Qty. on Inventory");
+        AvailableQty := Item.Inventory - Item."Reserved Qty. on Inventory";
+        
+        if SalesLine.Quantity > AvailableQty then
+            SalesLine.FieldError(Quantity, 
+                StrSubstNo('exceeds available inventory (%1 available)', AvailableQty));
+    end;
+    
+    // Pattern: Multi-field validation with specific field error
+    procedure ValidatePriceAndDiscount(var SalesLine: Record "Sales Line")
+    begin
+        // Validate that discount doesn't exceed unit price
+        if (SalesLine."Unit Price" > 0) and 
+           (SalesLine."Line Discount Amount" > SalesLine."Unit Price" * SalesLine.Quantity) then
+            SalesLine.FieldError("Line Discount Amount", 
+                'cannot exceed line amount');
+                
+        // Validate price against minimum price rules
+        if SalesLine."Unit Price" < GetMinimumPrice(SalesLine) then
+            SalesLine.FieldError("Unit Price", 
+                StrSubstNo('cannot be below minimum price (%1)', GetMinimumPrice(SalesLine)));
+    end;
+    
+    local procedure GetMinimumPrice(SalesLine: Record "Sales Line"): Decimal
+    var
+        Item: Record Item;
+    begin
+        if Item.Get(SalesLine."No.") then
+            exit(Item."Unit Cost" * 1.1)  // 10% markup minimum
+        else
+            exit(0);
+    end;
+}
+```
+
+## Error Context and Message Output Examples
+
+```al
+// When this validation fails:
+procedure ExampleValidationScenarios()
+var
+    SalesHeader: Record "Sales Header";
+begin
+    SalesHeader."Document Type" := SalesHeader."Document Type"::Order;
+    SalesHeader."No." := 'SO001';
+    SalesHeader."Sell-to Customer No." := '';  // Empty value
+    
+    // This will generate message:
+    // "Sell-to Customer No. must have a value in Sales Header Document Type='Order', No.='SO001'."
+    SalesHeader.FieldError("Sell-to Customer No.");
+    
+    // With custom message:
+    // "Sell-to Customer No. is required for orders in Sales Header Document Type='Order', No.='SO001'."
+    SalesHeader.FieldError("Sell-to Customer No.", 'is required for orders');
+    
+    // For non-empty field with custom message:
+    SalesHeader."Sell-to Customer No." := 'INVALID';
+    // "Sell-to Customer No. customer does not exist in Sales Header Document Type='Order', No.='SO001'."
+    SalesHeader.FieldError("Sell-to Customer No.", 'customer does not exist');
+end;
+```

package/embedded-knowledge/domains/eva-errors/samples/table-safety-validation-patterns.md

@@ -0,0 +1,101 @@
+# Table Safety Validation Patterns
+
+## IsTemporary Safeguard Implementation
+```al
+procedure ProcessBulkData(var DataBuffer: Record "Data Processing Buffer")
+begin
+    // Always validate temporary status before bulk operations
+    if not DataBuffer.IsTemporary then
+        Error('This procedure requires a temporary table to prevent data corruption.');
+        
+    DataBuffer.Reset();
+    if DataBuffer.FindSet() then
+        repeat
+            ProcessIndividualRecord(DataBuffer);
+            DataBuffer.Delete(); // Safe because table is confirmed temporary
+        until DataBuffer.Next() = 0;
+end;
+```
+
+## Database Write Protection
+```al
+procedure SafeDataManipulation(var TempCustomer: Record Customer temporary)
+var
+    Customer: Record Customer;
+begin
+    // Validate temporary status before any modifications
+    if not TempCustomer.IsTemporary then
+        Error('Database safety violation: Expected temporary table for data manipulation.');
+        
+    // Safe to perform destructive operations
+    TempCustomer.Reset();
+    TempCustomer.DeleteAll();
+    
+    // Load fresh data from permanent table
+    Customer.FindSet();
+    repeat
+        TempCustomer := Customer;
+        TempCustomer.Insert();
+    until Customer.Next() = 0;
+end;
+```
+
+## Bulk Operation Validation
+```al
+procedure ProcessLargeDataSet(var TempItem: Record Item temporary; ProcessingMode: Option Validate,Update,Delete)
+begin
+    // Critical safety check for bulk operations
+    if not TempItem.IsTemporary then
+        Error('Bulk processing operations require temporary tables. This prevents accidental permanent data modification.');
+        
+    case ProcessingMode of
+        ProcessingMode::Validate:
+            ValidateAllRecords(TempItem);
+        ProcessingMode::Update:
+            UpdateAllRecords(TempItem);
+        ProcessingMode::Delete:
+            TempItem.DeleteAll(); // Safe deletion
+    end;
+end;
+
+local procedure ValidateAllRecords(var TempItem: Record Item temporary)
+begin
+    TempItem.Reset();
+    if TempItem.FindSet() then
+        repeat
+            ValidateItemData(TempItem);
+        until TempItem.Next() = 0;
+end;
+```
+
+## Data Integrity Protection
+```al
+procedure SecureDataProcessing(var WorkingTable: Record "Working Data Buffer")
+var
+    OriginalFilters: Text;
+begin
+    // Mandatory safety validation
+    if not WorkingTable.IsTemporary then
+        Error('Data integrity protection: This operation requires a temporary working table.');
+        
+    OriginalFilters := WorkingTable.GetFilters();
+    
+    try
+        WorkingTable.Reset();
+        ProcessAllRecords(WorkingTable);
+    finally
+        // Restore original state
+        WorkingTable.Reset();
+        WorkingTable.SetView(OriginalFilters);
+    end;
+end;
+
+local procedure ProcessAllRecords(var WorkingTable: Record "Working Data Buffer")
+begin
+    if WorkingTable.FindSet(true) then
+        repeat
+            WorkingTable."Processing Status" := WorkingTable."Processing Status"::Completed;
+            WorkingTable.Modify();
+        until WorkingTable.Next() = 0;
+end;
+```

package/embedded-knowledge/domains/eva-errors/samples/testfield-error-handling.md

@@ -0,0 +1,108 @@
+# TestField Error Handling Patterns
+
+## Try-Catch with TestField
+```al
+procedure ValidateDocumentSafely(var SalesHeader: Record "Sales Header"): Boolean
+begin
+    if not TryValidateDocument(SalesHeader) then begin
+        LogValidationError(GetLastErrorText());
+        exit(false);
+    end;
+    exit(true);
+end;
+
+local procedure TryValidateDocument(var SalesHeader: Record "Sales Header")
+begin
+    SalesHeader.TestField("Document Type");
+    SalesHeader.TestField("No.");
+    SalesHeader.TestField("Sell-to Customer No.");
+end;
+```
+
+## Batch Validation with Error Collection
+```al
+procedure ValidateCustomerBatch(var TempCustomer: Record Customer temporary): Text
+var
+    ErrorMessages: Text;
+    Customer: Record Customer;
+begin
+    TempCustomer.Reset();
+    if TempCustomer.FindSet() then
+        repeat
+            Customer := TempCustomer;
+            if not TryValidateCustomer(Customer) then
+                ErrorMessages += StrSubstNo('Customer %1: %2\', Customer."No.", GetLastErrorText());
+        until TempCustomer.Next() = 0;
+    
+    exit(ErrorMessages);
+end;
+
+local procedure TryValidateCustomer(Customer: Record Customer): Boolean
+begin
+    Customer.TestField(Name);
+    Customer.TestField("Customer Posting Group");
+    exit(true);
+end;
+```
+
+## Conditional TestField with Fallback
+```al
+procedure ValidateVendorWithDefaults(var Vendor: Record Vendor)
+var
+    VendorPostingGroup: Record "Vendor Posting Group";
+begin
+    if not TryTestVendorFields(Vendor) then begin
+        // Apply defaults and retry
+        if Vendor."Vendor Posting Group" = '' then begin
+            VendorPostingGroup.FindFirst();
+            Vendor."Vendor Posting Group" := VendorPostingGroup.Code;
+        end;
+        
+        // Retry validation
+        Vendor.TestField("Vendor Posting Group");
+    end;
+end;
+
+local procedure TryTestVendorFields(Vendor: Record Vendor): Boolean
+begin
+    Vendor.TestField("Vendor Posting Group");
+    exit(true);
+end;
+```
+
+## Graceful Degradation Pattern
+```al
+procedure ProcessOrderWithValidation(var SalesHeader: Record "Sales Header"): Boolean
+var
+    ValidationLevel: Integer;
+begin
+    // Try strict validation first
+    ValidationLevel := 1;
+    if TryValidateOrderStrict(SalesHeader) then
+        exit(true);
+    
+    // Fall back to basic validation
+    ValidationLevel := 2;
+    if TryValidateOrderBasic(SalesHeader) then begin
+        LogWarning('Order %1 processed with basic validation only', SalesHeader."No.");
+        exit(true);
+    end;
+    
+    exit(false);
+end;
+
+local procedure TryValidateOrderStrict(SalesHeader: Record "Sales Header"): Boolean
+begin
+    SalesHeader.TestField("External Document No.");
+    SalesHeader.TestField("Requested Delivery Date");
+    SalesHeader.TestField("Shipment Method Code");
+    exit(true);
+end;
+
+local procedure TryValidateOrderBasic(SalesHeader: Record "Sales Header"): Boolean
+begin
+    SalesHeader.TestField("Sell-to Customer No.");
+    SalesHeader.TestField("Order Date");
+    exit(true);
+end;
+```

package/embedded-knowledge/domains/eva-errors/testfield-error-handling.md

@@ -0,0 +1,80 @@
+---
+title: "TestField Error Handling and Custom Messages"
+domain: "eva-errors"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["error-handling", "validation", "user-experience", "custom-messages"]
+prerequisites: ["testfield-basic-syntax", "error-handling-fundamentals"]
+samples: "samples/testfield-error-handling.md"
+---
+# TestField Error Handling and Custom Messages
+
+## Overview
+
+TestField generates automatic error messages, but business scenarios often require custom error handling and messaging. Understanding TestField error behavior enables better user experience and error management strategies.
+
+**Key Principle**: TestField errors are runtime exceptions that halt procedure execution unless caught and handled.
+
+## Default Error Behavior
+
+### Standard Error Messages
+TestField generates system messages like "You must specify Name in Customer" when validation fails. These messages include:
+- Field caption from table definition
+- Table name
+- Current record context when available
+
+### Error Flow Impact
+TestField errors immediately terminate current procedure execution. Control returns to calling code or user interface with error state.
+
+## Custom Error Handling Patterns
+
+### Try-Function Approach
+Wrap TestField calls in TryFunction procedures to catch validation errors without terminating execution. Returns boolean success indicator for error-tolerant processing scenarios.
+
+### Custom Validation with Better Messages
+Replace TestField with custom validation logic when business context requires specific error messages. Provides more meaningful feedback to users than system-generated messages.
+
+### Conditional TestField Usage
+Apply TestField validation based on business rules or record state. Ensures appropriate validation intensity for different scenarios without over-validating.
+
+## Advanced Error Management
+
+### Error Context Enhancement
+Capture TestField errors using TryFunction pattern and enhance with business context before re-throwing. Provides users with meaningful error information including document details.
+
+### Multiple Field Validation with Aggregated Errors
+Collect multiple validation failures before reporting to users. Improves user experience by showing all validation issues at once rather than one-by-one error correction.
+
+## Integration with Business Logic
+
+### Workflow Integration
+TestField works seamlessly with workflow validations. Use TestField for mandatory data checks within workflow step validations.
+
+### API Integration
+For API endpoints, catch TestField errors and return structured error responses rather than allowing raw BC errors to propagate.
+
+### Batch Processing
+In batch processing scenarios, use TryFunction pattern to continue processing other records when individual record validation fails.
+
+## User Experience Considerations
+
+### Progressive Validation
+Validate fields in logical order so users get meaningful first-error feedback rather than random field validation failures.
+
+### Context-Aware Messages
+Include business context in custom error messages to help users understand why specific fields are required.
+
+### Field Focus Integration
+Custom validation procedures can integrate with page field focus to direct users to specific fields requiring attention.
+
+## Common Patterns
+
+### Validation Procedures
+Create dedicated validation procedures that use TestField internally but provide business-context error messages.
+
+### Status-Based Validation
+Use TestField with status checks to enforce business rules at specific workflow stages.
+
+### Cross-Table Validation
+Combine TestField with related table lookups to validate complex business relationships.
+

package/embedded-knowledge/domains/jordan-bridge/al-event-subscriber-architecture.md

@@ -0,0 +1,98 @@
+---
+title: "AL Event Subscriber Architecture"
+domain: "jordan-bridge"
+difficulty: "advanced"
+bc_versions: "14+"
+tags: ["events", "subscribers", "integration", "extensibility"]
+type: "improvement-pattern"
+category: "architecture"
+pattern_type: "good"
+severity: "high"
+impact_level: "high"
+improvement_suggestion: "Design event subscriber architecture for maintainable, performant integration solutions"
+implementation_steps: ["design-subscriber-structure", "implement-loose-coupling", "validate-performance"]
+validation_criteria: ["maintained-loose-coupling", "acceptable-performance-impact"]
+technical_areas: ["al-code", "integration"]
+samples: "samples/al-event-subscriber-architecture.md"
+---
+
+# AL Event Subscriber Architecture
+
+## Overview
+
+Event subscriber architecture in AL enables loosely coupled integration patterns that extend base functionality without modifying existing code. Proper subscriber design ensures maintainable, performant, and scalable integration solutions.
+
+**Key Principle**: Event subscribers should maintain loose coupling, minimize performance impact, and provide clear integration contracts.
+
+## Strategic Framework
+
+### Subscriber Design Patterns
+**Single Responsibility**: Each subscriber handles one specific integration concern
+**Loose Coupling**: Subscribers depend only on event contracts, not implementation details
+**Error Isolation**: Subscriber failures don't impact publisher or other subscribers
+**Performance Conscious**: Minimal processing overhead in subscriber implementations
+
+### Integration Architecture
+Events enable clean separation between core business logic and integration concerns, supporting modular application design and third-party extensions.
+
+### Extensibility Framework
+Subscribers provide extension points for customization without code modification, supporting ISV and customer enhancement scenarios.
+
+## Architecture Focus
+
+### Decoupling Benefits
+**Module Independence**: Publishers and subscribers can evolve independently
+**Extension Points**: Well-defined integration points for custom functionality
+**Testing Isolation**: Subscribers can be tested independently of publishers
+**Deployment Flexibility**: Subscribers can be deployed separately from base functionality
+
+### Performance Considerations
+**Event Overhead**: Each subscriber adds processing overhead to publisher execution
+**Synchronous Execution**: Subscribers execute synchronously unless using background sessions
+**Error Propagation**: Subscriber errors can impact publisher performance and reliability
+**Memory Impact**: Multiple subscribers increase memory usage during event processing
+
+### Integration Patterns
+- **Data Transformation**: Transform data between systems during business processes
+- **Audit Logging**: Capture business events for compliance and monitoring
+- **External Integration**: Trigger external system calls based on BC events
+- **Custom Validation**: Add business-specific validation to standard processes
+
+## Best Practices
+
+### Subscriber Implementation
+- **Minimal Processing**: Keep subscriber logic lightweight and focused
+- **Error Handling**: Implement robust error handling to prevent publisher disruption
+- **Conditional Execution**: Use appropriate conditions to avoid unnecessary processing
+- **Clear Contracts**: Design clear interfaces between publishers and subscribers
+
+### Performance Optimization
+- **Efficient Filtering**: Apply early filtering to avoid unnecessary subscriber execution
+- **Background Processing**: Use background sessions for time-intensive operations
+- **Bulk Operations**: Design subscribers to handle bulk scenarios efficiently
+- **Resource Management**: Monitor memory and database usage in subscribers
+
+### Architecture Design
+- **Codeunit Organization**: Group related subscribers in dedicated codeunits by functional area
+- **Event Contract Stability**: Design event parameters for long-term stability
+- **Documentation**: Document event contracts and subscriber responsibilities clearly
+- **Version Management**: Plan for event contract evolution without breaking subscribers
+
+### Error Handling Strategy
+- **Graceful Degradation**: Handle subscriber failures without impacting core functionality
+- **Logging and Monitoring**: Implement comprehensive logging for troubleshooting
+- **Retry Mechanisms**: Design appropriate retry logic for transient failures
+- **Circuit Breaker**: Implement circuit breaker patterns for failing external integrations
+
+## Anti-Patterns
+
+### Avoid These Approaches
+- **Tight Coupling Issues**: Subscribers that depend on publisher implementation details
+- **Direct Data Access**: Bypassing event parameters to access publisher data directly
+- **Circular Dependencies**: Publishers depending on subscriber functionality
+- **Version Coupling**: Subscribers tied to specific publisher versions
+
+Poor subscriber design can compromise system reliability and create maintenance burdens that outweigh the benefits of event-driven architecture.
+
+*Related patterns: al-event-publishers.md, al-integration-patterns.md*
+*Implementation examples: see samples/al-event-subscriber-architecture.md*