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

package/embedded-knowledge/domains/alex-architect/samples/systemid-integration.md

@@ -0,0 +1,433 @@
+# SystemId Integration in API Pages - AL Code Sample
+
+## Basic SystemId Usage as Primary Key
+
+```al
+page 50200 "Customer SystemId API"
+{
+    PageType = API;
+    APIPublisher = 'contoso';
+    APIGroup = 'customers';
+    APIVersion = 'v1.0';
+    EntityName = 'customer';
+    EntitySetName = 'customers';
+    SourceTable = Customer;
+    DelayedInsert = true;
+    ODataKeyFields = SystemId;  // Use SystemId as primary OData key
+    
+    layout
+    {
+        area(Content)
+        {
+            repeater(GroupName)
+            {
+                // SystemId exposed as 'id' for REST conventions
+                field(id; Rec.SystemId)
+                {
+                    Caption = 'Id';
+                    Editable = false;  // SystemId is system-generated
+                }
+                field(number; Rec."No.")
+                {
+                    Caption = 'Number';
+                    // Business key still available for reference
+                }
+                field(displayName; Rec.Name)
+                {
+                    Caption = 'Display Name';
+                }
+                field(lastModifiedDateTime; Rec.SystemModifiedAt)
+                {
+                    Caption = 'Last Modified Date Time';
+                    Editable = false;
+                }
+            }
+        }
+    }
+    
+    // SystemId automatically handled by BC platform
+    // No custom triggers needed for SystemId generation
+}
+```
+
+## SystemId with Related Records Navigation
+
+```al
+page 50201 "Sales Order SystemId API"
+{
+    PageType = API;
+    APIPublisher = 'contoso';
+    APIGroup = 'sales';
+    APIVersion = 'v1.0';
+    EntityName = 'salesOrder';
+    EntitySetName = 'salesOrders';
+    SourceTable = "Sales Header";
+    DelayedInsert = true;
+    ODataKeyFields = SystemId;
+    
+    layout
+    {
+        area(Content)
+        {
+            repeater(GroupName)
+            {
+                field(id; Rec.SystemId)
+                {
+                    Caption = 'Id';
+                    Editable = false;
+                }
+                field(number; Rec."No.")
+                {
+                    Caption = 'Number';
+                }
+                field(customerId; CustomerSystemId)
+                {
+                    Caption = 'Customer Id';
+                    // Link to customer using SystemId instead of business key
+                }
+                field(customerNumber; Rec."Sell-to Customer No.")
+                {
+                    Caption = 'Customer Number';
+                    // Keep business key for backward compatibility
+                }
+                field(orderDate; Rec."Order Date")
+                {
+                    Caption = 'Order Date';
+                }
+                field(totalAmount; TotalAmount)
+                {
+                    Caption = 'Total Amount';
+                }
+            }
+        }
+    }
+    
+    var
+        CustomerSystemId: Guid;
+        TotalAmount: Decimal;
+    
+    trigger OnAfterGetRecord()
+    var
+        Customer: Record Customer;
+    begin
+        // Resolve customer SystemId from business key
+        if Customer.Get(Rec."Sell-to Customer No.") then
+            CustomerSystemId := Customer.SystemId
+        else
+            Clear(CustomerSystemId);
+            
+        // Calculate total amount
+        Rec.CalcFields("Amount Including VAT");
+        TotalAmount := Rec."Amount Including VAT";
+    end;
+    
+    trigger OnModifyRecord(): Boolean
+    var
+        Customer: Record Customer;
+    begin
+        // Handle customer assignment via SystemId
+        if not IsNullGuid(CustomerSystemId) then begin
+            Customer.SetRange(SystemId, CustomerSystemId);
+            if Customer.FindFirst() then
+                Rec.Validate("Sell-to Customer No.", Customer."No.");
+        end;
+        exit(true);
+    end;
+}
+```
+
+## SystemId Cross-Reference Implementation
+
+```al
+// Helper codeunit for SystemId operations
+codeunit 50200 "SystemId Helper"
+{
+    // Find record by SystemId across different tables
+    procedure FindRecordBySystemId(TableID: Integer; SystemIdValue: Guid; var RecRef: RecordRef): Boolean
+    var
+        SystemIdFieldRef: FieldRef;
+    begin
+        RecRef.Open(TableID);
+        SystemIdFieldRef := RecRef.Field(RecRef.SystemIdNo);
+        SystemIdFieldRef.SetRange(SystemIdValue);
+        exit(RecRef.FindFirst());
+    end;
+    
+    // Get SystemId from business key
+    procedure GetSystemIdFromBusinessKey(TableID: Integer; KeyFieldNo: Integer; KeyValue: Variant): Guid
+    var
+        RecRef: RecordRef;
+        KeyFieldRef: FieldRef;
+        SystemIdFieldRef: FieldRef;
+    begin
+        RecRef.Open(TableID);
+        KeyFieldRef := RecRef.Field(KeyFieldNo);
+        KeyFieldRef.SetRange(KeyValue);
+        if RecRef.FindFirst() then begin
+            SystemIdFieldRef := RecRef.Field(RecRef.SystemIdNo);
+            exit(SystemIdFieldRef.Value);
+        end;
+        exit(CreateGuid());  // Return empty GUID if not found
+    end;
+    
+    // Validate SystemId exists in target table
+    procedure ValidateSystemIdExists(TableID: Integer; SystemIdValue: Guid): Boolean
+    var
+        RecRef: RecordRef;
+    begin
+        exit(FindRecordBySystemId(TableID, SystemIdValue, RecRef));
+    end;
+}
+
+// API page demonstrating SystemId cross-references
+page 50202 "Purchase Order Line API"
+{
+    PageType = API;
+    APIPublisher = 'contoso';
+    APIGroup = 'purchasing';
+    APIVersion = 'v1.0';
+    EntityName = 'purchaseOrderLine';
+    EntitySetName = 'purchaseOrderLines';
+    SourceTable = "Purchase Line";
+    DelayedInsert = true;
+    ODataKeyFields = SystemId;
+    
+    layout
+    {
+        area(Content)
+        {
+            repeater(GroupName)
+            {
+                field(id; Rec.SystemId)
+                {
+                    Caption = 'Id';
+                    Editable = false;
+                }
+                field(documentId; DocumentSystemId)
+                {
+                    Caption = 'Document Id';
+                    // Reference to purchase header via SystemId
+                }
+                field(itemId; ItemSystemId)
+                {
+                    Caption = 'Item Id';
+                    // Reference to item via SystemId
+                }
+                field(lineNumber; Rec."Line No.")
+                {
+                    Caption = 'Line Number';
+                }
+                field(quantity; Rec.Quantity)
+                {
+                    Caption = 'Quantity';
+                }
+                field(unitCost; Rec."Unit Cost")
+                {
+                    Caption = 'Unit Cost';
+                }
+            }
+        }
+    }
+    
+    var
+        DocumentSystemId: Guid;
+        ItemSystemId: Guid;
+        SystemIdHelper: Codeunit "SystemId Helper";
+    
+    trigger OnAfterGetRecord()
+    var
+        PurchaseHeader: Record "Purchase Header";
+        Item: Record Item;
+    begin
+        // Get document SystemId
+        if PurchaseHeader.Get(Rec."Document Type", Rec."Document No.") then
+            DocumentSystemId := PurchaseHeader.SystemId;
+            
+        // Get item SystemId
+        if Item.Get(Rec."No.") then
+            ItemSystemId := Item.SystemId;
+    end;
+    
+    trigger OnModifyRecord(): Boolean
+    var
+        PurchaseHeader: Record "Purchase Header";
+        Item: Record Item;
+    begin
+        // Validate and set document reference
+        if not IsNullGuid(DocumentSystemId) then begin
+            PurchaseHeader.SetRange(SystemId, DocumentSystemId);
+            if PurchaseHeader.FindFirst() then begin
+                Rec.Validate("Document Type", PurchaseHeader."Document Type");
+                Rec.Validate("Document No.", PurchaseHeader."No.");
+            end else
+                Error('Purchase document with SystemId %1 not found', DocumentSystemId);
+        end;
+        
+        // Validate and set item reference
+        if not IsNullGuid(ItemSystemId) then begin
+            Item.SetRange(SystemId, ItemSystemId);
+            if Item.FindFirst() then
+                Rec.Validate("No.", Item."No.")
+            else
+                Error('Item with SystemId %1 not found', ItemSystemId);
+        end;
+        
+        exit(true);
+    end;
+}
+```
+
+## SystemId URL Navigation Patterns
+
+```al
+// API page with SystemId-based navigation URLs
+page 50203 "Enhanced Customer API"
+{
+    PageType = API;
+    APIPublisher = 'contoso';
+    APIGroup = 'customers';
+    APIVersion = 'v1.0';
+    EntityName = 'customer';
+    EntitySetName = 'customers';
+    SourceTable = Customer;
+    DelayedInsert = true;
+    ODataKeyFields = SystemId;
+    
+    layout
+    {
+        area(Content)
+        {
+            repeater(GroupName)
+            {
+                field(id; Rec.SystemId)
+                {
+                    Caption = 'Id';
+                    Editable = false;
+                }
+                field(number; Rec."No.")
+                {
+                    Caption = 'Number';
+                }
+                field(displayName; Rec.Name)
+                {
+                    Caption = 'Display Name';
+                }
+                field(salesOrdersUrl; SalesOrdersNavigationUrl)
+                {
+                    Caption = 'Sales Orders URL';
+                    Editable = false;
+                    // Navigation URL using SystemId
+                }
+                field(paymentsUrl; PaymentsNavigationUrl)
+                {
+                    Caption = 'Payments URL';
+                    Editable = false;
+                }
+            }
+        }
+    }
+    
+    var
+        SalesOrdersNavigationUrl: Text;
+        PaymentsNavigationUrl: Text;
+    
+    trigger OnAfterGetRecord()
+    begin
+        // Build navigation URLs using SystemId
+        SalesOrdersNavigationUrl := BuildNavigationUrl('salesOrders', Rec.SystemId);
+        PaymentsNavigationUrl := BuildNavigationUrl('customerPayments', Rec.SystemId);
+    end;
+    
+    local procedure BuildNavigationUrl(EntitySet: Text; RelatedSystemId: Guid): Text
+    var
+        BaseUrl: Text;
+        CompanyName: Text;
+    begin
+        // Get base API URL from current request context
+        BaseUrl := GetUrl(ClientType::ODataV4, CompanyName(), ObjectType::Page, 0);
+        
+        // Build related entity URL with SystemId filter
+        exit(StrSubstNo('%1/%2?$filter=customerId eq %3', 
+                       BaseUrl, EntitySet, RelatedSystemId));
+    end;
+}
+
+// Related sales orders API filtered by customer SystemId
+page 50204 "Customer Sales Orders API"
+{
+    PageType = API;
+    APIPublisher = 'contoso';
+    APIGroup = 'sales';
+    APIVersion = 'v1.0';
+    EntityName = 'customerSalesOrder';
+    EntitySetName = 'customerSalesOrders';
+    SourceTable = "Sales Header";
+    DelayedInsert = true;
+    ODataKeyFields = SystemId;
+    SourceTableView = WHERE("Document Type" = CONST(Order));
+    
+    layout
+    {
+        area(Content)
+        {
+            repeater(GroupName)
+            {
+                field(id; Rec.SystemId)
+                {
+                    Caption = 'Id';
+                    Editable = false;
+                }
+                field(customerId; CustomerSystemId)
+                {
+                    Caption = 'Customer Id';
+                    Editable = false;
+                }
+                field(orderNumber; Rec."No.")
+                {
+                    Caption = 'Order Number';
+                }
+                field(orderDate; Rec."Order Date")
+                {
+                    Caption = 'Order Date';
+                }
+            }
+        }
+    }
+    
+    var
+        CustomerSystemId: Guid;
+    
+    trigger OnAfterGetRecord()
+    var
+        Customer: Record Customer;
+    begin
+        // Resolve customer SystemId
+        if Customer.Get(Rec."Sell-to Customer No.") then
+            CustomerSystemId := Customer.SystemId;
+    end;
+}
+```
+
+## Implementation Notes
+
+**SystemId Integration Best Practices:**
+
+1. **Primary Key Strategy:**
+   - Always use SystemId as ODataKeyFields for API pages
+   - Expose SystemId as 'id' field following REST conventions
+   - Keep business keys available for backward compatibility
+
+2. **Cross-Reference Management:**
+   - Use SystemId for all entity relationships in APIs
+   - Implement validation for SystemId references before updates
+   - Provide helper functions for SystemId to business key conversion
+
+3. **Navigation Patterns:**
+   - Build related entity URLs using SystemId parameters
+   - Implement consistent URL structures across API endpoints
+   - Use SystemId filtering for efficient related data queries
+
+4. **Performance Considerations:**
+   - SystemId fields are automatically indexed by BC platform
+   - Use SystemId for faster record lookups in large tables
+   - Cache SystemId mappings for frequently accessed relationships

package/embedded-knowledge/domains/alex-architect/samples/testability-design-patterns.md

@@ -0,0 +1,223 @@
+# Testability Design Pattern Samples
+
+## Complete Interface Abstraction Example
+
+### The Interfaces
+```al
+interface ICurrencyConverter
+{
+    procedure Convert(AtDate: Date; FromCurrency: Code[10]; ToCurrency: Code[10]; Amount: Decimal): Decimal;
+}
+
+interface IPermissionChecker
+{
+    procedure CanConvert(FromCurrency: Code[10]; ToCurrency: Code[10]; UserID: Text[50]): Boolean;
+}
+
+interface ILogger
+{
+    procedure Log(FromCurrency: Code[10]; ToCurrency: Code[10]; FromAmount: Decimal; ToAmount: Decimal; UserID: Text[50]);
+}
+```
+
+### Production Implementations
+```al
+codeunit 50100 "BC Currency Converter" implements ICurrencyConverter
+{
+    procedure Convert(AtDate: Date; FromCurrency: Code[10]; ToCurrency: Code[10]; Amount: Decimal): Decimal
+    var
+        ExchRate: Record "Currency Exchange Rate";
+    begin
+        exit(ExchRate.ExchangeAmtFCYToFCY(AtDate, FromCurrency, ToCurrency, Amount));
+    end;
+}
+
+codeunit 50101 "Database Permission Checker" implements IPermissionChecker
+{
+    procedure CanConvert(FromCurrency: Code[10]; ToCurrency: Code[10]; UserID: Text[50]): Boolean
+    var
+        Permission: Record "Currency Exchange Permission";
+    begin
+        Permission.SetRange("User ID", UserID);
+        Permission.SetFilter("From Currency Code", '%1|%2', '', FromCurrency);
+        Permission.SetFilter("To Currency Code", '%1|%2', '', ToCurrency);
+        exit(not Permission.IsEmpty());
+    end;
+}
+
+codeunit 50102 "Database Logger" implements ILogger
+{
+    procedure Log(FromCurrency: Code[10]; ToCurrency: Code[10]; FromAmount: Decimal; ToAmount: Decimal; UserID: Text[50])
+    var
+        ExchangeLog: Record "Currency Exchange Log";
+    begin
+        ExchangeLog."Date and Time" := CurrentDateTime();
+        ExchangeLog."User ID" := CopyStr(UserID, 1, MaxStrLen(ExchangeLog."User ID"));
+        ExchangeLog."From Currency Code" := FromCurrency;
+        ExchangeLog."To Currency Code" := ToCurrency;
+        ExchangeLog."From Amount" := FromAmount;
+        ExchangeLog."To Amount" := ToAmount;
+        ExchangeLog.Insert(true);
+    end;
+}
+```
+
+### The Business Logic (Decoupled)
+```al
+codeunit 50110 "Currency Conversion"
+{
+    // Main entry point - backward compatible, no breaking changes
+    procedure Convert(FromAmount: Decimal; FromCurrency: Code[10]; ToCurrency: Code[10]): Decimal
+    var
+        BCConverter: Codeunit "BC Currency Converter";
+        DBPermission: Codeunit "Database Permission Checker";
+        DBLogger: Codeunit "Database Logger";
+    begin
+        exit(Convert(FromAmount, FromCurrency, ToCurrency, DBPermission, BCConverter, DBLogger));
+    end;
+
+    // Testable version with dependency injection
+    procedure Convert(
+        FromAmount: Decimal; 
+        FromCurrency: Code[10]; 
+        ToCurrency: Code[10];
+        PermissionChecker: Interface IPermissionChecker;
+        CurrencyConverter: Interface ICurrencyConverter;
+        Logger: Interface ILogger
+    ): Decimal
+    var
+        Result: Decimal;
+    begin
+        if not PermissionChecker.CanConvert(FromCurrency, ToCurrency, UserId()) then
+            Error('Currency exchange not allowed for %1 from %2 to %3.', UserId(), FromCurrency, ToCurrency);
+
+        Result := CurrencyConverter.Convert(WorkDate(), FromCurrency, ToCurrency, FromAmount);
+        Logger.Log(FromCurrency, ToCurrency, FromAmount, Result, UserId());
+        exit(Result);
+    end;
+}
+```
+
+---
+
+## Before and After: Tightly Coupled vs Decoupled
+
+### ❌ Before: Tightly Coupled
+```al
+procedure Convert(FromAmount: Decimal; FromCurrency: Code[10]; ToCurrency: Code[10]): Decimal
+var
+    Permission: Record "Currency Exchange Permission";
+    ExchRate: Record "Currency Exchange Rate";
+    ExchangeLog: Record "Currency Exchange Log";
+    Result: Decimal;
+begin
+    // Permission check - tightly coupled to table
+    Permission.SetRange("User ID", UserId());
+    Permission.SetFilter("From Currency Code", '%1|%2', '', FromCurrency);
+    Permission.SetFilter("To Currency Code", '%1|%2', '', ToCurrency);
+    if not Permission.FindFirst() then
+        Error('Not allowed');
+
+    // Conversion - tightly coupled to BC base app
+    Result := ExchRate.ExchangeAmtFCYToFCY(WorkDate(), FromCurrency, ToCurrency, FromAmount);
+
+    // Logging - tightly coupled to table
+    ExchangeLog."Date and Time" := CurrentDateTime();
+    ExchangeLog."User ID" := UserId();
+    ExchangeLog."From Currency Code" := FromCurrency;
+    ExchangeLog."To Currency Code" := ToCurrency;
+    ExchangeLog."From Amount" := FromAmount;
+    ExchangeLog."To Amount" := Result;
+    ExchangeLog.Insert();
+
+    exit(Result);
+end;
+```
+
+**Problems**:
+- Testing requires Currency, Exchange Rate, Permission, and Log tables
+- Can't test permission logic without the table
+- Can't test conversion without BC exchange rates
+- Can't verify logging without reading from table
+
+### ✅ After: Decoupled with Interfaces
+```al
+procedure Convert(
+    FromAmount: Decimal; 
+    FromCurrency: Code[10]; 
+    ToCurrency: Code[10];
+    PermissionChecker: Interface IPermissionChecker;
+    CurrencyConverter: Interface ICurrencyConverter;
+    Logger: Interface ILogger
+): Decimal
+var
+    Result: Decimal;
+begin
+    if not PermissionChecker.CanConvert(FromCurrency, ToCurrency, UserId()) then
+        Error('Currency exchange not allowed for %1 from %2 to %3.', UserId(), FromCurrency, ToCurrency);
+
+    Result := CurrencyConverter.Convert(WorkDate(), FromCurrency, ToCurrency, FromAmount);
+    Logger.Log(FromCurrency, ToCurrency, FromAmount, Result, UserId());
+    exit(Result);
+end;
+```
+
+**Benefits**:
+- Test business logic with mocks - no database needed
+- Each dependency tested separately
+- Fast, reliable, focused tests
+
+---
+
+## Alternative Implementations Example
+
+The power of interfaces: easy to swap implementations.
+
+```al
+// Production: Use BC tables
+codeunit 50100 "BC Currency Converter" implements ICurrencyConverter
+{
+    procedure Convert(AtDate: Date; FromCurrency: Code[10]; ToCurrency: Code[10]; Amount: Decimal): Decimal
+    var
+        ExchRate: Record "Currency Exchange Rate";
+    begin
+        exit(ExchRate.ExchangeAmtFCYToFCY(AtDate, FromCurrency, ToCurrency, Amount));
+    end;
+}
+
+// Alternative: External bank API
+codeunit 50103 "Bank API Converter" implements ICurrencyConverter
+{
+    procedure Convert(AtDate: Date; FromCurrency: Code[10]; ToCurrency: Code[10]; Amount: Decimal): Decimal
+    var
+        Client: HttpClient;
+        Response: HttpResponseMessage;
+        Rate: Decimal;
+    begin
+        // Call external API for rate
+        Client.Get(BuildAPIUrl(FromCurrency, ToCurrency), Response);
+        Rate := ParseRateFromResponse(Response);
+        exit(Amount * Rate);
+    end;
+}
+
+// Alternative: Telemetry logging
+codeunit 50104 "Telemetry Logger" implements ILogger
+{
+    procedure Log(FromCurrency: Code[10]; ToCurrency: Code[10]; FromAmount: Decimal; ToAmount: Decimal; UserID: Text[50])
+    var
+        Dimensions: Dictionary of [Text, Text];
+    begin
+        Dimensions.Add('FromCurrency', FromCurrency);
+        Dimensions.Add('ToCurrency', ToCurrency);
+        Dimensions.Add('FromAmount', Format(FromAmount));
+        Dimensions.Add('ToAmount', Format(ToAmount));
+        Dimensions.Add('UserID', UserID);
+        
+        Session.LogMessage('EXCHANGE-001', 'Currency exchanged', Verbosity::Normal,
+            DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher, Dimensions);
+    end;
+}
+```
+
+**Key Point**: Business logic doesn't change when you switch implementations. Tests don't change either.