bc-code-intelligence-mcp 1.1.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/subscriber-codeunit-size-optimization.md

@@ -0,0 +1,66 @@
+---
+title: "Subscriber Codeunit Size and Organization"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["codeunit-design", "organization", "maintainability", "performance"]
+prerequisites: ["codeunit-basics", "event-subscriber-patterns"]
+samples: "samples/subscriber-organization.md"
+---
+# Subscriber Codeunit Size and Organization
+
+## Overview
+
+Subscriber codeunit size and organization significantly impact maintainability, performance, and development workflow. Proper subscriber architecture balances functional cohesion with practical constraints around codeunit compilation, deployment, and runtime performance.
+
+Large monolithic subscriber codeunits create maintenance challenges and compilation overhead, while excessive fragmentation leads to deployment complexity and runtime inefficiencies. Optimal subscriber organization requires understanding both technical constraints and business domain boundaries.
+
+The architectural decisions around subscriber codeunit size affect development team productivity, system performance, and long-term maintainability. Strategic organization patterns prevent common pitfalls while enabling scalable event-driven architectures.
+
+## Size Impact on Development
+
+Large subscriber codeunits slow development cycles through increased compilation time and complex merge conflict resolution. When multiple developers work on the same subscriber codeunit, coordination overhead increases significantly.
+
+Oversized codeunits make specific subscriber logic harder to locate and modify, reducing development velocity. Navigation through hundreds of procedures to find specific event handling logic creates unnecessary friction.
+
+Version control systems struggle with large files, making code review processes more difficult and increasing the likelihood of merge conflicts during parallel development efforts.
+
+## Functional Cohesion Principles
+
+Subscriber codeunits should group related event handling logic based on business domain or functional area rather than purely technical organization. Domain-driven organization improves maintainability and understanding.
+
+Event subscribers addressing the same business process or data entity naturally belong together, enabling shared utility functions and consistent business rule implementation across related events.
+
+Cross-cutting concerns like logging, audit trails, or security enforcement may warrant separate subscriber codeunits despite spanning multiple business domains, maintaining clean separation of concerns.
+
+## Performance Considerations
+
+Codeunit initialization overhead affects performance when subscribers are distributed across many small codeunits. Each codeunit requires separate loading and initialization, creating cumulative startup costs.
+
+Memory usage patterns differ between large consolidated codeunits and distributed smaller ones. SingleInstance subscribers particularly benefit from consolidation to minimize per-instance memory overhead.
+
+Runtime performance characteristics vary based on subscriber organization, with consolidated codeunits providing better CPU cache locality while distributed codeunits enable more granular memory management.
+
+## Deployment and Versioning
+
+Subscriber codeunit organization affects deployment granularity and rollback capabilities. Smaller codeunits enable more precise deployment control but increase deployment complexity and coordination requirements.
+
+Version management becomes more complex with highly distributed subscriber architectures, requiring careful dependency tracking and coordinated updates across multiple related codeunits.
+
+Extension development scenarios benefit from smaller, focused subscriber codeunits that minimize conflicts with base application changes and other extensions.
+
+## Maintenance Strategies
+
+Subscriber codeunits require regular refactoring to maintain optimal size as functionality grows. Established size thresholds and refactoring triggers prevent architectural degradation over time.
+
+Documentation and naming conventions become increasingly important as subscriber codeunit count grows. Clear organization patterns enable developers to quickly locate relevant event handling logic.
+
+Code analysis tools and metrics help monitor subscriber codeunit size and complexity trends, providing objective data for refactoring decisions and architectural improvements.
+
+## Organization Patterns
+
+Domain-based organization groups subscribers by business functionality, creating natural boundaries for related event handling logic and shared business rules implementation.
+
+Layer-based organization separates subscribers by architectural concerns such as data validation, business logic, and integration logic, providing clear separation of responsibilities.
+
+Hybrid organization combines domain and layer approaches, grouping related business functionality while maintaining separation between different types of event processing logic.

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

@@ -0,0 +1,115 @@
+---
+title: "SystemId Integration in API Pages"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["systemid", "data-modeling", "entity-relationships"]
+samples: "samples/systemid-integration.md"
+---
+# SystemId Integration in API Pages
+
+## Overview
+
+SystemId provides a universal unique identifier for records in Business Central tables, offering significant advantages for API Page implementations. Understanding SystemId integration patterns enables robust API designs that support efficient data synchronization and external system integration.
+
+SystemId is a GUID field automatically maintained by the BC platform for most tables. This field provides stable, unique identification that remains consistent across system operations, making it ideal for external system references and API operations.
+
+Proper SystemId integration supports advanced API scenarios including optimistic concurrency control, efficient data synchronization, and reliable external system integration patterns.
+
+## SystemId Characteristics
+
+SystemId values are automatically generated and maintained by the BC platform, ensuring uniqueness across all records in the database. These values remain stable throughout the record lifecycle unless explicitly regenerated.
+
+The SystemId field is of type GUID, providing 128-bit unique identifiers that are virtually guaranteed to be unique across systems and time. This makes SystemId ideal for distributed system integration scenarios.
+
+SystemId values are immutable under normal circumstances, providing reliable external references that don't change due to business data modifications or system operations.
+
+## API Page Integration Patterns
+
+Use SystemId as the primary key or unique identifier for API Page implementations when stable external references are required. This provides consistent identification for API consumers regardless of business key changes.
+
+SystemId enables efficient OData query operations through unique record identification. API consumers can reliably reference specific records using SystemId values without depending on complex business key combinations.
+
+Consider exposing SystemId alongside business keys to provide flexible identification options for different API consumer scenarios and integration requirements.
+
+## External System Integration
+
+SystemId provides excellent external system reference capabilities, allowing external systems to maintain stable references to BC records without depending on business data that might change.
+
+External systems can store SystemId values as foreign keys or reference identifiers, enabling reliable record lookups and data synchronization operations across system boundaries.
+
+SystemId-based integration patterns support incremental synchronization scenarios where external systems need to track changes to specific BC records over time.
+
+## Data Synchronization Benefits
+
+SystemId enables efficient change tracking and synchronization operations by providing stable record identification that persists across data modifications and system operations.
+
+Synchronization processes can use SystemId values to identify specific records for update operations, avoiding complex business key matching logic that may be unreliable or inefficient.
+
+Consider implementing timestamp fields alongside SystemId for efficient change detection and synchronization optimization in high-volume scenarios.
+
+## Relationship Modeling
+
+SystemId can be used in related table structures to create stable relationships that don't depend on business key values. This provides more robust relationship models for complex data structures.
+
+Foreign key relationships using SystemId values remain valid even when business keys change, reducing the complexity of maintaining referential integrity across related tables.
+
+Consider the performance implications of SystemId-based relationships, as GUID comparisons may have different performance characteristics compared to integer-based keys.
+
+## Query Performance Considerations
+
+SystemId is typically indexed by the BC platform, providing efficient query performance for unique record lookups and equality comparisons in API operations.
+
+GUID-based queries may have different performance characteristics compared to integer or string-based queries. Consider these differences when designing high-performance API implementations.
+
+Range queries or sorting operations on SystemId fields may be less efficient than similar operations on business keys with more meaningful sort orders.
+
+## OData Integration Patterns
+
+SystemId integrates seamlessly with OData operations, providing reliable record identification for GET, PATCH, PUT, and DELETE operations through API Pages.
+
+Use SystemId in OData key segments to enable efficient record access patterns that don't depend on complex business key combinations or field ordering requirements.
+
+SystemId values work well with OData expansion operations, providing stable relationship navigation that remains consistent across API requests and system operations.
+
+## Concurrency Control Integration
+
+SystemId can be combined with ETag implementations to provide robust optimistic concurrency control in API scenarios. This combination enables reliable conflict detection and resolution.
+
+The stability of SystemId values supports long-running API operations where record identification must remain consistent across extended time periods or multiple API interactions.
+
+Consider using SystemId in combination with timestamp fields for advanced concurrency control scenarios that require both unique identification and change detection.
+
+## Migration and Data Import Scenarios
+
+SystemId values can be preserved during data migration operations, maintaining external system references and integration consistency across system transitions.
+
+Data import processes should consider SystemId handling requirements, especially when maintaining references from external systems or preserving integration relationships.
+
+Plan for SystemId regeneration scenarios that might be required during major system upgrades or data restructuring operations that affect external system integration.
+
+## Security and Access Control
+
+SystemId values are generally safe to expose through API interfaces as they don't reveal sensitive business information while providing unique identification capabilities.
+
+Consider SystemId exposure in security models, as these values provide persistent record identification that could be used in unauthorized access attempts over extended time periods.
+
+SystemId-based access control patterns can provide more granular security implementations compared to business key-based approaches, especially in multi-tenant scenarios.
+
+## Testing and Validation
+
+Implement proper testing for SystemId-based API operations, including validation of unique identification, relationship consistency, and external system integration scenarios.
+
+Test SystemId behavior across different BC operations including record creation, modification, deletion, and restoration to ensure consistent integration behavior.
+
+Validate SystemId performance characteristics under realistic data volumes and query patterns to ensure scalable API implementations.
+
+## Best Practices
+
+Use SystemId for external system integration scenarios where stable, unique identification is required across system boundaries and extended time periods.
+
+Consider combining SystemId with business keys to provide flexible identification options that support different API consumer requirements and usage patterns.
+
+Document SystemId integration decisions and patterns for API implementations to ensure consistent approaches and support ongoing maintenance requirements.
+
+Plan for SystemId lifecycle management in scenarios involving data archiving, system migrations, or major structural changes that might affect external system integration.