Add TransferFields SkipFieldsNotMatchingType guidance

community/knowledge/data-modeling/transferfields-skip-type-mismatch-can-drop-data.bad.al

@@ -0,0 +1,55 @@
+table 50123 "Transfer Source Bad"
+{
+    fields
+    {
+        field(1; "Entry No."; Integer)
+        {
+            DataClassification = CustomerContent;
+        }
+        field(2; "Reference"; Code[20])
+        {
+            DataClassification = CustomerContent;
+        }
+    }
+
+    keys
+    {
+        key(PK; "Entry No.")
+        {
+            Clustered = true;
+        }
+    }
+
+}
+
+table 50124 "Transfer Target Bad"
+{
+    fields
+    {
+        field(1; "Entry No."; Integer)
+        {
+            DataClassification = CustomerContent;
+        }
+        field(2; "Reference"; Integer)
+        {
+            DataClassification = CustomerContent;
+        }
+    }
+
+    keys
+    {
+        key(PK; "Entry No.")
+        {
+            Clustered = true;
+        }
+    }
+
+}
+
+codeunit 50492 "TransferFields Bad"
+{
+    procedure CopyData(Source: Record "Transfer Source Bad"; var Target: Record "Transfer Target Bad")
+    begin
+        Target.TransferFields(Source, true, true);
+    end;
+}

community/knowledge/data-modeling/transferfields-skip-type-mismatch-can-drop-data.good.al

@@ -0,0 +1,56 @@
+table 50121 "Transfer Source"
+{
+    fields
+    {
+        field(1; "Entry No."; Integer)
+        {
+            DataClassification = CustomerContent;
+        }
+        field(2; "Reference"; Code[20])
+        {
+            DataClassification = CustomerContent;
+        }
+    }
+
+    keys
+    {
+        key(PK; "Entry No.")
+        {
+            Clustered = true;
+        }
+    }
+
+}
+
+table 50122 "Transfer Target"
+{
+    fields
+    {
+        field(1; "Entry No."; Integer)
+        {
+            DataClassification = CustomerContent;
+        }
+        field(2; "Reference"; Integer)
+        {
+            DataClassification = CustomerContent;
+        }
+    }
+
+    keys
+    {
+        key(PK; "Entry No.")
+        {
+            Clustered = true;
+        }
+    }
+
+}
+
+codeunit 50491 "TransferFields Good"
+{
+    procedure CopyData(Source: Record "Transfer Source"; var Target: Record "Transfer Target")
+    begin
+        Target."Entry No." := Source."Entry No.";
+        Evaluate(Target."Reference", Source."Reference");
+    end;
+}

community/knowledge/data-modeling/transferfields-skip-type-mismatch-can-drop-data.md

@@ -0,0 +1,26 @@
+---
+bc-version: [all]
+domain: data-modeling
+keywords: [transferfields, skipfieldsnotmatchingtype, type-mismatch, field-mapping, data-transfer]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Do not use SkipFieldsNotMatchingType to hide required TransferFields mismatches
+
+## Description
+
+`Record.TransferFields` copies values between fields with matching field numbers. Without `SkipFieldsNotMatchingType` (or with it `false`), a type mismatch between two fields in the same extension raises a runtime error at the point of transfer. Setting `SkipFieldsNotMatchingType` to `true` removes that error: the field is skipped instead, and the rest of the transfer completes normally. The caller gets no indication that a field was not copied.
+
+## Best Practice
+
+Use `TransferFields(Source)` when matching field definitions are an expected part of the table design. If source and destination fields intentionally have different types, map those fields explicitly and handle the conversion or validation in code. Use `SkipFieldsNotMatchingType = true` only when skipping incompatible fields is an intentional, documented part of the transfer contract.
+
+## Anti Pattern
+
+Using `TransferFields(Source, InitPrimaryKeyFields, true)` as a generic way to make two evolving table schemas transfer without errors, when the destination depends on every required source field being copied. A type change on either table can turn a previously transferred field into a silently skipped one without making the transfer itself fail.
+
+See sample: `transferfields-skip-type-mismatch-can-drop-data.good.al`.
+
+See sample: `transferfields-skip-type-mismatch-can-drop-data.bad.al`.