Resolve al-data-modeling-review.md by union: scope, not-applicable
definition and targeted cues now cover both this PR's document
distribution/price/barcode topics and main's dimension-wiring,
posting-routine and Item Ledger Entry topics.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Barcode: drop the false claim that '*value*' is mismatched with the
IDAutomation Code 39 font; '*' is a documented start/stop form and
'(' / ')' an accepted alternative. Cue and article now route only
independently provable validation/checksum/font-binding defects.
- Dispatch good samples (and matching bad samples) now pass a
Sales Invoice Header with the S.Invoice usage, matching the record
the selected report (1306 "Standard Sales - Invoice") expects.
- custom-document-dispatch rule made disjunctive: a hardcoded report
or a hand-built email is each a bypass on its own; scoped to
customer/vendor-facing documents. Bad fixture shows the hardcoded
report alone.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Add 3 more AL/BC patterns from CURABIS Academy testing course material
Third batch from CURABIS ApS: item-ledger-entry document-no lookup after Ship-and-Invoice posting, TestPage.Visible()/.Enabled() as the mechanism for verifying field UI state, and LibraryUtility.GenerateGUID() for collision-free test fixture values.
* Address Jesper Schulz-Wedde's review on PR #158
- use-generateguid-for-unique-test-fixture-values.md: GenerateGUID()
is a Code[10] number-series value, not a real GUID; truncating it
with CopyStr for a shorter field cuts off the changing digits. Point
to GenerateRandomCode/GenerateRandomCodeWithLength/GenerateRandomXMLText
instead, which verify uniqueness against the actual table.
- Split use-testpage-visible-enabled-to-verify-field-ui-state.md: drop
its editability claim (the sample opens with OpenView() and asserts
Enabled(), which verifies enabled state, not editability — Editable()
and Enabled() are distinct TestField methods). New companion article
use-testpage-editable-to-verify-field-editability.md covers Editable()
with OpenEdit() specifically.
- Wire GenerateGUID/CopyStr and TestPage Visible/Enabled/Editable cues
into al-testing-review.md, and the Item Ledger Entry/Last Shipping No.
posting cue into al-data-modeling-review.md.
The Item Ledger Entry article itself was independently verified against
current BCApps source and needs no changes.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Address second round of Jesper Schulz-Wedde's review on PR #158
- use-generateguid-for-unique-test-fixture-values.md/.good.al: documented
each LibraryUtility helper's actual behavior, verified against
LibraryUtility.Codeunit.al. GenerateRandomCode opens the target table as
a temporary RecordRef, so despite taking TableNo it never checks real
data. GenerateRandomXMLText performs no table lookup at all. Only
GenerateRandomCodeWithLength/GenerateRandomCode20 (capped at Code[10]/
Code[20]) genuinely verify against the real table. Fixture switched to
GenerateRandomCodeWithLength where the comment claims verified
uniqueness.
- al-testing-review.md: rewired the cue to catch the actual anti-pattern
(hardcoded literals, hand-built uniqueness, short-field GUID truncation)
instead of only matching the compliant GenerateGUID()+CopyStr shape;
broadened tokens to include TestPage, Library - Utility, and
.Visible()/.Enabled()/.Editable().
- al-data-modeling-review.md: restricted the Item Ledger Entry
Last-Shipping-No. cue to sales combined posting; purchase combined
posting is Receive+Invoice and uses different fields entirely.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Fix remaining correctness issues from Jesper's 2026-09-15 re-review
- use-generateguid-for-unique-test-fixture-values.md: narrowed the
collision rule to primary-key/unique-lookup fields - an ordinary
descriptive field carries no uniqueness constraint, so a hardcoded
or deterministic value there isn't the anti-pattern (the article and
its al-testing-review.md worklist cue both said "primary-key or
descriptive field"). Also corrected GenerateRandomCode: it opens its
target table as a temporary RecordRef that starts and stays empty,
so its repeat/until loop always exits after one iteration and never
retries even within a single test run - the "non-colliding within a
test run" claim was false. It's the rightmost N characters of
GenerateGUID()'s sequential series, so a short field's value cycles
(Code[1] repeats every 10 calls, Code[2] every 100). Verified against
LibraryUtility.Codeunit.al in the BCApps reference clone.
- item-ledger-entry-document-no-follows-last-shipping-no: both
fixtures called FindSet() without consuming its optional Boolean,
which raises a runtime error on an empty result set - the opposite
of the article's own claimed "silently matches zero rows, no error"
behavior. Wrapped in `if ... then;` per the existing
guard-database-reads.good.al idiom.
- al-data-modeling-review.md: widened both not-applicable scope
clauses (intro and outcome) to include dimension wiring, posting-
routine structure, and Item Ledger Entry document-number lookups -
the leaf declared itself not-applicable outside setup/master/key/
numbering/block/audit surfaces despite having a targeted cue for
this PR's own new article.
- Converted this PR's 8 plain-backtick "See sample: `x.good.al`."
references (across all 4 new articles) to the READ-convention
markdown-link form required by Knowledge-Retrieval.ps1.
Rebased onto upstream/main (one conflict in al-data-modeling-review.md
intro wording, merged).
* Stop routing GenerateRandomCode20 as compliant for shorter fields
al-testing-review.md's cue presented GenerateRandomCodeWithLength and
GenerateRandomCode20 as interchangeable options for "a shorter field
needing real verified uniqueness." They aren't: verified against
LibraryUtility.Codeunit.al, GenerateRandomCode20 truncates
GenerateGUID()'s sequential value down to the target field's length by
keeping the leftmost (slowest-changing) characters via PadStr, so its
retry loop against a field shorter than 20 can churn through the same
truncated prefix for a long time. GenerateRandomCodeWithLength has no
such problem (it generates exactly the requested length of random
text). The knowledge article itself already scoped GenerateRandomCode20
to Code[20] correctly - only the skill cue needed narrowing to match.
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* Add 18 community AL/BC patterns across style, data-modeling, web-services, appsource, breaking-changes, performance, and testing
Contributed by CURABIS ApS, generalized from patterns observed across real AppSource/PTE development. Each article follows the knowledge file format (frontmatter, Description/Best Practice/Anti Pattern, sibling .good.al/.bad.al samples).
* Address Jesper Schulz-Wedde's review on PR #156
- Rename 3 articles so their .good.al/.bad.al companion stems match
(do-not-change-primary-key, testfield-required-setup-field,
al-identifiers-english), fixing the R14 orphan-sample errors.
- do-not-change-primary-key.good.al: include Flow in the new table's
own primary key so it actually models the discriminating dimension.
- al-build-output-must-not-pollute-project-root.md: drop the
unsubstantiated AL0197 causal claim and the non-existent
al.outputPath setting; reframe as build-artifact hygiene sourced
from ALTool --outfolder / al_build outputPath.
- prefer-email-module.md: Email Message is Codeunit 8904, not a table;
distinguish it from the underlying Sent/Outbox/Draft storage.
- file-datatype-saas.md: File.Open/Create/Read/Write fails to compile
against a Cloud-scoped project, it does not compile and silently
fail at runtime.
- namespace-must-be-verified-from-source.md: narrow to "resolve from
the referenced object's source or symbols," since source-file line
one is not the only authoritative source (symbol packages, comments
before the namespace line).
- test-data-must-be-random-and-complete.md: drop "assume an empty
database" and "collision-free" absolutes; reframe around
independence from unrelated business records and reserving explicit
values for scenario-defining inputs.
- binary-choice-must-be-boolean.md: scope to genuine true/false
semantics, not mechanical two-member-enum-to-boolean conversion.
- document-report-word-layout.md: scope down to a sourced Microsoft
Learn recommendation instead of an unconditional performance
guarantee; cite the three Learn pages.
- Wire the new articles into their review skills' candidate-selection
signals (file-datatype-saas, prefer-email-module,
namespace-must-be-verified-from-source, var-parameters-require-an-
addressable-variable) so they can actually enter a worklist.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Fix dimension-management-wiring.md: ValidateShortcutDimCode and CreateDim
do not exist on the current DimensionManagement codeunit
Verified against microsoft/BCApps: the real master-table validation
procedure is ValidateDimValueCode (or ValidateShortcutDimValues when a
DimSetID is also needed), and the real document-side inheritance
procedure is GetDefaultDimID, not CreateDim. Caught from Jesper
Schulz-Wedde's review thread, which had been partially hidden by
GitHub's comment folding.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Address second round of Jesper Schulz-Wedde's review on PR #156
- dimension-management-wiring.md/.good.al: split into the two distinct
models the article was conflating - master data (Default Dimension
records via ValidateDimValueCode/SaveDefaultDim) vs. transactional/
document data (a single Dimension Set ID assembled via AddDimSource +
GetDefaultDimID, verified against BCApps' ExchRateAdjmtProcess.Codeunit.al).
Added a compiling document-table example alongside the existing master
table one.
- Deleted api-page-flowfields-must-be-calcfields (.md/.good.al/.bad.al):
Microsoft's own FlowFields documentation states a FlowField used as a
control's direct source expression is automatically calculated on any
page - no API-page exception is documented, and none could be
reproduced.
- prefer-email-module.bad.al/.md: Codeunit Mail has no Send/GetErrorDesc
members; fixed to the real current 7-argument CreateMessage signature,
and corrected the claim that the legacy path "still runs" - its base
implementation no longer sends anything, only raises integration events.
- check-post-line-batch-pattern.md/.good.al: reframed from a universal
invariant to the standard shape, naming the real Gen./Item/CA/Res./Job/
Insurance/Mfg. Item/FA Jnl.-Check Line/-Post Line/-Post Batch codeunits
it's based on. Added the missing Check Line companion codeunit so the
good fixture is internally complete.
- test-data-must-be-random-and-complete.good.al: removed leftover
"collision-free" wording contradicting the already-corrected article text.
- fixed-choice-set-must-use-enum-not-integer.md: removed the reintroduced
state-count heuristic ("the line is the state count"), aligned with
binary-choice-must-be-boolean.md's semantics-based distinction.
- namespace-must-be-verified-from-source.md: removed the false claim that
the compiler and AL Language Server use different namespace-resolution
rules.
- intrinsic-al-functions-must-use-modern-casing.md: removed the unverified
claim that PascalCase is the VS Code formatter's default output.
Worklist completeness: added cues for the 8 rules in data-modeling,
testing, performance, and web-services that had none (Jesper's explicit
ask), plus the same gap in all 7 style rules from this PR (not explicitly
named this round, but the identical systemic issue) - 15 cues total across
al-data-modeling-review.md, al-testing-review.md, al-performance-review.md,
al-web-services-review.md, and al-style-review.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Fix remaining correctness issues from Jesper's 2026-09-15 re-review
- dimension-management-wiring: SaveDefaultDim's third argument is the
shortcut dimension number (1-8), not the field's AL field ID; the
fixture passed FieldNo(...) = 10. GetDefaultDimID's InheritFromDimSetID
must be 0 when recomputing after the linking record changes, not the
document's existing Dimension Set ID (which would retain the previous
customer's leftover dimensions). Verified against
DimensionManagement.Codeunit.al and BankDepositHeader.Table.al in the
BCApps reference clone.
- check-post-line-batch-pattern: "Post Line writes exactly one line to
the ledger" overclaimed - Gen. Jnl.-Post Line alone calls InsertGLEntry
from a dozen call sites (balancing entry, VAT, currency rounding,
deferrals) and can write several G/L Entries per journal line.
Reworded to "posts exactly one journal line" and softened the
"distinct, non-overlapping responsibilities" absolute.
- namespace-must-be-verified-from-source.bad.al: dropped the "resolves
in a local build, fails in VS Code" comment (taught an inherent
compiler/language-server disagreement that isn't real); reframed as
stale/cached symbols, matching the prose fix already made.
- file-datatype-saas.good.al: replaced the deprecated 5-argument
UploadIntoStream overload with the current 2-argument one, and
actually staged through TempBlob as the article's own Best Practice
instructs (the declared TempBlob variable was previously unused).
- test-data-must-be-random-and-complete: no longer treats a
short-but-valid value as defective merely for being "underfilled" -
AL field lengths are maxima, not minimums. Scoped to missing values
or a scenario with an explicit length/format requirement (e.g. a
truncation test). Updated the al-testing-review.md routing cue to
match.
- stored-derived-fields-must-not-be-exposed-directly: stopped mandating
source-field exposure as part of the core pattern: the good fixture
exposed only one of the derived value's two inputs (Hours Used, not
Budgeted Hours), making the claimed "so the consumer can verify it"
impossible. Reframed as an optional, all-or-nothing addition and
fixed the fixture to expose both inputs.
Rebased onto upstream/main to resolve conflicts in
al-breaking-changes-review.md, al-data-modeling-review.md,
al-performance-review.md, and al-style-review.md against merged PRs
#148 and #153; all sides' worklist tokens/cues retained.
* Fix remaining READ-convention sample links across this PR's 18 articles
The same plain-backtick "See sample: \`x.good.al\`." form fixed on
al-methods-limited-during-write-transactions (PR #161) turned up
repo-wide on 15 more of this PR's articles - Knowledge-Retrieval.ps1
requires the markdown-link form to associate a sample with its
article. All 16 fixed; the four local validators (frontmatter,
knowledge-index, knowledge-retrieval, review-fixtures, skill-index)
pass.
* Fix two merge-critical correctness issues from Jesper's 2026-09-22 review
- api-page-key-fields-must-be-editable-on-insert.good.al and
stored-derived-fields-must-not-be-exposed-directly.good.al: both were
writable API pages missing DelayedInsert = true, contradicting this
repo's own api-page-delayedinsert-true rule - the canonical "good"
samples were teaching code BCQuality itself flags.
- dimension-management-wiring.good.al: UpdateDimensionSetID exited
early when Customer.Get failed, leaving the previous customer's
shortcut dimension and Dimension Set ID in place - the same staleness
bug the InheritFromDimSetID = 0 fix (from the prior review round) was
meant to prevent, just triggered by a failed lookup instead of a
successful one. Now clears the shortcut field and recomputes with an
empty source list on a failed lookup too, so GetDefaultDimID
correctly returns an empty Dimension Set ID instead of never running.
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
The previous bad fixture (literal '*' delimiters, no layout/font/provider
evidence) no longer matched the narrowed routing cue. It now shows an
IDAutomation 1D provider path that calls EncodeFont without ValidateInput,
which is visible in AL alone. Article Anti Pattern and Source updated to
describe this variant (verified: IDAutomation 1D Provider's EncodeFont
does not call IsValidInput).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- activate-new-price-calculation-handler-via-onfindsupportedsetup: Default
:= true is required only for the fallback branch of PriceCalculationMgt's
two-stage FindSetup - a handler reachable via a specific Dtld. Price
Calculation Setup row needs no Default. Softened the article and its
worklist cue accordingly. Also fixed an undefined "Sample Price Calc -
Special" codeunit referenced but never declared in the eval fixtures -
added a real implementation of interface "Price Calculation" with stub
methods.
- new-price-source-must-add-candidate-and-trigger-recalculation: the good
fixture called UpdateUnitPriceByField directly, which is a silent no-op
without a prior PlanPriceCalcByField call (FieldCausedPriceCalculation
gating, verified against SalesLine.Table.al). Switched to the public
UpdateUnitPrice wrapper, matching real BCApps usage in
ItemReferenceManagement.Codeunit.al.
- report-barcodes-must-use-barcode-module-and-production-font-name: split
the 1D (ValidateInput + EncodeFont) and 2D (EncodeFont only) Barcode Font
Provider interfaces, which the article previously conflated. Reframed the
Code 39 anti-pattern around demonstrable encoding/checksum mismatch
(verified against IDA1DCode39Encoder.Codeunit.al's real '(value)' output)
rather than rejecting all manual delimiter use, since '*' is a legitimate
Code 39 start/stop character. Also fixed extend-find-entries-navigate-
for-new-document-types' eval fixtures, which referenced an undefined
"Sample Posted Document Header" table/page - declared both.
All claims re-verified against live microsoft/BCApps source. Validators:
frontmatter 0/0, review-fixtures 126/20 domains PASSED, knowledge-index
342/575 PASSED, skill-index 19 leaves PASSED.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- Resolve conflicts in al-data-modeling-review.md by keeping both sides'
additions (folder-path support, InitRecord/Round cues from upstream;
the 9 document-distribution/pricing/barcode cues from this branch).
- Switch the data-modeling evaluation override from an ad-hoc
additionalArticles field to upstream's now-established articles[]
convention (used elsewhere for finance/scm/query/reporting/style),
removing the redundant parallel code path from Test-ReviewFixtures.ps1.
- Fix all 9 new articles' sample references to the markdown-link READ
convention required by Knowledge-Retrieval.ps1's Assert-SampleLink
(plain backticks satisfy validate_frontmatter.py's regex alone but not
this stricter check - both validators must pass).
Validators: frontmatter 0/0, review-fixtures 126 cases/20 domains PASSED,
knowledge-index 342 articles/575 samples PASSED, skill-index 19 review
leaves PASSED.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Addresses microsoft/BCQuality#175 review feedback:
- Extend al-data-modeling-review's entry gate/relevance scope and token
list to recognize document actions, Navigate subscribers, Report
Selection registration, price-calculation/price-source extensibility,
TransferFields posting-cascade mirroring, and barcode font-provider
usage - previously excluded before any worklist cue could run.
- Fix document-print-and-email-actions-call-report-selections-directly:
permit the legitimate stateless DocumentSendingProfile.TrySendToPrinter/
TrySendToEMail path; rework the bad fixture to load a configured
profile instead of demonstrating a trivial blank-record no-op.
- Fix extend-report-selection-usage-for-new-document-types: scope to the
applicable single counterparty (ReportSelectionHandlerCZZ partitions
strictly; only genuinely two-sided usages like Compensation need both),
and add the page-facing usage-enum map/validate events alongside the
filter-event subscription for full Document Layouts support.
- Fix a stale field-citation in custom-document-dispatch-must-not-bypass-
report-selections (Custom Report Layout Code is field 7, not part of
the 19-26 email-configuration range).
- Add deterministic positive/clean evaluation coverage (review-fixtures.json
additionalArticles + Test-ReviewFixtures.ps1 support) so all 9 new
good/bad pairs are actually exercised, not just present.
- Add 4 new patterns: activate-new-price-calculation-handler-via-
onfindsupportedsetup, extend-price-source-type-must-sync-document-
subset-enum, new-price-source-must-add-candidate-and-trigger-
recalculation, report-barcodes-must-use-barcode-module-and-production-
font-name.
All claims verified against live microsoft/BCApps source and Microsoft
Learn. Validators: frontmatter 0/0, review-fixtures 52 cases/17 domains
PASSED, knowledge-index 309 articles PASSED.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Five rules about Business Central's document distribution architecture,
verified against BCApps source and Microsoft Learn.
- custom-document-dispatch-must-not-bypass-report-selections
- document-print-and-email-actions-call-report-selections-directly
- extend-find-entries-navigate-for-new-document-types
- extend-report-selection-usage-for-new-document-types
- transferfields-mirrored-fields-must-match-type-and-length
Wired into al-data-modeling-review.md's worklist cues. Added a
disambiguation note on the TransferFields article distinguishing it from
the existing transferfields-skip-type-mismatch-can-drop-data.md
(type-mismatch skipping vs. length mismatch, which SkipFieldsNotMatchingType
does not affect).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Move canonical knowledge for Microsoft-owned review domains into the Microsoft layer and document the skill/knowledge co-location policy.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
Copilot-Session: 2a6ea875-d38e-4f30-aadb-0d606f9be231
data-modeling: add insert-only-transfer-may-rely-on-caller-cleanup. A filter-and-insert transfer routine was reported for stale rows and duplicate keys even though the field OnValidate trigger calls a sibling cleanup procedure that clears the same range immediately before it. Deciding this requires reading the caller, so the article asks reviewers to trace call sites and keeps uncleared or mismatched-filter paths reportable.
appsource: scope two-level-namespace-replaces-object-affix-not-extension-member-affix to apps that actually configure a mandatory affix. AS0011 only runs when AppSourceCop is enabled with a mandatory affix; a first-party in-box app that ships no such configuration is not subject to it. The member-affix requirement itself is unchanged for apps that do configure one.
testing: allow permission-tests-must-lower-the-execution-context to accept a composed role. The article demanded the exact permission set under test be assigned directly, so a test that lowered permissions through a role including that set and then asserted WritePermission was false was reported as a coverage gap. What matters is the effective context plus a boundary assertion, not which object the test names.
Co-authored-by: wenjiefan <wenjiefan@microsoft.com>
* Complete AL review knowledge readiness
Fill telemetry and Query coverage, strengthen thin review domains, correct audited content defects, and add deterministic cheap-model evaluation and reference-integrity safeguards.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9825b012-e653-496a-9310-c1f4b6f8ac27
* Generalize review fixture discovery
Derive smoke cases from the leaf, domain, and paired-sample conventions so new leaves require no scoring-contract changes. Keep only exceptional selection/context overrides and fail when retrieval metadata cannot rank the selected article.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9825b012-e653-496a-9310-c1f4b6f8ac27
* Preserve published field IDs in sample
Keep the existing Email and Contact Email field IDs unchanged, clarify that the sample represents an independent baseline, and use a local breaking-change rule for the generic smoke evaluation.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9825b012-e653-496a-9310-c1f4b6f8ac27
* Clarify published field identity rules
State explicitly that a published field keeps its ID, name, and type while a replacement is added as a separate field under an unused ID.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9825b012-e653-496a-9310-c1f4b6f8ac27
* Align field obsoletion sample baselines
Use Email field ID 3 as the shared baseline so the bad example demonstrates a same-ID rename while the good example retains the original field and adds a separate replacement.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9825b012-e653-496a-9310-c1f4b6f8ac27
---------
Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
Author 7 remedial BCQuality knowledge articles plus good/bad AL samples
(21 files) covering AL master-table and data-model design:
- data-modeling: master No. from number series in OnInsert; use codeunit
"No. Series" not obsolete NoSeriesManagement; setup table is a singleton;
set Last Date Modified in OnModify and OnRename; enforce Blocked in
referencing code not in the master.
- style: ApplicationArea required on page controls (AS0062).
- appsource: object affixes prevent collisions (AS0011).
Clean-room authored from own BC knowledge; specifics verified against public
sources only (learn.microsoft.com, microsoft/BCApps). Introduces two new
domains (data-modeling, appsource).
Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
