bc-code-intelligence-mcp 1.1.1

package/embedded-knowledge/domains/eva-errors/fielderror-message-construction.md

@@ -0,0 +1,104 @@
+---
+title: "FieldError Message Construction Patterns"
+domain: "eva-errors"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["fielderror", "error-messages", "user-experience", "localization", "message-formatting", "validation-feedback"]
+prerequisites: ["fielderror-syntax-usage", "text-constants", "label-variables"]
+samples: "samples/fielderror-message-construction.md"
+related_topics: ["localization-patterns", "user-feedback-design", "validation-error-handling"]
+---
+# FieldError Message Construction Patterns
+
+## Overview
+
+FieldError message construction combines automatic field context with custom messaging to provide meaningful validation feedback. Understanding how FieldError builds error messages enables developers to create user-friendly validation experiences that guide users toward successful data entry.
+
+The method automatically includes field captions, current values, and record identification, while allowing custom text to provide specific business context and correction guidance.
+
+**Key Principle**: Effective FieldError messages combine system-generated field context with business-specific guidance to create actionable user feedback.
+
+## Automatic Message Components
+
+### Field Context Integration
+FieldError automatically includes the field caption from table metadata, ensuring consistent field identification across different user interface languages. The system retrieves localized field captions when multiple languages are configured.
+
+The current field value is included in the error message, providing users with immediate context about the data that triggered the validation failure. This eliminates ambiguity about which specific value caused the problem.
+
+### Record Identification
+FieldError includes the table name and primary key values to identify the specific record where the validation failure occurred. This record context helps users navigate back to the problematic data when working with large datasets.
+
+## Default Message Patterns
+
+### Empty Field Messages
+When a field is empty and FieldError is called without custom text, the system generates messages following the pattern: "You must specify [Field Caption] in [Table Caption] [Primary Key Values]". This pattern clearly indicates missing required data.
+
+### Invalid Value Messages
+When a field contains data and FieldError is called without custom text, the system generates messages following the pattern: "[Field Caption] must not be [Field Value] in [Table Caption] [Primary Key Values]". This pattern indicates that the current value is invalid.
+
+## Custom Message Integration
+
+### Text Parameter Usage
+The optional text parameter allows developers to provide specific validation guidance while maintaining automatic field context. Custom text becomes the primary error description, with field context appended for complete user guidance.
+
+### Message Formatting Rules
+Custom FieldError text should not begin with capital letters, as the system automatically capitalizes the complete error message. This formatting rule ensures grammatically correct error messages when combined with automatic field context.
+
+### Business Context Addition
+Custom messages should provide business rule context that helps users understand why the validation failed and what action they need to take to correct the data.
+
+## Localization Considerations
+
+### Label Variable Integration
+Use Label variables for custom FieldError text to support multilingual applications. Label variables automatically provide localized text based on user language preferences, ensuring consistent user experience across language configurations.
+
+### Field Caption Localization
+FieldError automatically uses localized field captions from table metadata, ensuring field names appear in the user's preferred language without additional development effort.
+
+### Message Consistency
+Maintain consistent message formatting patterns across the application by establishing standard Label variables for common validation scenarios.
+
+## Message Construction Strategies
+
+### Actionable Guidance
+Construct custom messages that tell users not only what is wrong but also what they should do to fix the problem. Include specific value ranges, acceptable formats, or procedural steps when appropriate.
+
+### Business Rule Explanation
+When FieldError is triggered by complex business rules, provide enough context for users to understand the underlying business logic without overwhelming them with technical details.
+
+### Progressive Information
+For complex validation scenarios, consider whether a single FieldError message can adequately explain the problem, or if multiple validation steps with different error messages would provide better user guidance.
+
+## Integration with Validation Logic
+
+### OnValidate Trigger Usage
+FieldError integrates seamlessly with OnValidate triggers, where business rule validation typically occurs. The method provides immediate feedback when field changes violate business constraints.
+
+### Posting Routine Integration
+Business Central's posting codeunits extensively use FieldError to provide specific feedback about data validation failures during complex business processes. This pattern ensures users receive targeted guidance about posting failures.
+
+### Cross-Field Validation
+When validation involves multiple fields, FieldError can focus user attention on the specific field that needs correction while explaining the relationship to other field values in the custom message text.
+
+## User Experience Design
+
+### Clear Problem Identification
+Effective FieldError messages clearly identify what specific validation rule was violated, helping users understand the exact nature of the problem.
+
+### Solution Guidance
+Include positive instructions about correct data entry rather than just negative statements about what is wrong. Guide users toward successful completion of their data entry task.
+
+### Context Preservation
+Leverage FieldError's automatic context inclusion to help users maintain orientation within complex data entry scenarios, especially when working with large forms or multi-step processes.
+
+## Common Message Patterns
+
+### Range Validation
+For numeric or date range validation, FieldError messages should specify the acceptable range and explain any business rationale for the constraints.
+
+### Format Validation
+For data format requirements, FieldError messages should provide examples of acceptable formats and explain any special formatting rules.
+
+### Dependency Validation
+For fields that depend on other field values, FieldError messages should explain the relationship and guide users toward consistent data entry.
+

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

@@ -0,0 +1,114 @@
+---
+title: "FieldError Method Syntax and Behavior"
+domain: "eva-errors"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["fielderror", "validation", "error-messages", "posting"]
+samples: "samples/fielderror-syntax.md"
+---
+# FieldError Method Syntax and Behavior
+
+## Overview
+
+The FieldError method generates field-specific error messages with automatic field name inclusion and record context. Unlike TestField, FieldError assumes validation has already failed and focuses on error message generation rather than condition checking.
+
+**Core Purpose**: Generate contextual error messages that clearly identify the problematic field and its current state.
+
+## Method Signatures
+
+### Basic Syntax
+The FieldError method accepts two forms:
+- `Record.FieldError(FieldNo: Integer)` - Uses default message generation
+- `Record.FieldError(FieldNo: Integer, MsgText: Text)` - Uses custom message text
+
+### Parameter Details
+- **FieldNo**: Integer identifying the field causing the error
+- **MsgText**: Optional custom error message text (follows lowercase convention)
+
+## Behavioral Characteristics
+
+### Automatic Context Building
+FieldError automatically constructs error messages including:
+- Field caption from table metadata
+- Current field value (when not blank)
+- Record identification (primary key values)
+- Table name context
+
+### Error Message Structure
+Messages follow the pattern: `[Field Caption] [Current Value] [Custom Message] in [Table Name] [Record Key]`
+
+Example output: "Document No. SO-001 must be unique in Sales Header Document Type='Order',No.='SO-001'"
+
+## Implementation Patterns
+
+### Standard Posting Codeunit Usage
+FieldError is extensively used in standard BC posting codeunits (12 Gen. Jnl.-Post Line, 80 Sales-Post, 90 Purch.-Post) for validation failure reporting after conditions have been tested.
+
+### Field Validation Context
+Common usage involves testing business conditions first, then calling FieldError when validation fails. This pattern separates condition testing from error reporting.
+
+## FieldError vs TestField Comparison
+
+### Use FieldError When
+- **Validation already failed**: Error condition has been determined
+- **Custom error context needed**: Standard TestField message insufficient
+- **Complex validation logic**: Multiple conditions or calculations involved
+- **Posting routine errors**: Standard pattern in posting codeunits
+
+### Use TestField When
+- **Simple null/empty checks**: Standard "must have a value" scenarios
+- **Direct field validation**: Single condition testing
+- **Setup validation**: Configuration fields that must be populated
+
+### Behavioral Differences
+- **TestField**: Tests condition AND generates error
+- **FieldError**: Only generates error (assumes condition already tested)
+- **TestField**: Limited to empty/non-empty and value matching
+- **FieldError**: Accepts any custom error message
+
+## Best Practices
+
+### Message Design
+- **Be specific**: Describe exactly what's wrong and why
+- **Include context**: Reference related fields or business rules when relevant
+- **Provide guidance**: Suggest how to resolve the issue when possible
+- **Follow conventions**: Start custom messages with lowercase letter
+
+### Error Timing
+- **Use after validation**: Don't duplicate condition checking
+- **Fail fast**: Call FieldError immediately when error is detected
+- **Single responsibility**: One FieldError per validation condition
+
+### Performance Considerations
+- **Field number constants**: Use field number constants, not field names
+- **Message construction**: Keep custom messages concise but informative
+- **Early exit**: Place FieldError calls after all condition checks
+
+## Common Implementation Scenarios
+
+### Required Field Validation
+Use FieldError without custom message for standard empty field scenarios where default messaging is sufficient.
+
+### Range Validation
+Combine condition testing with FieldError for numeric range violations, providing specific boundary information in custom messages.
+
+### Business Rule Violations
+Apply FieldError for complex business logic failures, including cross-field dependencies and calculated validation scenarios.
+
+### Cross-Field Dependencies
+Validate relationships between fields using FieldError to identify the specific field causing the constraint violation.
+
+## Anti-Patterns
+
+### Avoid These Approaches
+- **Redundant condition checking**: Don't test condition if already validated
+- **Generic error messages**: Don't use FieldError for non-field-specific errors
+- **Message duplication**: Don't repeat information already included automatically
+- **Complex message logic**: Keep message construction simple and direct
+
+## Usage Guidelines
+
+FieldError is most effective when integrated into structured validation routines where business logic testing precedes error reporting. The method's strength lies in automatic context generation combined with flexible custom messaging.
+
+For comprehensive implementation examples and working code samples, see the companion AL code file referenced below.
+

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

@@ -0,0 +1,356 @@
+# FieldError Default Messages - AL Code Sample
+
+## Empty Field Default Messages
+
+```al
+table 50200 "Document Header"
+{
+    fields
+    {
+        field(1; "Document Type"; Enum "Sales Document Type") { }
+        field(2; "Document No."; Code[20]) { }
+        field(3; "Customer No."; Code[20]) { }
+        field(10; "Posting Date"; Date) { }
+        field(20; "Amount"; Decimal) { }
+        field(30; "Currency Code"; Code[10]) { }
+        field(40; "Description"; Text[100]) { }
+    }
+    
+    keys
+    {
+        key(PK; "Document Type", "Document No.") { Clustered = true; }
+    }
+    
+    procedure DemonstrateEmptyFieldMessages()
+    begin
+        // For empty Code field - generates specific "must have a value" message
+        "Customer No." := '';
+        // Output: "Customer No. must have a value in Document Header Document Type='Order', Document No.='DOC001'."
+        FieldError("Customer No.");
+        
+        // For zero Date field - generates specific "must be filled in" message  
+        "Posting Date" := 0D;
+        // Output: "Posting Date must be filled in in Document Header Document Type='Order', Document No.='DOC001'."
+        FieldError("Posting Date");
+        
+        // For zero Decimal field - generates "must not be 0" message
+        Amount := 0;
+        // Output: "Amount must not be 0 in Document Header Document Type='Order', Document No.='DOC001'."
+        FieldError(Amount);
+        
+        // For empty Text field - generates "must have a value" message
+        Description := '';
+        // Output: "Description must have a value in Document Header Document Type='Order', Document No.='DOC001'."
+        FieldError(Description);
+    end;
+}
+```
+
+## Non-Empty Field Default Messages
+
+```al
+table 50201 "Validation Examples"
+{
+    fields
+    {
+        field(1; "Entry No."; Integer) { }
+        field(10; "Status"; Option) { OptionMembers = " ",Open,Released,Closed; }
+        field(20; "Item No."; Code[20]) { }
+        field(30; "Quantity"; Decimal) { }
+        field(40; "Unit Price"; Decimal) { }
+    }
+    
+    keys
+    {
+        key(PK; "Entry No.") { Clustered = true; }
+    }
+    
+    procedure DemonstrateNonEmptyFieldMessages()
+    begin
+        "Entry No." := 1001;
+        "Item No." := 'ITEM001';
+        Quantity := 5.5;
+        "Unit Price" := 100.00;
+        Status := Status::Released;
+        
+        // For non-empty Code field - generates "is not valid" message
+        // Output: "Item No. ITEM001 is not valid in Validation Examples Entry No.='1001'."
+        FieldError("Item No.");
+        
+        // For non-zero Decimal field - generates "is not valid" message  
+        // Output: "Quantity 5.5 is not valid in Validation Examples Entry No.='1001'."
+        FieldError(Quantity);
+        
+        // For non-zero Option field - generates "is not valid" message
+        // Output: "Status Released is not valid in Validation Examples Entry No.='1001'."
+        FieldError(Status);
+    end;
+}
+```
+
+## Record Context in Error Messages
+
+```al
+table 50202 "Customer Transaction"
+{
+    fields
+    {
+        field(1; "Customer No."; Code[20]) { }
+        field(2; "Transaction Date"; Date) { }
+        field(3; "Transaction No."; Code[20]) { }
+        field(10; "Amount"; Decimal) { }
+        field(20; "Currency Code"; Code[10]) { }
+    }
+    
+    keys
+    {
+        key(PK; "Customer No.", "Transaction Date", "Transaction No.") { Clustered = true; }
+    }
+    
+    procedure DemonstrateRecordContextMessages()
+    begin
+        "Customer No." := 'CUST001';
+        "Transaction Date" := Today;
+        "Transaction No." := 'TXN001';
+        Amount := 0;
+        
+        // BC automatically includes primary key fields in error message
+        // Output: "Amount must not be 0 in Customer Transaction Customer No.='CUST001', Transaction Date='01/28/25', Transaction No.='TXN001'."
+        FieldError(Amount);
+        
+        // Even with custom message, record context is automatically included
+        // Output: "Amount cannot be zero for transactions in Customer Transaction Customer No.='CUST001', Transaction Date='01/28/25', Transaction No.='TXN001'."
+        FieldError(Amount, 'cannot be zero for transactions');
+    end;
+}
+```
+
+## Default vs Custom Message Comparison
+
+```al
+codeunit 50200 "Message Comparison Examples"
+{
+    procedure CompareDefaultAndCustomMessages()
+    var
+        SalesHeader: Record "Sales Header";
+        Customer: Record Customer;
+    begin
+        SalesHeader."Document Type" := SalesHeader."Document Type"::Order;
+        SalesHeader."No." := 'SO001';
+        SalesHeader."Sell-to Customer No." := '';
+        
+        // DEFAULT MESSAGE EXAMPLES
+        
+        // Empty field default message
+        // "Sell-to Customer No. must have a value in Sales Header Document Type='Order', No.='SO001'."
+        // SalesHeader.FieldError("Sell-to Customer No.");
+        
+        // Non-empty field default message  
+        SalesHeader."Sell-to Customer No." := 'INVALID';
+        // "Sell-to Customer No. INVALID is not valid in Sales Header Document Type='Order', No.='SO001'."
+        // SalesHeader.FieldError("Sell-to Customer No.");
+        
+        // CUSTOM MESSAGE EXAMPLES
+        
+        // Custom message with empty field
+        SalesHeader."Sell-to Customer No." := '';
+        // "Sell-to Customer No. is required for sales orders in Sales Header Document Type='Order', No.='SO001'."
+        // SalesHeader.FieldError("Sell-to Customer No.", 'is required for sales orders');
+        
+        // Custom message with non-empty field
+        SalesHeader."Sell-to Customer No." := 'BLOCKED';
+        // "Sell-to Customer No. customer is blocked in Sales Header Document Type='Order', No.='SO001'."
+        // SalesHeader.FieldError("Sell-to Customer No.", 'customer is blocked');
+        
+        // Complex custom message with context
+        if not Customer.Get(SalesHeader."Sell-to Customer No.") then
+            // "Sell-to Customer No. does not exist in customer master in Sales Header Document Type='Order', No.='SO001'."
+            SalesHeader.FieldError("Sell-to Customer No.", 'does not exist in customer master');
+    end;
+}
+```
+
+## Real-World Message Generation Scenarios
+
+```al
+codeunit 50201 "Real-World Validation Messages"
+{
+    // Scenario 1: Document Processing Validation
+    procedure ValidateDocumentForPosting(var SalesHeader: Record "Sales Header")
+    begin
+        // Required field validations - using default messages for consistency
+        if SalesHeader."Sell-to Customer No." = '' then
+            // "Sell-to Customer No. must have a value in Sales Header..."
+            SalesHeader.FieldError("Sell-to Customer No.");
+            
+        if SalesHeader."Posting Date" = 0D then  
+            // "Posting Date must be filled in in Sales Header..."
+            SalesHeader.FieldError("Posting Date");
+            
+        // Business rule validations - using custom messages for clarity
+        if SalesHeader."Posting Date" > WorkDate() + 30 then
+            // "Posting Date cannot be more than 30 days in future in Sales Header..."
+            SalesHeader.FieldError("Posting Date", 'cannot be more than 30 days in future');
+    end;
+    
+    // Scenario 2: Setup Validation with Detailed Messages
+    procedure ValidateCustomerSetup(var Customer: Record Customer)
+    var
+        PostCode: Record "Post Code";
+    begin
+        // Default message for required field
+        if Customer."No." = '' then
+            // "No. must have a value in Customer..."
+            Customer.FieldError("No.");
+            
+        // Custom message for business logic
+        if Customer."Credit Limit (LCY)" < 0 then
+            // "Credit Limit (LCY) cannot be negative in Customer No.='CUST001'."
+            Customer.FieldError("Credit Limit (LCY)", 'cannot be negative');
+            
+        // Validation with lookup and detailed custom message
+        if (Customer."Post Code" <> '') and not PostCode.Get(Customer."Post Code", Customer.City) then
+            // "Post Code is not valid for the specified city in Customer No.='CUST001'."
+            Customer.FieldError("Post Code", 'is not valid for the specified city');
+    end;
+    
+    // Scenario 3: Line Validation with Context
+    procedure ValidateSalesLine(var SalesLine: Record "Sales Line")
+    var
+        Item: Record Item;
+        AvailableInventory: Decimal;
+    begin
+        // Standard required field validation
+        if SalesLine."No." = '' then
+            // "No. must have a value in Sales Line Document Type='Order', Document No.='SO001', Line No.='10000'."
+            SalesLine.FieldError("No.");
+            
+        // Business logic with calculated values in message
+        if SalesLine.Type = SalesLine.Type::Item then begin
+            Item.Get(SalesLine."No.");
+            Item.CalcFields(Inventory);
+            AvailableInventory := Item.Inventory;
+            
+            if SalesLine.Quantity > AvailableInventory then
+                // "Quantity exceeds available inventory (50 units available) in Sales Line..."
+                SalesLine.FieldError(Quantity, 
+                    StrSubstNo('exceeds available inventory (%1 units available)', AvailableInventory));
+        end;
+        
+        // Price validation with business context
+        if SalesLine."Unit Price" <= 0 then
+            // "Unit Price must be positive for sales transactions in Sales Line..."
+            SalesLine.FieldError("Unit Price", 'must be positive for sales transactions');
+    end;
+}
+```
+
+## Message Formatting Rules and Patterns
+
+```al
+codeunit 50202 "Message Formatting Examples"
+{
+    procedure DemonstrateFormattingRules()
+    var
+        Item: Record Item;
+        PurchaseLine: Record "Purchase Line";
+    begin
+        Item."No." := 'ITEM001';
+        
+        // RULE 1: Default messages automatically include field value for non-empty fields
+        Item.Description := 'Invalid Description Content';
+        // "Description Invalid Description Content is not valid in Item No.='ITEM001'."
+        // Item.FieldError(Description);
+        
+        // RULE 2: Custom messages start with lowercase (BC convention)
+        // CORRECT:
+        // "Description must not contain special characters in Item No.='ITEM001'."
+        // Item.FieldError(Description, 'must not contain special characters');
+        
+        // INCORRECT (would still work but doesn't follow BC conventions):
+        // Item.FieldError(Description, 'Must not contain special characters');
+        
+        // RULE 3: Record context automatically appended using primary key
+        PurchaseLine."Document Type" := PurchaseLine."Document Type"::Order;
+        PurchaseLine."Document No." := 'PO001';
+        PurchaseLine."Line No." := 10000;
+        PurchaseLine.Quantity := -5;
+        
+        // "Quantity cannot be negative in Purchase Line Document Type='Order', Document No.='PO001', Line No.='10000'."
+        PurchaseLine.FieldError(Quantity, 'cannot be negative');
+        
+        // RULE 4: Multiple primary key fields included in order
+        // All key fields shown in error context for complete record identification
+    end;
+    
+    procedure DemonstrateMessageCustomization()
+    var
+        Customer: Record Customer;
+        CreditLimit: Decimal;
+    begin
+        Customer."No." := 'CUST001';
+        Customer."Credit Limit (LCY)" := 5000;
+        CreditLimit := 10000;  // Required limit for this customer
+        
+        // Pattern: Specific business context in custom messages
+        // "Credit Limit (LCY) insufficient for customer risk category (minimum 10000 required) in Customer No.='CUST001'."
+        Customer.FieldError("Credit Limit (LCY)", 
+            StrSubstNo('insufficient for customer risk category (minimum %1 required)', CreditLimit));
+        
+        // Pattern: Action guidance in custom messages
+        // "Credit Limit (LCY) requires manager approval for amounts above 50000 in Customer No.='CUST001'."
+        Customer.FieldError("Credit Limit (LCY)", 'requires manager approval for amounts above 50000');
+        
+        // Pattern: Reference to related data in custom messages  
+        // "Credit Limit (LCY) conflicts with existing payment terms (Net 60) in Customer No.='CUST001'."
+        Customer.FieldError("Credit Limit (LCY)", 'conflicts with existing payment terms (Net 60)');
+    end;
+}
+```
+
+## Advanced Default Message Scenarios
+
+```al
+table 50203 "Advanced Message Examples"
+{
+    fields
+    {
+        field(1; "Primary Key"; Code[20]) { }
+        field(10; "Boolean Field"; Boolean) { }
+        field(20; "DateTime Field"; DateTime) { }
+        field(30; "GUID Field"; Guid) { }
+        field(40; "Blob Field"; Blob) { }
+    }
+    
+    procedure DemonstrateAdvancedDefaultMessages()
+    begin
+        "Primary Key" := 'TEST001';
+        
+        // Boolean field default messages
+        "Boolean Field" := false;
+        // "Boolean Field No is not valid in Advanced Message Examples Primary Key='TEST001'."
+        // FieldError("Boolean Field");
+        
+        "Boolean Field" := true;  
+        // "Boolean Field Yes is not valid in Advanced Message Examples Primary Key='TEST001'."
+        // FieldError("Boolean Field");
+        
+        // DateTime field default messages
+        "DateTime Field" := 0DT;
+        // "DateTime Field must be filled in in Advanced Message Examples Primary Key='TEST001'."
+        // FieldError("DateTime Field");
+        
+        "DateTime Field" := CurrentDateTime;
+        // "DateTime Field 01/28/25 09:30:00 is not valid in Advanced Message Examples Primary Key='TEST001'."
+        // FieldError("DateTime Field");
+        
+        // GUID field default messages
+        Clear("GUID Field");
+        // "GUID Field must have a value in Advanced Message Examples Primary Key='TEST001'."
+        // FieldError("GUID Field");
+        
+        "GUID Field" := CreateGuid();
+        // "GUID Field {12345678-1234-1234-1234-123456789012} is not valid in Advanced Message Examples Primary Key='TEST001'."
+        // FieldError("GUID Field");
+    end;
+}