bc-code-intelligence-mcp 1.1.1

package/embedded-knowledge/domains/alex-architect/facade-pattern-al-implementation.md

@@ -0,0 +1,138 @@
+---
+title: "Facade Pattern AL Implementation"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["facade-pattern", "structural-patterns", "api-simplification", "complexity-hiding"]
+prerequisites: ["object-orientation-al", "interface-basics", "module-design"]
+samples: "samples/facade-pattern-al.md"
+related_topics: ["complex-facade-patterns", "adapter-pattern-al"]
+---
+
+# Facade Pattern AL Implementation
+
+## Overview
+
+The Facade Pattern provides a simplified interface to a complex subsystem, hiding the complexity of multiple interacting objects behind a single, easy-to-use interface. In AL development, facades are essential for creating clean APIs and managing complex business logic interactions.
+
+**Key Benefit**: Simplifies client code by providing a unified interface to complex subsystems while maintaining loose coupling and flexibility.
+
+## Core Facade Architecture
+
+### Unified Interface Design
+Create single interfaces that encapsulate complex operations across multiple AL objects, procedures, and business logic components.
+
+### Complexity Encapsulation
+Hide implementation details of complex subsystems behind simple, focused facade methods that handle coordination and orchestration.
+
+### Dependency Management
+Manage dependencies between multiple subsystem components within the facade, preventing clients from needing to understand complex relationships.
+
+## Implementation Strategies
+
+### Business Process Facades
+Design facades that encapsulate complete business processes, coordinating multiple tables, pages, and codeunits to provide single-operation interfaces.
+
+### Data Access Facades
+Implement facades that simplify complex data access patterns, hiding join operations, filtering logic, and data transformation from client code.
+
+### Integration Facades
+Create facades for external system integration that hide protocol details, authentication, and error handling behind simple method calls.
+
+## AL-Specific Patterns
+
+### Codeunit Facade Implementation
+Use codeunits as facade implementations that coordinate multiple AL objects while providing clean, procedure-based interfaces.
+
+### Table Facade Extensions
+Extend table objects with facade methods that encapsulate complex business logic while maintaining data integrity and validation rules.
+
+### Page Integration Facades
+Design page-level facades that coordinate multiple page elements and actions to provide simplified user interaction patterns.
+
+## Advanced Facade Techniques
+
+### Layered Facade Architecture
+Implement multiple facade layers that provide different levels of abstraction for different types of clients and usage scenarios.
+
+### Context-Aware Facades
+Design facades that adapt their behavior based on user context, permissions, or system configuration while maintaining consistent interfaces.
+
+### Event-Integrated Facades
+Integrate facade operations with AL event systems to provide notifications and enable extensibility without facade modification.
+
+## Performance Considerations
+
+### Operation Optimization
+Optimize facade operations to minimize unnecessary object instantiation and method calls while maintaining interface simplicity.
+
+### Caching Integration
+Implement intelligent caching within facades to improve performance for frequently accessed complex operations.
+
+### Resource Management
+Design facades to efficiently manage resources and connections, especially for integration and external system access scenarios.
+
+## Error Handling and Validation
+
+### Unified Error Management
+- Implement consistent error handling across all facade operations
+- Provide meaningful error messages that abstract subsystem complexity
+- Support error recovery and retry mechanisms within facade logic
+- Maintain error logging and diagnostics for troubleshooting
+
+### Input Validation
+- Centralize validation logic within facade methods
+- Provide comprehensive parameter validation before subsystem operations
+- Support business rule validation across multiple subsystem components
+- Enable early error detection to prevent inconsistent states
+
+## Best Practices
+
+### Design Principles
+- Keep facade interfaces focused and cohesive
+- Implement facades at appropriate abstraction levels for target clients
+- Maintain clear separation between facade logic and subsystem implementation
+- Design for both simplicity and extensibility
+
+### Documentation Standards
+- Provide clear documentation for facade capabilities and limitations
+- Include examples of common usage patterns and scenarios
+- Document any performance characteristics or constraints
+- Maintain clear guidance for when to use facade versus direct subsystem access
+
+## Integration Patterns
+
+### Service Layer Integration
+Integrate facades with service layer patterns to provide business service interfaces that coordinate multiple business capabilities.
+
+### API Gateway Patterns
+Use facades as API gateways that provide external access to internal Business Central capabilities with appropriate security and validation.
+
+### Microservice Coordination
+Design facades that coordinate microservice interactions while providing unified interfaces for complex business operations.
+
+## Testing Strategies
+
+### Facade Testing
+- Implement comprehensive testing for facade operations and edge cases
+- Mock subsystem dependencies to enable isolated facade testing
+- Test error handling and recovery scenarios thoroughly
+- Validate facade performance under different load conditions
+
+### Integration Testing
+- Test complete end-to-end scenarios through facade interfaces
+- Validate subsystem coordination and data consistency
+- Test facade behavior under various system conditions and configurations
+- Ensure facade operations maintain transactional integrity
+
+## Common Pitfalls
+
+### Over-Simplification
+Avoid over-simplifying facades to the point where necessary functionality becomes inaccessible to clients requiring more control.
+
+### Facade Bloat
+Prevent facades from becoming bloated with too many responsibilities that reduce their effectiveness and maintainability.
+
+*Complete facade implementation examples: samples/facade-pattern-al.md*
+*Complex facade patterns: complex-facade-patterns.md*
+*Related structural patterns: adapter-pattern-al.md*

package/embedded-knowledge/domains/alex-architect/facade-pattern-external-api.md

@@ -0,0 +1,79 @@
+---
+title: "AL Facade Pattern for External API Integration"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["facade-pattern", "api-integration", "abstraction", "maintainability"]
+samples: "samples/facade-pattern.md"
+type: improvement-pattern
+category: "architectural-patterns"
+pattern_type: good
+severity: medium
+impact_level: medium
+improvement_suggestion: "Use facade pattern to simplify external API integration"
+implementation_steps: ["create-facade-codeunit", "abstract-api-calls", "centralize-error-handling"]
+validation_criteria: ["single-entry-point", "hidden-complexity", "clean-interfaces"]
+technical_areas: ["al-code", "integration"]
+---
+
+# AL Facade Pattern for External API Integration
+
+## Overview
+
+The facade pattern creates a unified, simplified interface to complex external API systems. Instead of exposing raw API complexity throughout your AL codebase, the facade provides a clean business-focused entry point that handles all technical implementation details internally.
+
+**Core Principle**: One dedicated codeunit acts as the single gateway to external systems, abstracting authentication, error handling, retry logic, and data transformation.
+
+## Strategic Framework
+
+### When to Apply Facade Pattern
+- **Multiple API endpoints** required for single business operation
+- **Complex authentication flows** (OAuth, JWT, multi-step auth)
+- **Inconsistent external API responses** requiring normalization
+- **Rate limiting and retry logic** needed across multiple calls
+- **Future API changes** anticipated requiring isolation from business logic
+
+### Architecture Benefits
+- **Dependency Isolation**: External system changes don't cascade through codebase
+- **Simplified Testing**: Clear boundaries for mocking external dependencies
+- **Centralized Logic**: Authentication, error handling, and retry patterns in one place
+- **Business Focus**: Consuming objects work with business concepts, not technical APIs
+
+## Architecture Focus
+
+### Facade Structure
+Create a dedicated codeunit containing:
+- **Public Methods**: Business-focused operations (GetCustomerData, SyncOrderStatus)
+- **Private Methods**: Technical API calls, authentication, error handling
+- **Internal State**: Connection management, token caching, configuration
+
+### Interface Design Principles
+- **Business Language**: Method names reflect business operations, not API endpoints
+- **Simplified Parameters**: Hide complex API parameter mapping from consumers
+- **Consistent Returns**: Standardized response patterns regardless of underlying API variations
+- **Error Abstraction**: Convert technical errors to business-meaningful messages
+
+## Best Practices
+
+### Implementation Guidelines
+- **Single Responsibility**: Each facade handles one external system or related service group
+- **Stateless Design**: Avoid maintaining connection state between method calls
+- **Configuration Driven**: Use setup tables for URLs, credentials, and API versions
+- **Comprehensive Logging**: Log all external interactions for troubleshooting
+
+### Error Handling Strategy
+- **Graceful Degradation**: Provide fallback behaviors when external systems unavailable
+- **Retry Logic**: Implement exponential backoff for transient failures
+- **Circuit Breaker**: Prevent cascading failures when external system is down
+- **User-Friendly Messages**: Translate technical errors to actionable business guidance
+
+## Anti-Patterns
+
+### Avoid These Approaches
+- **Direct API Calls** scattered throughout business logic objects
+- **Shared HTTP Client** instances without proper abstraction layer
+- **Exposed Technical Details** like HTTP status codes in business methods
+- **Mixed Responsibilities** combining business logic with API communication
+
+**Implementation Reference**: see samples/facade-pattern.md
+**Related Patterns**: error-handling-patterns.md, api-authentication-patterns.md

package/embedded-knowledge/domains/alex-architect/samples/api-delegate-operation.md

@@ -0,0 +1,280 @@
+# API Delegate Operation Pattern - AL Code Examples
+
+This sample demonstrates implementing delegate operations for extensible APIs in Business Central.
+
+## Basic Delegate Interface
+
+```al
+// Define delegate operation interface
+interface IDelegateOperation
+{
+    procedure Execute(var Parameters: Dictionary of [Text, Variant]): Boolean;
+    procedure GetName(): Text[50];
+    procedure GetDescription(): Text[250];
+}
+```
+
+## Simple Delegate Implementation
+
+```al
+// Customer validation delegate example
+codeunit 50100 "Customer Validation Delegate" implements IDelegateOperation
+{
+    procedure Execute(var Parameters: Dictionary of [Text, Variant]): Boolean
+    var
+        Customer: Record Customer;
+        CustomerNo: Code[20];
+        ValidationResult: Boolean;
+    begin
+        // Extract parameters
+        if not Parameters.Get('CustomerNo', CustomerNo) then
+            exit(false);
+
+        if not Customer.Get(CustomerNo) then
+            exit(false);
+
+        // Custom validation logic
+        ValidationResult := ValidateCustomerForOperation(Customer);
+        Parameters.Set('IsValid', ValidationResult);
+
+        exit(ValidationResult);
+    end;
+
+    procedure GetName(): Text[50]
+    begin
+        exit('CUSTOMER_VALIDATION');
+    end;
+
+    procedure GetDescription(): Text[250]
+    begin
+        exit('Validates customer eligibility for business operations');
+    end;
+
+    local procedure ValidateCustomerForOperation(Customer: Record Customer): Boolean
+    begin
+        // Business logic for customer validation
+        exit((Customer.Blocked = Customer.Blocked::" ") and (Customer."Credit Limit (LCY)" > 0));
+    end;
+}
+```
+
+## Delegate Registry System
+
+```al
+// Central delegate registry for operation management
+codeunit 50101 "Delegate Registry"
+{
+    var
+        DelegateOperations: Dictionary of [Text, Interface IDelegateOperation];
+
+    procedure RegisterDelegate(OperationType: Text[50]; DelegateOperation: Interface IDelegateOperation)
+    begin
+        DelegateOperations.Set(OperationType, DelegateOperation);
+    end;
+
+    procedure ExecuteDelegate(OperationType: Text[50]; var Parameters: Dictionary of [Text, Variant]): Boolean
+    var
+        DelegateOperation: Interface IDelegateOperation;
+    begin
+        if not DelegateOperations.Get(OperationType, DelegateOperation) then
+            exit(false);
+
+        exit(DelegateOperation.Execute(Parameters));
+    end;
+
+    procedure GetAvailableDelegates(): List of [Text]
+    var
+        AvailableTypes: List of [Text];
+        OperationType: Text;
+    begin
+        foreach OperationType in DelegateOperations.Keys do
+            AvailableTypes.Add(OperationType);
+
+        exit(AvailableTypes);
+    end;
+}
+```
+
+## API with Delegate Operations
+
+```al
+// Sales API that uses delegate operations for extensibility
+page 50100 "Sales API"
+{
+    PageType = API;
+    APIPublisher = 'mycompany';
+    APIGroup = 'sales';
+    APIVersion = 'v1.0';
+    EntityName = 'salesOrder';
+    EntitySetName = 'salesOrders';
+    SourceTable = "Sales Header";
+
+    layout
+    {
+        area(Content)
+        {
+            repeater(Group)
+            {
+                field(documentNo; Rec."No.")
+                {
+                    ApplicationArea = All;
+                }
+                field(customerNo; Rec."Sell-to Customer No.")
+                {
+                    ApplicationArea = All;
+                }
+                field(status; Rec.Status)
+                {
+                    ApplicationArea = All;
+                }
+            }
+        }
+    }
+
+    trigger OnInsertRecord(BelowxRec: Boolean): Boolean
+    var
+        DelegateRegistry: Codeunit "Delegate Registry";
+        Parameters: Dictionary of [Text, Variant];
+        ValidationResult: Boolean;
+    begin
+        // Use delegate for customer validation
+        Parameters.Set('CustomerNo', Rec."Sell-to Customer No.");
+        ValidationResult := DelegateRegistry.ExecuteDelegate('CUSTOMER_VALIDATION', Parameters);
+
+        if not ValidationResult then
+            Error('Customer validation failed through delegate operation');
+
+        exit(true);
+    end;
+}
+```
+
+## Advanced Delegate Chain
+
+```al
+// Chain multiple delegates for complex operations
+codeunit 50102 "Multi-Step Delegate Chain"
+{
+    var
+        DelegateRegistry: Codeunit "Delegate Registry";
+
+    procedure ExecuteChain(ChainName: Text[50]; var Parameters: Dictionary of [Text, Variant]): Boolean
+    var
+        ChainSteps: List of [Text];
+        StepName: Text;
+        StepResult: Boolean;
+    begin
+        ChainSteps := GetChainSteps(ChainName);
+
+        foreach StepName in ChainSteps do begin
+            StepResult := DelegateRegistry.ExecuteDelegate(StepName, Parameters);
+            if not StepResult then begin
+                Parameters.Set('FailedStep', StepName);
+                exit(false);
+            end;
+        end;
+
+        exit(true);
+    end;
+
+    local procedure GetChainSteps(ChainName: Text[50]): List of [Text]
+    var
+        Steps: List of [Text];
+    begin
+        case ChainName of
+            'SALES_VALIDATION':
+                begin
+                    Steps.Add('CUSTOMER_VALIDATION');
+                    Steps.Add('INVENTORY_CHECK');
+                    Steps.Add('CREDIT_APPROVAL');
+                end;
+            'PURCHASE_VALIDATION':
+                begin
+                    Steps.Add('VENDOR_VALIDATION');
+                    Steps.Add('BUDGET_CHECK');
+                    Steps.Add('APPROVAL_WORKFLOW');
+                end;
+        end;
+
+        exit(Steps);
+    end;
+}
+```
+
+## Error Handling Delegate
+
+```al
+// Delegate with comprehensive error handling
+codeunit 50103 "Error Handling Delegate" implements IDelegateOperation
+{
+    procedure Execute(var Parameters: Dictionary of [Text, Variant]): Boolean
+    var
+        ErrorMessages: List of [Text];
+        HasErrors: Boolean;
+    begin
+        HasErrors := false;
+        Clear(ErrorMessages);
+
+        // Perform validation with error collection
+        if not ValidateRequiredParameters(Parameters, ErrorMessages) then
+            HasErrors := true;
+
+        if not ValidateBusinessRules(Parameters, ErrorMessages) then
+            HasErrors := true;
+
+        // Set error information in parameters
+        Parameters.Set('HasErrors', HasErrors);
+        Parameters.Set('ErrorMessages', ErrorMessages);
+
+        exit(not HasErrors);
+    end;
+
+    procedure GetName(): Text[50]
+    begin
+        exit('ERROR_HANDLING');
+    end;
+
+    procedure GetDescription(): Text[250]
+    begin
+        exit('Comprehensive error handling and validation delegate');
+    end;
+
+    local procedure ValidateRequiredParameters(Parameters: Dictionary of [Text, Variant]; var ErrorMessages: List of [Text]): Boolean
+    var
+        IsValid: Boolean;
+    begin
+        IsValid := true;
+
+        if not Parameters.ContainsKey('CustomerNo') then begin
+            ErrorMessages.Add('Missing required parameter: CustomerNo');
+            IsValid := false;
+        end;
+
+        if not Parameters.ContainsKey('Amount') then begin
+            ErrorMessages.Add('Missing required parameter: Amount');
+            IsValid := false;
+        end;
+
+        exit(IsValid);
+    end;
+
+    local procedure ValidateBusinessRules(Parameters: Dictionary of [Text, Variant]; var ErrorMessages: List of [Text]): Boolean
+    var
+        Amount: Decimal;
+        IsValid: Boolean;
+    begin
+        IsValid := true;
+
+        if Parameters.Get('Amount', Amount) then begin
+            if Amount <= 0 then begin
+                ErrorMessages.Add('Amount must be greater than zero');
+                IsValid := false;
+            end;
+        end;
+
+        exit(IsValid);
+    end;
+}
+```
+
+This implementation shows how delegate operations enable flexible, extensible APIs in Business Central while maintaining clean separation of concerns and supporting runtime configuration of business logic.

package/embedded-knowledge/domains/alex-architect/samples/api-fieldset-registration.md

@@ -0,0 +1,200 @@
+# API Fieldset Registration Sample
+
+## Overview
+This sample demonstrates how to implement fieldset registration patterns for dynamic API field management and metadata-driven field selection.
+
+## Basic Fieldset Registration
+
+```al
+codeunit 50100 "API Fieldset Registration"
+{
+    procedure RegisterCustomerFieldset()
+    var
+        FieldsetRegistry: Codeunit "Fieldset Registry";
+        CustomerFieldset: Record "API Fieldset";
+    begin
+        // Register basic customer fieldset
+        CustomerFieldset.Init();
+        CustomerFieldset."Table ID" := Database::Customer;
+        CustomerFieldset."Fieldset Name" := 'BASIC';
+        CustomerFieldset."Field No." := Customer.FieldNo("No.");
+        CustomerFieldset.Insert();
+
+        CustomerFieldset."Field No." := Customer.FieldNo(Name);
+        CustomerFieldset.Insert();
+
+        CustomerFieldset."Field No." := Customer.FieldNo("Phone No.");
+        CustomerFieldset.Insert();
+
+        // Register extended customer fieldset
+        CustomerFieldset."Fieldset Name" := 'EXTENDED';
+        CustomerFieldset."Field No." := Customer.FieldNo("Credit Limit (LCY)");
+        CustomerFieldset.Insert();
+
+        CustomerFieldset."Field No." := Customer.FieldNo("Balance (LCY)");
+        CustomerFieldset.Insert();
+    end;
+}
+```
+
+## Dynamic Field Selection
+
+```al
+codeunit 50101 "Dynamic Field Selection"
+{
+    procedure GetCustomerFields(FieldsetName: Text): List of [Integer]
+    var
+        APIFieldset: Record "API Fieldset";
+        FieldList: List of [Integer];
+    begin
+        APIFieldset.SetRange("Table ID", Database::Customer);
+        APIFieldset.SetRange("Fieldset Name", FieldsetName);
+        if APIFieldset.FindSet() then
+            repeat
+                FieldList.Add(APIFieldset."Field No.");
+            until APIFieldset.Next() = 0;
+
+        exit(FieldList);
+    end;
+
+    procedure ApplyFieldset(var CustomerRec: Record Customer; FieldsetName: Text)
+    var
+        FieldList: List of [Integer];
+        FieldNo: Integer;
+    begin
+        FieldList := GetCustomerFields(FieldsetName);
+        CustomerRec.SetLoadFields();
+
+        foreach FieldNo in FieldList do
+            CustomerRec.AddLoadFields(FieldNo);
+    end;
+}
+```
+
+## Conditional Registration
+
+```al
+codeunit 50102 "Conditional Fieldset Reg"
+{
+    procedure RegisterConditionalFieldset(TableID: Integer; Condition: Text)
+    var
+        ConditionalFieldset: Record "Conditional API Fieldset";
+    begin
+        ConditionalFieldset.Init();
+        ConditionalFieldset."Table ID" := TableID;
+        ConditionalFieldset.Condition := Condition;
+        ConditionalFieldset."Field Selection" := GetFieldsForCondition(TableID, Condition);
+        ConditionalFieldset.Insert();
+    end;
+
+    local procedure GetFieldsForCondition(TableID: Integer; Condition: Text): Text
+    var
+        FieldSelection: Text;
+    begin
+        case Condition of
+            'MINIMAL':
+                FieldSelection := 'No.,Name';
+            'STANDARD':
+                FieldSelection := 'No.,Name,Phone No.,E-Mail';
+            'COMPLETE':
+                FieldSelection := '*';
+        end;
+
+        exit(FieldSelection);
+    end;
+}
+```
+
+## API Integration
+
+```al
+page 50100 "Customer API with Fieldsets"
+{
+    APIPublisher = 'contoso';
+    APIGroup = 'sample';
+    APIVersion = 'v1.0';
+    EntityName = 'customer';
+    EntitySetName = 'customers';
+    SourceTable = Customer;
+
+    trigger OnOpenPage()
+    var
+        FieldsetManager: Codeunit "Dynamic Field Selection";
+        RequestedFieldset: Text;
+    begin
+        // Get fieldset from query parameter
+        RequestedFieldset := GetFieldsetFromRequest();
+        if RequestedFieldset <> '' then
+            FieldsetManager.ApplyFieldset(Rec, RequestedFieldset);
+    end;
+
+    local procedure GetFieldsetFromRequest(): Text
+    var
+        RequestHeaders: HttpHeaders;
+        FieldsetHeader: Text;
+    begin
+        // Extract fieldset preference from request
+        if RequestHeaders.Contains('X-Fieldset') then begin
+            RequestHeaders.GetValues('X-Fieldset', FieldsetHeader);
+            exit(FieldsetHeader);
+        end;
+
+        exit('STANDARD');
+    end;
+}
+```
+
+## Metadata-Driven Configuration
+
+```al
+table 50100 "API Fieldset"
+{
+    fields
+    {
+        field(1; "Table ID"; Integer) { }
+        field(2; "Fieldset Name"; Code[20]) { }
+        field(3; "Field No."; Integer) { }
+        field(4; "Field Name"; Text[100]) { }
+        field(5; Required; Boolean) { }
+        field(6; "Display Order"; Integer) { }
+    }
+
+    keys
+    {
+        key(PK; "Table ID", "Fieldset Name", "Field No.") { Clustered = true; }
+    }
+}
+```
+
+## Performance Considerations
+
+```al
+codeunit 50103 "Fieldset Performance Mgmt"
+{
+    var
+        FieldsetCache: Dictionary of [Text, List of [Integer]];
+
+    procedure GetCachedFieldset(TableID: Integer; FieldsetName: Text): List of [Integer]
+    var
+        CacheKey: Text;
+        FieldList: List of [Integer];
+    begin
+        CacheKey := StrSubstNo('%1_%2', TableID, FieldsetName);
+
+        if FieldsetCache.ContainsKey(CacheKey) then
+            exit(FieldsetCache.Get(CacheKey));
+
+        FieldList := LoadFieldsetFromDatabase(TableID, FieldsetName);
+        FieldsetCache.Set(CacheKey, FieldList);
+
+        exit(FieldList);
+    end;
+
+    procedure ClearCache()
+    begin
+        Clear(FieldsetCache);
+    end;
+}
+```
+
+This sample demonstrates comprehensive fieldset registration patterns including basic registration, dynamic selection, conditional logic, API integration, and performance optimization through caching.