@jwikman/bc-code-intelligence-mcp 1.5.7-dev.1

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

@@ -0,0 +1,145 @@
+---
+title: "FieldError Default Message Logic"
+domain: "eva-errors"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["fielderror", "default-messages", "field-state", "error-text"]
+samples: "samples/fielderror-default-messages.md"
+---
+# FieldError Default Message Logic
+
+## Overview
+
+When FieldError is called without the MsgText parameter, Business Central automatically generates contextual error messages based on field state and metadata. This default message logic provides consistent, informative error reporting with minimal code.
+
+**Key Advantage**: Automatic message generation reduces code maintenance while providing rich contextual information.
+
+## Default Message Construction
+
+### Message Components
+Business Central constructs default error messages using five key components:
+1. **Field Caption**: From table field definition
+2. **Current Value**: Field content (if not empty)
+3. **Standard Text**: Context-appropriate default message
+4. **Record Context**: Primary key fields for record identification
+5. **Table Name**: Source table identification
+
+### Field State Detection
+
+#### Empty Field Messages
+For empty fields, BC generates "must have a value" or "must be filled in" messages depending on field type. Code and Text fields use "must have a value" while Date fields use "must be filled in".
+
+#### Non-Empty Field Messages
+For fields containing data, BC generates "is not valid" messages that include the current field value, helping users identify exactly what data caused the validation failure.
+
+#### Record Context Inclusion
+All FieldError messages automatically include primary key field values to provide complete record identification, enabling users to locate the specific record causing the error.
+
+## Default Message Patterns
+
+### Standard Empty Field Pattern
+Structure follows: "[Field Caption] must have a value in [Table Name] [Record Key]"
+- **Use Case**: Required field validation
+- **Common Scenario**: Setup tables, document headers, required configuration
+
+### Standard Value Conflict Pattern
+Structure follows: "[Field Caption] [Current Value] already exists in [Table Name] [Record Key]"
+- **Use Case**: Uniqueness violations, duplicate detection
+- **Common Scenario**: Primary key conflicts, unique index violations
+
+### Context-Specific Patterns
+Business Central applies different default messages based on:
+- Field data type and properties
+- Table relationships and constraints
+- Current field state and validation context
+
+## Strategic Decision Matrix
+
+### Use Default Messages When
+- **Standard validation scenarios**: Common empty/duplicate field errors
+- **Consistent user experience desired**: Uniform error message formatting
+- **Minimal maintenance required**: Automatic message updates with metadata changes
+- **Field caption changes**: Messages automatically reflect caption updates
+
+### Use Custom Messages When
+- **Business rule violations**: Complex validation logic requiring explanation
+- **Specific guidance needed**: Error messages should guide user resolution
+- **Context-sensitive information**: Additional fields or calculations referenced
+- **User experience optimization**: Tailored messages for specific user workflows
+
+## Implementation Examples
+
+### Leveraging Default Messages
+Setup validation scenarios benefit from default messaging where standard "must have a value" text provides adequate user guidance without additional context.
+
+### Mixed Default and Custom Messages
+Combining default empty field detection with custom business logic provides optimal balance between consistency and specificity in error reporting.
+
+### Record State-Aware Validation
+Different validation approaches based on record state allow for appropriate use of default messages for standard scenarios while applying custom messages for complex business rules.
+
+## Best Practices
+
+### Default Message Optimization
+- **Field captions**: Ensure field captions are user-friendly and descriptive
+- **Table design**: Structure primary keys to provide meaningful record context
+- **Consistent patterns**: Use default messages for standard validation scenarios
+- **Message testing**: Verify default messages provide adequate user guidance
+
+### Custom vs Default Decision Process
+1. **Evaluate standard patterns**: Does default message adequately describe the problem?
+2. **Consider user guidance**: Do users need additional context or resolution steps?
+3. **Assess business rules**: Does the error involve complex business logic?
+4. **Plan for maintenance**: Will custom messages require ongoing updates?
+
+### Performance Considerations
+- **Default message efficiency**: BC generates default messages efficiently
+- **Custom message overhead**: Complex custom messages may impact performance
+- **Field access patterns**: Default messages access field metadata, not additional data
+- **Localization support**: Default messages automatically support multiple languages
+
+## Message Quality Assessment
+
+### Effective Default Messages
+- **Clear field identification**: Field caption clearly identifies the problematic field
+- **Sufficient context**: Record key provides adequate record identification
+- **Consistent formatting**: Uniform message structure across application
+- **Automatic updates**: Messages reflect metadata changes without code updates
+
+### When Defaults Fall Short
+- **Insufficient business context**: Generic messages don't explain business rules
+- **Poor field captions**: Technical field names don't guide users effectively
+- **Complex relationships**: Multi-field or cross-table validation scenarios
+- **Specific user workflows**: Messages don't align with user task patterns
+
+## Localization and Maintenance
+
+### Automatic Benefits
+- **Language support**: Default messages automatically support BC language packs
+- **Metadata synchronization**: Messages update when field captions change
+- **Consistent terminology**: Standard message patterns across entire application
+- **Reduced translation overhead**: No custom message translation required
+
+### Maintenance Advantages
+- **Code simplification**: Fewer message strings to maintain
+- **Automatic updates**: Metadata changes propagate to error messages
+- **Quality consistency**: Standard message quality across all validation scenarios
+- **Development efficiency**: Faster implementation of standard validation patterns
+
+## Advanced Default Message Behavior
+
+### Field Type Variations
+Different field types generate contextually appropriate default messages. Boolean fields show "Yes/No" states, DateTime fields include full timestamp information, and GUID fields display the complete identifier.
+
+### Multi-Language Considerations
+Default messages automatically adapt to user language settings without requiring additional translation effort, making them ideal for international deployments.
+
+### Record Key Complexity
+Tables with complex primary keys automatically include all key fields in error context, providing comprehensive record identification regardless of table structure complexity.
+
+## Implementation Guidelines
+
+Default message logic works most effectively when field captions accurately represent user-facing terminology and primary key structures provide meaningful record identification. Strategic use of default messages reduces maintenance overhead while maintaining user experience quality.
+
+For detailed implementation examples and working code samples demonstrating default message behavior across various field types and scenarios, see the companion AL code file.
+

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/codeunit-run-pattern.md

@@ -0,0 +1,239 @@
+# Codeunit.Run() Pattern Samples
+
+## Basic Pattern: Isolated Processing
+```al
+procedure ProcessDocumentSafely(DocumentNo: Code[20]): Boolean
+var
+    ProcessingCodeunit: Codeunit "Document Processor";
+    DocumentRec: Record "My Document";
+begin
+    DocumentRec.Get(DocumentNo);
+    
+    // CRITICAL: Commit any pending transaction first
+    Commit();
+    
+    // Run with result capture - creates new transaction
+    if ProcessingCodeunit.Run(DocumentRec) then begin
+        Message('Document %1 processed successfully', DocumentNo);
+        exit(true);
+    end else begin
+        // Error captured, transaction rolled back
+        LogError(DocumentNo, GetLastErrorText());
+        Message('Processing failed: %1', GetLastErrorText());
+        exit(false);
+    end;
+end;
+```
+
+## Batch Processing with Continuation
+```al
+procedure ProcessSalesOrderBatch(var TempOrdersToProcess: Record "Sales Header" temporary)
+var
+    PostingCodeunit: Codeunit "Sales-Post";
+    SalesHeader: Record "Sales Header";
+    SuccessCount: Integer;
+    FailureCount: Integer;
+begin
+    if TempOrdersToProcess.FindSet() then
+        repeat
+            // Get fresh record for each iteration
+            SalesHeader.Get(TempOrdersToProcess."Document Type", TempOrdersToProcess."No.");
+            
+            // Commit before each run - clean transaction boundary
+            Commit();
+            
+            // Each posting runs in its own transaction
+            if PostingCodeunit.Run(SalesHeader) then
+                SuccessCount += 1
+            else begin
+                FailureCount += 1;
+                LogPostingError(SalesHeader."No.", GetLastErrorText());
+            end;
+            
+            // Clear for next iteration
+            Clear(PostingCodeunit);
+        until TempOrdersToProcess.Next() = 0;
+    
+    Message('Processed: %1 successful, %2 failed', SuccessCount, FailureCount);
+end;
+```
+
+## Integration with Error Recovery
+```al
+procedure SyncInventoryWithRetry(ItemNo: Code[20]): Boolean
+var
+    InventorySyncCodeunit: Codeunit "Inventory Sync";
+    Item: Record Item;
+    RetryCount: Integer;
+    MaxRetries: Integer;
+begin
+    MaxRetries := 3;
+    Item.Get(ItemNo);
+    
+    for RetryCount := 1 to MaxRetries do begin
+        // Must commit before each attempt
+        Commit();
+        
+        if InventorySyncCodeunit.Run(Item) then
+            exit(true);
+        
+        LogRetry(ItemNo, RetryCount, GetLastErrorText());
+        
+        if RetryCount < MaxRetries then begin
+            Sleep(2000);  // Wait before retry
+            Clear(InventorySyncCodeunit);
+        end;
+    end;
+    
+    LogFinalFailure(ItemNo, 'Max retries exceeded');
+    exit(false);
+end;
+```
+
+## WRONG: Missing Commit
+```al
+// ❌ THIS WILL FAIL AT RUNTIME
+procedure WrongPattern(CustomerNo: Code[20])
+var
+    Customer: Record Customer;
+    ProcessCodeunit: Codeunit "Customer Processor";
+begin
+    Customer.Get(CustomerNo);
+    Customer.Status := Customer.Status::Pending;
+    Customer.Modify();  // Transaction is now open
+    
+    // ❌ ERROR: Cannot start new transaction with pending changes
+    if ProcessCodeunit.Run(Customer) then
+        Message('Success')
+    else
+        Message('Failed');
+end;
+```
+
+## CORRECT: Proper Commit Placement
+```al
+// ✅ CORRECT PATTERN
+procedure CorrectPattern(CustomerNo: Code[20])
+var
+    Customer: Record Customer;
+    ProcessCodeunit: Codeunit "Customer Processor";
+begin
+    Customer.Get(CustomerNo);
+    Customer.Status := Customer.Status::Pending;
+    Customer.Modify();
+    
+    // ✅ Commit pending changes first
+    Commit();
+    
+    // Now safe to run with result capture
+    if ProcessCodeunit.Run(Customer) then
+        Message('Success')
+    else begin
+        Message('Processing failed: %1', GetLastErrorText());
+        // Note: The status change IS committed, 
+        // only the processor's changes are rolled back
+    end;
+end;
+```
+
+## Optional Processing Steps
+```al
+procedure PostInvoiceWithNotification(var SalesHeader: Record "Sales Header")
+var
+    PostingCodeunit: Codeunit "Sales-Post";
+    NotificationCodeunit: Codeunit "Customer Notifier";
+begin
+    // Main posting - must succeed
+    PostingCodeunit.Run(SalesHeader);  // No capture - errors propagate
+    
+    // Notification is optional - failure shouldn't block posting
+    Commit();  // Commit the successful posting
+    
+    if not NotificationCodeunit.Run(SalesHeader) then
+        // Log but don't fail - invoice is already posted
+        LogWarning('Customer notification failed: ' + GetLastErrorText());
+end;
+```
+
+## Archive Operation Pattern
+```al
+procedure ProcessAndArchive(var SourceRecord: Record "Source Document")
+var
+    MainProcessor: Codeunit "Main Processor";
+    ArchiveProcessor: Codeunit "Archive Processor";
+begin
+    // Main processing - required
+    MainProcessor.Run(SourceRecord);
+    
+    // Archive - nice to have but not critical
+    Commit();
+    
+    if not ArchiveProcessor.Run(SourceRecord) then begin
+        // Archive failed but main process succeeded
+        LogWarning('Archive failed for ' + SourceRecord."No." + 
+            ': ' + GetLastErrorText());
+        // Continue - don't fail the entire operation
+    end;
+end;
+```
+
+## Comparison: Without vs With Result Capture
+```al
+// WITHOUT result capture - errors propagate
+procedure StandardRun()
+var
+    MyCodeunit: Codeunit "My Codeunit";
+begin
+    MyCodeunit.Run();  // Error here stops everything
+    Message('This only runs if codeunit succeeded');
+end;
+
+// WITH result capture - errors are caught
+procedure CapturedRun(): Boolean
+var
+    MyCodeunit: Codeunit "My Codeunit";
+begin
+    Commit();  // Required before captured run
+    
+    if MyCodeunit.Run() then begin
+        Message('Codeunit succeeded');
+        exit(true);
+    end else begin
+        Message('Codeunit failed: ' + GetLastErrorText());
+        exit(false);
+    end;
+    // Execution continues either way
+end;
+```
+
+## Multi-Step Process with Clean Boundaries
+```al
+procedure CompleteOrderFulfillment(OrderNo: Code[20])
+var
+    Order: Record "Sales Header";
+    PickProcessor: Codeunit "Pick Processor";
+    ShipProcessor: Codeunit "Ship Processor";
+    InvoiceProcessor: Codeunit "Invoice Processor";
+begin
+    Order.Get(Order."Document Type"::Order, OrderNo);
+    
+    // Phase 1: Picking
+    Commit();
+    if not PickProcessor.Run(Order) then
+        Error('Pick failed: %1', GetLastErrorText());
+    
+    // Phase 2: Shipping  
+    Order.Get(Order."Document Type"::Order, OrderNo);  // Refresh
+    Commit();
+    if not ShipProcessor.Run(Order) then
+        Error('Ship failed: %1', GetLastErrorText());
+    
+    // Phase 3: Invoicing
+    Order.Get(Order."Document Type"::Order, OrderNo);  // Refresh
+    Commit();
+    if not InvoiceProcessor.Run(Order) then
+        Error('Invoice failed: %1', GetLastErrorText());
+    
+    Message('Order %1 fully fulfilled', OrderNo);
+end;
+```