bc-code-intelligence-mcp 1.1.1

package/embedded-knowledge/domains/quinn-tester/fielderror-validation-patterns.md

@@ -0,0 +1,119 @@
+---
+title: "FieldError in Validation Patterns"
+domain: "quinn-tester"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["fielderror", "validation", "business-rules", "onvalidate", "posting-codeunits", "data-integrity"]
+prerequisites: ["fielderror-syntax-usage", "field-triggers", "validation-fundamentals"]
+related_topics: ["business-rule-validation", "posting-procedures", "data-integrity-patterns"]
+samples: "samples/fielderror-validation-patterns.md"
+---
+# FieldError in Validation Patterns
+
+## Overview
+
+FieldError serves as a critical component in Business Central validation patterns, providing immediate user feedback when business rules are violated. The method integrates seamlessly with AL validation triggers and posting procedures to enforce data integrity and guide users toward correct data entry.
+
+Understanding how to effectively use FieldError within different validation contexts enables developers to create robust business applications with clear user guidance and consistent error handling.
+
+**Validation Philosophy**: FieldError should provide specific, actionable feedback that helps users understand business rule violations and guides them toward successful data correction.
+
+## OnValidate Trigger Integration
+
+### Field-Level Business Rules
+FieldError commonly appears in OnValidate triggers where field values must meet specific business criteria. The method provides immediate feedback when users enter data that violates established business rules, preventing invalid data from being saved.
+
+### Cross-Field Validation
+When field validity depends on other field values within the same record, FieldError helps identify which specific field needs correction while explaining the relationship to other data. This targeted approach guides users efficiently through complex validation scenarios.
+
+### State-Dependent Validation
+Fields often have different validation requirements based on record state or document status. FieldError enables context-sensitive validation that adapts to changing business requirements throughout the record lifecycle.
+
+## Posting Procedure Validation
+
+### Pre-Posting Validation
+Business Central's posting codeunits use FieldError extensively to validate data completeness and business rule compliance before executing posting transactions. This pattern ensures that only valid business documents are posted to the system.
+
+### Transaction Integrity
+FieldError respects transaction boundaries during posting procedures, ensuring that validation failures trigger appropriate rollback behavior. This maintains database consistency when complex business processes encounter validation errors.
+
+### Batch Processing Validation
+In batch processing scenarios, FieldError provides specific feedback about which records and fields prevent successful processing, enabling users to correct data systematically.
+
+## Business Rule Enforcement Patterns
+
+### Mandatory Field Validation
+FieldError enforces mandatory field requirements by providing clear feedback about missing data. Unlike TestField, FieldError allows custom messages that explain business context for field requirements.
+
+### Value Range Validation
+For fields with acceptable value ranges, FieldError messages can specify valid ranges and explain business rationale for constraints, helping users understand and comply with business rules.
+
+### Format and Pattern Validation
+When fields must conform to specific formats or patterns, FieldError provides targeted feedback about format requirements and examples of acceptable values.
+
+## Complex Validation Scenarios
+
+### Multi-Condition Validation
+For validation scenarios involving multiple conditions, FieldError can be called after comprehensive business rule evaluation, providing specific feedback about which particular condition failed.
+
+### Hierarchical Validation
+In scenarios where field validation depends on parent-child relationships or hierarchical data structures, FieldError helps identify specific validation failures within complex data relationships.
+
+### Workflow-Dependent Validation
+Fields may have different validation requirements based on document workflow status or approval stages. FieldError enables dynamic validation that adapts to changing business process requirements.
+
+## Integration with Validation Procedures
+
+### Centralized Validation Logic
+FieldError works effectively within dedicated validation procedures that encapsulate complex business rules. This approach separates validation logic from user interface code while maintaining clear error feedback.
+
+### Reusable Validation Components
+Validation procedures using FieldError can be reused across different objects and contexts, providing consistent business rule enforcement throughout the application.
+
+### Layered Validation Architecture
+FieldError supports layered validation architectures where basic field validation occurs at the table level, while complex business rule validation happens in specialized validation procedures.
+
+## Error Context and User Guidance
+
+### Business Process Context
+FieldError messages should provide enough business context for users to understand why specific validation rules exist and how they relate to overall business processes.
+
+### Correction Guidance
+Effective FieldError usage includes specific instructions about how users can correct validation failures, reducing frustration and improving data entry efficiency.
+
+### Workflow Integration
+FieldError messages can guide users through complex business workflows by explaining next steps and prerequisites for successful process completion.
+
+## Performance Considerations in Validation
+
+### Validation Timing
+FieldError should be called at appropriate validation phases to minimize performance impact while providing timely user feedback. Consider the cost of validation logic versus the benefit of early error detection.
+
+### Batch Validation Efficiency
+In batch processing scenarios, consider whether FieldError provides the most efficient error handling approach, or if collecting validation errors for batch reporting would be more appropriate.
+
+### Database Impact
+FieldError calls within validation procedures should consider database access patterns and transaction boundaries to maintain optimal performance during validation operations.
+
+## Best Practices for Validation Integration
+
+### Validation Separation
+Separate business rule logic from error reporting logic to improve maintainability and testability of validation code. Use FieldError as the reporting mechanism after business rule evaluation.
+
+### Consistent Error Standards
+Establish consistent FieldError message formats and content standards across the application to provide predictable user experience during validation scenarios.
+
+### Testing Validation Logic
+Design validation procedures using FieldError to be easily testable, enabling thorough verification of business rule enforcement and error message accuracy.
+
+## Common Validation Patterns
+
+### Document Header Validation
+Document headers often require comprehensive validation before processing. FieldError provides targeted feedback about specific header fields that prevent document progression.
+
+### Line Item Validation
+Individual line items within documents may have specific validation requirements. FieldError helps users identify and correct specific line validation issues without losing context of the overall document.
+
+### Setup Table Validation
+Configuration and setup tables use FieldError to ensure that system configuration data meets business requirements and maintains system integrity.
+

package/embedded-knowledge/domains/quinn-tester/rule-execution.md

@@ -0,0 +1,123 @@
+---
+title: "API Page Validation Rule Execution"
+domain: "quinn-tester"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["validation", "business-rules", "data-integrity"]
+samples: "samples/rule-execution.md"
+---
+# API Page Validation Rule Execution
+
+## Overview
+
+API Page validation rule execution ensures data integrity and business rule compliance for data operations performed through OData endpoints. Understanding validation execution patterns is critical for implementing reliable API solutions that maintain data quality and business logic consistency.
+
+Validation rules execute automatically during API operations, applying the same business logic that governs interactive user operations. This ensures consistent data validation regardless of the interface used to modify business data.
+
+Proper validation implementation provides meaningful error feedback to API consumers while preventing invalid data from entering the system and maintaining overall data integrity standards.
+
+## Validation Execution Timing
+
+Validation rules execute at multiple points during API operations including field-level validation during data entry, record-level validation before commit operations, and cross-table validation for related data integrity.
+
+Field validation occurs immediately when field values are modified through API operations, providing early detection of invalid data before complex business logic execution.
+
+Record validation executes before database commit operations, ensuring all business rules are satisfied before persisting changes to the database system.
+
+## Standard Table Validation
+
+API Pages inherit all standard table validation logic including field constraints, table relations, and business logic implemented in table triggers and validation procedures.
+
+Standard validations include data type validation, range checking, required field validation, and referential integrity constraints that ensure data consistency with existing business rules.
+
+Custom table validation logic executes during API operations with the same behavior as interactive data entry, ensuring consistent business rule enforcement across all data entry mechanisms.
+
+## Field-Level Validation Patterns
+
+Individual field validation rules execute when field values are modified through PATCH or PUT operations, providing immediate feedback for invalid field values before processing related business logic.
+
+Field validation includes format validation, range checking, lookup validation, and custom business logic specific to individual fields or field combinations.
+
+Consider the user experience implications of field-level validation errors in API scenarios, providing clear error messages that help API consumers understand and correct validation issues.
+
+## Cross-Field and Record Validation
+
+Record-level validation rules execute after all field modifications are processed, enabling validation logic that depends on multiple field values or complex business rule combinations.
+
+Cross-field validation ensures data consistency across related fields and implements business rules that require analysis of complete record state rather than individual field values.
+
+Advanced validation scenarios may require access to related table data or external system information to complete validation rule execution.
+
+## Related Table Validation
+
+API Page operations may trigger validation rules in related tables when modifications affect data relationships or referential integrity constraints.
+
+Related table validation ensures system-wide data integrity is maintained even when modifications originate from API operations rather than direct table access.
+
+Consider the performance implications of related table validation, especially in scenarios involving complex table relationships or large data volumes.
+
+## Custom Business Logic Integration
+
+Custom business logic implemented in table triggers, page triggers, or specialized validation procedures executes during API operations with the same behavior as interactive operations.
+
+Integration with custom business logic ensures API operations respect all business rules and constraints without requiring separate validation implementations for API scenarios.
+
+Design custom validation logic with API operations in mind, ensuring error messages and validation feedback are appropriate for both interactive and programmatic consumers.
+
+## Error Handling and Feedback
+
+Validation errors result in appropriate HTTP status codes and error messages that provide meaningful feedback to API consumers about the nature of validation failures.
+
+Error messages should provide sufficient information for API consumers to understand and correct validation issues without exposing sensitive system information or internal implementation details.
+
+Consider implementing structured error responses that include field-specific validation errors and suggested corrective actions for common validation scenarios.
+
+## Validation Performance Considerations
+
+Complex validation rules can impact API operation performance, especially in high-volume scenarios where validation overhead becomes significant compared to basic data operations.
+
+Monitor validation performance to identify optimization opportunities including caching validation results, optimizing validation logic, or restructuring validation approaches for better performance.
+
+Balance validation thoroughness with performance requirements, ensuring critical business rules are enforced while maintaining acceptable API response times.
+
+## Batch Operation Validation
+
+Batch API operations require special consideration for validation rule execution, as validation errors in individual records may affect the entire batch operation depending on transaction and error handling strategies.
+
+Implement appropriate error handling for batch scenarios including partial success scenarios, rollback strategies, and error reporting that identifies specific validation failures within batch operations.
+
+Consider the business impact of validation failures in batch operations and design appropriate handling strategies that balance data integrity requirements with operational efficiency.
+
+## Integration Testing Strategies
+
+Implement comprehensive testing for validation rule execution in API scenarios, including positive validation cases, negative validation cases, and edge cases that may not occur in interactive usage.
+
+Test validation behavior across different API operation types including creation, modification, and deletion operations to ensure consistent validation enforcement.
+
+Validate error handling and feedback mechanisms to ensure API consumers receive appropriate information for resolving validation issues.
+
+## Security and Validation
+
+Validation rules may include security-related constraints that prevent unauthorized data modifications or enforce data access restrictions based on user context or business rules.
+
+Ensure validation logic properly integrates with BC security systems to prevent security bypass through API operations while maintaining appropriate functionality for legitimate use cases.
+
+Consider the security implications of validation error messages, ensuring they provide helpful feedback without exposing sensitive information that could be exploited by unauthorized users.
+
+## Documentation and Communication
+
+Document validation behavior for API consumers including common validation scenarios, error message formats, and recommended approaches for handling validation failures in client applications.
+
+Provide clear guidance on validation requirements during API integration development to help API consumers implement appropriate error handling and data validation strategies.
+
+Maintain documentation consistency between interactive validation behavior and API validation behavior to ensure developers have accurate expectations for validation rule execution.
+
+## Best Practices
+
+Design validation rules with both interactive and API usage in mind, ensuring validation logic provides appropriate feedback and behavior for different consumption scenarios.
+
+Implement comprehensive error handling for validation scenarios including graceful degradation, meaningful error messages, and appropriate HTTP status codes for different validation failure types.
+
+Monitor validation rule performance and effectiveness in API scenarios, identifying optimization opportunities and ensuring validation rules continue to meet business requirements over time.
+
+Test validation behavior thoroughly across different API usage patterns and data scenarios to ensure robust validation enforcement that maintains data integrity without compromising API usability.

package/embedded-knowledge/domains/quinn-tester/samples/case-error-handling.md

@@ -0,0 +1,64 @@
+# Case Statement Error Handling - AL Code Samples
+
+## Basic Error Handling Pattern
+
+```al
+procedure ProcessOrderStatus(OrderStatus: Enum "Sales Document Status")
+begin
+    case OrderStatus of
+        OrderStatus::Open:
+            ProcessOpenOrder();
+        OrderStatus::Released:
+            ProcessReleasedOrder();
+        OrderStatus::"Pending Approval":
+            ProcessPendingOrder();
+        else
+            Error('Unsupported order status: %1', OrderStatus);
+    end;
+end;
+```
+
+## Safe Processing with TryFunction
+
+```al
+[TryFunction]
+procedure ProcessOrderStatusSafe(OrderStatus: Enum "Sales Document Status"): Boolean
+begin
+    case OrderStatus of
+        OrderStatus::Open:
+            exit(TryProcessOpenOrder());
+        OrderStatus::Released:
+            exit(TryProcessReleasedOrder());
+        else
+            exit(false);
+    end;
+end;
+```
+
+## Exception Recovery Pattern
+
+```al
+procedure ProcessWithRecovery(ProcessingType: Text; MaxAttempts: Integer)
+var
+    Attempts: Integer;
+    Success: Boolean;
+begin
+    repeat
+        Attempts += 1;
+        case ProcessingType of
+            'STANDARD':
+                Success := TryStandardProcessing();
+            'FALLBACK':
+                Success := TryFallbackProcessing();
+            else
+                Success := false;
+        end;
+        
+        if not Success and (Attempts < MaxAttempts) then
+            Sleep(1000);
+    until Success or (Attempts >= MaxAttempts);
+    
+    if not Success then
+        Error('Failed after %1 attempts', MaxAttempts);
+end;
+```

package/embedded-knowledge/domains/quinn-tester/samples/fielderror-message-construction.md

@@ -0,0 +1,60 @@
+# FieldError Message Construction Examples
+
+## Descriptive Error Messages
+```al
+trigger OnValidate()
+begin
+    if "Unit Price" < 0 then
+        FieldError("Unit Price", 'Unit price cannot be negative. Please enter a positive value.');
+        
+    if ("Discount %" < 0) or ("Discount %" > 100) then
+        FieldError("Discount %", 'Discount percentage must be between 0 and 100.');
+end;
+```
+
+## Context-Aware Messages
+```al
+procedure ValidateItemForLocation()
+begin
+    Item.Get("Item No.");
+    Location.Get("Location Code");
+    
+    if not Location."Allow Negative Inventory" and (CalculateAvailableQty() < Quantity) then
+        FieldError(Quantity, StrSubstNo('Insufficient inventory at location %1. Available: %2, Required: %3', 
+            "Location Code", CalculateAvailableQty(), Quantity));
+end;
+```
+
+## Business Rule Explanations
+```al
+trigger OnValidate()
+var
+    SalesSetup: Record "Sales & Receivables Setup";
+begin
+    SalesSetup.Get();
+    
+    if SalesSetup."Credit Warnings" = SalesSetup."Credit Warnings"::"No Warning" then
+        exit;
+        
+    Customer.Get("Sell-to Customer No.");
+    Customer.CalcFields("Balance (LCY)");
+    
+    if Customer."Balance (LCY)" > Customer."Credit Limit (LCY)" then
+        FieldError("Sell-to Customer No.", 
+            StrSubstNo('Customer %1 exceeds credit limit. Current balance: %2, Credit limit: %3. Please contact credit department.',
+                Customer.Name, Customer."Balance (LCY)", Customer."Credit Limit (LCY)"));
+end;
+```
+
+## Corrective Action Guidance
+```al
+procedure ValidateShippingSetup()
+begin
+    if "Shipment Method Code" = '' then
+        FieldError("Shipment Method Code", 'Shipment method is required. Select a method from the dropdown or create a new one in Shipment Methods setup.');
+        
+    if ("Shipping Agent Code" <> '') and ("Shipping Agent Service Code" = '') then
+        FieldError("Shipping Agent Service Code", 
+            'Service code is required when shipping agent is specified. Use the lookup to select an available service.');
+end;
+```

package/embedded-knowledge/domains/quinn-tester/samples/fielderror-validation-patterns.md

@@ -0,0 +1,83 @@
+# FieldError Validation Patterns
+
+## OnValidate Trigger Integration
+```al
+trigger OnValidate()
+begin
+    if "Starting Date" > "Ending Date" then
+        FieldError("Starting Date", 'Starting date must be earlier than or equal to ending date.');
+        
+    if ("Starting Date" < WorkDate()) and ("Document Status" = "Document Status"::Draft) then
+        FieldError("Starting Date", 'Starting date cannot be in the past for draft documents.');
+end;
+```
+
+## Cross-Field Validation
+```al
+trigger OnValidate()
+var
+    Item: Record Item;
+begin
+    if "Item No." <> '' then begin
+        Item.Get("Item No.");
+        
+        if (Item.Type = Item.Type::Service) and ("Location Code" <> '') then
+            FieldError("Location Code", 'Location cannot be specified for service items.');
+            
+        if (Item."Item Tracking Code" <> '') and ("Lot No." = '') and ("Serial No." = '') then
+            FieldError("Lot No.", 'Either lot number or serial number must be specified for tracked items.');
+    end;
+end;
+```
+
+## Business Rule Enforcement
+```al
+procedure ValidateCustomerCreditLimit()
+var
+    Customer: Record Customer;
+    CustomerLedgerEntry: Record "Cust. Ledger Entry";
+    OutstandingAmount: Decimal;
+begin
+    Customer.Get("Customer No.");
+    
+    if Customer."Credit Limit (LCY)" = 0 then
+        exit; // No credit limit enforced
+        
+    CustomerLedgerEntry.SetRange("Customer No.", "Customer No.");
+    CustomerLedgerEntry.SetRange(Open, true);
+    CustomerLedgerEntry.CalcSums("Remaining Amt. (LCY)");
+    OutstandingAmount := CustomerLedgerEntry."Remaining Amt. (LCY)";
+    
+    if OutstandingAmount + "Amount Including VAT" > Customer."Credit Limit (LCY)" then
+        FieldError("Amount Including VAT", 
+            StrSubstNo('Transaction exceeds credit limit. Outstanding: %1, Credit Limit: %2, This Transaction: %3',
+                OutstandingAmount, Customer."Credit Limit (LCY)", "Amount Including VAT"));
+end;
+```
+
+## Posting Procedure Validation
+```al
+procedure ValidateForPosting()
+begin
+    TestField("Document Type");
+    TestField("No.");
+    
+    case "Document Type" of
+        "Document Type"::Quote:
+            FieldError("Document Type", 'Quotes cannot be posted. Convert to order or invoice first.');
+        "Document Type"::Order:
+            ValidateOrderForPosting();
+        "Document Type"::Invoice:
+            ValidateInvoiceForPosting();
+    end;
+end;
+
+local procedure ValidateOrderForPosting()
+begin
+    if "Shipment Date" = 0D then
+        FieldError("Shipment Date", 'Shipment date is required for posting orders.');
+        
+    if not LinesExist() then
+        FieldError("Document Type", 'Document must have at least one line to post.');
+end;
+```