From ac9e4fd9a28952bb58d02a23f1aadc1482240618 Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Fri, 11 Sep 2026 09:09:53 +0200 Subject: [PATCH 01/35] Complete partner contribution and knowledge consumption guides (#176) * Improve partner onboarding and documentation navigation Lead with a complete plugin quick start and add task-oriented usage, troubleshooting, customization, and contribution guides. Preserve the broader plugin framing, correct conflicting contract guidance, support Agents folder reviews, and align repository validation. Convert existing sample references to clickable links without changing knowledge rules. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Complete partner contribution and knowledge consumption guides Explain direct reading, supplied skills, and custom-agent consumption. Add a first-contribution walkthrough and concrete integration bootstrap, and clarify SetLoadFields guidance with authoritative sources and explicit review heuristics. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 5 +- docs/README.md | 4 +- docs/agent-consumption.md | 59 +++++++++++++++++++ docs/contributing.md | 42 +++++++++++++ docs/standalone-runner.md | 3 + docs/using-bcquality.md | 53 +++++++++++++++-- .../use-setloadfields-for-partial-records.md | 11 +++- 7 files changed, 168 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 9eeee91..2118ce0 100644 --- a/README.md +++ b/README.md @@ -62,12 +62,13 @@ the review can still discover knowledge by reading the folders. | I want to... | Start here | | --- | --- | +| Choose direct reading, a supplied skill, or my own agent | [Ways to use BCQuality](docs/using-bcquality.md#choose-how-to-use-bcquality) | | Review a file, changes, a branch, or a particular concern | [Using BCQuality](docs/using-bcquality.md) | | Resolve setup problems, incomplete reviews, or incorrect findings | [Troubleshooting and support](docs/troubleshooting.md) | | Browse the available guidance | [Knowledge by domain](docs/using-bcquality.md#knowledge-by-domain) | | Configure the plugin or use my organization's rules | [Customizing BCQuality](docs/customizing-bcquality.md) | -| Contribute knowledge or improve a rule | [Contributing](docs/contributing.md) | -| Connect a host, agent, or CI integration | [How agents consume BCQuality](docs/agent-consumption.md) | +| Contribute knowledge or improve a rule | [Your first contribution](docs/contributing.md#your-first-contribution) | +| Connect a host, agent, or CI integration | [Minimal integration example](docs/agent-consumption.md#try-a-minimal-integration) | [All documentation and technical references](docs/README.md). diff --git a/docs/README.md b/docs/README.md index 1d7248b..d9ca27b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,12 +8,13 @@ of BCQuality's internal protocol is needed. | Goal | Guide | | --- | --- | +| Choose direct reading, a supplied skill, or my own agent | [Ways to use BCQuality](using-bcquality.md#choose-how-to-use-bcquality) | | Review an app, file, changes, or branch | [Using BCQuality](using-bcquality.md) | | Understand a report and its limitations | [Reading your results](using-bcquality.md#reading-your-results) | | Find a particular rule or example | [Knowledge by domain](using-bcquality.md#knowledge-by-domain) | | Fix setup problems or report an incorrect finding | [Troubleshooting and support](troubleshooting.md) | | Select layers, add company rules, or maintain a fork | [Customizing BCQuality](customizing-bcquality.md) | -| Add or improve shared knowledge | [Contributing](contributing.md) | +| Add or improve shared knowledge | [Your first contribution](contributing.md#your-first-contribution) | ## Integration and technical reference @@ -22,6 +23,7 @@ prerequisites for using the plugin. | Reference | Purpose | | --- | --- | +| [Minimal integration example](agent-consumption.md#try-a-minimal-integration) | A bootstrap prompt connecting your agent to a BCQuality checkout and an app folder. | | [How agents consume BCQuality](agent-consumption.md) | Architecture, repository structure, routing, and delivery of findings. | | [Standalone runner](standalone-runner.md) | Optional model selection, scheduling, retries, and telemetry. | | [Global skills](../skills/README.md) | Host adapters versus internal protocol files. | diff --git a/docs/agent-consumption.md b/docs/agent-consumption.md index 1bf4284..06858c0 100644 --- a/docs/agent-consumption.md +++ b/docs/agent-consumption.md @@ -10,6 +10,65 @@ mental model. This is the operational reference for integration authors. Partners using the installed plugin do not need to implement this flow themselves. +## Try a minimal integration + +**"Invoke `skills/entry.md`" means ask your agent to read and follow that +instruction document.** It is not a shell command, HTTP endpoint, or executable +library. Your host must be able to read files, enumerate directories, and +execute the selected skills as instructed. Merely mentioning BCQuality does +not make its content available to the model. + +For a first integration, create or reuse a dedicated BCQuality checkout. +For example, in PowerShell: + +```powershell +git clone https://github.com/microsoft/BCQuality.git "C:\Knowledge\BCQuality" +``` + +Give the host access to **both** that content directory and your own app +directory. The plugin is not required for this route. Replace the paths and +BC version below with your actual values, then send this prompt to the agent: + +```text +BCQuality root: C:\Knowledge\BCQuality +Review input: folder-path = C:\Repos\MyBusinessCentralApp + +Read BCQuality's skills\entry.md and follow it with this task context: +task-context: + goal: Review the complete AL app without changing its source files. + inputs-available: [folder-path] + technologies: [al] + bc-version: 28 + enabled-layers: [microsoft, community, custom] + disabled-skills: [] + +Resolve BCQuality instructions, knowledge, and index preparation against the +BCQuality root, not the app directory. Pass the actual review-input path above +when a dispatched skill accepts folder-path. +Follow Entry's preparation and dispatch instructions. Execute every dispatched +action skill with its exact input subset, reading READ and DO on demand. +Return each complete findings report unchanged. If Entry returns no-match or +failed, return that dispatch record unchanged instead of inventing a review. +``` + +`inputs-available` lists input **types**; the `Review input` line binds the type +to the actual app directory. It is not an extra Entry schema field. Omit +`bc-version` when unknown rather than guessing it; add localization or +application-area context only when known. Keep the two roots distinct so index +preparation operates on BCQuality, not your app. + +Expect Entry to select the action skills and the agent to execute them. +A broad review normally returns the Microsoft coordinator's report with +domain `sub-results`, plus any separately dispatched reports. Each report +must retain its outcome, including incomplete or failed work; see +[reading results](using-bcquality.md#reading-your-results). A dispatch record +alone is not a completed review. + +This prompt delegates the existing protocol rather than implementing new +routing logic. For repeatable runs, [pin the checkout](customizing-bcquality.md#updates-and-versions). +Add scheduling, retries, and rendering only when needed, using the +[runner contract](standalone-runner.md). + ## The actors - **Orchestrator** — the tool that triggers work. Lives *outside* BCQuality. Knows *when* to run something, not *what* to run. diff --git a/docs/contributing.md b/docs/contributing.md index b4cbb0b..0e493c2 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -6,6 +6,34 @@ Partners are welcome to contribute shared knowledge, examples, skills, and documentation. To report an incorrect finding without preparing a change, use the [support guide](troubleshooting.md#reporting-a-problem). +## Your first contribution + +You can propose shared guidance without write access to the upstream +repository. Use this path for a correction or a new article: + +1. Search the [existing knowledge](using-bcquality.md#knowledge-by-domain) and + [open issues](https://github.com/microsoft/BCQuality/issues). Correct or + extend an existing article when it already owns the concern; add a new + article only for a distinct concern that meets the admission test below. +2. [Fork BCQuality](https://github.com/microsoft/BCQuality/fork) into your GitHub + account or organization, clone your fork, and create a working branch from + the current upstream `main`. Make edits in that branch, not the plugin cache. +3. Choose the [owning layer and domain](#choose-the-right-destination), then + edit the article or use the [shared-article starter](#shared-article-starter). + A contribution intended for everyone does not belong in `custom/`. +4. Add supporting sources and relevant good/bad samples. For a false positive, + explain the valid pattern and the mistaken finding the rule should prevent. +5. Run the [documented checks](#before-opening-a-pr), then commit and push + your branch to your fork. +6. On GitHub, open a pull request with **base repository + `microsoft/BCQuality`, base branch `main`**, and your fork's working branch + as the head. Explain why the change is needed and respond to review by + pushing further commits to the same branch. + +Merged content is not automatically loaded into an existing agent session. +Consumers must pick up the updated content through their installation or +checkout; see [updates and versions](customizing-bcquality.md#updates-and-versions). + ## What belongs here BCQuality is a remedial knowledge base. A knowledge file exists because a @@ -69,6 +97,20 @@ to catch in `Anti Pattern`; those are the normative sections. Explain legitimate exceptions so a reviewer does not turn a useful rule into a false positive. Code fences are not allowed in knowledge articles. +### Shared-article starter + +Use [caption-required-on-page-fields.md](../microsoft/knowledge/style/caption-required-on-page-fields.md) +as a complete shared-knowledge example. It demonstrates all six metadata +fields, a clear concern, normative guidance and exceptions, linked good/bad +samples, and authoritative sources. + +For a new concern, follow that structure but choose your own descriptive +filename, domain, applicability, keywords, and guidance. Replace its sources +and sample links with ones supporting your concern; do not duplicate the +caption rule. If you are correcting caption guidance itself, edit the +existing article instead. Use a company-only rule only in your fork's Custom +layer, following the separate [customization example](customizing-bcquality.md#add-an-organization-specific-rule). + ### Sources and examples When adding or changing a platform claim, link the authoritative source that diff --git a/docs/standalone-runner.md b/docs/standalone-runner.md index 31ab1dd..61ecb55 100644 --- a/docs/standalone-runner.md +++ b/docs/standalone-runner.md @@ -12,6 +12,9 @@ Use the built-in standalone plugin when the host's default execution is sufficient. Build a runner when you need explicit control over cost, latency, concurrency, or integration with another review surface. +Start with the [minimal integration example](agent-consumption.md#try-a-minimal-integration) +to connect your agent to the content before adding runner-specific behavior. + ## Keep BCQuality current For plugin installation, use the [quick start](../README.md#quick-start). diff --git a/docs/using-bcquality.md b/docs/using-bcquality.md index bb1d955..44e5975 100644 --- a/docs/using-bcquality.md +++ b/docs/using-bcquality.md @@ -2,10 +2,55 @@ [Documentation](README.md) | [Quick start](../README.md#quick-start) | [Troubleshooting](troubleshooting.md) -BCQuality supplies knowledge and reusable skills to your AI host. The plugin -currently exposes `al-code-review`; the examples below use that skill. The -host supplies authentication, model access, tools, permissions, and rendering. -Installing BCQuality does not install a Business Central extension or an agent. +BCQuality is knowledge you can read and reuse, plus skills that tell an agent +how to apply it. You do not need an AI tool to read the articles. When using +an agent, your host supplies authentication, model access, tools, permissions, +and rendering; BCQuality does not install a BC extension or an agent. + +## Choose how to use BCQuality + +| Path | What to do | +| --- | --- | +| Read the knowledge yourself | Browse [knowledge by domain](#knowledge-by-domain), or search the repository for an AL concept. Read the article and its samples. No installation required. | +| Use a supplied skill | Follow the [plugin quick start](../README.md#quick-start). The currently exposed skill, `al-code-review`, performs reviews and returns findings. | +| Use your own agent or workflow | Supply selected articles as context, as described below, or use the [integration bootstrap](agent-consumption.md#try-a-minimal-integration) to execute BCQuality action skills without the plugin. | + +### Read and reuse an article + +Start with a concern, such as `SetLoadFields`, and search within +`microsoft/BCQuality` on GitHub or open its domain folder. For example, +[partial-record guidance](../microsoft/knowledge/performance/use-setloadfields-for-partial-records.md) +explains the concern and links good/bad samples. + +Before applying an article, read its frontmatter, the small metadata block at +the top: + +| Field | How to read it | +| --- | --- | +| `bc-version` | `[24..]` means BC 24 and later; `[26..28]` means BC 26 through 28; `[all]` means every version. Use your target BC major version, not your extension's version. | +| `technologies` | `[al]` means the guidance applies to AL; multiple values identify the technologies the article covers. | +| `countries` | `[w1]` means worldwide; a code such as `[dk]` limits the guidance to that localization. | +| `application-area` | `[all]` means any application area; a named area narrows applicability. | +| `domain` and `keywords` | Help you find the topic; they are not instructions or additional requirements. | + +Read `Description` for context, then `Best Practice` and `Anti Pattern` for the +rule and its exceptions. Follow any sample and source links. Do not turn a +sample into a production implementation without considering your own context. +The [READ reference](../skills/read.md) defines the precise matching rules. + +To use an article with your own agent, give it access to the full article and +relevant samples, not just a title or index row. For example, replace the +bracketed values in this prompt: + +> Read [article URL or local path] and its linked samples. Apply the relevant +> guidance while implementing [task] for BC [major version]. Explain which +> guidance you used, cite the article, and identify any missing context. + +A URL only works if the host can retrieve it; otherwise provide the files +directly. This is ordinary reuse of knowledge for explanation or code writing, +**not a packaged code-generation skill or a complete BCQuality review**. +For the structured review process, invoke a supplied skill or follow the +integration protocol. The remaining sections describe the review workflow. ## Hosts and prerequisites diff --git a/microsoft/knowledge/performance/use-setloadfields-for-partial-records.md b/microsoft/knowledge/performance/use-setloadfields-for-partial-records.md index 06b2d14..de92bb1 100644 --- a/microsoft/knowledge/performance/use-setloadfields-for-partial-records.md +++ b/microsoft/knowledge/performance/use-setloadfields-for-partial-records.md @@ -11,11 +11,13 @@ application-area: [all] ## Description -`SetLoadFields(...)` declares the subset of normal fields the next read should materialize, "reducing data read and transfer thereby improving performance significantly." Per the upstream guidance, "the gains scale with the amount of rows read, so for loops that read many rows `SetLoadFields` is even more important." Primary-key fields, `SystemId`, and system audit fields are loaded automatically, "and fields that are filtered on are also automatically included" — those do not need to appear in the list. `SetLoadFields` only affects `FieldClass = Normal`; it does not narrow FlowFields or FlowFilters. Its position relative to `SetRange`/`SetFilter` does not change the projection: filtered fields are added to the load set at read time either way. Projection-changing operations are separate: `AddLoadFields(...)` expands the selection, a later `SetLoadFields(...)` or `SetBaseLoadFields()` overwrites it, and `Reset()` or a fieldless `SetLoadFields()` restores all readable normal fields. +`SetLoadFields(...)` declares the subset of normal fields the next read should materialize. Microsoft's partial-record guidance explains how loading fewer fields reduces work, particularly for read loops and tables with extensions. Primary-key fields, `SystemId`, system audit fields, and fields being filtered on are loaded automatically; those do not need to appear in the selection. Only `FieldClass = Normal` fields can be selected, not FlowFields or FlowFilters. + +Its position relative to `SetRange`/`SetFilter` does not change the projection: filtered fields are included at read time either way. Projection-changing operations are separate: `AddLoadFields(...)` expands the selection, a later `SetLoadFields(...)` or `SetBaseLoadFields()` overwrites it, and `Reset()` or a fieldless `SetLoadFields()` restores all readable normal fields. The Microsoft Learn references below document the selection and reset behavior. ## Best Practice -Before a `Get`, `FindSet`, or `FindFirst` that the procedure follows by reading only a handful of the table's fields, call `SetLoadFields` listing exactly those fields. The pattern `SetLoadFields(...); if Record.Get(...) then ...` is the upstream-endorsed shape. Place the call immediately before the read, after any `SetRange`/`SetFilter`, so a reader can see at a glance which read the selection governs and any projection-changing operation is easy to spot. Skip `SetLoadFields` when the table has few fields (under ten), when the code reads most of them (above 60 %), when the loop runs ten or fewer iterations, or when the table is exempt for other reasons (`singleton-setup-tables-need-no-access-optimization.md`, `temporary-tables-have-no-database-cost.md`). For report dataitems, use `AddLoadFields` in `OnPreDataItem` instead (see `addloadfields-in-report-onpredataitem.md`). +Before a `Get`, `FindSet`, or `FindFirst` that the procedure follows by reading only a handful of the table's fields, call `SetLoadFields` listing exactly those fields. For example, `SetLoadFields(...); if Record.Get(...) then ...` selects fields before the read. Place the call immediately before the read, after any `SetRange`/`SetFilter`, so a reader can see at a glance which read the selection governs and any projection-changing operation is easy to spot. Skip `SetLoadFields` when the table has few fields (under ten), when the code reads most of them (above 60 %), when the loop runs ten or fewer iterations, or when the table is exempt for other reasons ([singleton setup tables](singleton-setup-tables-need-no-access-optimization.md), [temporary tables](temporary-tables-have-no-database-cost.md)). The numeric cutoffs are BCQuality review heuristics, not Microsoft platform thresholds. For report dataitems, use `AddLoadFields` in `OnPreDataItem` instead (see [report partial loads](addloadfields-in-report-onpredataitem.md)). See sample: [`use-setloadfields-for-partial-records.good.al`](use-setloadfields-for-partial-records.good.al). @@ -26,3 +28,8 @@ Loading a wide table and reading one field per row in a loop. The bytes transfer Statement order is not part of this anti pattern. `SetLoadFields` placed ahead of `SetRange`/`SetFilter` materializes exactly the same columns as the reverse order, so a reviewer reports it as a readability observation at most — never as a performance defect. See sample: [`use-setloadfields-for-partial-records.bad.al`](use-setloadfields-for-partial-records.bad.al). + +## References + +- [Record.SetLoadFields remarks](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/record/record-setloadfields-method#remarks): automatically loaded fields, normal-field restrictions, and resetting the selection. +- [Using partial records](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-partial-records): performance rationale, load-selection APIs, reset behavior, and report guidance. From c12b2f0a88c7316b82d2c9e01dfb8518a9eb6eea Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Fri, 11 Sep 2026 09:26:14 +0200 Subject: [PATCH 02/35] Separate analyzer rules from BCQuality knowledge (#178) Retire deterministic compiler and analyzer duplicates, remove their review routing, and clarify the admission test for contextual analyzer knowledge. Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 2 + docs/contributing.md | 13 +++++- docs/using-bcquality.md | 6 +++ evaluation/README.md | 2 +- evaluation/review-fixtures.json | 3 -- .../object-affixes-prevent-collisions.bad.al | 43 ------------------- .../object-affixes-prevent-collisions.good.al | 40 ----------------- .../object-affixes-prevent-collisions.md | 30 ------------- ...ct-affix-not-extension-member-affix.bad.al | 22 ---------- ...t-affix-not-extension-member-affix.good.al | 22 ---------- ...object-affix-not-extension-member-affix.md | 28 ------------ ...s-part-of-published-object-identity.bad.al | 9 ---- ...-part-of-published-object-identity.good.al | 8 ---- ...ce-is-part-of-published-object-identity.md | 26 ----------- ...ationarea-required-on-page-controls.bad.al | 25 ----------- ...tionarea-required-on-page-controls.good.al | 40 ----------------- ...plicationarea-required-on-page-controls.md | 28 ------------ .../begin-on-same-line-as-then-else-do.bad.al | 14 ------ ...begin-on-same-line-as-then-else-do.good.al | 24 ----------- .../begin-on-same-line-as-then-else-do.md | 26 ----------- .../block-keywords-start-new-line.bad.al | 15 ------- .../block-keywords-start-new-line.good.al | 23 ---------- .../style/block-keywords-start-new-line.md | 26 ----------- ...-subscriber-param-names-match-publisher.md | 26 ----------- .../function-call-parentheses-required.bad.al | 11 ----- ...function-call-parentheses-required.good.al | 11 ----- .../function-call-parentheses-required.md | 26 ----------- .../style/label-suffix-approved-list.bad.al | 14 ------ .../style/label-suffix-approved-list.good.al | 15 ------- .../style/label-suffix-approved-list.md | 26 ----------- .../style/lowercase-reserved-keywords.bad.al | 14 ------ .../style/lowercase-reserved-keywords.good.al | 14 ------ .../style/lowercase-reserved-keywords.md | 28 ------------ ...o-begin-end-around-single-statement.bad.al | 11 ----- ...-begin-end-around-single-statement.good.al | 10 ----- .../no-begin-end-around-single-statement.md | 26 ----------- .../no-space-before-method-parenthesis.bad.al | 11 ----- ...no-space-before-method-parenthesis.good.al | 11 ----- .../no-space-before-method-parenthesis.md | 26 ----------- ...on-required-and-matches-membercount.bad.al | 17 -------- ...n-required-and-matches-membercount.good.al | 18 -------- ...aption-required-and-matches-membercount.md | 26 ----------- .../single-space-after-not-operator.bad.al | 11 ----- .../single-space-after-not-operator.good.al | 11 ----- .../style/single-space-after-not-operator.md | 26 ----------- ...ingle-space-around-binary-operators.bad.al | 12 ------ ...ngle-space-around-binary-operators.good.al | 12 ------ .../single-space-around-binary-operators.md | 26 ----------- .../style/this-keyword-in-codeunits.bad.al | 14 ------ .../style/this-keyword-in-codeunits.good.al | 14 ------ .../style/this-keyword-in-codeunits.md | 26 ----------- .../variable-declaration-order-by-type.bad.al | 13 ------ ...variable-declaration-order-by-type.good.al | 13 ------ .../variable-declaration-order-by-type.md | 26 ----------- .../variable-name-must-not-shadow.bad.al | 19 -------- .../variable-name-must-not-shadow.good.al | 19 -------- .../style/variable-name-must-not-shadow.md | 26 ----------- .../skills/review/al-appsource-review.md | 29 ++++++------- .../review/al-breaking-changes-review.md | 5 +-- microsoft/skills/review/al-style-review.md | 22 +++++----- 60 files changed, 45 insertions(+), 1095 deletions(-) delete mode 100644 microsoft/knowledge/appsource/object-affixes-prevent-collisions.bad.al delete mode 100644 microsoft/knowledge/appsource/object-affixes-prevent-collisions.good.al delete mode 100644 microsoft/knowledge/appsource/object-affixes-prevent-collisions.md delete mode 100644 microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.bad.al delete mode 100644 microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.good.al delete mode 100644 microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.md delete mode 100644 microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.bad.al delete mode 100644 microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.good.al delete mode 100644 microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.md delete mode 100644 microsoft/knowledge/style/applicationarea-required-on-page-controls.bad.al delete mode 100644 microsoft/knowledge/style/applicationarea-required-on-page-controls.good.al delete mode 100644 microsoft/knowledge/style/applicationarea-required-on-page-controls.md delete mode 100644 microsoft/knowledge/style/begin-on-same-line-as-then-else-do.bad.al delete mode 100644 microsoft/knowledge/style/begin-on-same-line-as-then-else-do.good.al delete mode 100644 microsoft/knowledge/style/begin-on-same-line-as-then-else-do.md delete mode 100644 microsoft/knowledge/style/block-keywords-start-new-line.bad.al delete mode 100644 microsoft/knowledge/style/block-keywords-start-new-line.good.al delete mode 100644 microsoft/knowledge/style/block-keywords-start-new-line.md delete mode 100644 microsoft/knowledge/style/event-subscriber-param-names-match-publisher.md delete mode 100644 microsoft/knowledge/style/function-call-parentheses-required.bad.al delete mode 100644 microsoft/knowledge/style/function-call-parentheses-required.good.al delete mode 100644 microsoft/knowledge/style/function-call-parentheses-required.md delete mode 100644 microsoft/knowledge/style/label-suffix-approved-list.bad.al delete mode 100644 microsoft/knowledge/style/label-suffix-approved-list.good.al delete mode 100644 microsoft/knowledge/style/label-suffix-approved-list.md delete mode 100644 microsoft/knowledge/style/lowercase-reserved-keywords.bad.al delete mode 100644 microsoft/knowledge/style/lowercase-reserved-keywords.good.al delete mode 100644 microsoft/knowledge/style/lowercase-reserved-keywords.md delete mode 100644 microsoft/knowledge/style/no-begin-end-around-single-statement.bad.al delete mode 100644 microsoft/knowledge/style/no-begin-end-around-single-statement.good.al delete mode 100644 microsoft/knowledge/style/no-begin-end-around-single-statement.md delete mode 100644 microsoft/knowledge/style/no-space-before-method-parenthesis.bad.al delete mode 100644 microsoft/knowledge/style/no-space-before-method-parenthesis.good.al delete mode 100644 microsoft/knowledge/style/no-space-before-method-parenthesis.md delete mode 100644 microsoft/knowledge/style/optioncaption-required-and-matches-membercount.bad.al delete mode 100644 microsoft/knowledge/style/optioncaption-required-and-matches-membercount.good.al delete mode 100644 microsoft/knowledge/style/optioncaption-required-and-matches-membercount.md delete mode 100644 microsoft/knowledge/style/single-space-after-not-operator.bad.al delete mode 100644 microsoft/knowledge/style/single-space-after-not-operator.good.al delete mode 100644 microsoft/knowledge/style/single-space-after-not-operator.md delete mode 100644 microsoft/knowledge/style/single-space-around-binary-operators.bad.al delete mode 100644 microsoft/knowledge/style/single-space-around-binary-operators.good.al delete mode 100644 microsoft/knowledge/style/single-space-around-binary-operators.md delete mode 100644 microsoft/knowledge/style/this-keyword-in-codeunits.bad.al delete mode 100644 microsoft/knowledge/style/this-keyword-in-codeunits.good.al delete mode 100644 microsoft/knowledge/style/this-keyword-in-codeunits.md delete mode 100644 microsoft/knowledge/style/variable-declaration-order-by-type.bad.al delete mode 100644 microsoft/knowledge/style/variable-declaration-order-by-type.good.al delete mode 100644 microsoft/knowledge/style/variable-declaration-order-by-type.md delete mode 100644 microsoft/knowledge/style/variable-name-must-not-shadow.bad.al delete mode 100644 microsoft/knowledge/style/variable-name-must-not-shadow.good.al delete mode 100644 microsoft/knowledge/style/variable-name-must-not-shadow.md diff --git a/README.md b/README.md index 2118ce0..e9e18d5 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,8 @@ the agent's judgment; it is not an exhaustive BC manual or a substitute for compilation, analyzers, tests, or human review. See [coverage and limits](docs/using-bcquality.md#coverage-and-limits) for the available domains and the difference between a folder review and a comparison. +Mechanical issues already enforced by the AL compiler or standard analyzers are +intentionally left to those deterministic tools rather than duplicated here. Functional areas such as Finance, Supply Chain Management, Manufacturing, Jobs, Warehousing, and Service, and technologies such as PowerShell, pipelines, and diff --git a/docs/contributing.md b/docs/contributing.md index 0e493c2..27da177 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -41,7 +41,9 @@ capable LLM **would get something wrong, or miss something, without it**, not simply because the topic is important. Apply this admission test: > If this file did not exist, would a modern LLM reviewing or generating BC -> code make a mistake this file would have prevented? +> code make a BC-specific mistake that the configured compiler, analyzers, and +> tests would not reliably catch, or would it misinterpret or incorrectly +> remediate one of their diagnostics? Good candidates encode a BC-specific mechanic that models get wrong, a version-dependent behavior, or a misleading interpretation of an analyzer @@ -56,6 +58,15 @@ transactions short" does not earn a separate knowledge file merely by being sound advice. Negative clarifications that prevent false positives are as valuable as rules that catch defects. +Do not add knowledge whose anti-pattern is fully and deterministically detected +by the AL compiler or a standard analyzer. This applies to authoring as well as +review: an authoring agent should compile with the consuming app's actual +ruleset and correct the resulting diagnostics instead of carrying prose copies +of analyzer rules in context. Analyzer-related knowledge belongs here only when +it adds a BC-specific exception, version boundary, cross-object implication, or +remediation constraint that the diagnostic itself cannot establish. Merely +explaining why a deterministic rule exists is not sufficient. + **Skills hold discovery and execution mechanics; knowledge files hold BC facts.** Correct or extend a knowledge article when a BC fact is missing or wrong. Do not hide that fact in a skill's instructions. A genuine routing, diff --git a/docs/using-bcquality.md b/docs/using-bcquality.md index 44e5975..dcaddde 100644 --- a/docs/using-bcquality.md +++ b/docs/using-bcquality.md @@ -196,6 +196,12 @@ removal or another comparison-only regression requires an actual baseline. The corpus is technical AL guidance, not exhaustive functional validation or AppSource certification. +BCQuality intentionally does not duplicate mechanical diagnostics already +enforced by the AL compiler or standard analyzers. Run the consuming app's +normal compiler and analyzer pipeline alongside review and authoring. Knowledge +may still discuss a diagnostic when BC-specific context is needed to avoid a +false positive or choose a correct remediation. + ### Knowledge by domain Each article describes one concern. Where samples exist, use its linked diff --git a/evaluation/README.md b/evaluation/README.md index 7063baf..7be55b4 100644 --- a/evaluation/README.md +++ b/evaluation/README.md @@ -36,7 +36,7 @@ This credential-free check proves every selected leaf maps to a same-named knowl { "id": "case-a1b2c3d4", "findings": [ - { "id": "microsoft/knowledge/appsource/object-affixes-prevent-collisions.md" } + { "id": "microsoft/knowledge/appsource/permission-sets-cover-setup-and-usage-without-super.md" } ] } ] diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index f5c7046..e11508a 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -7,9 +7,6 @@ "agents": { "article": "wire-all-three-agent-interfaces" }, - "appsource": { - "context": "AppSourceCop mandatoryAffixes is configured to ABC." - }, "breaking-changes": { "article": "do-not-expose-sensitive-data-through-public-api" }, diff --git a/microsoft/knowledge/appsource/object-affixes-prevent-collisions.bad.al b/microsoft/knowledge/appsource/object-affixes-prevent-collisions.bad.al deleted file mode 100644 index dc1c6f3..0000000 --- a/microsoft/knowledge/appsource/object-affixes-prevent-collisions.bad.al +++ /dev/null @@ -1,43 +0,0 @@ -// Anti-pattern: an own object with no affix. Another app that also defines a -// "Loyalty Tier" table cannot be installed alongside this one. -table 50379 "Loyalty Tier" -{ - Caption = 'Loyalty Tier'; - DataClassification = CustomerContent; - - fields - { - field(1; "Code"; Code[20]) - { - Caption = 'Code'; - } - field(10; Description; Text[100]) - { - Caption = 'Description'; - } - } - - keys - { - key(PK; "Code") - { - Clustered = true; - } - } -} - -// Anti-pattern (the common half-measure): the extension object carries the -// affix, but the field it adds to the standard Customer table does not. That -// unaffixed field still collides with any other app that adds "Loyalty Points" -// to Customer, and AS0011 flags it. -tableextension 50378 "ABC Customer Ext" extends Customer -{ - fields - { - field(50378; "Loyalty Points"; Integer) - { - Caption = 'Loyalty Points'; - DataClassification = CustomerContent; - } - } -} diff --git a/microsoft/knowledge/appsource/object-affixes-prevent-collisions.good.al b/microsoft/knowledge/appsource/object-affixes-prevent-collisions.good.al deleted file mode 100644 index 28bfa4d..0000000 --- a/microsoft/knowledge/appsource/object-affixes-prevent-collisions.good.al +++ /dev/null @@ -1,40 +0,0 @@ -// Own object: the affix "ABC" is carried at object-name level. -table 50377 "ABC Loyalty Tier" -{ - Caption = 'Loyalty Tier'; - DataClassification = CustomerContent; - - fields - { - field(1; "Code"; Code[20]) - { - Caption = 'Code'; - } - field(10; Description; Text[100]) - { - Caption = 'Description'; - } - } - - keys - { - key(PK; "Code") - { - Clustered = true; - } - } -} - -// Extension of a standard object: the added field is individually affixed, -// because the object name (Customer) belongs to the base application. -tableextension 50376 "ABC Customer Ext" extends Customer -{ - fields - { - field(50376; "Loyalty Points ABC"; Integer) - { - Caption = 'Loyalty Points'; - DataClassification = CustomerContent; - } - } -} diff --git a/microsoft/knowledge/appsource/object-affixes-prevent-collisions.md b/microsoft/knowledge/appsource/object-affixes-prevent-collisions.md deleted file mode 100644 index a53e584..0000000 --- a/microsoft/knowledge/appsource/object-affixes-prevent-collisions.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -bc-version: [all] -domain: appsource -keywords: [object-affix, prefix, suffix, as0011, appsourcecop, collision, tableextension, first-party, isv] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Apply a reserved affix to objects and to members added to base objects - -## Description - -An AppSource extension must prevent name collisions through its registered affix or, on BC23 and later for objects it owns, a namespace with at least two levels. The affix still applies to every field, key, control, or action added to a base-application object; see `two-level-namespace-replaces-object-affix-not-extension-member-affix.md`. Without either mechanism, two apps that both define a `Loyalty Tier` table cannot coexist, and two apps that add an unaffixed `Loyalty Points` field to `Customer` still collide regardless of their namespaces. - -AppSourceCop enforces this. The primary rule is AS0011 ("An affix is required"); the affixes are configured through `mandatoryAffixes` (and `mandatoryPrefix`) in `AppSourceCop.json`. Two placements matter and are easy to get half-right: an object you define carries the affix at **object-name** level, while a member you add to a **standard** object carries the affix on that **member's** name. Adding an affixed object is not enough — an unaffixed field bolted onto `Customer` still collides and still fails validation. - -This rule scopes to Marketplace ISV extensions, which is what AppSourceCop validates. A first-party Microsoft in-box module (publisher `Microsoft`, an object range reserved for first-party use, and no `AppSourceCop.json`/`mandatoryAffixes` in the app) is not built or shipped as an Marketplace extension and is not subject to AS0011, so an unaffixed action or field it adds to a base-application page is not a collision risk to flag. Renaming an existing shipped first-party member to add an affix is itself a breaking change to that module's own history and is not required by this rule. - -## Best Practice - -Own objects use the registered affix (for example `ABC Loyalty Tier`) or, when targeting BC23 or later, a qualifying namespace. Every field or action added to a standard object remains individually affixed (for example `Loyalty Points ABC` on a `Customer` tableextension). - -See sample: [`object-affixes-prevent-collisions.good.al`](object-affixes-prevent-collisions.good.al). - -## Anti Pattern - -An owned object with neither a qualifying namespace nor an affix, an unaffixed extension member, or the common half-measure where the extension object carries the affix but a field it adds to a standard table does not. AS0011 flags the missing collision protection and the field can still collide with another app. - -See sample: [`object-affixes-prevent-collisions.bad.al`](object-affixes-prevent-collisions.bad.al). diff --git a/microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.bad.al b/microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.bad.al deleted file mode 100644 index de2d3ed..0000000 --- a/microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.bad.al +++ /dev/null @@ -1,22 +0,0 @@ -namespace Contoso; - -table 50462 "Rental Agreement" -{ - DataClassification = CustomerContent; - - fields - { - field(1; "No."; Code[20]) { } - } -} - -tableextension 50463 "Rental Customer Ext" extends Customer -{ - fields - { - field(50463; "Loyalty Points"; Integer) - { - DataClassification = CustomerContent; - } - } -} diff --git a/microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.good.al b/microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.good.al deleted file mode 100644 index 93fa9c6..0000000 --- a/microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.good.al +++ /dev/null @@ -1,22 +0,0 @@ -namespace Contoso.Rentals; - -table 50460 "Rental Agreement" -{ - DataClassification = CustomerContent; - - fields - { - field(1; "No."; Code[20]) { } - } -} - -tableextension 50461 "Rental Customer Ext" extends Customer -{ - fields - { - field(50461; "Loyalty Points RNT"; Integer) - { - DataClassification = CustomerContent; - } - } -} diff --git a/microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.md b/microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.md deleted file mode 100644 index fef6d6c..0000000 --- a/microsoft/knowledge/appsource/two-level-namespace-replaces-object-affix-not-extension-member-affix.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -bc-version: [23..] -domain: appsource -keywords: [namespace, two-level, affix, prefix, suffix, as0011, tableextension, pageextension, false-positive] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# A two-level namespace replaces an object affix, not an extension-member affix - -## Description - -Current AppSource naming guidance accepts a namespace with at least two levels, such as `Contoso.Rentals`, instead of a registered prefix or suffix on the names of objects the app owns. The namespace does not qualify members added to another publisher's object: fields, keys, controls, and actions introduced through table or page extensions still share the target object's flat member namespace and still need the registered affix. - -The requirement comes from AppSourceCop rule AS0011, which only runs when the app enables AppSourceCop and configures a mandatory affix — normally an `AppSourceCop.json` next to the app manifest. An app that ships no such configuration is not subject to AS0011, and its extension members are not a compliance gap. This is the usual situation for first-party, in-box apps that ship as part of the product rather than through AppSource: their uniqueness comes from allocated object ID ranges and a controlled source tree, not from a registered affix. Confirm the extending app actually configures a mandatory affix before reporting an unaffixed extension member. - -## Best Practice - -Choose one collision strategy for owned objects: a registered affix or a globally meaningful namespace with at least two levels. Regardless of that choice, apply the registered affix to every member added to a base or third-party object. Keep the affix configured for AppSourceCop so member validation remains deterministic. Do not raise a missing member affix against an app that does not enable AppSourceCop with a mandatory affix; there AS0011 never fires, and the app's namespace is not the reason — the absent configuration is. - -See sample: [`two-level-namespace-replaces-object-affix-not-extension-member-affix.good.al`](two-level-namespace-replaces-object-affix-not-extension-member-affix.good.al). - -## Anti Pattern - -Using `namespace Contoso;` as though one level satisfied the AppSource alternative, or declaring `namespace Contoso.Rentals;` and then adding an unaffixed `Loyalty Points` field to `Customer` in an app that does configure a mandatory affix. The namespace distinguishes the extension's own objects; it cannot disambiguate members on Customer. The mirror-image mistake is reporting an unaffixed extension member in an app that enables no mandatory affix at all — AS0011 does not apply there, and the finding is a false positive. - -See sample: [`two-level-namespace-replaces-object-affix-not-extension-member-affix.bad.al`](two-level-namespace-replaces-object-affix-not-extension-member-affix.bad.al). diff --git a/microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.bad.al b/microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.bad.al deleted file mode 100644 index e2a5152..0000000 --- a/microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.bad.al +++ /dev/null @@ -1,9 +0,0 @@ -// This published object previously used namespace Contoso.Rentals. -namespace Contoso.RentalManagement; - -codeunit 50467 "Rental Agreement Mgt." -{ - procedure CreateAgreement() - begin - end; -} diff --git a/microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.good.al b/microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.good.al deleted file mode 100644 index ea151a8..0000000 --- a/microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.good.al +++ /dev/null @@ -1,8 +0,0 @@ -namespace Contoso.Rentals; - -codeunit 50466 "Rental Agreement Mgt." -{ - procedure CreateAgreement() - begin - end; -} diff --git a/microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.md b/microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.md deleted file mode 100644 index 6c345ee..0000000 --- a/microsoft/knowledge/breaking-changes/namespace-is-part-of-published-object-identity.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [23..] -domain: breaking-changes -keywords: [namespace, published-object, dependency, breaking-change, as0007, compile-time-identity] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Treat a published namespace as part of object identity - -## Description - -AL resolves an object by namespace and name. Once an app ships and dependent extensions compile against that identity, changing the namespace breaks their references even when the object name and ID stay unchanged. AppSourceCop AS0007 rejects changing the namespace of published objects; namespaces are therefore not a cosmetic folder-like label that can be reorganized after release. - -## Best Practice - -Choose a globally meaningful namespace before first publication and keep it stable. Add new functional areas beneath that structure without moving existing published objects. If an identity must move, use the platform's supported move/obsoletion lifecycle rather than a source-only namespace rename. - -See sample: [`namespace-is-part-of-published-object-identity.good.al`](namespace-is-part-of-published-object-identity.good.al). - -## Anti Pattern - -Changing `namespace Contoso.Rentals;` to `namespace Contoso.RentalManagement;` as a cleanup while leaving the object name and ID untouched. Every dependent `using` directive and qualified reference targets the old identity and stops compiling. - -See sample: [`namespace-is-part-of-published-object-identity.bad.al`](namespace-is-part-of-published-object-identity.bad.al). diff --git a/microsoft/knowledge/style/applicationarea-required-on-page-controls.bad.al b/microsoft/knowledge/style/applicationarea-required-on-page-controls.bad.al deleted file mode 100644 index 8da7777..0000000 --- a/microsoft/knowledge/style/applicationarea-required-on-page-controls.bad.al +++ /dev/null @@ -1,25 +0,0 @@ -page 50375 "Sample App Area Bad" -{ - PageType = Card; - SourceTable = Customer; - layout - { - area(Content) - { - group(General) - { - // Anti-pattern: no ApplicationArea. AS0062 flags this control, - // and it is silently hidden in the Web client for profiles whose - // enabled areas do not already cover it. - field("No."; Rec."No.") - { - ToolTip = 'Specifies the number that identifies the customer.'; - } - field(Name; Rec.Name) - { - ToolTip = 'Specifies the customer''s name.'; - } - } - } - } -} diff --git a/microsoft/knowledge/style/applicationarea-required-on-page-controls.good.al b/microsoft/knowledge/style/applicationarea-required-on-page-controls.good.al deleted file mode 100644 index d344337..0000000 --- a/microsoft/knowledge/style/applicationarea-required-on-page-controls.good.al +++ /dev/null @@ -1,40 +0,0 @@ -page 50374 "Sample App Area Good" -{ - PageType = Card; - SourceTable = Customer; - layout - { - area(Content) - { - group(General) - { - field("No."; Rec."No.") - { - ApplicationArea = All; - ToolTip = 'Specifies the number that identifies the customer.'; - } - field(Name; Rec.Name) - { - ApplicationArea = All; - ToolTip = 'Specifies the customer''s name.'; - } - } - } - } - actions - { - area(Processing) - { - action(Refresh) - { - ApplicationArea = All; - ToolTip = 'Reloads the current record.'; - - trigger OnAction() - begin - CurrPage.Update(false); - end; - } - } - } -} diff --git a/microsoft/knowledge/style/applicationarea-required-on-page-controls.md b/microsoft/knowledge/style/applicationarea-required-on-page-controls.md deleted file mode 100644 index 3766dda..0000000 --- a/microsoft/knowledge/style/applicationarea-required-on-page-controls.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [application-area, page-control, as0062, appsourcecop, hidden-control, web-client] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Every page control needs an `ApplicationArea` (AppSourceCop AS0062) - -## Description - -A field control on a page or pageextension that has no `ApplicationArea` property is silently hidden in the Web client for every profile whose enabled application areas do not cover it. There is no error and no warning at runtime — the field simply does not appear, which reads as data loss to the user. AppSourceCop AS0062 flags any page control or action that is missing the `ApplicationArea` property, and AppSource technical validation rejects the app until it is set. - -Set the property to an area the app actually enables. `All` makes the control visible under every profile and is the common default; if the app declares narrower areas in `app.json`, use one of those. The property applies to field controls and to actions. This is a sibling concern to `caption-required-on-page-fields.md` and `tooltip-required-on-page-fields.md`; note that the ToolTip requirement is the separate CodeCop rule AA0218, not AS0062. - -## Best Practice - -Every field control and action carries `ApplicationArea = All;` (or a declared area of the app). The value is set once per control and keeps the control visible in the Web client. - -See sample: [`applicationarea-required-on-page-controls.good.al`](applicationarea-required-on-page-controls.good.al). - -## Anti Pattern - -A field control with no `ApplicationArea`. AS0062 flags it, and the control is invisible in the Web client for any profile that does not already enable a matching area. - -See sample: [`applicationarea-required-on-page-controls.bad.al`](applicationarea-required-on-page-controls.bad.al). diff --git a/microsoft/knowledge/style/begin-on-same-line-as-then-else-do.bad.al b/microsoft/knowledge/style/begin-on-same-line-as-then-else-do.bad.al deleted file mode 100644 index fd3ac45..0000000 --- a/microsoft/knowledge/style/begin-on-same-line-as-then-else-do.bad.al +++ /dev/null @@ -1,14 +0,0 @@ -codeunit 50235 "Sample Begin Own Line Bad" -{ - procedure Run(Condition: Boolean) - begin - if Condition then - begin - DoSomething(); - DoSomethingElse(); - end; - end; - - local procedure DoSomething() begin end; - local procedure DoSomethingElse() begin end; -} diff --git a/microsoft/knowledge/style/begin-on-same-line-as-then-else-do.good.al b/microsoft/knowledge/style/begin-on-same-line-as-then-else-do.good.al deleted file mode 100644 index 6043c5b..0000000 --- a/microsoft/knowledge/style/begin-on-same-line-as-then-else-do.good.al +++ /dev/null @@ -1,24 +0,0 @@ -codeunit 50234 "Sample Begin Same Line Good" -{ - procedure Run(Condition: Boolean) - var - i: Integer; - begin - if Condition then begin - DoSomething(); - DoSomethingElse(); - end else begin - Reset(); - Notify(); - end; - for i := 1 to 10 do begin - DoSomething(); - DoSomethingElse(); - end; - end; - - local procedure DoSomething() begin end; - local procedure DoSomethingElse() begin end; - local procedure Reset() begin end; - local procedure Notify() begin end; -} diff --git a/microsoft/knowledge/style/begin-on-same-line-as-then-else-do.md b/microsoft/knowledge/style/begin-on-same-line-as-then-else-do.md deleted file mode 100644 index de30708..0000000 --- a/microsoft/knowledge/style/begin-on-same-line-as-then-else-do.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [begin, end, compound-statement, aa0005, codecop, formatting] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# `begin` goes on the same line as `then`, `else`, or `do` (CodeCop AA0005) - -## Description - -When a compound block follows `then`, `else`, or `do`, the `begin` keyword must sit on the same line as the preceding keyword, separated by exactly one space. `if Condition then begin` and `for i := 1 to N do begin` are correct. The form that puts `begin` on its own line — common in older AL and in languages like Pascal — is flagged by CodeCop AA0005. The rule does not change indentation of the block body; it only governs the placement of `begin` relative to `then`/`else`/`do`. - -## Best Practice - -`if Condition then begin … end;`, `else begin … end;`, `for i := 1 to N do begin … end;`. The block body is indented one level below the `if`/`for` line, and `end;` sits at the same indentation as the line that opened the block. - -See sample: [`begin-on-same-line-as-then-else-do.good.al`](begin-on-same-line-as-then-else-do.good.al). - -## Anti Pattern - -A line that ends with `then` (or `else`, or `do`) and is followed by a line whose only content is `begin`. The compiler accepts it but CodeCop AA0005 flags it; the visual cost is a wasted line per block and a layout that looks alien to readers used to current AL style. - -See sample: [`begin-on-same-line-as-then-else-do.bad.al`](begin-on-same-line-as-then-else-do.bad.al). diff --git a/microsoft/knowledge/style/block-keywords-start-new-line.bad.al b/microsoft/knowledge/style/block-keywords-start-new-line.bad.al deleted file mode 100644 index ef7f937..0000000 --- a/microsoft/knowledge/style/block-keywords-start-new-line.bad.al +++ /dev/null @@ -1,15 +0,0 @@ -codeunit 50239 "Sample Block Kw Bad" -{ - procedure Dispatch(IsContactName: Boolean; IsSalespersonCode: Boolean) - var - i: Integer; - begin - if IsContactName then ValidateContactName() else if IsSalespersonCode then ValidateSalespersonCode(); - for i := 1 to 10 do begin DoSomething(i); DoSomethingElse(i); end; - end; - - local procedure ValidateContactName() begin end; - local procedure ValidateSalespersonCode() begin end; - local procedure DoSomething(I: Integer) begin end; - local procedure DoSomethingElse(I: Integer) begin end; -} diff --git a/microsoft/knowledge/style/block-keywords-start-new-line.good.al b/microsoft/knowledge/style/block-keywords-start-new-line.good.al deleted file mode 100644 index eb6c3d4..0000000 --- a/microsoft/knowledge/style/block-keywords-start-new-line.good.al +++ /dev/null @@ -1,23 +0,0 @@ -codeunit 50238 "Sample Block Kw Good" -{ - procedure Dispatch(IsContactName: Boolean; IsSalespersonCode: Boolean) - var - i: Integer; - begin - if IsContactName then - ValidateContactName() - else - if IsSalespersonCode then - ValidateSalespersonCode(); - - for i := 1 to 10 do begin - DoSomething(i); - DoSomethingElse(i); - end; - end; - - local procedure ValidateContactName() begin end; - local procedure ValidateSalespersonCode() begin end; - local procedure DoSomething(I: Integer) begin end; - local procedure DoSomethingElse(I: Integer) begin end; -} diff --git a/microsoft/knowledge/style/block-keywords-start-new-line.md b/microsoft/knowledge/style/block-keywords-start-new-line.md deleted file mode 100644 index 8161a08..0000000 --- a/microsoft/knowledge/style/block-keywords-start-new-line.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [block-keyword, end, if, repeat, until, for, while, case, aa0018] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Block keywords (`end`, `if`, `repeat`, `until`, `for`, `while`, `case`) start a new line (CodeCop AA0018) - -## Description - -CodeCop AA0018 requires that the block-introducing keywords `if`, `repeat`, `until`, `for`, `while`, `case`, and the block-terminating keyword `end` always start a new line. Multiple statements packed onto one line — `if A then X() else if B then Y();` written inline, or `for i := 1 to 10 do begin X(i); Y(i); end;` — defeat code review tooling that operates line-by-line and obscure the control flow. The rule does not prohibit short single-statement constructs spread across two lines (`if Cond then X();`); it prohibits packing the entire control structure onto one line. - -## Best Practice - -Each `if`, `else if`, `repeat`, `for`, `while`, and `case` starts a line. Each `end;` (the closing of a `begin … end` block or a `case`) starts a line. Branch bodies are on their own line, indented. - -See sample: [`block-keywords-start-new-line.good.al`](block-keywords-start-new-line.good.al). - -## Anti Pattern - -`if IsContactName then ValidateContactName() else if IsSalespersonCode then ValidateSalespersonCode();` collapses an `if/else if` chain onto a single line; AA0018 flags both the `else` and the second `if`. The same applies to `for i := 1 to 10 do begin DoX(i); DoY(i); end;` — `end` is not at the start of its line. - -See sample: [`block-keywords-start-new-line.bad.al`](block-keywords-start-new-line.bad.al). diff --git a/microsoft/knowledge/style/event-subscriber-param-names-match-publisher.md b/microsoft/knowledge/style/event-subscriber-param-names-match-publisher.md deleted file mode 100644 index e408ebb..0000000 --- a/microsoft/knowledge/style/event-subscriber-param-names-match-publisher.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [event-subscriber, parameter-name, publisher, signature, eventsubscriber, false-positive] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Event subscriber parameter names must match the publisher signature - -## Description - -In AL, an `[EventSubscriber]` procedure is bound to its publisher by event name and parameter list. For every parameter the subscriber declares, the name is not a style choice — it must match the name the publisher declared. The compiler validates the match at build time and emits an error if the subscriber renames a parameter. This means a reviewer cannot apply a generic "use better names" pass to subscriber parameters: `Sender`, `Rec`, `xRec`, `RunTrigger`, the table-and-field-specific parameter names a publisher emits — all are dictated by the publisher and must be reproduced verbatim. - -A subscriber may, however, declare fewer parameters than the publisher. AL binds each subscriber parameter to the publisher parameter of the same name, so the subscriber can omit any parameters its handler does not use, from any position, and can even declare the ones it keeps in a different order than the publisher. This compiles and binds correctly, so a shorter or differently ordered subscriber signature is not a signature mismatch. In shipping BCApps code, `Test Runner - Mgt::OnBeforeTestMethodRun` publishes `CurrentTestMethodLine, CodeunitID, CodeunitName, FunctionName, FunctionTestPermissions, Skip`, and subscribers such as `ALTestRunnerResetEnvironment` bind to it while omitting `Skip` and declaring `CurrentTestMethodLine` last. - -## Best Practice - -Copy each parameter's name and type from the publisher verbatim for every parameter the subscriber keeps, and omit the ones the handler does not use. When in doubt, navigate to the publisher (`OnAfterValidateEvent`, `OnBeforePostSalesDoc`, etc.) and copy its parameter list. Style rules that apply to other locals — descriptive names, no spaces — do not apply to subscriber parameters. Do not flag a subscriber for declaring fewer parameters than the publisher, for omitting one from the middle of the list, or for declaring them in a different order, as long as every parameter it does declare matches a publisher parameter by name and type: that is valid AL, not a mismatch. - -## Anti Pattern - -Renaming a publisher parameter to look prettier in the subscriber. The build breaks immediately, because the name is what the runtime binds on. More insidiously, a parameter name that happens to match by coincidence in one event publisher but not in a similar one will compile in some versions of BC and fail in others when the publisher signature evolves. - -Detection: a subscriber parameter whose name or type does not correspond to any parameter on the publisher — not a subscriber that merely declares fewer parameters, drops one from the middle, or lists them in a different order. diff --git a/microsoft/knowledge/style/function-call-parentheses-required.bad.al b/microsoft/knowledge/style/function-call-parentheses-required.bad.al deleted file mode 100644 index 2677716..0000000 --- a/microsoft/knowledge/style/function-call-parentheses-required.bad.al +++ /dev/null @@ -1,11 +0,0 @@ -codeunit 50213 "Sample Parens Bad" -{ - procedure Run() - var - Customer: Record Customer; - begin - Customer.Init; - if Customer.FindFirst then - Customer.Modify; - end; -} diff --git a/microsoft/knowledge/style/function-call-parentheses-required.good.al b/microsoft/knowledge/style/function-call-parentheses-required.good.al deleted file mode 100644 index 53f6f85..0000000 --- a/microsoft/knowledge/style/function-call-parentheses-required.good.al +++ /dev/null @@ -1,11 +0,0 @@ -codeunit 50212 "Sample Parens Good" -{ - procedure Run() - var - Customer: Record Customer; - begin - Customer.Init(); - if Customer.FindFirst() then - Customer.Modify(); - end; -} diff --git a/microsoft/knowledge/style/function-call-parentheses-required.md b/microsoft/knowledge/style/function-call-parentheses-required.md deleted file mode 100644 index f24985a..0000000 --- a/microsoft/knowledge/style/function-call-parentheses-required.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [parentheses, function-call, method-call, aa0008, codecop] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Always write parentheses on procedure calls (CodeCop AA0008) - -## Description - -AL allows a parameterless procedure to be called without parentheses — `Customer.Init` instead of `Customer.Init()` — and the result is syntactically identical at runtime. CodeCop AA0008 still flags the parenthesis-less form. The reason is twofold: written without parentheses, a procedure call is visually indistinguishable from a property read, which makes BC code harder to scan; and the same identifier may exist as both a property and a procedure on different objects, so the parentheses are the only local signal that this is a call. The rule applies to every parameterless invocation, including `Init`, `Insert`, `Modify`, `Delete`, `DeleteAll`, `FindFirst`, `FindSet`, `Next`, `Get`, `CalcFields`, and user-defined procedures. - -## Best Practice - -Always write `()` on a procedure call, even when it takes no arguments: `Customer.Init();`, `TempBuffer.DeleteAll();`, `if Customer.FindFirst() then …`. The same applies inside expressions and as a condition. - -See sample: [`function-call-parentheses-required.good.al`](function-call-parentheses-required.good.al). - -## Anti Pattern - -`Customer.Init;`, `TempBuffer.DeleteAll;`, `if Customer.FindFirst then …`. Every one of those is an AA0008 violation. Reviewers should treat a parameterless procedure name appearing without parentheses as a defect, even though the compiler accepts it. - -See sample: [`function-call-parentheses-required.bad.al`](function-call-parentheses-required.bad.al). diff --git a/microsoft/knowledge/style/label-suffix-approved-list.bad.al b/microsoft/knowledge/style/label-suffix-approved-list.bad.al deleted file mode 100644 index 6b227de..0000000 --- a/microsoft/knowledge/style/label-suffix-approved-list.bad.al +++ /dev/null @@ -1,14 +0,0 @@ -codeunit 50201 "Sample Label Suffix Bad" -{ - var - CannotDeleteLine: Label 'Cannot delete this line.'; - Text000: Label 'Update complete'; - UpdateLocation: Label 'Update location?'; - WrongSuffixTok: Label 'Customer %1 not found.'; - - procedure ShowMessages() - begin - Error(WrongSuffixTok, '10000'); - Message(Text000); - end; -} diff --git a/microsoft/knowledge/style/label-suffix-approved-list.good.al b/microsoft/knowledge/style/label-suffix-approved-list.good.al deleted file mode 100644 index f3ec561..0000000 --- a/microsoft/knowledge/style/label-suffix-approved-list.good.al +++ /dev/null @@ -1,15 +0,0 @@ -codeunit 50200 "Sample Label Suffix Good" -{ - var - UpdateCompleteMsg: Label 'Update complete.'; - CustomerNotFoundErr: Label 'Customer %1 does not exist.'; - DeleteRecordQst: Label 'Delete this record?'; - CustomerNameLbl: Label 'Customer Name'; - GetMethodTok: Label 'GET', Locked = true; - TelemetryStartedTxt: Label 'Operation started for customer %1.', Locked = true; - - procedure ShowMessage() - begin - Message(UpdateCompleteMsg); - end; -} diff --git a/microsoft/knowledge/style/label-suffix-approved-list.md b/microsoft/knowledge/style/label-suffix-approved-list.md deleted file mode 100644 index 2bda119..0000000 --- a/microsoft/knowledge/style/label-suffix-approved-list.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [label, textconst, suffix, aa0074, codecop, msg, err, qst, lbl, tok] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Use approved suffixes on Label and TextConst names (CodeCop AA0074) - -## Description - -CodeCop AA0074 flags `Label` and `TextConst` identifiers that do not end with an approved usage suffix. The suffix signals at the call site how the text is consumed and what translation behaviour it should get. The approved suffixes and their intended usage are: `Msg` for text shown via `Message()`; `Err` for text passed to `Error()`; `Qst` for text used with `Confirm` or `StrMenu`; `Lbl` for captions and tooltips; `Tok` for short tokens such as `'GET'`, `'PUT'`, `'HTTPS'`, GUIDs, or JSON/XML snippets that are not translated (typically with `Locked = true`); and `Txt` for general text including telemetry messages. A `Label` named `Text000` or `CannotDeleteLine` without a suffix violates the rule, regardless of how readable the prose is. - -## Best Practice - -Pick the suffix that matches the call where the label is consumed: `UpdateCompleteMsg` for `Message(...)`, `CustomerNotFoundErr` for `Error(...)`, `DeleteRecordQst` for `Confirm(...)`, `CustomerNameLbl` for tooltips and captions, `GetMethodTok` for locked tokens, `TelemetryDataTxt` for telemetry payloads. Suffix choices between `Tok`, `Lbl`, `Txt`, and `Msg` are judgment calls when the suffix is valid for the usage — what matters is that the suffix is on the approved list and matches the actual call. - -See sample: [`label-suffix-approved-list.good.al`](label-suffix-approved-list.good.al). - -## Anti Pattern - -A `Label` declared with no suffix (`CannotDeleteLine: Label '…';`), a generic name (`Text000: Label '…';`), or a suffix that contradicts the usage (`WrongSuffixTok: Label 'Customer %1 not found.'` then passed to `Error()`). All three trip AA0074 or its reviewers and obscure the call-site contract. - -See sample: [`label-suffix-approved-list.bad.al`](label-suffix-approved-list.bad.al). diff --git a/microsoft/knowledge/style/lowercase-reserved-keywords.bad.al b/microsoft/knowledge/style/lowercase-reserved-keywords.bad.al deleted file mode 100644 index 83d5994..0000000 --- a/microsoft/knowledge/style/lowercase-reserved-keywords.bad.al +++ /dev/null @@ -1,14 +0,0 @@ -codeunit 50245 "Sample Upper Keywords Bad" -{ - procedure Walk(VAR Customer: Record Customer) - VAR - Found: Boolean; - BEGIN - IF Customer.FindSet() THEN - REPEAT - Found := TRUE; - UNTIL Customer.Next() = 0; - IF Found THEN - EXIT; - END; -} diff --git a/microsoft/knowledge/style/lowercase-reserved-keywords.good.al b/microsoft/knowledge/style/lowercase-reserved-keywords.good.al deleted file mode 100644 index 25fb20e..0000000 --- a/microsoft/knowledge/style/lowercase-reserved-keywords.good.al +++ /dev/null @@ -1,14 +0,0 @@ -codeunit 50244 "Sample Lower Keywords Good" -{ - procedure Walk(var Customer: Record Customer) - var - Found: Boolean; - begin - if Customer.FindSet() then - repeat - Found := true; - until Customer.Next() = 0; - if Found then - exit; - end; -} diff --git a/microsoft/knowledge/style/lowercase-reserved-keywords.md b/microsoft/knowledge/style/lowercase-reserved-keywords.md deleted file mode 100644 index 7215491..0000000 --- a/microsoft/knowledge/style/lowercase-reserved-keywords.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [reserved-keyword, lowercase, aa0241, codecop, if, then, begin] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Reserved keywords are written in lowercase (CodeCop AA0241) - -## Description - -CodeCop AA0241 requires reserved AL keywords — `if`, `then`, `else`, `begin`, `end`, `var`, `procedure`, `local`, `internal`, `for`, `while`, `repeat`, `until`, `case`, `of`, `do`, `not`, `and`, `or`, `exit`, `break`, `skip`, `quit`, and the rest — to be lowercase. Old Navision and C/AL code used `IF…THEN…BEGIN…END` in uppercase, and that style still lingers in training data and legacy modules. New AL code is lowercase. The rule applies to keywords only — type names (`Record`, `Codeunit`, `Integer`), property names (`Caption`, `ToolTip`), and identifiers are unaffected. - -Test codeunits that retain legacy uppercase forms (`OPENEDIT`, `ASSERTERROR`, `VALUE`) are an accepted exception: the test framework historically uses those identifiers and rewriting them brings no benefit. The rule applies to new code in modified lines, not to long-standing test patterns. - -## Best Practice - -Write keywords lowercase: `if Condition then begin … end;`, `repeat … until Found;`, `for i := 1 to N do …`. The standard AL formatter normalizes casing automatically. - -See sample: [`lowercase-reserved-keywords.good.al`](lowercase-reserved-keywords.good.al). - -## Anti Pattern - -`IF Condition THEN BEGIN DoSomething(); END;`, `REPEAT GetNext(); UNTIL Found;`. Uppercase keywords trip AA0241 and signal C/AL-era code that has not been modernized. - -See sample: [`lowercase-reserved-keywords.bad.al`](lowercase-reserved-keywords.bad.al). diff --git a/microsoft/knowledge/style/no-begin-end-around-single-statement.bad.al b/microsoft/knowledge/style/no-begin-end-around-single-statement.bad.al deleted file mode 100644 index 1803e1c..0000000 --- a/microsoft/knowledge/style/no-begin-end-around-single-statement.bad.al +++ /dev/null @@ -1,11 +0,0 @@ -codeunit 50237 "Sample Single Stmt Bad" -{ - procedure Validate(IsAssemblyOutputLine: Boolean) - var - SalesLine: Record "Sales Line"; - begin - if IsAssemblyOutputLine then begin - SalesLine.TestField("Order Line No.", 0); - end; - end; -} diff --git a/microsoft/knowledge/style/no-begin-end-around-single-statement.good.al b/microsoft/knowledge/style/no-begin-end-around-single-statement.good.al deleted file mode 100644 index 684a86c..0000000 --- a/microsoft/knowledge/style/no-begin-end-around-single-statement.good.al +++ /dev/null @@ -1,10 +0,0 @@ -codeunit 50236 "Sample Single Stmt Good" -{ - procedure Validate(IsAssemblyOutputLine: Boolean) - var - SalesLine: Record "Sales Line"; - begin - if IsAssemblyOutputLine then - SalesLine.TestField("Order Line No.", 0); - end; -} diff --git a/microsoft/knowledge/style/no-begin-end-around-single-statement.md b/microsoft/knowledge/style/no-begin-end-around-single-statement.md deleted file mode 100644 index 3c1cf9f..0000000 --- a/microsoft/knowledge/style/no-begin-end-around-single-statement.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [begin, end, single-statement, aa0013, codecop, compound] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Do not wrap a single statement in `begin … end` (CodeCop AA0013) - -## Description - -CodeCop AA0013 flags `begin … end` blocks that contain exactly one statement. The compound-block syntax exists to group multiple statements as a unit; using it for a single statement adds two lines and a level of nesting without adding meaning. `if IsAssemblyOutputLine then begin TestField("Order Line No.", 0); end;` should be `if IsAssemblyOutputLine then TestField("Order Line No.", 0);` — one statement, no block. The same logic applies after `else`, `for`, `while`, and `repeat`. - -## Best Practice - -A single statement following `then`, `else`, `do`, or a case label is written on its own line, indented one level, with no `begin … end`. Use `begin … end` only when there are two or more statements to group. - -See sample: [`no-begin-end-around-single-statement.good.al`](no-begin-end-around-single-statement.good.al). - -## Anti Pattern - -`if Cond then begin OneCall(); end;` — single statement wrapped in a block. AA0013 flags it. The reviewer signal is "a `begin` followed by exactly one statement before its `end`." - -See sample: [`no-begin-end-around-single-statement.bad.al`](no-begin-end-around-single-statement.bad.al). diff --git a/microsoft/knowledge/style/no-space-before-method-parenthesis.bad.al b/microsoft/knowledge/style/no-space-before-method-parenthesis.bad.al deleted file mode 100644 index b2f8295..0000000 --- a/microsoft/knowledge/style/no-space-before-method-parenthesis.bad.al +++ /dev/null @@ -1,11 +0,0 @@ -codeunit 50231 "Sample No Space Paren Bad" -{ - procedure Lookup(CustomerNo: Code[20]) - var - Customer: Record Customer; - GreetingMsg: Label 'Hello %1'; - begin - if Customer.Get ( CustomerNo ) then - Message ( GreetingMsg, Customer.Name ); - end; -} diff --git a/microsoft/knowledge/style/no-space-before-method-parenthesis.good.al b/microsoft/knowledge/style/no-space-before-method-parenthesis.good.al deleted file mode 100644 index eb16dc3..0000000 --- a/microsoft/knowledge/style/no-space-before-method-parenthesis.good.al +++ /dev/null @@ -1,11 +0,0 @@ -codeunit 50230 "Sample No Space Paren Good" -{ - procedure Lookup(CustomerNo: Code[20]) - var - Customer: Record Customer; - GreetingMsg: Label 'Hello %1'; - begin - if Customer.Get(CustomerNo) then - Message(GreetingMsg, Customer.Name); - end; -} diff --git a/microsoft/knowledge/style/no-space-before-method-parenthesis.md b/microsoft/knowledge/style/no-space-before-method-parenthesis.md deleted file mode 100644 index 9c5ffea..0000000 --- a/microsoft/knowledge/style/no-space-before-method-parenthesis.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [spacing, parenthesis, method-call, aa0002, codecop] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# No space between a method name and its opening parenthesis (CodeCop AA0002) - -## Description - -CodeCop AA0002 forbids whitespace between a procedure/method name and its `(`. `Customer.Get(CustomerNo)` is correct; `Customer.Get (CustomerNo)` is not. The rule applies to user-defined procedures, system methods (`Insert`, `FindFirst`, `CalcFields`), trigger-style invocations, and the parenthesised cast/conversion forms (`Format(Value)`, `CopyStr(Source, 1, 10)`). The whitespace between `(` and the first argument, and between the last argument and `)`, is also forbidden by the same rule. - -## Best Practice - -`Customer.Get(CustomerNo)`, `Customer.SetFilter("No.", '%1', '*A*')`, `Message(GreetingMsg, UserName)`. The standard AL formatter enforces this automatically. - -See sample: [`no-space-before-method-parenthesis.good.al`](no-space-before-method-parenthesis.good.al). - -## Anti Pattern - -`Customer.Get ( CustomerNo )`, `Message ( GreetingMsg, UserName )`. Both trip AA0002 and read as if the call had an extra unnamed parameter — a small but persistent friction every reader pays. - -See sample: [`no-space-before-method-parenthesis.bad.al`](no-space-before-method-parenthesis.bad.al). diff --git a/microsoft/knowledge/style/optioncaption-required-and-matches-membercount.bad.al b/microsoft/knowledge/style/optioncaption-required-and-matches-membercount.bad.al deleted file mode 100644 index 9d5269c..0000000 --- a/microsoft/knowledge/style/optioncaption-required-and-matches-membercount.bad.al +++ /dev/null @@ -1,17 +0,0 @@ -table 50255 "Sample OptionCaption Bad" -{ - fields - { - field(1; Status; Option) - { - Caption = 'Status'; - OptionMembers = Open,Released,Pending; - } - field(2; Priority; Option) - { - Caption = 'Priority'; - OptionMembers = Low,Medium,High,Critical; - OptionCaption = 'Low,Medium,High'; - } - } -} diff --git a/microsoft/knowledge/style/optioncaption-required-and-matches-membercount.good.al b/microsoft/knowledge/style/optioncaption-required-and-matches-membercount.good.al deleted file mode 100644 index d0e9866..0000000 --- a/microsoft/knowledge/style/optioncaption-required-and-matches-membercount.good.al +++ /dev/null @@ -1,18 +0,0 @@ -table 50254 "Sample OptionCaption Good" -{ - fields - { - field(1; Status; Option) - { - Caption = 'Status'; - OptionMembers = Open,Released,Pending; - OptionCaption = 'Open,Released,Pending'; - } - field(2; Priority; Option) - { - Caption = 'Priority'; - OptionMembers = Low,Medium,High,Critical; - OptionCaption = 'Low,Medium,High,Critical'; - } - } -} diff --git a/microsoft/knowledge/style/optioncaption-required-and-matches-membercount.md b/microsoft/knowledge/style/optioncaption-required-and-matches-membercount.md deleted file mode 100644 index e90fb16..0000000 --- a/microsoft/knowledge/style/optioncaption-required-and-matches-membercount.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [optioncaption, option, member-count, aa0221, aa0223, aa0224] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Option fields need `OptionCaption`, and its element count must match `OptionMembers` (CodeCop AA0221/AA0223/AA0224) - -## Description - -CodeCop AA0221 requires an `OptionCaption` on every option-type field that is not sourced from a table column (table-sourced option fields inherit the captions of the underlying field). AA0223 and AA0224 add two integrity checks: the number of comma-separated entries in `OptionCaption` must equal the number of entries in `OptionMembers`, and each caption must align by position with its member. The position alignment is what the platform uses to translate option values — the `OptionMembers` list never changes per locale, the `OptionCaption` list does. A mismatch in count or order produces silent corruption: the option `Released` shows the caption that belongs to `Pending`, and the bug is locale-dependent. - -## Best Practice - -`OptionMembers = Open,Released,Pending;` and `OptionCaption = 'Open,Released,Pending';` — same count, same order. When adding a new member, update both lines in the same commit. - -See sample: [`optioncaption-required-and-matches-membercount.good.al`](optioncaption-required-and-matches-membercount.good.al). - -## Anti Pattern - -`OptionMembers = Open,Released,Pending;` with no `OptionCaption` at all (the user sees the raw English members and translation is impossible), or `OptionMembers = Low,Medium,High,Critical;` paired with `OptionCaption = 'Low,Medium,High';` — count mismatch, `Critical` displays as blank or carries the wrong caption depending on platform version. - -See sample: [`optioncaption-required-and-matches-membercount.bad.al`](optioncaption-required-and-matches-membercount.bad.al). diff --git a/microsoft/knowledge/style/single-space-after-not-operator.bad.al b/microsoft/knowledge/style/single-space-after-not-operator.bad.al deleted file mode 100644 index c7143e7..0000000 --- a/microsoft/knowledge/style/single-space-after-not-operator.bad.al +++ /dev/null @@ -1,11 +0,0 @@ -codeunit 50233 "Sample Not Spacing Bad" -{ - procedure Check(): Boolean - var - Customer: Record Customer; - begin - if NOT Customer.IsEmpty() then - exit(true); - exit(false); - end; -} diff --git a/microsoft/knowledge/style/single-space-after-not-operator.good.al b/microsoft/knowledge/style/single-space-after-not-operator.good.al deleted file mode 100644 index 92d8f33..0000000 --- a/microsoft/knowledge/style/single-space-after-not-operator.good.al +++ /dev/null @@ -1,11 +0,0 @@ -codeunit 50232 "Sample Not Spacing Good" -{ - procedure Check(): Boolean - var - Customer: Record Customer; - begin - if not Customer.IsEmpty() then - exit(true); - exit(false); - end; -} diff --git a/microsoft/knowledge/style/single-space-after-not-operator.md b/microsoft/knowledge/style/single-space-after-not-operator.md deleted file mode 100644 index 41e65fe..0000000 --- a/microsoft/knowledge/style/single-space-after-not-operator.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [spacing, not, operator, aa0003, codecop] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Exactly one space between `not` and its argument (CodeCop AA0003) - -## Description - -CodeCop AA0003 requires exactly one space between the `not` operator and the expression it negates. `if not Customer.FindFirst() then …` is correct; `if not Customer.FindFirst() then …` (two spaces) and `if notCustomer.FindFirst() then …` (zero — which fails parsing anyway) are not. The rule is also the place where uppercase `NOT` is flagged in combination with CodeCop AA0241 (reserved keywords must be lowercase): `if NOT Condition then` is doubly wrong. - -## Best Practice - -`if not Condition then`, `if not Customer.IsEmpty() then`, `exit(not Result)`. One space, lowercase keyword, no parentheses around the bare boolean. - -See sample: [`single-space-after-not-operator.good.al`](single-space-after-not-operator.good.al). - -## Anti Pattern - -`if NOT condition then`, `if not condition then`, `if !condition then` (which is not even AL — `!` is not a negation operator in AL). All three either trip AA0003 / AA0241 or fail to compile. - -See sample: [`single-space-after-not-operator.bad.al`](single-space-after-not-operator.bad.al). diff --git a/microsoft/knowledge/style/single-space-around-binary-operators.bad.al b/microsoft/knowledge/style/single-space-around-binary-operators.bad.al deleted file mode 100644 index 2515d33..0000000 --- a/microsoft/knowledge/style/single-space-around-binary-operators.bad.al +++ /dev/null @@ -1,12 +0,0 @@ -codeunit 50229 "Sample Spaces Op Bad" -{ - procedure Compute(Amount: Decimal; Quantity: Decimal): Decimal - var - Price: Decimal; - begin - Price:=Amount*Quantity; - if (Amount>0)and(Quantity>0) then - exit(Price); - exit(0); - end; -} diff --git a/microsoft/knowledge/style/single-space-around-binary-operators.good.al b/microsoft/knowledge/style/single-space-around-binary-operators.good.al deleted file mode 100644 index 55793d3..0000000 --- a/microsoft/knowledge/style/single-space-around-binary-operators.good.al +++ /dev/null @@ -1,12 +0,0 @@ -codeunit 50228 "Sample Spaces Op Good" -{ - procedure Compute(Amount: Decimal; Quantity: Decimal): Decimal - var - Price: Decimal; - begin - Price := Amount * Quantity; - if (Amount > 0) and (Quantity > 0) then - exit(Price); - exit(0); - end; -} diff --git a/microsoft/knowledge/style/single-space-around-binary-operators.md b/microsoft/knowledge/style/single-space-around-binary-operators.md deleted file mode 100644 index 1ad0184..0000000 --- a/microsoft/knowledge/style/single-space-around-binary-operators.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [spacing, binary-operator, aa0001, codecop, formatting] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# One space on each side of every binary operator (CodeCop AA0001) - -## Description - -CodeCop AA0001 requires exactly one space on each side of every binary operator: assignment (`:=`), arithmetic (`+`, `-`, `*`, `/`, `mod`, `div`), comparison (`=`, `<>`, `<`, `<=`, `>`, `>=`), logical (`and`, `or`, `xor`), and string concatenation. `x:=1+2`, `Price:=Amount*Quantity`, `if a=b then`, and `if a and b then` all violate the rule. The rule applies to the binary use of `-` (subtraction); the unary minus (`-Profit`) takes no leading space. - -## Best Practice - -Write `x := 1 + 2`, `Price := Amount * Quantity`, `if a = b then`, `if a and b then`. The standard AL formatter inserts these spaces automatically; running `Alt+Shift+F` (Format Document) in the AL extension is the simplest way to bring an entire file into compliance. - -See sample: [`single-space-around-binary-operators.good.al`](single-space-around-binary-operators.good.al). - -## Anti Pattern - -`x:=1+2;`, `Price:=Amount*Quantity;`, `if a=b then`, `if a and b then`. All trip AA0001. - -See sample: [`single-space-around-binary-operators.bad.al`](single-space-around-binary-operators.bad.al). diff --git a/microsoft/knowledge/style/this-keyword-in-codeunits.bad.al b/microsoft/knowledge/style/this-keyword-in-codeunits.bad.al deleted file mode 100644 index 7fd03a1..0000000 --- a/microsoft/knowledge/style/this-keyword-in-codeunits.bad.al +++ /dev/null @@ -1,14 +0,0 @@ -codeunit 50215 "Sample This Bad" -{ - procedure ProcessRecord(Customer: Record Customer) - var - Helper: Codeunit "Sample This Helper"; - begin - ValidateCustomer(Customer); - Helper.DoWork(); - end; - - local procedure ValidateCustomer(Customer: Record Customer) - begin - end; -} diff --git a/microsoft/knowledge/style/this-keyword-in-codeunits.good.al b/microsoft/knowledge/style/this-keyword-in-codeunits.good.al deleted file mode 100644 index 392c042..0000000 --- a/microsoft/knowledge/style/this-keyword-in-codeunits.good.al +++ /dev/null @@ -1,14 +0,0 @@ -codeunit 50214 "Sample This Good" -{ - procedure ProcessRecord(Customer: Record Customer) - var - Helper: Codeunit "Sample This Helper"; - begin - this.ValidateCustomer(Customer); - Helper.DoWork(this); - end; - - local procedure ValidateCustomer(Customer: Record Customer) - begin - end; -} diff --git a/microsoft/knowledge/style/this-keyword-in-codeunits.md b/microsoft/knowledge/style/this-keyword-in-codeunits.md deleted file mode 100644 index cb0a8a3..0000000 --- a/microsoft/knowledge/style/this-keyword-in-codeunits.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [25..] -domain: style -keywords: [this, codeunit, self-reference, aa0248, scope] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Use the `this` keyword for self-reference inside codeunits (CodeCop AA0248) - -## Description - -CodeCop AA0248 recommends prefixing self-references inside a codeunit with `this`. `this.ValidateCustomer(Customer)` is unambiguous: the call resolves to a procedure on the current codeunit, not to a local variable or a procedure on a passed-in object. Without the prefix, a reader of a 200-line procedure has to scan the whole codeunit to confirm whether `ValidateCustomer` is local. `this` also makes it possible to pass the current codeunit as an argument — `SomeOtherCodeunit.DoWork(this)` — which is the only way to expose the running codeunit instance to a collaborator. The rule applies only to codeunits, not to pages, reports, queries, or tables — those object types do not have a `this` reference in AL. - -## Best Practice - -Inside a codeunit, prefix calls to procedures and accesses to global variables on the same codeunit with `this.`, and pass `this` when an external codeunit needs a reference to the running instance. - -See sample: [`this-keyword-in-codeunits.good.al`](this-keyword-in-codeunits.good.al). - -## Anti Pattern - -Calling a codeunit-local procedure as a bare identifier (`ValidateCustomer(Customer)`) when other readings are possible. The ambiguity costs reading time on every encounter and grows with codeunit size. - -See sample: [`this-keyword-in-codeunits.bad.al`](this-keyword-in-codeunits.bad.al). diff --git a/microsoft/knowledge/style/variable-declaration-order-by-type.bad.al b/microsoft/knowledge/style/variable-declaration-order-by-type.bad.al deleted file mode 100644 index 3131fa6..0000000 --- a/microsoft/knowledge/style/variable-declaration-order-by-type.bad.al +++ /dev/null @@ -1,13 +0,0 @@ -codeunit 50247 "Sample Var Order Bad" -{ - procedure Run() - var - CustomerNo: Code[20]; - TempBuffer: Record "Integer" temporary; - Amount: Decimal; - Customer: Record Customer; - IsValid: Boolean; - begin - IsValid := Customer.Get(CustomerNo); - end; -} diff --git a/microsoft/knowledge/style/variable-declaration-order-by-type.good.al b/microsoft/knowledge/style/variable-declaration-order-by-type.good.al deleted file mode 100644 index 590ed25..0000000 --- a/microsoft/knowledge/style/variable-declaration-order-by-type.good.al +++ /dev/null @@ -1,13 +0,0 @@ -codeunit 50246 "Sample Var Order Good" -{ - procedure Run() - var - Customer: Record Customer; - TempBuffer: Record "Integer" temporary; - CustomerNo: Code[20]; - Amount: Decimal; - IsValid: Boolean; - begin - IsValid := Customer.Get(CustomerNo); - end; -} diff --git a/microsoft/knowledge/style/variable-declaration-order-by-type.md b/microsoft/knowledge/style/variable-declaration-order-by-type.md deleted file mode 100644 index a133e87..0000000 --- a/microsoft/knowledge/style/variable-declaration-order-by-type.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [variable-declaration, order, var, complex-types, aa0021] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Order variable declarations by type, complex types first (CodeCop AA0021) - -## Description - -CodeCop AA0021 requires that variable declarations inside a `var` block follow a fixed ordering by type, with complex (composite) types appearing before primitive types. The canonical order is `Record`, then `Report`, `Codeunit`, `XmlPort`, `Page`, `Query`, `Notification`, `BigText`, `DateFormula`, `RecordId`, `RecordRef`, `FieldRef`, `FilterPageBuilder`, then the simple types `Text`, `Code`, `Integer`, `Decimal`, `Boolean`, `Date`, `Time`, `DateTime`, `Char`, `Byte`. Inside each type group the variables can be alphabetical or in usage order. Temporary records still sort under `Record`. - -## Best Practice - -Declare all `Record` variables first, then other complex types, then primitives. A consistent order makes diffs review-friendly and matches the convention enforced by the AL formatter and CodeCop. - -See sample: [`variable-declaration-order-by-type.good.al`](variable-declaration-order-by-type.good.al). - -## Anti Pattern - -A `var` block where records and primitives are interleaved — `CustomerNo: Code[20];` between two `Record` variables, or `Amount: Decimal;` declared above the `Customer: Record Customer;` it is computed from. AA0021 flags it and the block is harder to scan; readers expect composite types at the top. - -See sample: [`variable-declaration-order-by-type.bad.al`](variable-declaration-order-by-type.bad.al). diff --git a/microsoft/knowledge/style/variable-name-must-not-shadow.bad.al b/microsoft/knowledge/style/variable-name-must-not-shadow.bad.al deleted file mode 100644 index 65c8223..0000000 --- a/microsoft/knowledge/style/variable-name-must-not-shadow.bad.al +++ /dev/null @@ -1,19 +0,0 @@ -codeunit 50249 "Sample Shadow Bad" -{ - var - Customer: Record Customer; - - procedure ProcessSales() - var - Customer: Text; - Amount: Decimal; - begin - Customer := 'C-100'; - Amount := 0; - end; - - procedure Amount(): Decimal - begin - exit(0); - end; -} diff --git a/microsoft/knowledge/style/variable-name-must-not-shadow.good.al b/microsoft/knowledge/style/variable-name-must-not-shadow.good.al deleted file mode 100644 index f5391ef..0000000 --- a/microsoft/knowledge/style/variable-name-must-not-shadow.good.al +++ /dev/null @@ -1,19 +0,0 @@ -codeunit 50248 "Sample No Shadow Good" -{ - var - CustomerRec: Record Customer; - - procedure ProcessSales() - var - CustomerName: Text; - SalesAmount: Decimal; - begin - CustomerName := CustomerRec.Name; - SalesAmount := GetAmount(); - end; - - procedure GetAmount(): Decimal - begin - exit(0); - end; -} diff --git a/microsoft/knowledge/style/variable-name-must-not-shadow.md b/microsoft/knowledge/style/variable-name-must-not-shadow.md deleted file mode 100644 index 200cae2..0000000 --- a/microsoft/knowledge/style/variable-name-must-not-shadow.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -bc-version: [all] -domain: style -keywords: [variable-name, shadow, conflict, aa0198, aa0202, aa0204, codecop] -technologies: [al] -countries: [w1] -application-area: [all] ---- - -# Local variable names must not shadow globals, fields, methods, or actions (CodeCop AA0198/AA0202/AA0204) - -## Description - -Three CodeCop rules — AA0198, AA0202, AA0204 — together forbid a local variable from sharing a name with a global variable on the same object, with a field on the same table or page source, with a procedure on the same object, or with an action on the same page. The compiler resolves the conflict by binding the closer scope, so a local `Customer: Text` will silently override a global `Customer: Record Customer` for the duration of a procedure — every call site reading `Customer.Name` from inside that procedure refers to the text, and the breakage is invisible to a reader who has both declarations on screen. - -## Best Practice - -Differentiate every local declaration from globals, fields, procedures, and actions on the same object. `Customer` global plus `CustomerName` local; method `GetAmount` plus local `SalesAmount`. The standard pattern is to attach a noun suffix to the local (`CustomerName`, `CustomerRec`, `CustomerNo`) rather than to the global. - -See sample: [`variable-name-must-not-shadow.good.al`](variable-name-must-not-shadow.good.al). - -## Anti Pattern - -A procedure that declares a local `Customer: Text` inside a codeunit that already has a global `Customer: Record Customer`. The local wins and the global becomes unreachable inside the procedure. AA0198/AA0202/AA0204 flag this category of conflict whether the colliding entity is a global, a field, a method, or an action. - -See sample: [`variable-name-must-not-shadow.bad.al`](variable-name-must-not-shadow.bad.al). diff --git a/microsoft/skills/review/al-appsource-review.md b/microsoft/skills/review/al-appsource-review.md index 3ba30e4..ebbed36 100644 --- a/microsoft/skills/review/al-appsource-review.md +++ b/microsoft/skills/review/al-appsource-review.md @@ -16,7 +16,7 @@ application-area: [all] Reviews AL source and app metadata changes against the `appsource` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`. -An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. AppSource findings are narrow by design — they apply when the review scope contains AppSourceCop configuration, AL object or extension-member names, or AppSource-facing `app.json` metadata. The skill returns `not-applicable` when none of those apply. +An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. AppSource findings are narrow by design — they apply to AppSource-facing metadata and complete permission coverage that requires repository context. Mechanical AppSourceCop diagnostics are intentionally outside this skill. The skill returns `not-applicable` when none of those surfaces apply. ## Source @@ -37,19 +37,14 @@ Discard files that are not applicable. Retain conditionally applicable files (an Narrow the relevant files to the subset that applies to the changes under review. For each relevant file, compute overlap against: -- The changed files and AL object types — especially `app.json`, `AppSourceCop.json`, namespace declarations, permission-set objects, new objects, and table/page/report extensions that add fields, keys, controls, or actions to base objects. -- The changed object and member names, weighted toward prefix/suffix consistency with `mandatoryAffixes` or `mandatoryPrefix`, plus AppSource-facing help metadata. -- Tokens extracted from the diff that relate to AppSource (`AppSourceCop`, `mandatoryAffixes`, `mandatoryPrefix`, `AS0011`, `prefix`, `suffix`, `namespace`, `using`, `permissionset`, `Assignable`, `Permissions`, `SUPER`, `tableextension`, `pageextension`, `reportextension`, `field`, `key`, `control`, `action`, `app.json`, `help`, `ContextSensitiveHelpPage`, `Copilot`, `https`). +- The changed files and AL object types — especially `app.json`, permission-set objects, setup and usage entry points, and AppSource-facing help metadata. +- Tokens extracted from the diff that relate to AppSource (`permissionset`, `Assignable`, `Permissions`, `SUPER`, `tabledata`, `execute`, `app.json`, `help`, `ContextSensitiveHelpPage`, `Copilot`, `https`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. When the diff contains no AppSource-related source or metadata changes by any of the above signals, return `outcome: "not-applicable"` without evaluating files. The following targeted checks cover every current `appsource` article across the Microsoft and community layers. Treat each as a candidate-selection cue: when the signal appears in changed code, add the named article to the worklist and evaluate it in Action. -- Select exactly one naming-collision owner. When no namespace declaration is present, a new/renamed object lacks the reserved prefix/suffix, or an extension object adds an unaffixed member to a base object — `object-affixes-prevent-collisions`. -- For BC23 or later, use `two-level-namespace-replaces-object-affix-not-extension-member-affix` instead when the changed source actually declares or changes a namespace and relies on it as the owned-object affix alternative, but has fewer than two levels or incorrectly applies that exception to members on another publisher's object. Never worklist this article for an unaffixed source file with no namespace declaration. - The app has no assignable permission set covering its setup and usage paths, omits visible object/tabledata grants, or requires `SUPER` for normal operation — `permission-sets-cover-setup-and-usage-without-super`. Require repository-level app context; one isolated permission-set object cannot prove complete coverage. - -Before emitting an affix finding, compare every owned object name and every member added to another publisher's object against the configured `mandatoryAffixes`/`mandatoryPrefix`. A matching prefix or suffix is compliant. Do not flag an `ABC`-prefixed object or an `ABC`-suffixed extension member when `ABC` is the configured affix. - For BC v27 or later, `app.json` adds or changes the `help` URL to a path deeper than two levels, or a changed Copilot/context-sensitive help arrangement would ground the app under an overly broad truncated parent — `keep-copilot-help-url-to-two-path-levels`. Once the candidate worklist is known, resolve layer-precedence conflicts per READ. Drop lower-precedence files whose normative guidance (`## Best Practice` or `## Anti Pattern`) directly contradicts a higher-precedence candidate, and record each dropped file in `suppressed` with `reason: "layer-precedence"`. Files that would have been candidates but are hidden because their layer is disabled in consumer configuration are recorded with `reason: "configuration"`. Files that never became candidates are NOT recorded in `suppressed`. @@ -66,13 +61,13 @@ For each worklist entry, evaluate the diff against the file's `## Best Practice` Set `confidence` to: -- `high` when the detection is based on an unambiguous pattern match (affix configuration/name or URL path depth). +- `high` when the detection is based on an unambiguous pattern match such as URL path depth. - `medium` when detection relies on heuristics or when any frontmatter dimension was `unknown`. - `low` when the finding is an advisory derived only from applicability. After evaluating each worklist entry, also consider whether the diff exhibits an AppSource defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with `references: []`, an `id` slug prefixed with `agent:`, `confidence` capped at `medium`, `severity` capped at `minor` (agent findings are advisory and non-gating), and a `message` that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). Hold every candidate to the precision bar in `skills/do.md` (*Agent findings*): emit only a concrete, material AppSource defect a knowledgeable BC reviewer would agree is wrong — steelman it first and drop anything stylistic, speculative, dependent on code outside the diff, or merely a valid alternative; when in doubt, omit. The scope is strictly AppSource; defects outside this domain belong to other leaves and MUST NOT be emitted here. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See `skills/do.md` for the full contract. -For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: add the configured affix to one object or extension member, or replace a deep help URL with a known two-level canonical URL). For mechanical findings, emit `findings[].suggested-code` with the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, adapt the `.good.al` replacement into `suggested-code`. +For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example, replacing a deep help URL with a known two-level canonical URL). For mechanical findings, emit `findings[].suggested-code` with the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, adapt the `.good.al` replacement into `suggested-code`. Omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract. @@ -80,7 +75,7 @@ Outcome selection: - `completed` — the skill evaluated every worklist item. - `no-knowledge` — no applicable AppSource knowledge survived filtering. -- `not-applicable` — the diff touches no AppSource source, analyzer configuration, or app-metadata surface. +- `not-applicable` — the diff touches no AppSource permission or app-metadata surface. - `partial` — a budget was hit before the worklist was exhausted. - `failed` — an unrecoverable error occurred. @@ -98,19 +93,19 @@ Output conforms to the DO output contract. Every finding this skill emits MUST s }, "findings": [ { - "id": "microsoft/knowledge/appsource/object-affixes-prevent-collisions.md", + "id": "microsoft/knowledge/appsource/keep-copilot-help-url-to-two-path-levels.md", "severity": "major", - "message": "The tableextension adds an unaffixed Loyalty Points field to Customer, so it violates the configured AppSource affix and can collide with another extension.", + "message": "The app help URL is deeper than two path levels, so Copilot truncates it and may ground answers on unrelated sibling documentation.", "location": { - "file": "src/CustomerExt.TableExt.al", - "line": 8 + "file": "app.json", + "line": 12 }, "references": [ - { "path": "microsoft/knowledge/appsource/object-affixes-prevent-collisions.md" } + { "path": "microsoft/knowledge/appsource/keep-copilot-help-url-to-two-path-levels.md" } ], "confidence": "high", "domain": "AppSource", - "suggested-code": "field(50100; \"Loyalty Points ABC\"; Integer)" + "suggested-code": "\"help\": \"https://contoso.com/docs/myapp\"" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-breaking-changes-review.md b/microsoft/skills/review/al-breaking-changes-review.md index 1ddd810..cf962ba 100644 --- a/microsoft/skills/review/al-breaking-changes-review.md +++ b/microsoft/skills/review/al-breaking-changes-review.md @@ -39,7 +39,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially codeunits, tables, and table extensions that expose procedures, fields, or events to other apps, and any member whose access is being widened. - The changed procedures, fields, and triggers, weighted toward non-`local` procedures, published table fields, event publishers, and any member whose signature, access modifier, or obsolete state is being altered. -- Tokens extracted from the diff that relate to API stability and deprecation (`signature`, `parameter`, `return`, `var`, `Obsolete`, `ObsoleteState`, `ObsoleteReason`, `ObsoleteTag`, `Pending`, `Removed`, `CLEAN`, `SecretText`, `token`, `internal`, `local`, `public`, `protected`, `Scope`, `namespace`, `using`, `AS0007`). +- Tokens extracted from the diff that relate to API stability and deprecation (`signature`, `parameter`, `return`, `var`, `Obsolete`, `ObsoleteState`, `ObsoleteReason`, `ObsoleteTag`, `Pending`, `Removed`, `CLEAN`, `SecretText`, `token`, `internal`, `local`, `public`, `protected`, `Scope`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. @@ -50,8 +50,7 @@ The following targeted checks cover every current `breaking-changes` article: - A published procedure changes parameter count/order/type/name, `var`, return type, or array shape instead of preserving the old signature and adding an overload — `do-not-change-published-procedure-signatures`. - A public procedure/event/interface exposes a credential or other sensitive value through `Text` or an externally callable contract — `do-not-expose-sensitive-data-through-public-api`. - Code already marked obsolete is expanded with new behavior instead of routing new callers to its replacement — `do-not-modify-code-already-marked-obsolete`. -- A shipped table field is deleted, renamed, renumbered, or replaced without retaining the original field as `ObsoleteState = Pending` and migrating its data — `obsolete-table-fields-instead-of-deleting-them`. This owns AS0005 field-name changes; do not substitute the namespace article. -- A published object's namespace changes between the base and changed source while its identity otherwise remains — `namespace-is-part-of-published-object-identity`. Do not apply it to a new, unshipped object or to an ordinary object-name change with no namespace change. +- A shipped table field is deleted, renamed, renumbered, or replaced without retaining the original field as `ObsoleteState = Pending` and migrating its data — `obsolete-table-fields-instead-of-deleting-them`. For `obsolete-table-fields-instead-of-deleting-them`, compare the baseline ID and name before emitting. When the original field remains under the same ID and name with `ObsoleteState = Pending`, and the replacement uses a new ID, the change follows the rule and must not be flagged. diff --git a/microsoft/skills/review/al-style-review.md b/microsoft/skills/review/al-style-review.md index 223fbbd..6c8e63c 100644 --- a/microsoft/skills/review/al-style-review.md +++ b/microsoft/skills/review/al-style-review.md @@ -16,7 +16,7 @@ application-area: [all] Reviews AL source changes against the `style` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`. -Style findings cover AL conventions that CodeCop and similar analyzers partially enforce — label suffixes, API page naming, temporary-variable prefixes, label properties, named invocations, `FieldCaption`/`TableCaption` in user messages, `OptionCaption` pairing, Error-parameter passing, `this` keyword, required parentheses, file-naming. Use together with a formal analyzer; this skill adds BCQuality's remedial-knowledge explanations of why each rule exists. +Style findings cover AL conventions that require contextual judgment — API page naming, temporary-variable prefixes, label semantics, named invocations, `FieldCaption`/`TableCaption` in user messages, error-parameter handling, and file naming. Mechanical compiler and analyzer rules are intentionally outside this skill; run the consuming app's configured analyzers separately. An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract. @@ -40,8 +40,8 @@ Discard files that are not applicable. Retain conditionally applicable files onl Narrow the relevant files to the subset that applies to the changes under review. For each relevant file, compute overlap against: - Changed AL objects — especially API pages (`PageType = API`), tables and pages declaring Labels/TextConsts, codeunits issuing `Error`/`Message`/`Confirm`, and any file whose name violates the `..al` convention. -- Changed declarations, weighted toward `: Label '...'`, `: TextConst '...'`, temporary record variables, option fields, error-handling call sites, and codeunit-internal method calls. -- Tokens extracted from the diff (`Label`, `TextConst`, `Locked`, `Comment`, `MaxLength`, `temporary`, `OptionMembers`, `OptionCaption`, `APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `DelayedInsert`, `FieldCaption`, `TableCaption`, `FieldName`, `TableName`, `Page.RunModal`, `Report.Run`, `this.`, `StrSubstNo`). +- Changed declarations, weighted toward `: Label '...'`, `: TextConst '...'`, temporary record variables, error-handling call sites, and API declarations. +- Tokens extracted from the diff (`Label`, `TextConst`, `Locked`, `Comment`, `MaxLength`, `temporary`, `APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `DelayedInsert`, `FieldCaption`, `TableCaption`, `FieldName`, `TableName`, `Page.RunModal`, `Report.Run`, `StrSubstNo`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object or declaration. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. @@ -50,8 +50,6 @@ Do not worklist `temporary-variable-temp-prefix.md` for an event publisher param Apply these high-signal mappings before fuzzy topic ranking: - A `Label` or `TextConst` contains multiple or ambiguous placeholders but has no `Comment`, or its Comment does not explain every placeholder — `label-comment-explains-placeholders.md`. A single placeholder whose meaning is explicit in the text, such as `Customer %1`, is allowed without a Comment and must not be flagged. -- `function-call-parentheses-required.md` applies only to a zero-argument invocation written without `()`. Never worklist it from an invocation that already has parentheses or supplies arguments, including `Error(Label, Arg1, Arg2)`. - Once the candidate worklist is known, resolve layer-precedence conflicts per READ and record suppressions. When the post-conflict worklist is empty because no applicable style knowledge exists, or because configuration suppressed every candidate, emit `outcome: "no-knowledge"`. When the worklist is empty because no applicable style knowledge matched the changes, emit `outcome: "completed"` with an empty `findings` array. @@ -60,7 +58,7 @@ When the post-conflict worklist is empty because no applicable style knowledge e For each worklist entry, evaluate the diff against the file's `## Best Practice` and `## Anti Pattern` sections. Style findings rarely reach `blocker` — reserve it for cases where the knowledge file documents a platform-level requirement (for example, API page property constraints the OData runtime rejects). Most style findings are `minor` or `info`; egregious misuse (`Error` with pre-built Text losing translation and telemetry classification) may reach `major`. -Severity calibration — a formal analyzer already flags the mechanical presence/naming conventions (the `this` keyword AA0248, approved label suffixes AA0074, variable-declaration order by type AA0021, a missing `ToolTip`, required parentheses). On those, BCQuality's value is the *explanation* of why the rule exists, not a second gate; emit them at `info` so a consumer that gates on severity does not re-flag what CodeCop/AppSourceCop already reports. Reserve `minor` for style issues with concrete downstream impact the analyzer does not catch — lost translation or telemetry classification from a string-built `Error`, an `OptionCaption` that does not match its `OptionMembers`, or a misleading named invocation. A procedure-local `Label` is valid and is not a correctness or localization finding; an explicit repository preference for object scope is at most low-severity maintainability guidance. This keeps the domain's default output advisory and prevents analyzer-redundant noise from competing with substantive review. +Severity calibration — reserve `minor` for style issues with concrete downstream impact that deterministic tooling does not establish, such as lost translation or telemetry classification from a string-built `Error` or a misleading named invocation. A procedure-local `Label` is valid and is not a correctness or localization finding; an explicit repository preference for object scope is at most low-severity maintainability guidance. Do not rediscover or report mechanical compiler or analyzer diagnostics, even at `info`. Set `confidence` to: @@ -70,7 +68,7 @@ Set `confidence` to: After evaluating each worklist entry, also consider whether the diff exhibits a style defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with `references: []`, an `id` slug prefixed with `agent:`, `confidence` capped at `medium`, `severity` capped at `minor` (agent findings are advisory and non-gating), and a `message` that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). Hold every candidate to the precision bar in `skills/do.md` (*Agent findings*): emit only a clear, widely-accepted AL style violation with a concrete basis a knowledgeable BC reviewer would agree on — steelman it first and drop personal preference, speculation, and any single defensible formatting choice among several; when in doubt, omit. The scope is strictly style — naming, labelling, formatting, and analyzer-adjacent conventions. A correctness, logic, data-integrity, or contract defect is NOT a style finding even when it can be reworded as a convention: a method that mutates a shared `Record`'s filters, an unfiltered `DeleteAll`, a violated interface contract, or a wrong boolean guard are behavioural defects, not conventions — do not emit them here under a style framing. If a specific domain leaf covers the concern (performance, security, error-handling, …) it belongs there; if no knowledge file in any domain covers it, it belongs to the `al-code-review` super-skill's cross-cutting self-review agent channel (`from-sub-skill: "agent"`, `severity` capped at `minor`), not to this leaf. A reliable test: if you cannot cite a style `## Best Practice`/`## Anti Pattern` for the concern, it is very likely not a style finding. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See `skills/do.md` for the full contract. -For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: delete unreachable lines; replace `Count() > 0` with `not IsEmpty()`; add a missing `ToolTip`, `OptionCaption`, or `DataClassification`; replace a string-concatenated `Error` with a Label-backed call; change an over-broad permission token; or add an obvious `else`/guard branch). For mechanical findings, emit `findings[].suggested-code` with the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, adapt the `.good.al` replacement into `suggested-code`. +For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: add a missing contextual `ToolTip`, replace a string-concatenated `Error` with a Label-backed call, or correct an API naming property whose intended value is clear). For mechanical findings, emit `findings[].suggested-code` with the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, adapt the `.good.al` replacement into `suggested-code`. Omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract. @@ -91,20 +89,20 @@ Output conforms to the DO output contract. Every finding this skill emits MUST s "skill": { "id": "al-style-review", "version": 1 }, "outcome": "completed", "summary": { - "counts": { "blocker": 0, "major": 0, "minor": 0, "info": 1 }, + "counts": { "blocker": 0, "major": 0, "minor": 1, "info": 0 }, "coverage": { "worklist-size": 1, "items-evaluated": 1 } }, "findings": [ { - "id": "microsoft/knowledge/style/label-suffix-approved-list.md", - "severity": "info", - "message": "A Label named Text000 has no approved suffix (Msg/Err/Qst/Tok/Lbl/Txt). Per the referenced CodeCop AA0074 guidance, every Label and TextConst carries a suffix indicating its consuming call.", + "id": "microsoft/knowledge/style/label-comment-explains-placeholders.md", + "severity": "minor", + "message": "The label has two ambiguous placeholders but no Comment explaining what each value represents to translators.", "location": { "file": "src/Sales/PostingRoutines.Codeunit.al", "line": 42 }, "references": [ - { "path": "microsoft/knowledge/style/label-suffix-approved-list.md" } + { "path": "microsoft/knowledge/style/label-comment-explains-placeholders.md" } ], "confidence": "high", "domain": "Style" From 51597068b1bc2ac6dda10d3bb1103b0d7da4f4bd Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Fri, 11 Sep 2026 12:35:31 +0200 Subject: [PATCH 03/35] Add bounded knowledge retrieval (#179) * Add bounded knowledge retrieval Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0d8b7764-f15a-49ea-8d50-d9147334f8af * Fix bc-version overflow and pathless-row identity in bounded retrieval Catalog matching compared an Int32 -BCVersion against a bigint range bound. PowerShell coerces the right operand to the left operand's type, so a bound wider than Int32 threw a conversion error and failed the whole domain catalog rather than the single row. Metadata validation already accepts such bounds, so compare as bigint on both sides. The shared pager built its oversized-row message with $row.path, which throws under Set-StrictMode -Version Latest when a row carries no path, replacing the explicit bound failure with a property-lookup error. Resolve the path defensively for dictionary and object rows so the offset-based fallback is reachable. Both paths gain regression coverage that fails without these fixes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0d8b7764-f15a-49ea-8d50-d9147334f8af --- .github/scripts/Test-KnowledgeIndex.ps1 | 3 + .../skills/review/al-appsource-review.md | 2 +- .../review/al-breaking-changes-review.md | 2 +- microsoft/skills/review/al-code-review.md | 14 +- .../skills/review/al-data-modeling-review.md | 2 +- .../skills/review/al-error-handling-review.md | 2 +- microsoft/skills/review/al-events-review.md | 2 +- .../skills/review/al-interfaces-review.md | 2 +- .../skills/review/al-performance-review.md | 2 +- microsoft/skills/review/al-privacy-review.md | 2 +- microsoft/skills/review/al-query-review.md | 2 +- microsoft/skills/review/al-security-review.md | 2 +- microsoft/skills/review/al-style-review.md | 2 +- .../skills/review/al-telemetry-review.md | 2 +- microsoft/skills/review/al-testing-review.md | 2 +- microsoft/skills/review/al-ui-review.md | 2 +- microsoft/skills/review/al-upgrade-review.md | 2 +- .../skills/review/al-web-services-review.md | 2 +- skills/do.md | 30 + skills/read.md | 55 ++ tools/Bounded-Results.ps1 | 117 +++ tools/Build-KnowledgeIndex.ps1 | 178 +++- tools/Get-KnowledgeArticles.ps1 | 187 +++++ tools/Knowledge-Retrieval.ps1 | 298 +++++++ tools/Search-Knowledge.ps1 | 244 ++++++ tools/Test-KnowledgeRetrieval.ps1 | 788 ++++++++++++++++++ 26 files changed, 1891 insertions(+), 55 deletions(-) create mode 100644 tools/Bounded-Results.ps1 create mode 100644 tools/Get-KnowledgeArticles.ps1 create mode 100644 tools/Knowledge-Retrieval.ps1 create mode 100644 tools/Search-Knowledge.ps1 create mode 100644 tools/Test-KnowledgeRetrieval.ps1 diff --git a/.github/scripts/Test-KnowledgeIndex.ps1 b/.github/scripts/Test-KnowledgeIndex.ps1 index 76896af..1e61064 100644 --- a/.github/scripts/Test-KnowledgeIndex.ps1 +++ b/.github/scripts/Test-KnowledgeIndex.ps1 @@ -16,6 +16,8 @@ 3. Selection-input integrity — every parsed article row carries the non-empty `domain` + `keywords` the worklist predicate selects on, and every article parses (an unparseable article is an invalid file). + 4. Bounded retrieval — delegates to tools/Test-KnowledgeRetrieval.ps1 for + lossless paging, exact-body round trips, and explicit failure cases. Exit code 0 = healthy; non-zero = a problem CI must block on. #> @@ -90,4 +92,5 @@ if ($problems.Count) { exit 1 } Write-Host "Knowledge-index check PASSED: $($rows.Count) articles, deterministic, full coverage, selection inputs intact." -ForegroundColor Green +& (Join-Path $Root 'tools/Test-KnowledgeRetrieval.ps1') -Root $Root exit 0 diff --git a/microsoft/skills/review/al-appsource-review.md b/microsoft/skills/review/al-appsource-review.md index ebbed36..c851ea2 100644 --- a/microsoft/skills/review/al-appsource-review.md +++ b/microsoft/skills/review/al-appsource-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `appsource` as this skill's candidate set across every enabled Microsoft, community, and custom layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/appsource/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain appsource`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-breaking-changes-review.md b/microsoft/skills/review/al-breaking-changes-review.md index cf962ba..7f30713 100644 --- a/microsoft/skills/review/al-breaking-changes-review.md +++ b/microsoft/skills/review/al-breaking-changes-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `breaking-changes` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/breaking-changes/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain breaking-changes`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-code-review.md b/microsoft/skills/review/al-code-review.md index 9972aca..6a577ba 100644 --- a/microsoft/skills/review/al-code-review.md +++ b/microsoft/skills/review/al-code-review.md @@ -65,7 +65,10 @@ The worklist is the list of sub-skills judged relevant by the previous step. Eve The Action step consists of **discrete leaf invocations**, not one combined generation. Invocation scheduling belongs to the orchestrator: independent leaves may run serially or concurrently, but their evaluation contexts and findings-reports remain isolated. Concretely this means: -- **Isolate leaf invocations when the host supports it.** For fast/small models, each sub-skill SHOULD run in a fresh model call or child context containing only the task input, READ/DO contracts, the leaf instructions, a domain-filtered slice of the current knowledge index, and articles that leaf worklists. Preserve each index row's exact `path`; the leaf must copy references from that slice. The coordinator then collects the resulting JSON. This is the preferred fast-model profile: it bounds context, prevents later leaves from being skipped as attention is exhausted, and removes any reason to synthesize article paths. +- **Isolate leaf invocations when the host supports it.** Each sub-skill SHOULD run in a fresh model call or child context containing only its assigned source paths, READ/DO contracts, the leaf instructions, the complete bounded domain catalog per READ, and articles that leaf worklists. Preserve each catalog row's exact `path`; the leaf must copy references from that catalog. +- **Keep run artifacts private.** Before dispatch, allocate a new GUID-named directory under the current session's artifact directory and a distinct scratch/report child directory for every leaf. Pass a leaf only its own assigned source paths and child directory, never the run root or sibling paths. A leaf MUST NOT discover, enumerate, read, modify, or delete sibling artifacts. Do not reuse a prior run directory, and do not clean up any run artifact until every leaf has finished and consolidation is complete. +- **Use the exact Task return as the report.** Capture each leaf's exact return as the primary transport and apply DO's consumer acceptance gate before rollup. Worker-side persistence of the same report in its private directory is optional and redundant; a missing report file does not invalidate an otherwise valid exact return. +- **Treat automatic output spills as host-owned.** If the host reports that a Task return was automatically spilled, the coordinator MAY read that file read-only only at the exact path returned by the tool. Never modify, delete, enumerate around, or reuse an automatic spill path. Never bypass a content-exclusion or access denial. - Treat each sub-skill in the worklist as its own pass: read the sub-skill's instructions, apply its Source → Relevance → Worklist → Action steps to the orchestrator-supplied inputs, and produce that sub-skill's complete findings-report independently. - Do not collapse multiple sub-skills into one shared reasoning step. Each sub-skill has a distinct knowledge subset and a distinct evaluation procedure; sharing one rolled-up scan dilutes per-skill attention and causes leaves to silently underreport (this has been observed in production: leaf skills returned empty `findings[]` while their standalone runs against the same diff produced multiple matches). - The agent self-review pass is its own final iteration. Begin it only after every sub-skill in the worklist has completed and its sub-result is recorded. @@ -77,8 +80,8 @@ The Action step consists of **discrete leaf invocations**, not one combined gene For each sub-skill in the worklist: 1. Invoke the sub-skill with the orchestrator's inputs, passing only the subset each sub-skill declares in its `inputs`. -2. Capture the sub-skill's complete findings-report verbatim and append it to `sub-results`. -3. If the sub-skill's `outcome` is `failed`, stop here for this sub-skill: its findings are not reliable per the DO contract and MUST NOT be copied into the super-skill's top-level `findings[]` or counted in `summary.counts`. +2. Capture the exact Task return and validate it against DO's consumer acceptance gate before accepting it. Preserve an invalid raw return unchanged in the leaf's private artifacts or host log; do not reconstruct or repair it. Record a separate failed validation result with no findings for rollup. +3. Append the accepted findings-report, or the separate failed validation result, to `sub-results`. If its `outcome` is `failed`, stop here for this sub-skill: its findings are not reliable per the DO contract and MUST NOT be copied into the super-skill's top-level `findings[]` or counted in `summary.counts`. 4. Otherwise, compare each entry from the sub-skill's `findings[]` with findings already rolled up. Two findings are duplicates when they point to the same file and overlapping line/range and prescribe materially the same correction, even when their knowledge-file IDs differ. Merge duplicates instead of appending both: keep the more specific domain owner, preserve that finding's optional `domain` field verbatim (including its absence), use its reference as `references[0]` and therefore as `id`, append the other references as supporting references, keep the highest severity and confidence justified by either report, and preserve one self-contained message. Article and leaf ownership notes decide specificity; do not choose by execution order. 5. Append each non-duplicate finding, setting `from-sub-skill` to the sub-skill's `skill.id` and preserving its optional `domain` field verbatim, including its absence. For non-citation findings (those whose `id` is a skill-defined slug rather than a reference path), prefix `id` with `:` to prevent collisions across sub-skills. Other finding fields are preserved. @@ -122,7 +125,10 @@ Calculate `summary.counts` from the final top-level `findings[]`, after failed s Derive `outcome` using the DO rollup rules. `outcome-reason` is populated for `partial` and `failed` and SHOULD summarize per-sub-skill state, for example: *"al-security-review failed (tool timeout); al-performance-review completed."* -Before emitting the rollup, apply DO's reference-integrity gate to every nested and top-level finding. Every knowledge-backed ID/reference path must exist in the live checkout, must have been opened by the producing leaf, and must be copied verbatim rather than synthesized. Treat a sub-result containing an unverifiable citation as failed and exclude its findings from the top-level rollup. +Before emitting the rollup, apply DO's consumer acceptance gate to every nested +and top-level finding. Treat an invalid sub-result as failed and exclude all of +its findings from the top-level rollup. Preserve its exact raw payload +separately; never reconstruct it into a success-shaped report. ## Output diff --git a/microsoft/skills/review/al-data-modeling-review.md b/microsoft/skills/review/al-data-modeling-review.md index 01a983a..05dcd0b 100644 --- a/microsoft/skills/review/al-data-modeling-review.md +++ b/microsoft/skills/review/al-data-modeling-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `data-modeling` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/data-modeling/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain data-modeling`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-error-handling-review.md b/microsoft/skills/review/al-error-handling-review.md index 63c4d5e..56bc0fe 100644 --- a/microsoft/skills/review/al-error-handling-review.md +++ b/microsoft/skills/review/al-error-handling-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `error-handling` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/error-handling/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain error-handling`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-events-review.md b/microsoft/skills/review/al-events-review.md index 559d036..68bcdb0 100644 --- a/microsoft/skills/review/al-events-review.md +++ b/microsoft/skills/review/al-events-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `events` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/events/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain events`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-interfaces-review.md b/microsoft/skills/review/al-interfaces-review.md index 885cd0b..f5d65cd 100644 --- a/microsoft/skills/review/al-interfaces-review.md +++ b/microsoft/skills/review/al-interfaces-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `interfaces` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/interfaces/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain interfaces`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-performance-review.md b/microsoft/skills/review/al-performance-review.md index f2fa80d..664f20d 100644 --- a/microsoft/skills/review/al-performance-review.md +++ b/microsoft/skills/review/al-performance-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `performance` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/performance/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain performance`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-privacy-review.md b/microsoft/skills/review/al-privacy-review.md index 469000c..17b4e7b 100644 --- a/microsoft/skills/review/al-privacy-review.md +++ b/microsoft/skills/review/al-privacy-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `privacy` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/privacy/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain privacy`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-query-review.md b/microsoft/skills/review/al-query-review.md index 3681b23..c52ddd8 100644 --- a/microsoft/skills/review/al-query-review.md +++ b/microsoft/skills/review/al-query-review.md @@ -18,7 +18,7 @@ Reviews AL source changes against the `query` knowledge domain in BCQuality. Thi ## Source -Read `knowledge-index.json` once and take entries whose `domain` is `query` across enabled layers. Open an article body only after it enters the Worklist. If the index is unavailable, discover `*/knowledge/query/*.md` by path. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain query`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-security-review.md b/microsoft/skills/review/al-security-review.md index e3e4049..00e8d10 100644 --- a/microsoft/skills/review/al-security-review.md +++ b/microsoft/skills/review/al-security-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `security` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/security/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain security`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-style-review.md b/microsoft/skills/review/al-style-review.md index 6c8e63c..2703c87 100644 --- a/microsoft/skills/review/al-style-review.md +++ b/microsoft/skills/review/al-style-review.md @@ -22,7 +22,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `style` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/style/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain style`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-telemetry-review.md b/microsoft/skills/review/al-telemetry-review.md index 4b50a9e..1c2046d 100644 --- a/microsoft/skills/review/al-telemetry-review.md +++ b/microsoft/skills/review/al-telemetry-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `telemetry` as this skill's candidate set across every enabled Microsoft, community, and custom layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/telemetry/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain telemetry`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-testing-review.md b/microsoft/skills/review/al-testing-review.md index ed50c46..c96ac83 100644 --- a/microsoft/skills/review/al-testing-review.md +++ b/microsoft/skills/review/al-testing-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `testing` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/testing/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain testing`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-ui-review.md b/microsoft/skills/review/al-ui-review.md index c04a30a..8ffd731 100644 --- a/microsoft/skills/review/al-ui-review.md +++ b/microsoft/skills/review/al-ui-review.md @@ -22,7 +22,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `ui` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/ui/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain ui`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-upgrade-review.md b/microsoft/skills/review/al-upgrade-review.md index 2bb1877..94851a3 100644 --- a/microsoft/skills/review/al-upgrade-review.md +++ b/microsoft/skills/review/al-upgrade-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `upgrade` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/upgrade/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain upgrade`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/microsoft/skills/review/al-web-services-review.md b/microsoft/skills/review/al-web-services-review.md index e818e46..19d0735 100644 --- a/microsoft/skills/review/al-web-services-review.md +++ b/microsoft/skills/review/al-web-services-review.md @@ -20,7 +20,7 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat ## Source -Read the BCQuality knowledge index once — the `knowledge-index.json` BCQuality builds at the root of the knowledge checkout (Entry's preparation step regenerates it over the live, already-filtered clone — see `skills/entry.md`). It lists every article that survived layer and allow/deny filtering and carries, per article, its `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint — exactly the fields Relevance and Worklist consume. Take the index entries whose `domain` is `web-services` as this skill's candidate set across every enabled layer; do not open the individual article files at this step. Open an article's full body only once it enters the Worklist below, so a review reads the index plus the handful of worklisted articles instead of every file under `*/knowledge/web-services/**`. +Use READ's **Bounded retrieval for review skills** workflow with `-Domain web-services`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. ## Relevance diff --git a/skills/do.md b/skills/do.md index 4ac433b..f86509b 100644 --- a/skills/do.md +++ b/skills/do.md @@ -159,6 +159,36 @@ The emitted document MUST be strict, valid JSON per [RFC 8259](https://www.rfc-e AL source is the common failure case. Quoted identifiers (for example `Rec."No."`) and multi-line snippets routinely appear in `message`, `suggested-code`, and `suggested-code-omission-reason`, and each embedded quote or newline MUST be escaped when placed in a string value. A `suggested-code` payload that spans several lines is a single JSON string with `\n` separators, not a literal multi-line block. Emit the document as one JSON value with no trailing commentary, and do not rely on the consumer to repair unescaped output. +### Consumer acceptance gate + +The exact action-skill return is the primary report transport. Before accepting +it as a findings-report, a coordinator or host MUST validate it +deterministically: + +1. Parse the exact return as strict JSON and validate every required field, + enum, type, conditional requirement, summary count, coverage value, and + leaf/super-skill constraint against this output contract. +2. For every knowledge-backed finding, verify each `references[].path` is an + exact repo-relative knowledge path that exists in the live BCQuality + snapshot, and verify `findings[].id` exactly equals + `references[0].path`. Verify each path is also present in the coordinator's + recorded set of complete article bodies retrieved for that leaf; catalog + membership alone is insufficient. Keep optional `references[].sha` + separate: it is commit provenance, not an article content hash. +3. For every `location`, verify `file` is an exact source path in the supplied + review scope, the file exists in that source snapshot, and `line` and any + inclusive range identify existing lines with `start-line == line` and + `end-line >= start-line`. + +Validation failure invalidates the complete return; consumers MUST NOT salvage +individual findings, infer missing fields, reconstruct JSON, clamp ranges, +rewrite paths, or otherwise silently repair model output. Preserve the invalid +raw payload unchanged in private run artifacts or host logs. Record a separate +failed validation result for that leaf with no findings, and derive the +super-skill outcome as `partial` or `failed` using the normal rollup rules. +Worker-side report-file persistence is optional and never replaces validation +of the exact return. + ### Field semantics **`outcome`** (required) — diff --git a/skills/read.md b/skills/read.md index f2e9c1e..dddd7db 100644 --- a/skills/read.md +++ b/skills/read.md @@ -149,3 +149,58 @@ The standard workflow for finding applicable files: 4. Resolve conflicts via layer precedence. Steps 1–3 are deterministic; step 4 is applied only when conflicts are detected. + +### Bounded retrieval for review skills + +Resolve `$root` to the BCQuality root, not the reviewed source. Entry prepares +the index once before dispatch; that prepared index is the catalog snapshot and +leaves use it read-only. Catalog retrieval validates the complete index metadata +and returned paths without reopening or rehashing article bodies. Post-Entry +body changes therefore take effect only after Entry rebuilds the index; exact +body retrieval rejects a selected article whose content hash differs from its +prepared row. In one PowerShell tool session, invoke the helpers with `&` so +array arguments remain arrays: + +```powershell +& (Join-Path $root 'tools\Search-Knowledge.ps1') -Domain $domain -Technologies @('al') +& (Join-Path $root 'tools\Get-KnowledgeArticles.ps1') -Paths @($exactPath) +``` + +Pass enabled layers and only task dimensions that are actually known. Catalog +retrieval returns every domain and READ-applicable row: it does not rank, +sample, apply top-k, deduplicate by basename, or omit rows based on query text. +Consume every page by passing `continuation.offset` as `-Offset` and +`continuation.snapshot` as `-Snapshot` with the unchanged request until +`complete` is `true`. Each page repeats request context, defaults, and totals. +An omitted applicability field on a row inherits that page's `defaults`; it +does not mean unknown task context. Preserve every row's exact `path`, `layer`, +complete `keywords`, `title`, one-line `description`, non-default applicability +fields, explicit `applicability`, and `unknownDimensions`. + +Apply the leaf's existing Relevance and Worklist to the complete catalog union. +Split the resulting exact paths into stable chunks of at most eight; never pass +more paths than `-MaxArticles` (whose maximum is eight). Request article bodies +only by one such chunk. Consume every +returned `body`, then request `remainingPaths` with +`continuation.snapshot` as `-Snapshot` until `complete` is `true`, preserving +the other request settings. Continuation is confined to that chunk. Bodies are +original strict UTF-8 text with source byte counts and SHA-256 content hashes; +they are never summarized or truncated. Samples are not loaded unless +requested explicitly with `-Samples` and exact sibling paths; their sibling +article must match its prepared hash and contain the exact READ link. + +The default serialized response limit is 16,000 bytes including its output +newline. Never combine pages or bodies into an unbounded prompt. A malformed or +internally inconsistent prepared index, changed continuation snapshot, selected +article hash mismatch, invalid continuation, unsafe or missing path, invalid +UTF-8, broken sample link, oversized path chunk, or row/envelope that cannot fit +fails explicitly. Entry is the only index preparation point: a leaf does not +rebuild. If PowerShell, a helper, or a valid prepared index is unavailable, +discover exact paths across the enabled domain folders and use native bounded +reads through EOF, validating frontmatter per READ and never treating retrieval +failure as an empty result. + +The helpers' `sha256` and `bytes` fields describe the retrieved file content. +They are not citation provenance. Optional findings `references[].sha` is the +BCQuality commit SHA the skill reviewed; omit it when that provenance is not +available or would misrepresent uncommitted content. diff --git a/tools/Bounded-Results.ps1 b/tools/Bounded-Results.ps1 new file mode 100644 index 0000000..6def944 --- /dev/null +++ b/tools/Bounded-Results.ps1 @@ -0,0 +1,117 @@ +# Shared deterministic paging. Callers build the complete immutable result first. +#requires -Version 7.2 +Set-StrictMode -Version Latest + +function Get-ResultSnapshot { + param([Parameter(Mandatory)] $Value) + + $json = ConvertTo-Json -InputObject $Value -Depth 30 -Compress + return [Convert]::ToHexString( + [Security.Cryptography.SHA256]::HashData([Text.Encoding]::UTF8.GetBytes($json)) + ).ToLowerInvariant() +} + +function Get-SerializedByteCount { + param([Parameter(Mandatory)] [string] $Json) + + # PowerShell writes one platform newline after the returned JSON string. + return [Text.Encoding]::UTF8.GetByteCount($Json) + + [Text.Encoding]::UTF8.GetByteCount([Environment]::NewLine) +} + +function ConvertTo-BoundedPage { + param( + [Parameter(Mandatory)] [Collections.IDictionary] $Header, + [Parameter(Mandatory)] [Collections.IDictionary] $Groups, + [ValidateRange(0, 2147483647)] [int] $Offset = 0, + [string] $Snapshot, + [ValidateRange(1024, 16000)] [int] $MaxBytes = 16000 + ) + + $total = 0 + foreach ($name in $Groups.Keys) { + $total += $Groups[$name].Count + } + if (($total -eq 0 -and $Offset -ne 0) -or ($total -gt 0 -and $Offset -ge $total)) { + throw "Invalid Offset=$Offset for totalCount=$total; no rows were returned." + } + if ($Offset -gt 0 -and -not $Snapshot) { + throw 'Continuation requires Snapshot from the preceding page.' + } + if ($Snapshot -and $Snapshot -cne $Header.snapshot) { + throw 'Snapshot changed or continuation belongs to another request. Discard partial results and restart at Offset=0.' + } + + $page = [ordered]@{} + foreach ($key in $Header.Keys) { + $page[$key] = $Header[$key] + } + $page.offset = $Offset + $page.returnedCount = 0 + $page.totalCount = $total + $page.remainingCount = $total - $Offset + $page.complete = ($total -eq 0) + $page.continuation = if ($total) { + [ordered]@{ offset = $Offset; snapshot = $Header.snapshot } + } + else { + $null + } + foreach ($name in $Groups.Keys) { + $page[$name] = [Collections.Generic.List[object]]::new() + } + + $json = ConvertTo-Json -InputObject $page -Depth 30 -Compress + if ((Get-SerializedByteCount -Json $json) -gt $MaxBytes) { + throw "Page envelope exceeds MaxBytes=$MaxBytes. Use READ's path-discovery fallback; never truncate." + } + + $position = 0 + foreach ($name in $Groups.Keys) { + foreach ($row in $Groups[$name]) { + if ($position++ -lt $Offset) { + continue + } + + $page[$name].Add($row) + $page.returnedCount++ + $page.remainingCount-- + $page.complete = ($page.remainingCount -eq 0) + $page.continuation = if ($page.complete) { + $null + } + else { + [ordered]@{ + offset = $Offset + $page.returnedCount + snapshot = $Header.snapshot + } + } + + $next = ConvertTo-Json -InputObject $page -Depth 30 -Compress + if ((Get-SerializedByteCount -Json $next) -gt $MaxBytes) { + $page[$name].RemoveAt($page[$name].Count - 1) + $page.returnedCount-- + $page.remainingCount++ + $page.complete = $false + $page.continuation = [ordered]@{ + offset = $Offset + $page.returnedCount + snapshot = $Header.snapshot + } + if ($page.returnedCount -eq 0) { + $rowPath = $null + if ($row -is [Collections.IDictionary]) { + if ($row.Contains('path')) { $rowPath = $row['path'] } + } + elseif ($null -ne $row -and $row.PSObject.Properties['path']) { + $rowPath = $row.PSObject.Properties['path'].Value + } + $identity = if ($rowPath) { " at $rowPath" } else { " at Offset=$Offset" } + throw "One complete $name row plus envelope exceeds MaxBytes=$MaxBytes$identity. No row was clipped." + } + return $json + } + $json = $next + } + } + return $json +} diff --git a/tools/Build-KnowledgeIndex.ps1 b/tools/Build-KnowledgeIndex.ps1 index 5835e5d..d246ff3 100644 --- a/tools/Build-KnowledgeIndex.ps1 +++ b/tools/Build-KnowledgeIndex.ps1 @@ -30,6 +30,8 @@ expected to prune its clone to policy first). For provenance and to reproduce a consumer's exact view, pass -EnabledLayers to restrict the walk to those layers and to record the policy in the index header. + Invalid articles are omitted with a path-specific warning so one bad + optional layer article cannot block valid siblings. .PARAMETER BCQualityRoot Path to the BCQuality content root to index (typically a filtered clone). @@ -69,6 +71,17 @@ param( Set-StrictMode -Version Latest $ErrorActionPreference = 'Stop' +. (Join-Path $PSScriptRoot 'Knowledge-Retrieval.ps1') + +if ($PSBoundParameters.ContainsKey('EnabledLayers')) { + if ($null -eq $EnabledLayers) { + throw 'EnabledLayers must be an array; omit it to index all layers.' + } + if (@($EnabledLayers | Where-Object { $_ -cnotin @('microsoft', 'community', 'custom') }).Count -or + @($EnabledLayers | Group-Object -CaseSensitive | Where-Object Count -gt 1).Count) { + throw 'EnabledLayers must contain unique canonical lowercase layer names.' + } +} # Default to the clone root (parent of this script's tools/ folder) so the # agent's Entry preparation step can invoke this with no arguments from the @@ -93,6 +106,45 @@ function Get-RelativePath { return ($rel -replace '\\', '/') } +function Get-BytesSha256 { + param([byte[]] $Bytes) + $sha = [Security.Cryptography.SHA256]::Create() + try { + return ([BitConverter]::ToString($sha.ComputeHash($Bytes)) -replace '-', '').ToLowerInvariant() + } + finally { + $sha.Dispose() + } +} + +function Read-ArticleSource { + param([string] $Path) + $bytes = [IO.File]::ReadAllBytes($Path) + try { + $text = [Text.UTF8Encoding]::new($false, $true).GetString($bytes) + } + catch [Text.DecoderFallbackException] { + throw [IO.InvalidDataException]::new('invalid UTF-8', $_.Exception) + } + return [pscustomobject]@{ + bytes = $bytes + text = $text + sha256 = Get-BytesSha256 -Bytes $bytes + } +} + +function Get-ValueSha256 { + param([Parameter(Mandatory)] $Value) + $bytes = [Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -InputObject $Value -Depth 8 -Compress)) + $sha = [Security.Cryptography.SHA256]::Create() + try { + return ([BitConverter]::ToString($sha.ComputeHash($bytes)) -replace '-', '').ToLowerInvariant() + } + finally { + $sha.Dispose() + } +} + # Trims a Description to a single short line (<= $Max chars) for the lean # index. Takes the first sentence; truncates on a word boundary if still long. function Get-LeanDescription { @@ -116,9 +168,12 @@ function ConvertFrom-ArticleFrontmatter { # Pattern) is included; the index is a lossless substitute for the # frontmatter + Description the worklist predicate reads, not a # substitute for the article's normative guidance. - param([string] $Path) + param( + [string] $Path, + [string] $Text + ) - $lines = Get-Content -LiteralPath $Path -ErrorAction Stop + $lines = [regex]::Split($Text.TrimStart([char]0xfeff), '\r\n|\n|\r') # Frontmatter is the first '---'-delimited block. if ($lines.Count -lt 1 -or $lines[0].Trim() -ne '---') { return $null } @@ -129,19 +184,42 @@ function ConvertFrom-ArticleFrontmatter { if ($fmEnd -lt 0) { return $null } $fm = @{} + $arrayFields = @('bc-version', 'keywords', 'technologies', 'countries', 'application-area') for ($i = 1; $i -lt $fmEnd; $i++) { $line = $lines[$i] if ($line -match '^\s*([a-zA-Z][\w-]*)\s*:\s*(.*)$') { $key = $Matches[1] $val = $Matches[2].Trim() - if ($val -match '^\[(.*)\]$') { + if ($key -in $arrayFields) { + if ($val -notmatch '^\[(.*)\]$') { + throw [IO.InvalidDataException]::new( + "frontmatter field '$key' must use non-empty bracket-array syntax" + ) + } $inner = $Matches[1].Trim() - if ($inner -eq '') { $fm[$key] = @() } - else { $fm[$key] = @($inner -split '\s*,\s*' | ForEach-Object { $_.Trim() }) } + if ($inner -eq '') { + throw [IO.InvalidDataException]::new( + "frontmatter field '$key' must use non-empty bracket-array syntax" + ) + } + $values = @($inner -split '\s*,\s*' | ForEach-Object { $_.Trim() }) + if (@($values | Where-Object { [string]::IsNullOrWhiteSpace($_) }).Count) { + throw [IO.InvalidDataException]::new( + "frontmatter field '$key' must use non-empty bracket-array syntax" + ) + } + $fm[$key] = $values } elseif ($val -ne '') { $fm[$key] = $val } } } + foreach ($field in $arrayFields) { + if (-not $fm.ContainsKey($field) -or $fm[$field] -isnot [array] -or -not $fm[$field].Count) { + throw [IO.InvalidDataException]::new( + "frontmatter field '$field' must use non-empty bracket-array syntax" + ) + } + } # Body parsing: H1 title and the full Description section. The Description # is the article's primary retrieval target per READ and is captured @@ -185,42 +263,71 @@ $indexArticles = [System.Collections.Generic.List[object]]::new() foreach ($layerDir in @('microsoft', 'community', 'custom')) { $kbRoot = Join-Path $BCQualityRoot (Join-Path $layerDir 'knowledge') if (-not (Test-Path $kbRoot)) { continue } - if ($EnabledLayers -and ($EnabledLayers -notcontains $layerDir)) { continue } + if ($EnabledLayers -and ($EnabledLayers -cnotcontains $layerDir)) { continue } - Get-ChildItem -LiteralPath $kbRoot -Recurse -File -Filter '*.md' -ErrorAction SilentlyContinue | - Sort-Object FullName | - ForEach-Object { - $rel = Get-RelativePath -Root $BCQualityRoot -Full $_.FullName - $parsed = $null - try { $parsed = ConvertFrom-ArticleFrontmatter -Path $_.FullName } catch { $parsed = $null } + $files = @( + Get-ChildItem -LiteralPath $kbRoot -Recurse -File -Filter '*.md' -ErrorAction SilentlyContinue | + Sort-Object FullName + ) + foreach ($file in $files) { + $rel = Get-RelativePath -Root $BCQualityRoot -Full $file.FullName + try { + $source = Read-ArticleSource -Path $file.FullName + $parsed = ConvertFrom-ArticleFrontmatter -Path $file.FullName -Text $source.text if (-not $parsed) { - # Invalid/unparseable file: list path + domain-from-path so it - # is never silently dropped from discovery. Consumers fall back - # to reading it in full. - $domainFromPath = if ($rel -match '/knowledge/([^/]+)/') { $Matches[1] } else { '' } - $indexArticles.Add([pscustomobject]@{ - path = $rel; layer = $layerDir; domain = $domainFromPath - 'bc-version' = @(); technologies = @(); countries = @(); 'application-area' = @() - keywords = @(); title = ''; description = ''; parsed = $false - }) | Out-Null - return + throw [IO.InvalidDataException]::new('missing or unterminated frontmatter') + } + foreach ($required in @( + @('domain', $parsed.domain), + @('H1 title', $parsed.title), + @('Description', $parsed.description) + )) { + if ([string]::IsNullOrWhiteSpace([string]$required[1])) { + throw [IO.InvalidDataException]::new("missing $($required[0])") + } } - $indexArticles.Add([pscustomobject]@{ - path = $rel - layer = $layerDir - domain = $parsed.domain - 'bc-version' = @($parsed.'bc-version') - technologies = @($parsed.technologies) - countries = @($parsed.countries) - 'application-area' = @($parsed.'application-area') - keywords = @($parsed.keywords) - title = $parsed.title - description = if ($FullIndex) { $parsed.description } else { Get-LeanDescription -Text $parsed.description } - parsed = $true - }) | Out-Null } + catch [IO.InvalidDataException] { + Write-Warning "Skipping invalid knowledge article '$rel': $($_.Exception.Message)." + continue + } + + $article = [ordered]@{ + path = $rel + layer = $layerDir + domain = $parsed.domain + 'bc-version' = @($parsed.'bc-version') + technologies = @($parsed.technologies) + countries = @($parsed.countries) + 'application-area' = @($parsed.'application-area') + keywords = @($parsed.keywords) + title = $parsed.title + description = if ($FullIndex) { $parsed.description } else { Get-LeanDescription -Text $parsed.description } + parsed = $true + sourceSha256 = $source.sha256 + } + $problem = Get-KnowledgeMetadataProblem -Row $article + if ($problem) { + Write-Warning "Skipping invalid knowledge article '$rel': $problem." + continue + } + $indexArticles.Add($article) | Out-Null + } } +$articlesByPath = [Collections.Generic.Dictionary[string, object]]::new([StringComparer]::Ordinal) +foreach ($article in $indexArticles) { + if (-not $articlesByPath.TryAdd($article.path, $article)) { + throw "Duplicate knowledge path while building source snapshot: $($article.path)" + } +} +$sourcePaths = [string[]]@($articlesByPath.Keys) +[Array]::Sort($sourcePaths, [StringComparer]::Ordinal) +$sourceManifest = @( + foreach ($path in $sourcePaths) { + [ordered]@{ path = $path; sha256 = $articlesByPath[$path].sourceSha256 } + } +) $index = [pscustomobject]@{ version = 1 generatedAt = (Get-Date).ToUniversalTime().ToString('o') @@ -228,6 +335,7 @@ $index = [pscustomobject]@{ knowledgeAllow= @($KnowledgeAllow) knowledgeDeny = @($KnowledgeDeny) articleCount = $indexArticles.Count + sourceSnapshot= Get-ValueSha256 -Value $sourceManifest articles = @($indexArticles) } diff --git a/tools/Get-KnowledgeArticles.ps1 b/tools/Get-KnowledgeArticles.ps1 new file mode 100644 index 0000000..cdd112a --- /dev/null +++ b/tools/Get-KnowledgeArticles.ps1 @@ -0,0 +1,187 @@ +<# +.SYNOPSIS + Reads a bounded prefix of exact article or sample paths without altering bodies. +.DESCRIPTION + The UTF-8 byte size bound covers the complete serialized JSON plus its output + newline. A body that cannot fit fails explicitly; it is never summarized or + truncated. Samples are loaded only with -Samples and must be linked by their + sibling article using READ's exact link convention. +#> +#requires -Version 7.2 +[CmdletBinding()] +param( + [ValidateNotNullOrEmpty()] [string] $BCQualityRoot = (Split-Path $PSScriptRoot -Parent), + [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [string[]] $Paths, + [ValidateRange(1, 8)] [int] $MaxArticles = 8, + [ValidateRange(1024, 16000)] [int] $MaxBytes = 16000, + [ValidateSet('microsoft', 'community', 'custom')] + [AllowEmptyCollection()] [string[]] $EnabledLayers = @('microsoft', 'community', 'custom'), + [string] $IndexPath, + [ValidatePattern('^[a-f0-9]{64}$')] [string] $Snapshot, + [switch] $Samples +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' +. (Join-Path $PSScriptRoot 'Knowledge-Retrieval.ps1') +. (Join-Path $PSScriptRoot 'Bounded-Results.ps1') + +$BCQualityRoot = Resolve-KnowledgeRoot $BCQualityRoot +if (-not $IndexPath) { + $IndexPath = Join-Path $BCQualityRoot 'knowledge-index.json' +} +if ($Paths.Count -gt $MaxArticles) { + throw "Paths count $($Paths.Count) exceeds MaxArticles=$MaxArticles. Split the worklist into stable chunks of at most $MaxArticles exact paths." +} +if ($null -eq $EnabledLayers) { + throw 'EnabledLayers must be an array.' +} +if (@($EnabledLayers | Where-Object { $_ -cnotin @('microsoft', 'community', 'custom') }).Count -or + @($EnabledLayers | Group-Object -CaseSensitive | Where-Object Count -gt 1).Count) { + throw 'EnabledLayers must contain unique canonical lowercase layer names.' +} + +$recovery = "Run Entry preparation once before dispatch, or use READ's bounded native-file fallback. Do not rebuild in a leaf." +$preparedIndex = Read-PreparedKnowledgeIndex -IndexPath $IndexPath -Recovery $recovery +$index = $preparedIndex.index +$byPath = $preparedIndex.byPath +$unrestricted = $index.enabledLayers.Count -eq 0 -or + ($index.enabledLayers.Count -eq 1 -and $null -eq $index.enabledLayers[0]) +$indexedLayers = @( + if ($unrestricted) { 'microsoft', 'community', 'custom' } else { $index.enabledLayers } +) +if (@($EnabledLayers | Where-Object { $_ -cnotin $indexedLayers }).Count) { + throw "Index layer coverage does not cover EnabledLayers. $recovery" +} + +$resolved = [Collections.Generic.List[string]]::new() +$records = [Collections.Generic.List[object]]::new() +$seen = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal) +$articleTexts = [Collections.Generic.Dictionary[string, string]]::new([StringComparer]::Ordinal) +$sampleContents = [Collections.Generic.Dictionary[string, object]]::new([StringComparer]::Ordinal) +foreach ($path in $Paths) { + $kind = if ($Samples) { 'sample' } else { 'article' } + $fullPath = Resolve-KnowledgePath -Root $BCQualityRoot -Path $path -Kind $kind + if ($path.Split('/')[0] -cnotin $EnabledLayers) { + throw "Layer disabled for path: $path" + } + if (-not $seen.Add($path)) { + throw "Duplicate requested path: $path" + } + if ($Samples) { + $articlePath = $path -replace '\.(good|bad)\.[a-z0-9]+$', '.md' + if (-not $byPath.ContainsKey($articlePath)) { + throw "Sample article is absent from the prepared index: $articlePath" + } + $fullArticlePath = Resolve-KnowledgePath -Root $BCQualityRoot -Path $articlePath + if (-not $articleTexts.ContainsKey($articlePath)) { + $articleContent = Read-KnowledgeText -Path $fullArticlePath + if ($articleContent.sha256 -cne $byPath[$articlePath].sourceSha256) { + throw "Selected article hash does not match the prepared index: $articlePath" + } + $articleTexts.Add($articlePath, $articleContent.text) + } + Assert-SampleLink -ArticleText $articleTexts[$articlePath] -SamplePath $fullPath + $sampleContent = Read-KnowledgeText -Path $fullPath + $sampleContents.Add($path, $sampleContent) + $records.Add([ordered]@{ + path = $path + articlePath = $articlePath + articleSha256 = $byPath[$articlePath].sourceSha256 + sampleSha256 = $sampleContent.sha256 + sampleBytes = $sampleContent.bytes + }) + } + else { + if (-not $byPath.ContainsKey($path)) { + throw "Selected article is absent from the prepared index: $path" + } + $records.Add([ordered]@{ + path = $path + expectedSha256 = $byPath[$path].sourceSha256 + }) + } + $resolved.Add($fullPath) +} + +$requestSnapshot = Get-ResultSnapshot -Value ([ordered]@{ + root = $BCQualityRoot + preparedIndexSha256 = $preparedIndex.content.sha256 + kind = if ($Samples) { 'samples' } else { 'articles' } + enabledLayers = @($EnabledLayers) + files = @($records) +}) +if ($Snapshot -and $Snapshot -cne $requestSnapshot) { + throw 'Article snapshot changed or continuation belongs to another exact path batch. Discard partial results and restart.' +} + +$articles = [Collections.Generic.List[object]]::new() +function ConvertTo-BatchJson { + param([int] $ReadCount) + + $remaining = @( + if ($ReadCount -lt $Paths.Count) { + $Paths[$ReadCount..($Paths.Count - 1)] + } + ) + $remainingRecords = @( + if ($ReadCount -lt $records.Count) { + $records[$ReadCount..($records.Count - 1)] + } + ) + $continuation = if ($remaining.Count) { + [ordered]@{ + snapshot = Get-ResultSnapshot -Value ([ordered]@{ + root = $BCQualityRoot + preparedIndexSha256 = $preparedIndex.content.sha256 + kind = if ($Samples) { 'samples' } else { 'articles' } + enabledLayers = @($EnabledLayers) + files = $remainingRecords + }) + } + } + else { + $null + } + return [ordered]@{ + version = 1 + kind = if ($Samples) { 'samples' } else { 'articles' } + snapshot = $requestSnapshot + requestedCount = $Paths.Count + returnedCount = $ReadCount + complete = ($ReadCount -eq $Paths.Count) + articles = @($articles) + remainingPaths = $remaining + continuation = $continuation + } | ConvertTo-Json -Depth 8 -Compress +} + +$json = '' +for ($i = 0; $i -lt [Math]::Min($MaxArticles, $Paths.Count); $i++) { + $content = if ($Samples) { + $sampleContents[$Paths[$i]] + } + else { + Read-KnowledgeText -Path $resolved[$i] + } + if (-not $Samples -and $content.sha256 -cne $records[$i].expectedSha256) { + throw "Selected article hash does not match the prepared index: $($Paths[$i])" + } + $articles.Add([ordered]@{ + path = $Paths[$i] + bytes = $content.bytes + sha256 = $content.sha256 + body = $content.text + }) + $next = ConvertTo-BatchJson -ReadCount ($i + 1) + if ((Get-SerializedByteCount -Json $next) -gt $MaxBytes) { + $articles.RemoveAt($articles.Count - 1) + if ($i -eq 0) { + throw "No complete body plus continuation fits MaxBytes=$MaxBytes at $($Paths[$i]). Use a smaller exact path batch or READ's bounded native-file fallback; never truncate." + } + break + } + $json = $next +} + +$json diff --git a/tools/Knowledge-Retrieval.ps1 b/tools/Knowledge-Retrieval.ps1 new file mode 100644 index 0000000..7007868 --- /dev/null +++ b/tools/Knowledge-Retrieval.ps1 @@ -0,0 +1,298 @@ +# Shared filesystem guards for catalog and exact article retrieval. +Set-StrictMode -Version Latest + +function Resolve-KnowledgeRoot { + param([string] $Root) + + $item = Get-Item -LiteralPath $Root -Force -ErrorAction Stop + if ($item.PSProvider.Name -ne 'FileSystem' -or -not $item.PSIsContainer) { + throw "BCQuality root must be a filesystem directory: $Root" + } + if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) { + throw "Linked BCQuality roots are not supported: $Root" + } + return $item.FullName +} + +function Assert-KnowledgePath { + param( + [string] $Path, + [ValidateSet('article', 'sample')] [string] $Kind = 'article' + ) + + if ([string]::IsNullOrWhiteSpace($Path) -or + $Path -cnotmatch '^(microsoft|community|custom)/knowledge/[^/]+/.+' -or + $Path -match '[\\:*?"<>|\x00-\x1f]' -or + @($Path.Split('/') | Where-Object { $_ -in '', '.', '..' -or $_ -match '[. ]$' }).Count) { + throw "Invalid knowledge path: $Path" + } + if (($Kind -eq 'article' -and -not $Path.EndsWith('.md', [StringComparison]::Ordinal)) -or + ($Kind -eq 'sample' -and $Path -cnotmatch '\.(good|bad)\.[a-z0-9]+$')) { + throw "Expected an exact $Kind path: $Path" + } +} + +function Resolve-KnowledgePath { + param( + [string] $Root, + [string] $Path, + [ValidateSet('article', 'sample')] [string] $Kind = 'article' + ) + + Assert-KnowledgePath -Path $Path -Kind $Kind + $current = $Root + foreach ($part in $Path.Split('/')) { + $items = @( + Get-ChildItem -LiteralPath $current -Filter $part -Force -ErrorAction Stop | + Where-Object Name -CEQ $part + ) + if ($items.Count -ne 1) { + throw "Knowledge path does not exist with exact casing: $Path" + } + $item = $items[0] + if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) { + throw "Linked knowledge paths are not supported: $Path" + } + $current = $item.FullName + } + if ($item.PSIsContainer) { + throw "Knowledge path is not a file: $Path" + } + return $item.FullName +} + +function Read-KnowledgeText { + param([string] $Path) + + $bytes = [IO.File]::ReadAllBytes($Path) + try { + $text = [Text.UTF8Encoding]::new($false, $true).GetString($bytes) + } + catch { + throw "Knowledge file is not valid strict UTF-8: $Path" + } + return [pscustomobject]@{ + text = $text + bytes = $bytes.Length + sha256 = [Convert]::ToHexString( + [Security.Cryptography.SHA256]::HashData($bytes) + ).ToLowerInvariant() + } +} + +function Get-NormalizedKnowledgeVersions { + param([string[]] $Values) + + foreach ($value in $Values) { + if ($value -match '^"([^"]*)"$' -or $value -match "^'([^']*)'$") { + $Matches[1] + } + else { + $value + } + } +} + +function Get-KnowledgeMetadataProblem { + param([Collections.IDictionary] $Row) + + if ($Row['parsed'] -isnot [bool] -or -not $Row['parsed']) { + return 'unparsed frontmatter' + } + if ($Row['domain'] -isnot [string] -or + $Row['domain'] -cnotmatch '^[a-z0-9]+(-[a-z0-9]+)*$') { + return 'missing/invalid domain' + } + foreach ($field in @('bc-version', 'technologies', 'countries', 'application-area', 'keywords')) { + if ($Row[$field] -isnot [array] -or -not $Row[$field].Count) { + return "missing/invalid $field" + } + foreach ($value in $Row[$field]) { + if ($value -isnot [string] -or [string]::IsNullOrWhiteSpace($value)) { + return "invalid $field value" + } + } + } + foreach ($field in @('title', 'description')) { + if ($Row[$field] -isnot [string] -or + [string]::IsNullOrWhiteSpace($Row[$field]) -or + $Row[$field] -match '[\r\n]') { + return "missing/invalid $field" + } + } + + $versions = @(Get-NormalizedKnowledgeVersions -Values $Row['bc-version']) + if ($versions -ccontains 'all') { + if ($versions.Count -ne 1) { + return 'mixed bc-version sentinel' + } + } + elseif ($versions.Count -eq 1 -and $versions[0] -match '^(\d+)\.\.(\d+)?$') { + $start = [bigint]::Parse($Matches[1]) + if ($start -le 0 -or ($Matches[2] -and [bigint]::Parse($Matches[2]) -le 0)) { + return 'invalid bc-version range bound' + } + if ($Matches[2] -and $start -gt [bigint]::Parse($Matches[2])) { + return 'descending bc-version range' + } + } + else { + foreach ($version in $versions) { + if ($version -notmatch '^\d+$' -or [bigint]::Parse($version) -le 0) { + return 'invalid bc-version' + } + } + } + if (@($Row.technologies | Where-Object { $_ -cnotmatch '^[a-z0-9]+(-[a-z0-9]+)*$' }).Count) { + return 'invalid technologies' + } + if ($Row.technologies -ccontains 'all') { + return 'invalid technologies sentinel' + } + if ($Row.countries -ccontains 'w1') { + if ($Row.countries.Count -ne 1) { + return 'mixed countries sentinel' + } + } + elseif (@($Row.countries | Where-Object { $_ -cnotmatch '^[a-z]{2}$' }).Count) { + return 'invalid countries' + } + if (@($Row['application-area'] | Where-Object { $_ -cnotmatch '^(all|[a-z0-9]+(-[a-z0-9]+)*)$' }).Count) { + return 'invalid application-area' + } + if ($Row['application-area'] -ccontains 'all' -and $Row['application-area'].Count -ne 1) { + return 'mixed application-area sentinel' + } + if (@($Row.keywords | Where-Object { $_ -cnotmatch '^[a-z0-9]+(-[a-z0-9]+)*$' }).Count) { + return 'invalid keywords' + } + return '' +} + +function Get-PreparedManifestSha256 { + param( + [string[]] $Paths, + [Collections.Generic.Dictionary[string, object]] $ByPath + ) + + $hash = [Security.Cryptography.IncrementalHash]::CreateHash( + [Security.Cryptography.HashAlgorithmName]::SHA256 + ) + try { + $hash.AppendData([byte[]][char]'[') + for ($i = 0; $i -lt $Paths.Count; $i++) { + if ($i) { + $hash.AppendData([byte[]][char]',') + } + $row = [ordered]@{ + path = $Paths[$i] + sha256 = $ByPath[$Paths[$i]].sourceSha256 + } + $hash.AppendData([Text.Encoding]::UTF8.GetBytes( + (ConvertTo-Json -InputObject $row -Depth 8 -Compress) + )) + } + $hash.AppendData([byte[]][char]']') + return [Convert]::ToHexString($hash.GetHashAndReset()).ToLowerInvariant() + } + finally { + $hash.Dispose() + } +} + +function Read-PreparedKnowledgeIndex { + param( + [string] $IndexPath, + [string] $Recovery + ) + + if (-not (Test-Path -LiteralPath $IndexPath -PathType Leaf)) { + throw "Knowledge index missing: $IndexPath. $Recovery" + } + $indexItem = Get-Item -LiteralPath $IndexPath -Force -ErrorAction Stop + if ($indexItem.PSProvider.Name -ne 'FileSystem' -or + ($indexItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) { + throw "Knowledge index must be an unlinked filesystem file: $IndexPath. $Recovery" + } + + $content = Read-KnowledgeText -Path $indexItem.FullName + try { + $index = $content.text.TrimStart([char]0xfeff) | + ConvertFrom-Json -AsHashtable -ErrorAction Stop + } + catch { + throw "Malformed knowledge index JSON: $($_.Exception.Message). $Recovery" + } + if ($index -isnot [Collections.IDictionary] -or + $index.version -ne 1 -or + $index.articles -isnot [array] -or + $index.articleCount -ne $index.articles.Count -or + $index.enabledLayers -isnot [array] -or + $index.knowledgeAllow -isnot [array] -or + $index.knowledgeDeny -isnot [array] -or + $index.sourceSnapshot -isnot [string] -or + $index.sourceSnapshot -cnotmatch '^[a-f0-9]{64}$') { + throw "Invalid knowledge index envelope. $Recovery" + } + + $generatedAt = [DateTimeOffset]::MinValue + if ($index.generatedAt -is [DateTime]) { + $generatedAt = [DateTimeOffset]$index.generatedAt + } + elseif (-not [DateTimeOffset]::TryParse( + [string]$index.generatedAt, + [Globalization.CultureInfo]::InvariantCulture, + [Globalization.DateTimeStyles]::RoundtripKind, + [ref]$generatedAt + )) { + throw "Invalid knowledge index generatedAt. $Recovery" + } + if ($generatedAt -gt [DateTimeOffset]::UtcNow.AddMinutes(1)) { + throw "Invalid knowledge index generatedAt. $Recovery" + } + + $byPath = [Collections.Generic.Dictionary[string, object]]::new([StringComparer]::Ordinal) + foreach ($row in $index.articles) { + if ($row -isnot [Collections.IDictionary] -or $row.path -isnot [string]) { + throw "Index row has no exact path. $Recovery" + } + Assert-KnowledgePath -Path $row.path + if ($row.layer -cne $row.path.Split('/')[0] -or + $row.layer -cnotin @('microsoft', 'community', 'custom')) { + throw "Invalid index layer: $($row.path). $Recovery" + } + if ($row.sourceSha256 -isnot [string] -or + $row.sourceSha256 -cnotmatch '^[a-f0-9]{64}$') { + throw "Invalid source hash in knowledge index: $($row.path). $Recovery" + } + if (-not $byPath.TryAdd($row.path, $row)) { + throw "Duplicate index path: $($row.path). $Recovery" + } + } + + $paths = [string[]]@($byPath.Keys) + [Array]::Sort($paths, [StringComparer]::Ordinal) + if ((Get-PreparedManifestSha256 -Paths $paths -ByPath $byPath) -cne $index.sourceSnapshot) { + throw "Stale or internally inconsistent prepared index snapshot. $Recovery" + } + + return [pscustomobject]@{ + index = $index + content = $content + byPath = $byPath + paths = $paths + } +} + +function Assert-SampleLink { + param( + [string] $ArticleText, + [string] $SamplePath + ) + + $sampleName = [IO.Path]::GetFileName($SamplePath) + $expected = '[`' + $sampleName + '`](' + $sampleName + ')' + if (-not $ArticleText.Contains($expected, [StringComparison]::Ordinal)) { + throw "Sample is not linked by its article using the READ convention: $sampleName" + } +} diff --git a/tools/Search-Knowledge.ps1 b/tools/Search-Knowledge.ps1 new file mode 100644 index 0000000..ade280e --- /dev/null +++ b/tools/Search-Knowledge.ps1 @@ -0,0 +1,244 @@ +<# +.SYNOPSIS + Returns bounded pages of every domain/layer/READ-applicable catalog row. +.DESCRIPTION + Consumes Entry's prepared index read-only. Results are never ranked, sampled, + top-k limited, deduplicated by basename, or narrowed by query text. Omit an + unknown task dimension; an explicit empty array is a known empty set. +#> +#requires -Version 7.2 +[CmdletBinding()] +param( + [ValidateNotNullOrEmpty()] [string] $BCQualityRoot = (Split-Path $PSScriptRoot -Parent), + [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] + [ValidateScript({ -not [string]::IsNullOrWhiteSpace($_) })] [string] $Domain, + [ValidateSet('microsoft', 'community', 'custom')] + [AllowEmptyCollection()] [string[]] $EnabledLayers = @('microsoft', 'community', 'custom'), + [ValidateRange(1, 2147483647)] [int] $BCVersion, + [AllowEmptyCollection()] [string[]] $Technologies, + [AllowEmptyCollection()] [string[]] $Countries, + [AllowEmptyCollection()] [string[]] $ApplicationAreas, + [switch] $ExcludeConditional, + [string] $IndexPath, + [ValidateRange(1024, 16000)] [int] $MaxBytes = 16000, + [ValidateRange(0, 2147483647)] [int] $Offset = 0, + [ValidatePattern('^[a-f0-9]{64}$')] [string] $Snapshot +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' +. (Join-Path $PSScriptRoot 'Knowledge-Retrieval.ps1') +. (Join-Path $PSScriptRoot 'Bounded-Results.ps1') + +$BCQualityRoot = Resolve-KnowledgeRoot $BCQualityRoot +if (-not $IndexPath) { + $IndexPath = Join-Path $BCQualityRoot 'knowledge-index.json' +} +if ($null -eq $EnabledLayers) { + throw 'EnabledLayers must be an array; use an empty array to disable all layers.' +} +if (@($EnabledLayers | Where-Object { $_ -cnotin @('microsoft', 'community', 'custom') }).Count -or + @($EnabledLayers | Group-Object -CaseSensitive | Where-Object Count -gt 1).Count) { + throw 'EnabledLayers must contain unique canonical lowercase layer names.' +} + +$context = [ordered]@{} +foreach ($pair in @( + @('BCVersion', 'bc-version'), + @('Technologies', 'technologies'), + @('Countries', 'countries'), + @('ApplicationAreas', 'application-area') +)) { + if (-not $PSBoundParameters.ContainsKey($pair[0])) { + continue + } + $value = $PSBoundParameters[$pair[0]] + if ($null -eq $value) { + throw "Omit unknown context; do not pass null for $($pair[0])." + } + if ($pair[0] -ne 'BCVersion') { + foreach ($entry in $value) { + if ([string]::IsNullOrWhiteSpace($entry) -or $entry -cne $entry.Trim()) { + throw "Invalid context value for $($pair[0]): '$entry'" + } + } + } + $context[$pair[1]] = $value +} +if ($context.Contains('technologies') -and $context['technologies'] -ccontains 'all') { + throw "Technologies has no 'all' sentinel. Omit unknown context." +} + +$recovery = "Run Entry preparation once before dispatch, or use READ's path-discovery fallback. Do not rebuild in a leaf." +$preparedIndex = Read-PreparedKnowledgeIndex -IndexPath $IndexPath -Recovery $recovery +$index = $preparedIndex.index +$indexContent = $preparedIndex.content +$byPath = $preparedIndex.byPath +$paths = $preparedIndex.paths + +# The v1 generator historically serialized an omitted EnabledLayers parameter as [null]. +$unrestricted = $index.enabledLayers.Count -eq 0 -or + ($index.enabledLayers.Count -eq 1 -and $null -eq $index.enabledLayers[0]) +$indexedLayers = @( + if ($unrestricted) { + 'microsoft', 'community', 'custom' + } + else { + $index.enabledLayers + } +) +if (@($indexedLayers | Where-Object { $_ -cnotin @('microsoft', 'community', 'custom') }).Count -or + @($indexedLayers | Group-Object -CaseSensitive | Where-Object Count -gt 1).Count -or + @($EnabledLayers | Where-Object { $_ -cnotin $indexedLayers }).Count) { + throw "Index layer coverage does not cover EnabledLayers. $recovery" +} + +foreach ($path in $paths) { + $row = $byPath[$path] + if ($row.layer -cnotin $indexedLayers) { + throw "Index row layer is outside index coverage: $path. $recovery" + } + $problem = Get-KnowledgeMetadataProblem -Row $row + if ($problem) { + throw "Malformed knowledge index row at ${path}: $problem. $recovery" + } +} + +$defaults = [ordered]@{ + 'bc-version' = @('all') + technologies = @('al') + countries = @('w1') + 'application-area' = @('all') +} +$candidates = [Collections.Generic.List[object]]::new() +$excluded = [Collections.Generic.List[object]]::new() +foreach ($path in $paths) { + $row = $byPath[$path] + if ($row.domain -cne $Domain) { + continue + } + + $unknown = [Collections.Generic.List[string]]::new() + $matchesContext = $true + foreach ($field in $defaults.Keys) { + $values = $row[$field] + if ($field -eq 'bc-version') { + $values = @(Get-NormalizedKnowledgeVersions -Values $values) + } + $sentinel = switch ($field) { + 'bc-version' { 'all' } + 'countries' { 'w1' } + 'application-area' { 'all' } + default { '' } + } + if ($sentinel -and $values -ccontains $sentinel) { + continue + } + if (-not $context.Contains($field)) { + $unknown.Add($field) + continue + } + + $target = $context[$field] + $matched = $false + if ($field -eq 'bc-version') { + # Compare as bigint on both sides: metadata validation accepts bounds + # wider than Int32, and an int left operand would coerce them down. + $targetVersion = [bigint]$target + if ($values.Count -eq 1 -and $values[0] -match '^(\d+)\.\.(\d+)?$') { + $matched = $targetVersion -ge [bigint]::Parse($Matches[1]) -and + (-not $Matches[2] -or $targetVersion -le [bigint]::Parse($Matches[2])) + } + else { + $matched = @($values | Where-Object { [bigint]::Parse($_) -eq $targetVersion }).Count -gt 0 + } + } + else { + $matched = @($values | Where-Object { $target -ccontains $_ }).Count -gt 0 + } + if (-not $matched) { + $matchesContext = $false + break + } + } + if (-not $matchesContext -or ($ExcludeConditional -and $unknown.Count)) { + continue + } + $null = Resolve-KnowledgePath -Root $BCQualityRoot -Path $path + + $candidate = [ordered]@{ + path = $path + layer = $row.layer + keywords = $row.keywords + title = $row.title + description = $row.description + } + foreach ($field in $defaults.Keys) { + if (($row[$field] -join "`0") -cne ($defaults[$field] -join "`0")) { + $candidate[$field] = $row[$field] + } + } + $candidate.applicability = if ($unknown.Count) { 'conditional' } else { 'applicable' } + $candidate.unknownDimensions = @($unknown) + if ($row.layer -cin $EnabledLayers) { + $candidates.Add($candidate) + } + else { + $excluded.Add($candidate) + } +} + +$header = [ordered]@{ + version = 2 + domain = $Domain + context = $context + enabledLayers = @($EnabledLayers) + indexedLayers = @($indexedLayers) + excludeConditional = [bool]$ExcludeConditional + defaults = $defaults + candidateCount = $candidates.Count + excludedByConfigurationCount = $excluded.Count +} + +function Get-CatalogSnapshot { + param( + [string] $PreparedIndexSha256, + [Collections.IDictionary] $Request, + [Collections.IDictionary] $Groups + ) + + $hash = [Security.Cryptography.IncrementalHash]::CreateHash( + [Security.Cryptography.HashAlgorithmName]::SHA256 + ) + try { + foreach ($value in @( + $PreparedIndexSha256, + (ConvertTo-Json -InputObject $Request -Depth 8 -Compress) + )) { + $hash.AppendData([Text.Encoding]::UTF8.GetBytes($value)) + $hash.AppendData([byte[]](10)) + } + foreach ($groupName in $Groups.Keys) { + $hash.AppendData([Text.Encoding]::UTF8.GetBytes("[$groupName]")) + $hash.AppendData([byte[]](10)) + foreach ($row in $Groups[$groupName]) { + $hash.AppendData([Text.Encoding]::UTF8.GetBytes( + (ConvertTo-Json -InputObject $row -Depth 8 -Compress) + )) + $hash.AppendData([byte[]](10)) + } + } + return [Convert]::ToHexString($hash.GetHashAndReset()).ToLowerInvariant() + } + finally { + $hash.Dispose() + } +} + +$groups = [ordered]@{ + candidates = $candidates + excludedByConfiguration = $excluded +} +$header.snapshot = Get-CatalogSnapshot -PreparedIndexSha256 $indexContent.sha256 -Request $header -Groups $groups + +ConvertTo-BoundedPage -Header $header -Groups $groups -Offset $Offset -Snapshot $Snapshot -MaxBytes $MaxBytes diff --git a/tools/Test-KnowledgeRetrieval.ps1 b/tools/Test-KnowledgeRetrieval.ps1 new file mode 100644 index 0000000..ef65812 --- /dev/null +++ b/tools/Test-KnowledgeRetrieval.ps1 @@ -0,0 +1,788 @@ +<# +.SYNOPSIS + Validates lossless bounded catalog and exact-body retrieval. +#> +#requires -Version 7.2 +[CmdletBinding()] +param( + [string] $Root = (Resolve-Path (Join-Path $PSScriptRoot '..')) +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' +$Root = (Resolve-Path -LiteralPath $Root).Path + +$generator = Join-Path $Root 'tools/Build-KnowledgeIndex.ps1' +$search = Join-Path $Root 'tools/Search-Knowledge.ps1' +$getArticles = Join-Path $Root 'tools/Get-KnowledgeArticles.ps1' +$utf8 = [Text.UTF8Encoding]::new($false, $true) + +function Assert-True { + param([bool] $Condition, [string] $Message) + if (-not $Condition) { + throw "Assertion failed: $Message" + } +} + +function Assert-Equal { + param($Actual, $Expected, [string] $Message) + if ($Actual -cne $Expected) { + throw "Assertion failed: $Message. Expected '$Expected', got '$Actual'." + } +} + +function Assert-Sequence { + param($Actual, $Expected, [string] $Message) + $actualJson = ConvertTo-Json -InputObject @($Actual) -Compress + $expectedJson = ConvertTo-Json -InputObject @($Expected) -Compress + if ($actualJson -cne $expectedJson) { + throw "Assertion failed: $Message. Expected $expectedJson, got $actualJson." + } +} + +function Assert-Throws { + param([scriptblock] $Action, [string] $Pattern, [string] $Message) + try { + & $Action + } + catch { + if ($_.Exception.Message -notmatch $Pattern) { + throw "Assertion failed: $Message. Wrong error: $($_.Exception.Message)" + } + return + } + throw "Assertion failed: $Message. No error was thrown." +} + +function Get-OutputByteCount { + param([string] $Text) + return [Text.Encoding]::UTF8.GetByteCount($Text) + + [Text.Encoding]::UTF8.GetByteCount([Environment]::NewLine) +} + +function Invoke-CatalogPages { + param( + [hashtable] $Arguments, + [int] $MaxBytes = 4096 + ) + + $allCandidates = [Collections.Generic.List[object]]::new() + $allExcluded = [Collections.Generic.List[object]]::new() + $offset = 0 + $snapshot = '' + $shared = '' + $pageCount = 0 + $lastPage = $null + do { + $pageArguments = @{} + $Arguments + $pageArguments.MaxBytes = $MaxBytes + $pageArguments.Offset = $offset + if ($snapshot) { + $pageArguments.Snapshot = $snapshot + } + $raw = & $search @pageArguments + Assert-True ($raw -is [string]) 'catalog helper emitted exactly one JSON string' + Assert-True ((Get-OutputByteCount -Text $raw) -le $MaxBytes) 'catalog page includes its newline in MaxBytes' + $page = $raw | ConvertFrom-Json + $pageCount++ + Assert-True ($pageCount -le 1000) 'catalog continuation terminates' + Assert-Equal $page.offset $offset 'catalog offset is exact' + Assert-Equal $page.returnedCount (@($page.candidates).Count + @($page.excludedByConfiguration).Count) 'page returnedCount matches rows' + Assert-Equal $page.remainingCount ($page.totalCount - $offset - $page.returnedCount) 'page remainingCount is exact' + + $currentShared = [ordered]@{ + version = $page.version + domain = $page.domain + context = $page.context + enabledLayers = $page.enabledLayers + indexedLayers = $page.indexedLayers + excludeConditional = $page.excludeConditional + defaults = $page.defaults + candidateCount = $page.candidateCount + excludedByConfigurationCount = $page.excludedByConfigurationCount + snapshot = $page.snapshot + totalCount = $page.totalCount + } | ConvertTo-Json -Depth 8 -Compress + if (-not $shared) { + $shared = $currentShared + $snapshot = $page.snapshot + } + else { + Assert-Equal $currentShared $shared 'catalog pages repeat shared context, defaults, totals, and snapshot' + } + + foreach ($row in @($page.candidates)) { + $allCandidates.Add($row) + } + foreach ($row in @($page.excludedByConfiguration)) { + $allExcluded.Add($row) + } + if (-not $page.complete) { + Assert-True ($null -ne $page.continuation) 'incomplete page has continuation' + Assert-Equal $page.continuation.snapshot $snapshot 'continuation is snapshot-bound' + Assert-True ($page.continuation.offset -gt $offset) 'continuation makes progress' + $offset = $page.continuation.offset + } + $lastPage = $page + } while (-not $page.complete) + + Assert-True ($null -eq $lastPage.continuation) 'final page has no continuation' + Assert-Equal $allCandidates.Count $lastPage.candidateCount 'candidate total survives paging' + Assert-Equal $allExcluded.Count $lastPage.excludedByConfigurationCount 'excluded total survives paging' + return [pscustomobject]@{ + candidates = @($allCandidates) + excluded = @($allExcluded) + pages = $pageCount + snapshot = $snapshot + lastPage = $lastPage + } +} + +function Test-BodyRoundTrip { + param( + [string[]] $Paths, + [string] $IndexPath, + [switch] $Samples + ) + + $seen = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal) + for ($start = 0; $start -lt $Paths.Count; $start += 8) { + $end = [Math]::Min($start + 7, $Paths.Count - 1) + $remaining = @($Paths[$start..$end]) + $snapshot = '' + do { + $arguments = @{ + BCQualityRoot = $Root + IndexPath = $IndexPath + Paths = $remaining + MaxArticles = 8 + MaxBytes = 16000 + } + if ($Samples) { + $arguments.Samples = $true + } + if ($snapshot) { + $arguments.Snapshot = $snapshot + } + $raw = & $getArticles @arguments + Assert-True ($raw -is [string]) 'article helper emitted exactly one JSON string' + Assert-True ((Get-OutputByteCount -Text $raw) -le 16000) 'article batch includes its newline in MaxBytes' + $batch = $raw | ConvertFrom-Json + Assert-True ($batch.returnedCount -gt 0) 'article batching makes progress' + Assert-Equal $batch.returnedCount @($batch.articles).Count 'article returnedCount matches rows' + Assert-Equal $batch.complete (@($batch.remainingPaths).Count -eq 0) 'article completion matches remaining paths' + if ($batch.complete) { + Assert-True ($null -eq $batch.continuation) 'complete article batch has no continuation' + } + else { + Assert-True ($batch.continuation.snapshot -match '^[a-f0-9]{64}$') 'article continuation is snapshot-bound' + } + + foreach ($article in @($batch.articles)) { + Assert-True ($seen.Add($article.path)) "body returned once: $($article.path)" + $fullPath = Join-Path $Root ($article.path.Replace('/', [IO.Path]::DirectorySeparatorChar)) + $bytes = [IO.File]::ReadAllBytes($fullPath) + $text = $utf8.GetString($bytes) + $hash = [Convert]::ToHexString( + [Security.Cryptography.SHA256]::HashData($bytes) + ).ToLowerInvariant() + Assert-Equal $article.bytes $bytes.Length "byte count round-trips: $($article.path)" + Assert-Equal $article.sha256 $hash "SHA-256 round-trips: $($article.path)" + Assert-Equal $article.body $text "body round-trips: $($article.path)" + } + $remaining = @($batch.remainingPaths) + $snapshot = if ($batch.complete) { '' } else { $batch.continuation.snapshot } + } while ($remaining.Count) + } + Assert-Equal $seen.Count $Paths.Count 'every requested body round-trips without loss' +} + +function New-NeutralArticle { + param( + [string] $FixtureRoot, + [string] $Layer, + [string] $Slug, + [string] $Version = 'all', + [string] $Technology = 'al', + [string] $Country = 'w1', + [string] $Area = 'all', + [string] $Title = 'Neutral retrieval example', + [string] $Description = 'Neutral retrieval metadata for deterministic tests.' + ) + + $directory = Join-Path $FixtureRoot "$Layer\knowledge\neutral" + New-Item -ItemType Directory -Force -Path $directory | Out-Null + $content = @" +--- +bc-version: [$Version] +domain: neutral +keywords: [neutral, retrieval, deterministic] +technologies: [$Technology] +countries: [$Country] +application-area: [$Area] +--- + +# $Title + +## Description + +$Description +"@ + Set-Content -LiteralPath (Join-Path $directory "$Slug.md") -Value $content -Encoding utf8NoBOM +} + +function Test-InvalidSourceIndexing { + param( + [string] $FixtureRoot, + [string] $Field, + [string] $ValidValue, + [string] $InvalidValue + ) + + New-NeutralArticle -FixtureRoot $FixtureRoot -Layer microsoft -Slug valid-source + New-NeutralArticle -FixtureRoot $FixtureRoot -Layer community -Slug invalid-source + $articlePath = Join-Path $FixtureRoot 'community\knowledge\neutral\invalid-source.md' + $text = [IO.File]::ReadAllText($articlePath, $utf8) + $text = $text.Replace("$Field`: $ValidValue", "$Field`: $InvalidValue") + [IO.File]::WriteAllText($articlePath, $text, $utf8) + + $indexPath = Join-Path (Split-Path $FixtureRoot -Parent) ("$Field-index.json") + $generation = @(& $generator -BCQualityRoot $FixtureRoot -IndexPath $indexPath 3>&1) + $warnings = @($generation | Where-Object { $_ -is [Management.Automation.WarningRecord] }) + Assert-Equal $warnings.Count 1 "scalar $Field source emits one omission warning" + Assert-True ( + $warnings[0].Message -match + "Skipping invalid knowledge article 'community/knowledge/neutral/invalid-source\.md': frontmatter field '$([regex]::Escape($Field))' must use non-empty bracket-array syntax\." + ) "scalar $Field warning identifies the exact path and reason" + $prepared = Get-Content -LiteralPath $indexPath -Raw -Encoding utf8 | ConvertFrom-Json + Assert-Equal $prepared.articleCount 1 "scalar $Field source is omitted while its valid sibling is indexed" + Assert-Sequence $prepared.articles.path @('microsoft/knowledge/neutral/valid-source.md') "scalar $Field index contains only the valid sibling" + $catalog = & $search -BCQualityRoot $FixtureRoot -IndexPath $indexPath -Domain neutral | + ConvertFrom-Json + Assert-Sequence $catalog.candidates.path @('microsoft/knowledge/neutral/valid-source.md') "scalar $Field catalog retrieves the valid sibling" + $valid = & $getArticles -BCQualityRoot $FixtureRoot -IndexPath $indexPath ` + -Paths 'microsoft/knowledge/neutral/valid-source.md' | + ConvertFrom-Json + Assert-True $valid.complete "scalar $Field valid sibling body retrieves completely" + Assert-Throws { + & $getArticles -BCQualityRoot $FixtureRoot -IndexPath $indexPath ` + -Paths 'community/knowledge/neutral/invalid-source.md' + } 'Selected article is absent from the prepared index' "scalar $Field omitted source cannot be retrieved" +} + +function Test-InvalidSemanticIndexing { + param( + [string] $FixtureRoot, + [string] $CaseName, + [string] $Field, + [string] $ValidValue, + [string] $InvalidValue, + [string] $ExpectedReason + ) + + New-NeutralArticle -FixtureRoot $FixtureRoot -Layer microsoft -Slug valid-source + New-NeutralArticle -FixtureRoot $FixtureRoot -Layer community -Slug invalid-source + $articlePath = Join-Path $FixtureRoot 'community\knowledge\neutral\invalid-source.md' + $text = [IO.File]::ReadAllText($articlePath, $utf8) + $text = $text.Replace("$Field`: $ValidValue", "$Field`: $InvalidValue") + [IO.File]::WriteAllText($articlePath, $text, $utf8) + + $indexPath = Join-Path (Split-Path $FixtureRoot -Parent) ("$CaseName-index.json") + $generation = @(& $generator -BCQualityRoot $FixtureRoot -IndexPath $indexPath 3>&1) + $warnings = @($generation | Where-Object { $_ -is [Management.Automation.WarningRecord] }) + Assert-Equal $warnings.Count 1 "$CaseName emits one omission warning" + Assert-Equal $warnings[0].Message "Skipping invalid knowledge article 'community/knowledge/neutral/invalid-source.md': $ExpectedReason." "$CaseName warning identifies exact path and reason" + + $prepared = Get-Content -LiteralPath $indexPath -Raw -Encoding utf8 | ConvertFrom-Json + Assert-Equal $prepared.articleCount 1 "$CaseName omits invalid source and retains valid sibling" + Assert-Sequence $prepared.articles.path @('microsoft/knowledge/neutral/valid-source.md') "$CaseName index contains only valid sibling" + Assert-True ($prepared.sourceSnapshot -match '^[a-f0-9]{64}$') "$CaseName source snapshot remains valid" + $validRow = $prepared.articles[0] + $manifest = @( + [ordered]@{ path = $validRow.path; sha256 = $validRow.sourceSha256 } + ) + $manifestBytes = [Text.Encoding]::UTF8.GetBytes( + (ConvertTo-Json -InputObject $manifest -Depth 8 -Compress) + ) + $expectedSnapshot = [Convert]::ToHexString( + [Security.Cryptography.SHA256]::HashData($manifestBytes) + ).ToLowerInvariant() + Assert-Equal $prepared.sourceSnapshot $expectedSnapshot "$CaseName source snapshot covers only retained rows" + + $catalog = & $search -BCQualityRoot $FixtureRoot -IndexPath $indexPath -Domain neutral | + ConvertFrom-Json + Assert-Sequence $catalog.candidates.path @('microsoft/knowledge/neutral/valid-source.md') "$CaseName catalog retains valid sibling" + $valid = & $getArticles -BCQualityRoot $FixtureRoot -IndexPath $indexPath ` + -Paths 'microsoft/knowledge/neutral/valid-source.md' | + ConvertFrom-Json + Assert-True $valid.complete "$CaseName valid sibling body retrieves" + Assert-Throws { + & $getArticles -BCQualityRoot $FixtureRoot -IndexPath $indexPath ` + -Paths 'community/knowledge/neutral/invalid-source.md' + } 'Selected article is absent from the prepared index' "$CaseName invalid source cannot be retrieved" +} + +function Test-InvalidEnabledLayers { + param( + [string] $FixtureRoot, + [string] $CaseName, + $Layers, + [string] $ExpectedPattern + ) + + $indexPath = Join-Path (Split-Path $FixtureRoot -Parent) ("layers-$CaseName.json") + $arguments = @{ + BCQualityRoot = $FixtureRoot + IndexPath = $indexPath + EnabledLayers = $Layers + } + Assert-Throws { + & $generator @arguments + } $ExpectedPattern "$CaseName EnabledLayers fails" + Assert-True (-not (Test-Path -LiteralPath $indexPath)) "$CaseName fails before index creation" +} + +$tmp = Join-Path ([IO.Path]::GetTempPath()) ("bcquality_retrieval_" + [guid]::NewGuid().ToString('N')) +New-Item -ItemType Directory -Force -Path $tmp | Out-Null +try { + $indexPath = Join-Path $tmp 'knowledge-index.json' + & $generator -BCQualityRoot $Root -IndexPath $indexPath | Out-Null + $index = Get-Content -LiteralPath $indexPath -Raw -Encoding utf8 | ConvertFrom-Json + $diskArticlePaths = @( + foreach ($layer in 'microsoft', 'community', 'custom') { + $knowledge = Join-Path $Root "$layer\knowledge" + if (Test-Path -LiteralPath $knowledge) { + Get-ChildItem -LiteralPath $knowledge -Recurse -File -Filter '*.md' | + ForEach-Object { + [IO.Path]::GetRelativePath($Root, $_.FullName).Replace('\', '/') + } + } + } + ) | Sort-Object + Assert-Equal $index.articleCount $diskArticlePaths.Count 'index covers every current article' + Assert-True ($index.sourceSnapshot -match '^[a-f0-9]{64}$') 'index carries an exact source snapshot' + + $allCatalogRows = [Collections.Generic.List[object]]::new() + $domains = @($index.articles.domain | Sort-Object -Unique) + foreach ($domain in $domains) { + $catalog = Invoke-CatalogPages -Arguments @{ + BCQualityRoot = $Root + IndexPath = $indexPath + Domain = $domain + } + Assert-Equal $catalog.excluded.Count 0 "all layers enabled for $domain" + foreach ($row in $catalog.candidates) { + $allCatalogRows.Add($row) + } + } + + $expectedRows = @($index.articles | Sort-Object path) + $actualRows = @($allCatalogRows | Sort-Object path) + Assert-Equal $actualRows.Count $expectedRows.Count 'paged union has no top-k or query-based loss' + Assert-Sequence ($actualRows.path) ($expectedRows.path) 'paged union equals all READ-filtered candidates' + Assert-Equal @($actualRows.path | Sort-Object -Unique).Count $actualRows.Count 'catalog does not deduplicate distinct paths' + + $defaults = [ordered]@{ + 'bc-version' = @('all') + technologies = @('al') + countries = @('w1') + 'application-area' = @('all') + } + for ($i = 0; $i -lt $actualRows.Count; $i++) { + $actual = $actualRows[$i] + $expected = $expectedRows[$i] + Assert-Equal $actual.path $expected.path 'catalog preserves exact path' + Assert-Equal $actual.layer $expected.layer 'catalog preserves layer' + Assert-Sequence $actual.keywords $expected.keywords 'catalog preserves full keywords' + Assert-Equal $actual.title $expected.title 'catalog preserves title' + Assert-Equal $actual.description $expected.description 'catalog preserves one-line description' + + $unknown = [Collections.Generic.List[string]]::new() + foreach ($field in $defaults.Keys) { + $expectedValues = @($expected.$field) + $sentinel = switch ($field) { + 'bc-version' { 'all' } + 'countries' { 'w1' } + 'application-area' { 'all' } + default { '' } + } + if (-not $sentinel -or $expectedValues -notcontains $sentinel) { + $unknown.Add($field) + } + $hasField = $actual.PSObject.Properties.Name -ccontains $field + if (($expectedValues -join "`0") -ceq (@($defaults[$field]) -join "`0")) { + Assert-True (-not $hasField) "default field is inherited from page: $field" + } + else { + Assert-True $hasField "non-default field survives paging: $field" + Assert-Sequence $actual.$field $expectedValues "non-default field is exact: $field" + } + } + Assert-Equal $actual.applicability ($(if ($unknown.Count) { 'conditional' } else { 'applicable' })) 'applicability verdict is explicit' + Assert-Sequence $actual.unknownDimensions @($unknown) 'unknown dimensions are explicit' + } + + $performanceFirst = & $search -BCQualityRoot $Root -IndexPath $indexPath -Domain performance -MaxBytes 4096 | + ConvertFrom-Json + Assert-True (-not $performanceFirst.complete) 'large domain produces deterministic continuation' + Assert-Throws { + & $search -BCQualityRoot $Root -IndexPath $indexPath -Domain performance -MaxBytes 4096 -Offset $performanceFirst.continuation.offset + } 'Continuation requires Snapshot' 'continuation without snapshot fails' + Assert-Throws { + & $search -BCQualityRoot $Root -IndexPath $indexPath -Domain performance -Offset $performanceFirst.totalCount + } 'Invalid Offset' 'offset at total fails' + Assert-Throws { + & $search -BCQualityRoot $Root -IndexPath $indexPath -Domain performance -Offset 1 -Snapshot ('0' * 64) + } 'Snapshot changed' 'wrong snapshot fails' + + $changedRawIndex = Join-Path $tmp 'changed-raw-index.json' + $changedRaw = Get-Content -LiteralPath $indexPath -Raw -Encoding utf8 | ConvertFrom-Json + $changedRaw.generatedAt = [DateTimeOffset]::UtcNow.ToString('O') + $changedRaw | ConvertTo-Json -Depth 8 -Compress | + Set-Content -LiteralPath $changedRawIndex -Encoding utf8NoBOM -NoNewline + Assert-Throws { + & $search -BCQualityRoot $Root -IndexPath $changedRawIndex -Domain performance ` + -MaxBytes 4096 -Offset $performanceFirst.continuation.offset ` + -Snapshot $performanceFirst.continuation.snapshot + } 'Snapshot changed' 'continuation is bound to the exact prepared index bytes' + + $malformedIndex = Join-Path $tmp 'malformed.json' + Set-Content -LiteralPath $malformedIndex -Value '{not-json' -Encoding utf8NoBOM + Assert-Throws { + & $search -BCQualityRoot $Root -IndexPath $malformedIndex -Domain performance + } 'Malformed knowledge index JSON' 'malformed JSON fails' + + $unsafeIndex = Join-Path $tmp 'unsafe.json' + $unsafe = Get-Content -LiteralPath $indexPath -Raw -Encoding utf8 | ConvertFrom-Json + $unsafe.articles[0].path = '../outside.md' + $unsafe | ConvertTo-Json -Depth 8 -Compress | + Set-Content -LiteralPath $unsafeIndex -Encoding utf8NoBOM + Assert-Throws { + & $search -BCQualityRoot $Root -IndexPath $unsafeIndex -Domain performance + } 'Invalid knowledge path' 'unsafe indexed path fails' + + $invalidRowIndex = Join-Path $tmp 'invalid-row.json' + $invalidRow = Get-Content -LiteralPath $indexPath -Raw -Encoding utf8 | ConvertFrom-Json + $invalidRow.articles[0].keywords = @() + $invalidRow | ConvertTo-Json -Depth 8 -Compress | + Set-Content -LiteralPath $invalidRowIndex -Encoding utf8NoBOM + Assert-Throws { + & $search -BCQualityRoot $Root -IndexPath $invalidRowIndex -Domain performance + } 'Malformed knowledge index row' 'malformed index row fails' + + $semanticCorruptIndex = Join-Path $tmp 'semantic-corrupt-row.json' + $semanticCorrupt = Get-Content -LiteralPath $indexPath -Raw -Encoding utf8 | ConvertFrom-Json + $semanticCorrupt.articles[0].countries = @('usa') + $semanticCorrupt | ConvertTo-Json -Depth 8 -Compress | + Set-Content -LiteralPath $semanticCorruptIndex -Encoding utf8NoBOM + Assert-Throws { + & $search -BCQualityRoot $Root -IndexPath $semanticCorruptIndex -Domain performance + } 'Malformed knowledge index row.*invalid countries' 'search rejects semantically invalid external index rows' + + $corruptSemanticCases = @( + @{ name = 'uppercase-all'; field = 'bc-version'; value = @('ALL'); reason = 'invalid bc-version' }, + @{ name = 'uppercase-w1'; field = 'countries'; value = @('W1'); reason = 'invalid countries' }, + @{ name = 'zero-open-range'; field = 'bc-version'; value = @('"0.."'); reason = 'invalid bc-version range bound' }, + @{ name = 'zero-closed-range'; field = 'bc-version'; value = @('"0..0"'); reason = 'invalid bc-version range bound' } + ) + foreach ($case in $corruptSemanticCases) { + $corruptPath = Join-Path $tmp ("corrupt-$($case.name).json") + $corrupt = Get-Content -LiteralPath $indexPath -Raw -Encoding utf8 | ConvertFrom-Json + $corrupt.articles[0].PSObject.Properties[$case.field].Value = $case.value + $corrupt | ConvertTo-Json -Depth 8 -Compress | + Set-Content -LiteralPath $corruptPath -Encoding utf8NoBOM + Assert-Throws { + & $search -BCQualityRoot $Root -IndexPath $corruptPath -Domain performance + } "Malformed knowledge index row.*$([regex]::Escape($case.reason))" "search rejects $($case.name) in an external index" + } + + $invalidUtf8Root = Join-Path $tmp 'invalid-utf8-source' + New-NeutralArticle -FixtureRoot $invalidUtf8Root -Layer microsoft -Slug valid-catalog + New-NeutralArticle -FixtureRoot $invalidUtf8Root -Layer community -Slug invalid-utf8-source + $invalidUtf8Article = Join-Path $invalidUtf8Root 'community\knowledge\neutral\invalid-utf8-source.md' + $validBytes = [IO.File]::ReadAllBytes($invalidUtf8Article) + [IO.File]::WriteAllBytes($invalidUtf8Article, [byte[]]@($validBytes + @(0xc3, 0x28))) + $invalidUtf8Index = Join-Path $tmp 'invalid-utf8-index.json' + $generation = @(& $generator -BCQualityRoot $invalidUtf8Root -IndexPath $invalidUtf8Index 3>&1) + $warnings = @($generation | Where-Object { $_ -is [Management.Automation.WarningRecord] }) + Assert-Equal $warnings.Count 1 'malformed UTF-8 source emits one omission warning' + Assert-Equal $warnings[0].Message "Skipping invalid knowledge article 'community/knowledge/neutral/invalid-utf8-source.md': invalid UTF-8." 'malformed UTF-8 warning identifies the exact path and reason' + $invalidUtf8Prepared = Get-Content -LiteralPath $invalidUtf8Index -Raw -Encoding utf8 | + ConvertFrom-Json + Assert-Equal $invalidUtf8Prepared.articleCount 1 'malformed UTF-8 source is omitted while its valid sibling is indexed' + Assert-Sequence $invalidUtf8Prepared.articles.path @('microsoft/knowledge/neutral/valid-catalog.md') 'malformed UTF-8 index contains only the valid sibling' + $validCatalog = & $search -BCQualityRoot $invalidUtf8Root -IndexPath $invalidUtf8Index -Domain neutral | + ConvertFrom-Json + Assert-Sequence $validCatalog.candidates.path @('microsoft/knowledge/neutral/valid-catalog.md') 'catalog retrieves the valid sibling after malformed UTF-8 omission' + $validBody = & $getArticles -BCQualityRoot $invalidUtf8Root -IndexPath $invalidUtf8Index ` + -Paths 'microsoft/knowledge/neutral/valid-catalog.md' | + ConvertFrom-Json + Assert-True $validBody.complete 'valid sibling body retrieves after malformed UTF-8 omission' + Assert-Throws { + & $getArticles -BCQualityRoot $invalidUtf8Root -IndexPath $invalidUtf8Index ` + -Paths 'community/knowledge/neutral/invalid-utf8-source.md' + } 'Selected article is absent from the prepared index' 'omitted malformed UTF-8 source cannot be retrieved' + + $scalarCases = @( + @{ field = 'bc-version'; valid = '[all]'; invalid = 'all' }, + @{ field = 'keywords'; valid = '[neutral, retrieval, deterministic]'; invalid = 'neutral' }, + @{ field = 'technologies'; valid = '[al]'; invalid = 'al' }, + @{ field = 'countries'; valid = '[w1]'; invalid = 'w1' }, + @{ field = 'application-area'; valid = '[all]'; invalid = 'all' } + ) + foreach ($case in $scalarCases) { + Test-InvalidSourceIndexing -FixtureRoot (Join-Path $tmp "scalar-$($case.field)") ` + -Field $case.field -ValidValue $case.valid -InvalidValue $case.invalid + } + + $semanticCases = @( + @{ name = 'mixed-version-sentinel'; field = 'bc-version'; valid = '[all]'; invalid = '[all, 27]'; reason = 'mixed bc-version sentinel' }, + @{ name = 'invalid-country'; field = 'countries'; valid = '[w1]'; invalid = '[usa]'; reason = 'invalid countries' }, + @{ name = 'descending-version-range'; field = 'bc-version'; valid = '[all]'; invalid = '["28..27"]'; reason = 'descending bc-version range' }, + @{ name = 'malformed-version-range'; field = 'bc-version'; valid = '[all]'; invalid = '[twenty-seven]'; reason = 'invalid bc-version' }, + @{ name = 'malformed-keyword'; field = 'keywords'; valid = '[neutral, retrieval, deterministic]'; invalid = '[neutral, Bad_Token, deterministic]'; reason = 'invalid keywords' }, + @{ name = 'malformed-technology'; field = 'technologies'; valid = '[al]'; invalid = '[AL]'; reason = 'invalid technologies' }, + @{ name = 'malformed-application-area'; field = 'application-area'; valid = '[all]'; invalid = '[finance_]'; reason = 'invalid application-area' }, + @{ name = 'uppercase-version-sentinel'; field = 'bc-version'; valid = '[all]'; invalid = '[ALL]'; reason = 'invalid bc-version' }, + @{ name = 'uppercase-country-sentinel'; field = 'countries'; valid = '[w1]'; invalid = '[W1]'; reason = 'invalid countries' }, + @{ name = 'zero-open-version-range'; field = 'bc-version'; valid = '[all]'; invalid = '["0.."]'; reason = 'invalid bc-version range bound' }, + @{ name = 'zero-closed-version-range'; field = 'bc-version'; valid = '[all]'; invalid = '["0..0"]'; reason = 'invalid bc-version range bound' } + ) + foreach ($case in $semanticCases) { + Test-InvalidSemanticIndexing -FixtureRoot (Join-Path $tmp "semantic-$($case.name)") ` + -CaseName $case.name -Field $case.field -ValidValue $case.valid ` + -InvalidValue $case.invalid -ExpectedReason $case.reason + } + + Assert-Throws { + & $search -BCQualityRoot $Root -IndexPath $indexPath -Domain ('x' * 2000) -MaxBytes 1024 + } 'Page envelope exceeds' 'oversized page envelope fails' + + $articlePaths = @($index.articles.path | Sort-Object) + Assert-Sequence $articlePaths $diskArticlePaths 'exact article path union matches disk' + Assert-Throws { + & $getArticles -BCQualityRoot $Root -IndexPath $indexPath -Paths @($articlePaths[0..8]) + } 'exceeds MaxArticles=8' 'exact retrieval rejects path batches larger than eight' + $samplePaths = @( + foreach ($layer in 'microsoft', 'community', 'custom') { + $knowledge = Join-Path $Root "$layer\knowledge" + if (Test-Path -LiteralPath $knowledge) { + Get-ChildItem -LiteralPath $knowledge -Recurse -File | + Where-Object Name -Match '\.(good|bad)\.[a-z0-9]+$' | + ForEach-Object { + [IO.Path]::GetRelativePath($Root, $_.FullName).Replace('\', '/') + } + } + } + ) | Sort-Object + Test-BodyRoundTrip -Paths $articlePaths -IndexPath $indexPath + Test-BodyRoundTrip -Paths $samplePaths -IndexPath $indexPath -Samples + + $fixtureRoot = Join-Path $tmp 'neutral' + New-NeutralArticle -FixtureRoot $fixtureRoot -Layer microsoft -Slug default + New-NeutralArticle -FixtureRoot $fixtureRoot -Layer community -Slug versioned -Version '"27.."' -Technology javascript -Country dk -Area finance -Title 'Versioned neutral example' + New-NeutralArticle -FixtureRoot $fixtureRoot -Layer custom -Slug localized -Version 28 -Technology al -Country de -Area service -Title 'Localized neutral example' + $fixtureIndex = Join-Path $tmp 'neutral-index.json' + & $generator -BCQualityRoot $fixtureRoot -IndexPath $fixtureIndex | Out-Null + + foreach ($case in @( + @{ name = 'uppercase'; layers = @('Microsoft'); pattern = 'unique canonical lowercase layer names' }, + @{ name = 'duplicate'; layers = @('microsoft', 'microsoft'); pattern = 'unique canonical lowercase layer names' }, + @{ name = 'unknown'; layers = @('partner'); pattern = 'unique canonical lowercase layer names' }, + @{ name = 'null'; layers = $null; pattern = 'must be an array' } + )) { + Test-InvalidEnabledLayers -FixtureRoot $fixtureRoot -CaseName $case.name ` + -Layers $case.layers -ExpectedPattern $case.pattern + } + $subsetIndex = Join-Path $tmp 'community-only-index.json' + & $generator -BCQualityRoot $fixtureRoot -IndexPath $subsetIndex ` + -EnabledLayers @('community') | Out-Null + $subset = & $search -BCQualityRoot $fixtureRoot -IndexPath $subsetIndex ` + -Domain neutral -EnabledLayers @('community') | + ConvertFrom-Json + Assert-Equal $subset.candidateCount 1 'valid EnabledLayers subset builds and is consumable' + Assert-Sequence $subset.candidates.path @('community/knowledge/neutral/versioned.md') 'valid subset contains only its exact layer' + + $applicable = Invoke-CatalogPages -Arguments @{ + BCQualityRoot = $fixtureRoot + IndexPath = $fixtureIndex + Domain = 'neutral' + BCVersion = 28 + Technologies = @('al', 'javascript') + Countries = @('dk', 'de') + ApplicationAreas = @('finance', 'service') + } -MaxBytes 16000 + Assert-Equal $applicable.candidates.Count 3 'neutral layer/version rows all survive matching context' + Assert-True (@($applicable.candidates | Where-Object applicability -CEQ applicable).Count -eq 3) 'matching rows are applicable' + $versioned = $applicable.candidates | Where-Object path -CEQ 'community/knowledge/neutral/versioned.md' + Assert-Equal $versioned.layer community 'non-default layer survives' + Assert-Sequence $versioned.'bc-version' @('"27.."') 'original version metadata survives' + Assert-Equal $versioned.applicability applicable 'lowercase sentinels and positive open range remain applicable' + Assert-Sequence $versioned.technologies @('javascript') 'non-default technology survives' + Assert-Sequence $versioned.countries @('dk') 'non-default country survives' + Assert-Sequence $versioned.'application-area' @('finance') 'non-default application area survives' + + # Metadata validation accepts range bounds wider than Int32, so version + # matching must compare as bigint rather than coercing the bound down. + $wideRoot = Join-Path $tmp 'wide-version' + New-NeutralArticle -FixtureRoot $wideRoot -Layer microsoft -Slug wide-closed -Version '"1..99999999999"' + New-NeutralArticle -FixtureRoot $wideRoot -Layer microsoft -Slug wide-open -Version '"99999999999.."' + $wideIndex = Join-Path $tmp 'wide-version-index.json' + & $generator -BCQualityRoot $wideRoot -IndexPath $wideIndex | Out-Null + $wide = Invoke-CatalogPages -Arguments @{ + BCQualityRoot = $wideRoot + IndexPath = $wideIndex + Domain = 'neutral' + BCVersion = 28 + } -MaxBytes 16000 + Assert-Sequence $wide.candidates.path @('microsoft/knowledge/neutral/wide-closed.md') 'bc-version bounds beyond Int32 compare without overflow' + + $conditional = Invoke-CatalogPages -Arguments @{ + BCQualityRoot = $fixtureRoot + IndexPath = $fixtureIndex + Domain = 'neutral' + BCVersion = 28 + Technologies = @('al', 'javascript') + } -MaxBytes 16000 + $conditionalVersioned = $conditional.candidates | + Where-Object path -CEQ 'community/knowledge/neutral/versioned.md' + Assert-Equal $conditionalVersioned.applicability conditional 'unknown context produces conditional verdict' + Assert-Sequence $conditionalVersioned.unknownDimensions @('countries', 'application-area') 'unknown dimensions survive' + + $layerFiltered = Invoke-CatalogPages -Arguments @{ + BCQualityRoot = $fixtureRoot + IndexPath = $fixtureIndex + Domain = 'neutral' + EnabledLayers = @('microsoft') + } -MaxBytes 16000 + Assert-Equal $layerFiltered.candidates.Count 1 'enabled layer remains a candidate' + Assert-Equal $layerFiltered.excluded.Count 2 'disabled layers remain explicit' + Assert-Sequence ($layerFiltered.excluded.layer | Sort-Object) @('community', 'custom') 'excluded rows preserve layer' + + $oldSnapshot = $conditional.snapshot + Add-Content -LiteralPath (Join-Path $fixtureRoot 'community\knowledge\neutral\versioned.md') -Value ' ' -Encoding utf8NoBOM + $preparedCatalog = & $search -BCQualityRoot $fixtureRoot -IndexPath $fixtureIndex -Domain neutral | + ConvertFrom-Json + Assert-Equal $preparedCatalog.candidateCount 3 'catalog uses the prepared index without rehashing article bodies' + Assert-Throws { + & $getArticles -BCQualityRoot $fixtureRoot -IndexPath $fixtureIndex ` + -Paths 'community/knowledge/neutral/versioned.md' + } 'Selected article hash does not match the prepared index' 'exact retrieval detects selected article changes' + & $generator -BCQualityRoot $fixtureRoot -IndexPath $fixtureIndex | Out-Null + Assert-Throws { + & $search -BCQualityRoot $fixtureRoot -IndexPath $fixtureIndex -Domain neutral -Offset 1 -Snapshot $oldSnapshot + } 'Snapshot changed' 'continuation cannot cross rebuilt snapshots' + + $largeRoot = Join-Path $tmp 'large-catalog' + New-NeutralArticle -FixtureRoot $largeRoot -Layer microsoft -Slug huge-title -Title ('T' * 3000) + $largeIndex = Join-Path $tmp 'large-index.json' + & $generator -BCQualityRoot $largeRoot -IndexPath $largeIndex | Out-Null + Assert-Throws { + & $search -BCQualityRoot $largeRoot -IndexPath $largeIndex -Domain neutral -MaxBytes 1024 + } 'One complete candidates row|Page envelope exceeds' 'oversized catalog row fails without clipping' + + # The shared pager reports the oversized row's identity for any row shape; + # a row without a path must still reach its explicit offset-based failure. + . (Join-Path $Root 'tools/Bounded-Results.ps1') + $pagerHeader = [ordered]@{ version = 2; snapshot = ('0' * 64) } + foreach ($shape in @( + @{ name = 'dictionary'; row = [ordered]@{ blob = ('x' * 3000) } }, + @{ name = 'object'; row = [pscustomobject]@{ blob = ('x' * 3000) } } + )) { + Assert-Throws { + ConvertTo-BoundedPage -Header $pagerHeader ` + -Groups ([ordered]@{ rows = @($shape.row) }) -MaxBytes 1024 + } 'One complete rows row plus envelope exceeds MaxBytes=1024 at Offset=0' "oversized pathless $($shape.name) row fails with its offset identity" + } + + $bodyRoot = Join-Path $tmp 'body-failures' + New-NeutralArticle -FixtureRoot $bodyRoot -Layer microsoft -Slug huge-body -Description ('x' * 3000) + New-NeutralArticle -FixtureRoot $bodyRoot -Layer microsoft -Slug broken-link + New-NeutralArticle -FixtureRoot $bodyRoot -Layer microsoft -Slug continuation-one -Description ('a' * 300) + New-NeutralArticle -FixtureRoot $bodyRoot -Layer microsoft -Slug continuation-two -Description ('b' * 300) + New-NeutralArticle -FixtureRoot $bodyRoot -Layer microsoft -Slug invalid-utf8 + New-NeutralArticle -FixtureRoot $bodyRoot -Layer microsoft -Slug sample-one + New-NeutralArticle -FixtureRoot $bodyRoot -Layer microsoft -Slug sample-two + Add-Content -LiteralPath (Join-Path $bodyRoot 'microsoft\knowledge\neutral\sample-one.md') ` + -Value '[`sample-one.good.al`](sample-one.good.al)' -Encoding utf8NoBOM + Add-Content -LiteralPath (Join-Path $bodyRoot 'microsoft\knowledge\neutral\sample-two.md') ` + -Value '[`sample-two.good.al`](sample-two.good.al)' -Encoding utf8NoBOM + Set-Content -LiteralPath (Join-Path $bodyRoot 'microsoft\knowledge\neutral\sample-one.good.al') ` + -Value ('a' * 900) -Encoding utf8NoBOM + Set-Content -LiteralPath (Join-Path $bodyRoot 'microsoft\knowledge\neutral\sample-two.good.al') ` + -Value ('b' * 900) -Encoding utf8NoBOM + $bodyIndex = Join-Path $tmp 'body-index.json' + & $generator -BCQualityRoot $bodyRoot -IndexPath $bodyIndex | Out-Null + Assert-Throws { + & $getArticles -BCQualityRoot $bodyRoot -IndexPath $bodyIndex ` + -Paths 'microsoft/knowledge/neutral/huge-body.md' -MaxBytes 1024 + } 'No complete body plus continuation fits' 'oversized body fails without truncation' + Assert-Throws { + & $getArticles -BCQualityRoot $bodyRoot -IndexPath $bodyIndex -Paths '../outside.md' + } 'Invalid knowledge path' 'unsafe requested path fails' + Assert-Throws { + & $getArticles -BCQualityRoot $bodyRoot -IndexPath $bodyIndex ` + -Paths 'microsoft/knowledge/neutral/huge-body.md' -EnabledLayers community + } 'Layer disabled' 'disabled article layer fails' + Assert-Throws { + & $getArticles -BCQualityRoot $bodyRoot -IndexPath $bodyIndex -Paths @( + 'microsoft/knowledge/neutral/huge-body.md', + 'microsoft/knowledge/neutral/huge-body.md' + ) + } 'Duplicate requested path' 'duplicate exact paths fail' + + $brokenSample = Join-Path $bodyRoot 'microsoft\knowledge\neutral\broken-link.good.al' + Set-Content -LiteralPath $brokenSample -Value 'codeunit 1 Neutral { }' -Encoding utf8NoBOM + Assert-Throws { + & $getArticles -BCQualityRoot $bodyRoot -IndexPath $bodyIndex ` + -Paths 'microsoft/knowledge/neutral/broken-link.good.al' -Samples + } 'Sample is not linked' 'unlinked sample fails' + + $sampleContinuationPaths = @( + 'microsoft/knowledge/neutral/sample-one.good.al', + 'microsoft/knowledge/neutral/sample-two.good.al' + ) + $firstSamplePage = & $getArticles -BCQualityRoot $bodyRoot -IndexPath $bodyIndex ` + -Paths $sampleContinuationPaths -Samples -MaxBytes 1600 | + ConvertFrom-Json + Assert-True (-not $firstSamplePage.complete) 'bounded sample batch produces continuation' + Assert-Sequence $firstSamplePage.remainingPaths @('microsoft/knowledge/neutral/sample-two.good.al') 'sample continuation preserves pending path' + Add-Content -LiteralPath (Join-Path $bodyRoot 'microsoft\knowledge\neutral\sample-two.good.al') ` + -Value 'changed' -Encoding utf8NoBOM + Assert-Throws { + & $getArticles -BCQualityRoot $bodyRoot -IndexPath $bodyIndex ` + -Paths @($firstSamplePage.remainingPaths) -Samples ` + -Snapshot $firstSamplePage.continuation.snapshot + } 'Article snapshot changed' 'sample continuation rejects a changed pending sample' + + $continuationPaths = @( + 'microsoft/knowledge/neutral/continuation-one.md', + 'microsoft/knowledge/neutral/continuation-two.md' + ) + $firstBodyPage = & $getArticles -BCQualityRoot $bodyRoot -IndexPath $bodyIndex ` + -Paths $continuationPaths -MaxBytes 1300 | + ConvertFrom-Json + Assert-True (-not $firstBodyPage.complete) 'bounded article batch produces continuation' + Assert-Throws { + & $getArticles -BCQualityRoot $bodyRoot -IndexPath $bodyIndex ` + -Paths @($firstBodyPage.remainingPaths) -Snapshot ('0' * 64) + } 'Article snapshot changed' 'wrong article continuation snapshot fails' + Add-Content -LiteralPath (Join-Path $bodyRoot 'microsoft\knowledge\neutral\continuation-two.md') -Value 'changed' -Encoding utf8NoBOM + Assert-Throws { + & $getArticles -BCQualityRoot $bodyRoot -IndexPath $bodyIndex ` + -Paths @($firstBodyPage.remainingPaths) -Snapshot $firstBodyPage.continuation.snapshot + } 'Selected article hash does not match the prepared index' 'article continuation rejects a changed remaining body' + + $invalidUtf8 = Join-Path $bodyRoot 'microsoft\knowledge\neutral\invalid-utf8.md' + $indexedBytes = [IO.File]::ReadAllBytes($invalidUtf8) + [IO.File]::WriteAllBytes($invalidUtf8, [byte[]]@($indexedBytes + @(0xc3, 0x28))) + Assert-Throws { + & $getArticles -BCQualityRoot $bodyRoot -IndexPath $bodyIndex ` + -Paths 'microsoft/knowledge/neutral/invalid-utf8.md' + } 'Knowledge file is not valid strict UTF-8' 'invalid UTF-8 fails' + + Write-Host "Knowledge retrieval check PASSED: $($articlePaths.Count) articles and $($samplePaths.Count) samples round-tripped; catalog union was lossless and bounded." -ForegroundColor Green +} +finally { + Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue +} From 35d0966a8d45e8d4a7c2b0238afbffe338a31d2b Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Fri, 11 Sep 2026 15:24:20 +0200 Subject: [PATCH 04/35] Normalize recoverable leaf finding ranges (#180) * Normalize recoverable leaf ranges Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Run contract checks with review fixtures Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/contributing.md | 7 +- docs/standalone-runner.md | 20 ++- microsoft/skills/review/al-code-review.md | 13 +- skills/do.md | 57 ++++++-- tools/Test-ReviewContract.ps1 | 171 ++++++++++++++++++++++ tools/Test-ReviewFixtures.ps1 | 1 + 6 files changed, 249 insertions(+), 20 deletions(-) create mode 100644 tools/Test-ReviewContract.ps1 diff --git a/docs/contributing.md b/docs/contributing.md index 27da177..51f6d0f 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -161,12 +161,15 @@ If PyYAML is not installed in your development environment, install it with ```powershell python .github\scripts\validate_frontmatter.py --root . pwsh .\tools\Test-ReviewFixtures.ps1 -Root . +pwsh .\tools\Test-ReviewContract.ps1 -Root . ``` The first command checks schema, sections, naming, sample references, and skill registration. The second checks that every review leaf has a valid -positive/clean sample pair. Neither proves a model will find every defect. -See [evaluation](../evaluation/README.md) for optional model-based scoring. +positive/clean sample pair. The third checks the cross-surface findings-report +contract and its bounded range-normalization cases. None proves a model will +find every defect. See [evaluation](../evaluation/README.md) for optional +model-based scoring. In the PR description, explain the mistake being prevented, supporting evidence, applicable BC versions, and why the chosen domain owns it. For a diff --git a/docs/standalone-runner.md b/docs/standalone-runner.md index 61ecb55..5829e4e 100644 --- a/docs/standalone-runner.md +++ b/docs/standalone-runner.md @@ -52,10 +52,17 @@ only result. 4. When an action skill declares `sub-skills`, execute every relevant leaf as a discrete invocation. Leaves are independent and may be scheduled serially or concurrently. -5. Collect each complete findings-report into `sub-results` in the declared +5. Capture the exact Task return as the immutable raw audit payload and primary + transport. Preserve it unchanged in private artifacts or host logs. Before + the full DO acceptance gate, create a normalized candidate only for DO's + bounded optional-range case, record that normalization separately in private + telemetry, and accept the candidate only if the entire copy passes the + unchanged strict gate. The accepted report contains no undeclared telemetry + fields. +6. Collect each accepted findings-report into `sub-results` in the declared `sub-skills` order, not completion order. Run the super-skill self-review only after all leaves have finished. -6. Apply the DO composition, failure, deduplication, reference-integrity, and +7. Apply the DO composition, failure, deduplication, reference-integrity, and outcome rules. Return strict JSON before rendering it for people or another system. @@ -86,6 +93,15 @@ A compatible runner: - invokes every worklisted leaf exactly once unless a documented retry replaces a failed attempt; - keeps leaf contexts isolated and passes only the inputs they declare; +- preserves each raw Task return unchanged for audit and distinguishes it from + any normalized accepted copy; +- removes only an optional range whose positive integer bounds contain the + primary line but start before it, and only when the complete report has no + other defect and the finding has no `suggested-code`; +- records normalization only in private runner telemetry and never adds fields + to the findings-report; +- rejects reversed, invalid, or out-of-bounds ranges, range mismatches attached + to `suggested-code`, and every repair outside DO's bounded exception; - preserves every leaf report, including failed reports, in `sub-results`; - excludes unreliable findings from failed leaves and returns `partial` when only part of the review is reliable; diff --git a/microsoft/skills/review/al-code-review.md b/microsoft/skills/review/al-code-review.md index 6a577ba..9239220 100644 --- a/microsoft/skills/review/al-code-review.md +++ b/microsoft/skills/review/al-code-review.md @@ -67,7 +67,7 @@ The Action step consists of **discrete leaf invocations**, not one combined gene - **Isolate leaf invocations when the host supports it.** Each sub-skill SHOULD run in a fresh model call or child context containing only its assigned source paths, READ/DO contracts, the leaf instructions, the complete bounded domain catalog per READ, and articles that leaf worklists. Preserve each catalog row's exact `path`; the leaf must copy references from that catalog. - **Keep run artifacts private.** Before dispatch, allocate a new GUID-named directory under the current session's artifact directory and a distinct scratch/report child directory for every leaf. Pass a leaf only its own assigned source paths and child directory, never the run root or sibling paths. A leaf MUST NOT discover, enumerate, read, modify, or delete sibling artifacts. Do not reuse a prior run directory, and do not clean up any run artifact until every leaf has finished and consolidation is complete. -- **Use the exact Task return as the report.** Capture each leaf's exact return as the primary transport and apply DO's consumer acceptance gate before rollup. Worker-side persistence of the same report in its private directory is optional and redundant; a missing report file does not invalidate an otherwise valid exact return. +- **Keep raw Task transport distinct from the accepted copy.** Capture the exact Task return as the immutable raw audit payload and primary transport. Preserve it unchanged in the leaf's private artifacts or host log. Then apply DO's bounded pre-gate range normalization, when eligible, and its full consumer acceptance gate. The report accepted for rollup is the exact return when no normalization occurred, or the normalized candidate copy when DO permits it; worker-side persistence of another report file is optional and redundant. - **Treat automatic output spills as host-owned.** If the host reports that a Task return was automatically spilled, the coordinator MAY read that file read-only only at the exact path returned by the tool. Never modify, delete, enumerate around, or reuse an automatic spill path. Never bypass a content-exclusion or access denial. - Treat each sub-skill in the worklist as its own pass: read the sub-skill's instructions, apply its Source → Relevance → Worklist → Action steps to the orchestrator-supplied inputs, and produce that sub-skill's complete findings-report independently. - Do not collapse multiple sub-skills into one shared reasoning step. Each sub-skill has a distinct knowledge subset and a distinct evaluation procedure; sharing one rolled-up scan dilutes per-skill attention and causes leaves to silently underreport (this has been observed in production: leaf skills returned empty `findings[]` while their standalone runs against the same diff produced multiple matches). @@ -80,7 +80,7 @@ The Action step consists of **discrete leaf invocations**, not one combined gene For each sub-skill in the worklist: 1. Invoke the sub-skill with the orchestrator's inputs, passing only the subset each sub-skill declares in its `inputs`. -2. Capture the exact Task return and validate it against DO's consumer acceptance gate before accepting it. Preserve an invalid raw return unchanged in the leaf's private artifacts or host log; do not reconstruct or repair it. Record a separate failed validation result with no findings for rollup. +2. Capture the exact Task return as the immutable raw audit payload and primary transport. Preserve it unchanged in the leaf's private artifacts or host log before deriving a candidate. Apply only DO's bounded pre-gate normalization: when the complete raw report has no other defect, a finding has positive-integer `line`, `start-line`, and `end-line`, `start-line <= line <= end-line`, `start-line != line`, and no `suggested-code` field, copy the complete report and remove only that finding's optional `location.range`. Record the normalization separately in private run telemetry or artifacts, never in the findings-report. Validate the entire candidate through DO's existing strict acceptance gate. Accept the exact return when unchanged or the normalized candidate when it passes; otherwise record a separate failed validation result with no findings for rollup. Do not reconstruct JSON, infer fields, alter paths or references, clamp lines, normalize reversed or out-of-bounds ranges, remove a range associated with `suggested-code`, or salvage individual findings. 3. Append the accepted findings-report, or the separate failed validation result, to `sub-results`. If its `outcome` is `failed`, stop here for this sub-skill: its findings are not reliable per the DO contract and MUST NOT be copied into the super-skill's top-level `findings[]` or counted in `summary.counts`. 4. Otherwise, compare each entry from the sub-skill's `findings[]` with findings already rolled up. Two findings are duplicates when they point to the same file and overlapping line/range and prescribe materially the same correction, even when their knowledge-file IDs differ. Merge duplicates instead of appending both: keep the more specific domain owner, preserve that finding's optional `domain` field verbatim (including its absence), use its reference as `references[0]` and therefore as `id`, append the other references as supporting references, keep the highest severity and confidence justified by either report, and preserve one self-contained message. Article and leaf ownership notes decide specificity; do not choose by execution order. 5. Append each non-duplicate finding, setting `from-sub-skill` to the sub-skill's `skill.id` and preserving its optional `domain` field verbatim, including its absence. For non-citation findings (those whose `id` is a skill-defined slug rather than a reference path), prefix `id` with `:` to prevent collisions across sub-skills. Other finding fields are preserved. @@ -126,9 +126,12 @@ Calculate `summary.counts` from the final top-level `findings[]`, after failed s Derive `outcome` using the DO rollup rules. `outcome-reason` is populated for `partial` and `failed` and SHOULD summarize per-sub-skill state, for example: *"al-security-review failed (tool timeout); al-performance-review completed."* Before emitting the rollup, apply DO's consumer acceptance gate to every nested -and top-level finding. Treat an invalid sub-result as failed and exclude all of -its findings from the top-level rollup. Preserve its exact raw payload -separately; never reconstruct it into a success-shaped report. +and top-level finding. A leaf's nested report is its accepted exact return or +its accepted normalized candidate copy; its exact Task return remains the +separate immutable raw audit payload. Treat an invalid sub-result as failed and +exclude all of its findings from the top-level rollup. Never reconstruct it +into a success-shaped report or perform normalization beyond DO's bounded +exception. ## Output diff --git a/skills/do.md b/skills/do.md index f86509b..9abdf58 100644 --- a/skills/do.md +++ b/skills/do.md @@ -161,13 +161,49 @@ AL source is the common failure case. Quoted identifiers (for example `Rec."No." ### Consumer acceptance gate -The exact action-skill return is the primary report transport. Before accepting -it as a findings-report, a coordinator or host MUST validate it -deterministically: +Capture the exact Task return as the immutable raw audit payload and primary +transport. Preserve it unchanged in private run artifacts or host logs before +creating any derived value. The accepted findings-report is either that exact +return or the bounded normalized candidate described below; the raw audit +payload never changes. -1. Parse the exact return as strict JSON and validate every required field, - enum, type, conditional requirement, summary count, coverage value, and - leaf/super-skill constraint against this output contract. +Before the full acceptance gate, a coordinator MAY create a normalized +candidate copy only through this deterministic procedure: + +1. Parse the exact return as strict JSON and provisionally check the complete + report without mutating it. Every acceptance rule below MUST already pass + except for one or more findings whose optional `location.range` has + `start-line != line`. +2. Each such finding is eligible only when `location.line`, + `location.range.start-line`, and `location.range.end-line` are positive + integers, `start-line <= line <= end-line`, and the finding does not contain + the `suggested-code` field. Field presence disqualifies normalization even + if its value is empty because suggested code may be bound to the reported + range. +3. Deep-copy the complete parsed report. In the candidate copy, remove only + `location.range` from every eligible finding. Retain `location.line` and + every other value unchanged. Do not add normalization metadata to the + findings-report. +4. Record each removed range separately in private run telemetry or artifacts, + associated with the immutable raw audit payload. This record is + runner-owned and is not part of the declared report schema. +5. Validate the entire normalized candidate with the existing full consumer + acceptance gate below. Only a candidate that passes every rule becomes the + accepted copy used for rollup. If any other validation defect exists, or + full validation fails, discard the candidate, preserve the raw payload, and + fail the complete leaf as before. + +This exception does not infer missing fields, alter references or paths, clamp +line numbers, repair JSON, normalize a reversed or out-of-bounds range, remove +a range from a finding containing `suggested-code`, or salvage arbitrary +individual findings. + +Before accepting either the exact return or an eligible normalized candidate +as a findings-report, a coordinator or host MUST validate it deterministically: + +1. Validate every required field, enum, type, conditional requirement, summary + count, coverage value, and leaf/super-skill constraint against this output + contract. 2. For every knowledge-backed finding, verify each `references[].path` is an exact repo-relative knowledge path that exists in the live BCQuality snapshot, and verify `findings[].id` exactly equals @@ -183,11 +219,10 @@ deterministically: Validation failure invalidates the complete return; consumers MUST NOT salvage individual findings, infer missing fields, reconstruct JSON, clamp ranges, rewrite paths, or otherwise silently repair model output. Preserve the invalid -raw payload unchanged in private run artifacts or host logs. Record a separate -failed validation result for that leaf with no findings, and derive the -super-skill outcome as `partial` or `failed` using the normal rollup rules. -Worker-side report-file persistence is optional and never replaces validation -of the exact return. +raw payload unchanged. Record a separate failed validation result for that leaf +with no findings, and derive the super-skill outcome as `partial` or `failed` +using the normal rollup rules. Worker-side report-file persistence is optional +and never replaces validation of the accepted exact or normalized copy. ### Field semantics diff --git a/tools/Test-ReviewContract.ps1 b/tools/Test-ReviewContract.ps1 new file mode 100644 index 0000000..1d40058 --- /dev/null +++ b/tools/Test-ReviewContract.ps1 @@ -0,0 +1,171 @@ +<# +.SYNOPSIS + Validates the bounded leaf-range normalization contract. + +.DESCRIPTION + BCQuality has no executable findings-report consumer. These assertions keep + the normative DO contract, AL coordinator, and standalone runner aligned + while exercising the exact normalization predicate against representative + safe and ambiguous inputs. +#> +[CmdletBinding()] +param( + [string] $Root = (Resolve-Path (Join-Path $PSScriptRoot '..')) +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +$Root = (Resolve-Path -LiteralPath $Root).Path + +function Assert-True { + param( + [bool] $Condition, + [string] $Message + ) + + if (-not $Condition) { + throw "Assertion failed: $Message" + } +} + +function Assert-Contains { + param( + [string] $Text, + [string] $Expected, + [string] $Message + ) + + Assert-True $Text.Contains($Expected) $Message +} + +function Test-PositiveInteger { + param([object] $Value) + + if (($null -eq $Value) -or ($Value -is [bool]) -or ($Value -isnot [ValueType])) { + return $false + } + + $number = [double]$Value + return [double]::IsFinite($number) -and ($number -gt 0) -and ([math]::Truncate($number) -eq $number) +} + +function Test-RangeNormalizationEligibility { + param([pscustomobject] $Finding) + + if ($Finding.PSObject.Properties.Name -contains 'suggested-code') { + return $false + } + if (-not ($Finding.PSObject.Properties.Name -contains 'location')) { + return $false + } + if (-not ($Finding.location.PSObject.Properties.Name -contains 'line')) { + return $false + } + if (-not ($Finding.location.PSObject.Properties.Name -contains 'range')) { + return $false + } + + $range = $Finding.location.range + if (-not ($range.PSObject.Properties.Name -contains 'start-line') -or + -not ($range.PSObject.Properties.Name -contains 'end-line')) { + return $false + } + + $line = $Finding.location.line + $startLine = $range.'start-line' + $endLine = $range.'end-line' + if (-not (Test-PositiveInteger $line) -or + -not (Test-PositiveInteger $startLine) -or + -not (Test-PositiveInteger $endLine)) { + return $false + } + + return ($startLine -le $line) -and ($line -le $endLine) -and ($startLine -ne $line) +} + +$transportSentence = 'Capture the exact Task return as the immutable raw audit payload and primary transport.' +$doContract = Get-Content -LiteralPath (Join-Path $Root 'skills/do.md') -Raw +$coordinatorContract = Get-Content -LiteralPath (Join-Path $Root 'microsoft/skills/review/al-code-review.md') -Raw +$runnerContract = Get-Content -LiteralPath (Join-Path $Root 'docs/standalone-runner.md') -Raw + +foreach ($surface in @( + [pscustomobject]@{ Name = 'DO'; Text = ($doContract -replace '\s+', ' ') } + [pscustomobject]@{ Name = 'AL coordinator'; Text = ($coordinatorContract -replace '\s+', ' ') } + [pscustomobject]@{ Name = 'standalone runner'; Text = ($runnerContract -replace '\s+', ' ') } +)) { + Assert-Contains $surface.Text $transportSentence "$($surface.Name) preserves exact Task transport wording" +} + +$normalizedDoContract = $doContract -replace '\s+', ' ' +foreach ($expected in @( + 'positive integers', + 'start-line <= line <= end-line', + 'does not contain the `suggested-code` field', + 'remove only', + 'private run telemetry or artifacts', + 'Validate the entire normalized candidate', + 'If any other validation defect exists', + 'salvage arbitrary individual findings' +)) { + Assert-Contains $normalizedDoContract $expected "DO documents '$expected'" +} + +$cases = @( + [pscustomobject]@{ + Name = 'contained mismatched range without suggested code' + Expected = $true + Finding = '{"message":"keep me","location":{"file":"src/codeunit.al","line":37,"range":{"start-line":36,"end-line":38}}}' | ConvertFrom-Json + } + [pscustomobject]@{ + Name = 'aligned range' + Expected = $false + Finding = '{"location":{"line":37,"range":{"start-line":37,"end-line":38}}}' | ConvertFrom-Json + } + [pscustomobject]@{ + Name = 'suggested code present' + Expected = $false + Finding = '{"location":{"line":37,"range":{"start-line":36,"end-line":38}},"suggested-code":""}' | ConvertFrom-Json + } + [pscustomobject]@{ + Name = 'line outside range' + Expected = $false + Finding = '{"location":{"line":39,"range":{"start-line":36,"end-line":38}}}' | ConvertFrom-Json + } + [pscustomobject]@{ + Name = 'reversed range' + Expected = $false + Finding = '{"location":{"line":37,"range":{"start-line":38,"end-line":36}}}' | ConvertFrom-Json + } + [pscustomobject]@{ + Name = 'zero bound' + Expected = $false + Finding = '{"location":{"line":1,"range":{"start-line":0,"end-line":2}}}' | ConvertFrom-Json + } + [pscustomobject]@{ + Name = 'fractional primary line' + Expected = $false + Finding = '{"location":{"line":37.5,"range":{"start-line":36,"end-line":38}}}' | ConvertFrom-Json + } + [pscustomobject]@{ + Name = 'missing end line' + Expected = $false + Finding = '{"location":{"line":37,"range":{"start-line":36}}}' | ConvertFrom-Json + } +) + +foreach ($case in $cases) { + $actual = Test-RangeNormalizationEligibility $case.Finding + Assert-True ($actual -eq $case.Expected) "$($case.Name) eligibility is $($case.Expected)" +} + +$rawFinding = $cases[0].Finding +$candidateFinding = $rawFinding | ConvertTo-Json -Depth 10 | ConvertFrom-Json +$candidateFinding.location.PSObject.Properties.Remove('range') + +Assert-True ($rawFinding.location.PSObject.Properties.Name -contains 'range') 'raw finding remains unchanged' +Assert-True (-not ($candidateFinding.location.PSObject.Properties.Name -contains 'range')) 'candidate removes only the optional range' +Assert-True ($candidateFinding.location.line -eq $rawFinding.location.line) 'candidate preserves the primary line' +Assert-True ($candidateFinding.message -ceq $rawFinding.message) 'candidate preserves all other finding content' + +Write-Output "Review contract validation passed ($($cases.Count) normalization cases)." diff --git a/tools/Test-ReviewFixtures.ps1 b/tools/Test-ReviewFixtures.ps1 index a9912b7..c4b0bf1 100644 --- a/tools/Test-ReviewFixtures.ps1 +++ b/tools/Test-ReviewFixtures.ps1 @@ -434,6 +434,7 @@ if ($PrepareDirectory) { } if (-not $ResultsPath -and -not $ResultsDirectory) { + & (Join-Path $PSScriptRoot 'Test-ReviewContract.ps1') -Root $Root Write-Host "Review fixture validation PASSED: $($cases.Count) cases cover $($leafDomains.Count) leaf domains." -ForegroundColor Green exit 0 } From 45ac371e7a8252f2ce7176060a640ea9506b320c Mon Sep 17 00:00:00 2001 From: Stefano Demiliani <33155438+demiliani@users.noreply.github.com> Date: Mon, 14 Sep 2026 12:42:45 +0200 Subject: [PATCH 05/35] Add AL-focused AppSource validation guidance (#142) * knowledge(appsource): add AL validation guidance * Address Marketplace review feedback * Address remaining Marketplace review feedback * Align AppSource review applicability outcome --- .../define-profiles-as-al-objects.bad.al | 12 +++++++++ .../define-profiles-as-al-objects.good.al | 6 +++++ .../define-profiles-as-al-objects.md | 26 +++++++++++++++++++ .../do-not-hard-code-time-zone-offsets.bad.al | 7 +++++ ...do-not-hard-code-time-zone-offsets.good.al | 7 +++++ .../do-not-hard-code-time-zone-offsets.md | 26 +++++++++++++++++++ ...-web-service-paths-free-of-ui-calls.bad.al | 21 +++++++++++++++ ...web-service-paths-free-of-ui-calls.good.al | 15 +++++++++++ ...keep-web-service-paths-free-of-ui-calls.md | 26 +++++++++++++++++++ ...on-actions-with-addfirst-or-addlast.bad.al | 15 +++++++++++ ...n-actions-with-addfirst-or-addlast.good.al | 15 +++++++++++ ...ension-actions-with-addfirst-or-addlast.md | 26 +++++++++++++++++++ ...category-on-searchable-entry-points.bad.al | 20 ++++++++++++++ ...ategory-on-searchable-entry-points.good.al | 21 +++++++++++++++ ...sagecategory-on-searchable-entry-points.md | 26 +++++++++++++++++++ .../use-invariant-date-literals.bad.al | 10 +++++++ .../use-invariant-date-literals.good.al | 7 +++++ .../appsource/use-invariant-date-literals.md | 26 +++++++++++++++++++ .../skills/review/al-appsource-review.md | 14 +++++++--- 19 files changed, 322 insertions(+), 4 deletions(-) create mode 100644 community/knowledge/appsource/define-profiles-as-al-objects.bad.al create mode 100644 community/knowledge/appsource/define-profiles-as-al-objects.good.al create mode 100644 community/knowledge/appsource/define-profiles-as-al-objects.md create mode 100644 community/knowledge/appsource/do-not-hard-code-time-zone-offsets.bad.al create mode 100644 community/knowledge/appsource/do-not-hard-code-time-zone-offsets.good.al create mode 100644 community/knowledge/appsource/do-not-hard-code-time-zone-offsets.md create mode 100644 community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.bad.al create mode 100644 community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.good.al create mode 100644 community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.md create mode 100644 community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.bad.al create mode 100644 community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.good.al create mode 100644 community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.md create mode 100644 community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.bad.al create mode 100644 community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.good.al create mode 100644 community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.md create mode 100644 community/knowledge/appsource/use-invariant-date-literals.bad.al create mode 100644 community/knowledge/appsource/use-invariant-date-literals.good.al create mode 100644 community/knowledge/appsource/use-invariant-date-literals.md diff --git a/community/knowledge/appsource/define-profiles-as-al-objects.bad.al b/community/knowledge/appsource/define-profiles-as-al-objects.bad.al new file mode 100644 index 0000000..20438c8 --- /dev/null +++ b/community/knowledge/appsource/define-profiles-as-al-objects.bad.al @@ -0,0 +1,12 @@ +codeunit 50100 "Rental Profile Install" +{ + Subtype = Install; + + trigger OnInstallAppPerDatabase() + var + RentalProfile: Record Profile; + begin + RentalProfile.Init(); + RentalProfile.Insert(true); + end; +} \ No newline at end of file diff --git a/community/knowledge/appsource/define-profiles-as-al-objects.good.al b/community/knowledge/appsource/define-profiles-as-al-objects.good.al new file mode 100644 index 0000000..23ed6bf --- /dev/null +++ b/community/knowledge/appsource/define-profiles-as-al-objects.good.al @@ -0,0 +1,6 @@ +profile "RENTAL MANAGER" +{ + Caption = 'Rental Manager'; + Description = 'Manages rental agreements and equipment availability.'; + RoleCenter = "Business Manager Role Center"; +} \ No newline at end of file diff --git a/community/knowledge/appsource/define-profiles-as-al-objects.md b/community/knowledge/appsource/define-profiles-as-al-objects.md new file mode 100644 index 0000000..6f34aee --- /dev/null +++ b/community/knowledge/appsource/define-profiles-as-al-objects.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: appsource +keywords: [profile-object, profile-table, install-codeunit, role-center, page-customization] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Define profiles as AL objects + +## Description + +Profiles delivered by a Marketplace extension must be declared as AL `profile` objects. A profile object is validated with its Role Center and page customizations when the extension is compiled and is registered through extension synchronization. Inserting profile-table records from install or setup code bypasses that object lifecycle. + +## Best Practice + +Declare each app-owned profile with the `profile` object and set its `RoleCenter`, user-facing caption, and optional customizations in AL. Let installation and synchronization register the object. + +See sample: [`define-profiles-as-al-objects.good.al`](define-profiles-as-al-objects.good.al). + +## Anti Pattern + +Install, upgrade, or setup code that creates an app-owned profile by inserting a `Profile` table record. Detection signal: a `Record Profile` variable followed by `Insert` in profile provisioning code. + +See sample: [`define-profiles-as-al-objects.bad.al`](define-profiles-as-al-objects.bad.al). \ No newline at end of file diff --git a/community/knowledge/appsource/do-not-hard-code-time-zone-offsets.bad.al b/community/knowledge/appsource/do-not-hard-code-time-zone-offsets.bad.al new file mode 100644 index 0000000..4ec258b --- /dev/null +++ b/community/knowledge/appsource/do-not-hard-code-time-zone-offsets.bad.al @@ -0,0 +1,7 @@ +codeunit 50100 "Rental Audit" +{ + procedure SetCreatedAt(var RentalAgreement: Record "Rental Agreement") + begin + RentalAgreement."Created At" := CurrentDateTime() + 7200000; + end; +} \ No newline at end of file diff --git a/community/knowledge/appsource/do-not-hard-code-time-zone-offsets.good.al b/community/knowledge/appsource/do-not-hard-code-time-zone-offsets.good.al new file mode 100644 index 0000000..c4e155e --- /dev/null +++ b/community/knowledge/appsource/do-not-hard-code-time-zone-offsets.good.al @@ -0,0 +1,7 @@ +codeunit 50100 "Rental Audit" +{ + procedure SetCreatedAt(var RentalAgreement: Record "Rental Agreement") + begin + RentalAgreement."Created At" := CurrentDateTime(); + end; +} \ No newline at end of file diff --git a/community/knowledge/appsource/do-not-hard-code-time-zone-offsets.md b/community/knowledge/appsource/do-not-hard-code-time-zone-offsets.md new file mode 100644 index 0000000..935b4d5 --- /dev/null +++ b/community/knowledge/appsource/do-not-hard-code-time-zone-offsets.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: appsource +keywords: [datetime, time-zone, utc, currentdatetime, locale, regional-settings] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Do not hard-code time-zone offsets + +## Description + +Marketplace extensions run for users and services in many time zones. Adding a fixed offset to a `DateTime` assumes one locale, ignores daylight-saving transitions, and changes an absolute timestamp into an incorrect value for other regions. + +## Best Practice + +Store and compare `DateTime` values without a manually applied regional offset. Business Central stores `DateTime` values in UTC and presents them according to the client time zone. Keep service contracts time-zone explicit and perform a conversion only when the business requirement identifies a particular zone. + +See sample: [`do-not-hard-code-time-zone-offsets.good.al`](do-not-hard-code-time-zone-offsets.good.al). + +## Anti Pattern + +Adding or subtracting a fixed duration solely to convert `CurrentDateTime` or another timestamp to an assumed local time. Detection signals include fixed hour-sized millisecond values near `DateTime` assignments and comments naming a specific time zone; confirm the duration is an offset rather than a legitimate deadline or schedule interval. + +See sample: [`do-not-hard-code-time-zone-offsets.bad.al`](do-not-hard-code-time-zone-offsets.bad.al). \ No newline at end of file diff --git a/community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.bad.al b/community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.bad.al new file mode 100644 index 0000000..d062837 --- /dev/null +++ b/community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.bad.al @@ -0,0 +1,21 @@ +codeunit 50100 "Rental Service" +{ + [ServiceEnabled] + procedure CloseAgreement(AgreementNo: Code[20]): Boolean + var + RentalAgreement: Record "Rental Agreement"; + begin + if not Confirm(CloseAgreementQst, false, AgreementNo) then + exit(false); + + RentalAgreement.Get(AgreementNo); + RentalAgreement.Closed := true; + RentalAgreement.Modify(true); + Message(AgreementClosedMsg, AgreementNo); + exit(true); + end; + + var + CloseAgreementQst: Label 'Close rental agreement %1?'; + AgreementClosedMsg: Label 'Rental agreement %1 was closed.'; +} \ No newline at end of file diff --git a/community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.good.al b/community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.good.al new file mode 100644 index 0000000..c990850 --- /dev/null +++ b/community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.good.al @@ -0,0 +1,15 @@ +codeunit 50100 "Rental Service" +{ + [ServiceEnabled] + procedure CloseAgreement(AgreementNo: Code[20]): Boolean + var + RentalAgreement: Record "Rental Agreement"; + begin + if not RentalAgreement.Get(AgreementNo) then + exit(false); + + RentalAgreement.Closed := true; + RentalAgreement.Modify(true); + exit(true); + end; +} \ No newline at end of file diff --git a/community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.md b/community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.md new file mode 100644 index 0000000..45b06b2 --- /dev/null +++ b/community/knowledge/appsource/keep-web-service-paths-free-of-ui-calls.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: appsource +keywords: [web-service, serviceenabled, guiallowed, message, confirm, strmenu] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Keep web-service paths free of UI calls + +## Description + +Pages and codeunits exposed as web services run without an interactive client. Calls that require a UI callback, including `Confirm`, `StrMenu`, and modal pages, can terminate the service request instead of completing the operation. `Message` does not raise the callback error: the message is suppressed and logged, making it ineffective for communicating a service result. + +## Best Practice + +Keep service entry points and every procedure they call free of interactive UI. Return data through the service contract and report validation failures with service-safe error handling. When a procedure is shared with an interactive client, guard UI-only behavior with `GuiAllowed` while preserving the underlying operation. + +See sample: [`keep-web-service-paths-free-of-ui-calls.good.al`](keep-web-service-paths-free-of-ui-calls.good.al). + +## Anti Pattern + +A web-service-exposed page or codeunit calls an interactive UI method directly or indirectly. Detection signals include `Message`, `Confirm`, `StrMenu`, `Page.RunModal`, and confirmation-dialog pages on a service call path. Treat `Message` as suppressed and ineffective, not as a callback failure. Do not flag a controlled `Error` solely because it returns a service fault. + +See sample: [`keep-web-service-paths-free-of-ui-calls.bad.al`](keep-web-service-paths-free-of-ui-calls.bad.al). \ No newline at end of file diff --git a/community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.bad.al b/community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.bad.al new file mode 100644 index 0000000..81e8f83 --- /dev/null +++ b/community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.bad.al @@ -0,0 +1,15 @@ +pageextension 50100 "Rental Customer List" extends "Customer List" +{ + actions + { + addafter("Customer Ledger Entries") + { + action(OpenRentalAgreements) + { + ApplicationArea = All; + Caption = 'Rental Agreements'; + RunObject = page "Rental Agreement List"; + } + } + } +} \ No newline at end of file diff --git a/community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.good.al b/community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.good.al new file mode 100644 index 0000000..155a211 --- /dev/null +++ b/community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.good.al @@ -0,0 +1,15 @@ +pageextension 50100 "Rental Customer List" extends "Customer List" +{ + actions + { + addlast(Processing) + { + action(OpenRentalAgreements) + { + ApplicationArea = All; + Caption = 'Rental Agreements'; + RunObject = page "Rental Agreement List"; + } + } + } +} \ No newline at end of file diff --git a/community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.md b/community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.md new file mode 100644 index 0000000..4967645 --- /dev/null +++ b/community/knowledge/appsource/place-page-extension-actions-with-addfirst-or-addlast.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: appsource +keywords: [pageextension, actions, addfirst, addlast, addbefore, addafter] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Place page extension actions with addfirst or addlast + +## Description + +Place new page-extension actions at the beginning or end of an existing action group with `addfirst` or `addlast`. Anchoring a new action relative to a specific base-app action with `addbefore` or `addafter` couples the extension to an implementation detail that can move or disappear between Business Central releases. + +## Best Practice + +Choose the semantic action area or group and append or prepend the extension's actions. This keeps placement deterministic without depending on the continued existence of one neighboring action. + +See sample: [`place-page-extension-actions-with-addfirst-or-addlast.good.al`](place-page-extension-actions-with-addfirst-or-addlast.good.al). + +## Anti Pattern + +Using `addbefore` or `addafter` to place newly added actions next to a specific action from another app. The syntax is valid AL, but the placement anchor is brittle for a Marketplace extension. + +See sample: [`place-page-extension-actions-with-addfirst-or-addlast.bad.al`](place-page-extension-actions-with-addfirst-or-addlast.bad.al). \ No newline at end of file diff --git a/community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.bad.al b/community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.bad.al new file mode 100644 index 0000000..d648f4a --- /dev/null +++ b/community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.bad.al @@ -0,0 +1,20 @@ +page 50100 "Rental Agreement List" +{ + PageType = List; + SourceTable = "Rental Agreement"; + ApplicationArea = All; + + layout + { + area(Content) + { + repeater(Agreements) + { + field("No."; Rec."No.") + { + ApplicationArea = All; + } + } + } + } +} \ No newline at end of file diff --git a/community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.good.al b/community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.good.al new file mode 100644 index 0000000..97fe848 --- /dev/null +++ b/community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.good.al @@ -0,0 +1,21 @@ +page 50100 "Rental Agreement List" +{ + PageType = List; + SourceTable = "Rental Agreement"; + ApplicationArea = All; + UsageCategory = Lists; + + layout + { + area(Content) + { + repeater(Agreements) + { + field("No."; Rec."No.") + { + ApplicationArea = All; + } + } + } + } +} \ No newline at end of file diff --git a/community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.md b/community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.md new file mode 100644 index 0000000..9241236 --- /dev/null +++ b/community/knowledge/appsource/set-usagecategory-on-searchable-entry-points.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: appsource +keywords: [usagecategory, tell-me, search, page, report, discoverability] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Set UsageCategory on searchable entry points + +## Description + +Pages and reports that users are expected to open directly must set `UsageCategory`. Without it, the object is absent from Tell Me and users cannot bookmark it from the web client. Supporting objects such as list parts, dialogs, API pages, and objects reached only through another page do not need to be searchable entry points. + +## Best Practice + +Set `UsageCategory` to the category that matches the entry point, such as `Lists`, `Tasks`, `ReportsAndAnalysis`, or `Documents`. Also set the appropriate object-level `ApplicationArea` so search results respect feature visibility. + +See sample: [`set-usagecategory-on-searchable-entry-points.good.al`](set-usagecategory-on-searchable-entry-points.good.al). + +## Anti Pattern + +A user-facing page or report intended for direct discovery omits `UsageCategory` or sets it to `None`. Do not infer intent from the object type alone; require evidence that the object is a direct user entry point. + +See sample: [`set-usagecategory-on-searchable-entry-points.bad.al`](set-usagecategory-on-searchable-entry-points.bad.al). \ No newline at end of file diff --git a/community/knowledge/appsource/use-invariant-date-literals.bad.al b/community/knowledge/appsource/use-invariant-date-literals.bad.al new file mode 100644 index 0000000..437083d --- /dev/null +++ b/community/knowledge/appsource/use-invariant-date-literals.bad.al @@ -0,0 +1,10 @@ +codeunit 50100 "Rental Period Defaults" +{ + procedure GetPolicyStartDate(): Date + var + PolicyStartDate: Date; + begin + Evaluate(PolicyStartDate, '01/31/2025'); + exit(PolicyStartDate); + end; +} \ No newline at end of file diff --git a/community/knowledge/appsource/use-invariant-date-literals.good.al b/community/knowledge/appsource/use-invariant-date-literals.good.al new file mode 100644 index 0000000..07b19c4 --- /dev/null +++ b/community/knowledge/appsource/use-invariant-date-literals.good.al @@ -0,0 +1,7 @@ +codeunit 50100 "Rental Period Defaults" +{ + procedure GetPolicyStartDate(): Date + begin + exit(20250131D); + end; +} \ No newline at end of file diff --git a/community/knowledge/appsource/use-invariant-date-literals.md b/community/knowledge/appsource/use-invariant-date-literals.md new file mode 100644 index 0000000..c38476c --- /dev/null +++ b/community/knowledge/appsource/use-invariant-date-literals.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: appsource +keywords: [date-literal, invariant-date, dateformula, localization, appsourcecop] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Use invariant date literals + +## Description + +Write fixed dates in AL with the invariant `yyyymmddD` syntax. A locale-dependent text value parsed with `Evaluate` can change meaning or fail under another user's regional settings, which makes the Marketplace extension unreliable across markets. + +## Best Practice + +Represent a fixed date directly as an AL date literal, such as `20250131D`. Use `CalcDate` with a date formula when the value is relative rather than fixed. + +See sample: [`use-invariant-date-literals.good.al`](use-invariant-date-literals.good.al). + +## Anti Pattern + +Building a fixed date by passing localized text such as `01/02/2025` to `Evaluate`. Detection signal: `Evaluate` converting a hard-coded or label-backed formatted string into a `Date`. + +See sample: [`use-invariant-date-literals.bad.al`](use-invariant-date-literals.bad.al). \ No newline at end of file diff --git a/microsoft/skills/review/al-appsource-review.md b/microsoft/skills/review/al-appsource-review.md index c851ea2..3f6a221 100644 --- a/microsoft/skills/review/al-appsource-review.md +++ b/microsoft/skills/review/al-appsource-review.md @@ -16,7 +16,7 @@ application-area: [all] Reviews AL source and app metadata changes against the `appsource` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`. -An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. AppSource findings are narrow by design — they apply to AppSource-facing metadata and complete permission coverage that requires repository context. Mechanical AppSourceCop diagnostics are intentionally outside this skill. The skill returns `not-applicable` when none of those surfaces apply. +An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. AppSource findings are narrow by design — they apply to Marketplace-facing metadata, complete permission coverage that requires repository context, and contextual AL constructs covered by Marketplace submission requirements. Mechanical compiler and analyzer diagnostics are intentionally outside this skill. The skill returns `not-applicable` when none of those surfaces apply. ## Source @@ -37,14 +37,20 @@ Discard files that are not applicable. Retain conditionally applicable files (an Narrow the relevant files to the subset that applies to the changes under review. For each relevant file, compute overlap against: -- The changed files and AL object types — especially `app.json`, permission-set objects, setup and usage entry points, and AppSource-facing help metadata. -- Tokens extracted from the diff that relate to AppSource (`permissionset`, `Assignable`, `Permissions`, `SUPER`, `tabledata`, `execute`, `app.json`, `help`, `ContextSensitiveHelpPage`, `Copilot`, `https`). +- The changed files and AL object types — especially `app.json`, permission-set and profile objects, setup and usage entry points, service-enabled procedures, user-facing pages and reports, and AppSource-facing help metadata. +- Tokens extracted from the diff that relate to AppSource (`permissionset`, `Assignable`, `Permissions`, `SUPER`, `tabledata`, `execute`, `profile`, `Record Profile`, `Evaluate`, `Date`, `DateTime`, `CurrentDateTime`, `UsageCategory`, `PageType`, `addfirst`, `addlast`, `addbefore`, `addafter`, `ServiceEnabled`, `GuiAllowed`, `Message`, `Confirm`, `StrMenu`, `RunModal`, `app.json`, `help`, `ContextSensitiveHelpPage`, `Copilot`, `https`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. When the diff contains no AppSource-related source or metadata changes by any of the above signals, return `outcome: "not-applicable"` without evaluating files. The following targeted checks cover every current `appsource` article across the Microsoft and community layers. Treat each as a candidate-selection cue: when the signal appears in changed code, add the named article to the worklist and evaluate it in Action. - The app has no assignable permission set covering its setup and usage paths, omits visible object/tabledata grants, or requires `SUPER` for normal operation — `permission-sets-cover-setup-and-usage-without-super`. Require repository-level app context; one isolated permission-set object cannot prove complete coverage. +- Install, upgrade, or setup code provisions an app-owned profile through `Record Profile` and `Insert` instead of declaring a `profile` object — `define-profiles-as-al-objects`. +- A hard-coded or label-backed formatted string is converted to `Date` with `Evaluate` — `use-invariant-date-literals`. Do not select this article for variable external input whose format must be validated at runtime. +- A page extension uses `addbefore` or `addafter` to place a newly added action relative to a specific action owned by another app — `place-page-extension-actions-with-addfirst-or-addlast`. Do not flag those keywords in layouts or placement relative to an action owned by the same extension. +- A page or codeunit web-service entry point, including a `[ServiceEnabled]` procedure, contains or reaches `Message`, `Confirm`, `StrMenu`, `Page.RunModal`, or a confirmation-dialog page without an effective non-GUI guard — `keep-web-service-paths-free-of-ui-calls`. Treat `Message` as suppressed and logged, making it ineffective as a service response; treat the other UI calls as callback-failure risks. Do not treat a controlled `Error` as interactive UI solely because it returns a service fault. +- A page or report that repository context identifies as a direct user entry point omits `UsageCategory` or sets it to `None` — `set-usagecategory-on-searchable-entry-points`. Do not select this article based only on object type; exclude supporting parts, dialogs, API pages, and objects intentionally reached through another page. +- A `DateTime` assignment adds or subtracts a fixed duration to represent an assumed regional offset — `do-not-hard-code-time-zone-offsets`. Require contextual evidence such as an hour-sized constant, offset-oriented name, or time-zone comment; do not flag deadlines, schedules, or elapsed-time calculations. - For BC v27 or later, `app.json` adds or changes the `help` URL to a path deeper than two levels, or a changed Copilot/context-sensitive help arrangement would ground the app under an overly broad truncated parent — `keep-copilot-help-url-to-two-path-levels`. Once the candidate worklist is known, resolve layer-precedence conflicts per READ. Drop lower-precedence files whose normative guidance (`## Best Practice` or `## Anti Pattern`) directly contradicts a higher-precedence candidate, and record each dropped file in `suppressed` with `reason: "layer-precedence"`. Files that would have been candidates but are hidden because their layer is disabled in consumer configuration are recorded with `reason: "configuration"`. Files that never became candidates are NOT recorded in `suppressed`. @@ -75,7 +81,7 @@ Outcome selection: - `completed` — the skill evaluated every worklist item. - `no-knowledge` — no applicable AppSource knowledge survived filtering. -- `not-applicable` — the diff touches no AppSource permission or app-metadata surface. +- `not-applicable` — the diff touches no Marketplace-related source, permission, or app-metadata surface. - `partial` — a budget was hit before the worklist was exhausted. - `failed` — an unrecoverable error occurred. From 8c26ba4e7640fd613e60a40734c744f0f3bda40b Mon Sep 17 00:00:00 2001 From: Stefano Demiliani <33155438+demiliani@users.noreply.github.com> Date: Mon, 14 Sep 2026 12:44:30 +0200 Subject: [PATCH 06/35] Add Job Queue reliability and scheduling guidance (#148) * knowledge(performance): add job queue reliability guidance * Address Job Queue review feedback * Address Job Queue routing review feedback * Encode job queue conflict in fixtures --- evaluation/README.md | 4 +- evaluation/review-fixtures.json | 10 ++- ...nt-inside-write-transaction-holds-locks.md | 2 +- ...ry-code-serializes-conflicting-jobs.bad.al | 11 +++ ...y-code-serializes-conflicting-jobs.good.al | 18 +++++ ...tegory-code-serializes-conflicting-jobs.md | 28 +++++++ ...external-effects-must-be-idempotent.bad.al | 57 ++++++++++++++ ...xternal-effects-must-be-idempotent.good.al | 65 ++++++++++++++++ ...eue-external-effects-must-be-idempotent.md | 30 ++++++++ ...-queue-handlers-must-not-require-ui.bad.al | 17 ++++ ...queue-handlers-must-not-require-ui.good.al | 14 ++++ .../job-queue-handlers-must-not-require-ui.md | 28 +++++++ ...ue-handlers-must-propagate-failures.bad.al | 23 ++++++ ...e-handlers-must-propagate-failures.good.al | 16 ++++ ...-queue-handlers-must-propagate-failures.md | 28 +++++++ ...-on-hold-does-not-stop-running-work.bad.al | 18 +++++ ...on-hold-does-not-stop-running-work.good.al | 49 ++++++++++++ ...ueue-on-hold-does-not-stop-running-work.md | 28 +++++++ ...ncompanyopen-subscribers-must-not-do-io.md | 2 +- ...ed-task-id-to-avoid-duplicate-tasks.bad.al | 15 ++++ ...d-task-id-to-avoid-duplicate-tasks.good.al | 23 ++++++ ...eduled-task-id-to-avoid-duplicate-tasks.md | 28 +++++++ .../skills/review/al-performance-review.md | 8 +- tools/Test-ReviewFixtures.ps1 | 77 ++++++++++++++----- 24 files changed, 574 insertions(+), 25 deletions(-) create mode 100644 microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.bad.al create mode 100644 microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.good.al create mode 100644 microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.md create mode 100644 microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.bad.al create mode 100644 microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.good.al create mode 100644 microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.md create mode 100644 microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.bad.al create mode 100644 microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.good.al create mode 100644 microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.md create mode 100644 microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.bad.al create mode 100644 microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.good.al create mode 100644 microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.md create mode 100644 microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.bad.al create mode 100644 microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.good.al create mode 100644 microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.md create mode 100644 microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.bad.al create mode 100644 microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.good.al create mode 100644 microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.md diff --git a/evaluation/README.md b/evaluation/README.md index 7be55b4..2125ce3 100644 --- a/evaluation/README.md +++ b/evaluation/README.md @@ -2,7 +2,7 @@ The evaluation is convention-driven. The harness discovers every `/skills/review/al--review.md` leaf across the enabled `microsoft`, `community`, and `custom` layers. Duplicate domains resolve with `custom > community > microsoft` precedence. For each selected leaf, the harness finds paired knowledge across the same layers, applies the same precedence to duplicate article slugs, selects the first article (by filename) with both `.bad.al` and `.good.al` companions, and derives the expected positive and clean control automatically. Adding a conforming leaf requires no scoring-contract edit. -`review-fixtures.json` contains only global thresholds and optional exceptional overrides. An override may select a different article or add context when the generic convention cannot express a scenario. It should remain empty in the normal case. +`review-fixtures.json` contains only global thresholds and optional exceptional overrides. An override may select a different `article`, add context when the generic convention cannot express a scenario, or use an `articles` array when one domain needs explicit regression coverage for several paired articles. Specify either `article` or `articles`, not both. The first selected article retains the stable `-bad` and `-good` manifest IDs; additional articles use slug-qualified IDs. Overrides should remain empty in the normal case. Model-facing preparation hashes case IDs, neutralizes `Good`/`Bad` object-name tokens, and removes full-line sample comments so neither the article slug, domain, nor expected outcome reveals the answer. @@ -26,7 +26,7 @@ This credential-free check proves every selected leaf maps to a same-named knowl 2. For a fast/small model, use one fresh invocation per `request-case-*.json`. Each request embeds the exact leaf instructions, that domain's candidate index rows with authoritative paths, and one opaque case. The model opens only matching articles and copies finding IDs from `candidateArticles[].path`. Save each response with the matching `result-case-*.json` name in the same directory. - `request-.json` files provide optional two-case leaf batches and identify the selected layer-owned skill path; save those as `result-.json`. Directory scoring prefers `result-case-*.json` when present and otherwise falls back to `result-*.json`. `review-request.json` is an optional all-domains stress test for larger models. Neither batch form is the preferred fast-model profile. + `request-.json` files provide optional leaf batches containing every selected case for that domain and identify the selected layer-owned skill path; save those as `result-.json`. A normal convention-selected domain has one bad/good pair, while an `articles` override contributes one pair per listed article. Directory scoring prefers `result-case-*.json` when present and otherwise falls back to `result-*.json`. `review-request.json` is an optional all-domains stress test for larger models. Neither batch form is the preferred fast-model profile. 3. Save only this result shape: diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index e11508a..352fccf 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -17,7 +17,15 @@ "article": "set-defaultimplementation-on-enum" }, "performance": { - "article": "use-isempty-for-existence-check" + "articles": [ + "use-isempty-for-existence-check", + "job-queue-category-code-serializes-conflicting-jobs", + "job-queue-external-effects-must-be-idempotent", + "job-queue-handlers-must-not-require-ui", + "job-queue-handlers-must-propagate-failures", + "job-queue-on-hold-does-not-stop-running-work", + "store-scheduled-task-id-to-avoid-duplicate-tasks" + ] }, "privacy": { "article": "no-pii-in-telemetry-message-string" diff --git a/microsoft/knowledge/performance/httpclient-inside-write-transaction-holds-locks.md b/microsoft/knowledge/performance/httpclient-inside-write-transaction-holds-locks.md index 21a2c04..88d0ff7 100644 --- a/microsoft/knowledge/performance/httpclient-inside-write-transaction-holds-locks.md +++ b/microsoft/knowledge/performance/httpclient-inside-write-transaction-holds-locks.md @@ -17,7 +17,7 @@ The first database write opens an AL write transaction that the runtime holds un ## Best Practice -Defer the HTTP call to a separate session. When the external operation must correspond to a committed database change, insert an outbox work item in the same transaction as that change and process committed outbox rows with a recurring job queue entry. The change and work item then commit or roll back together, and the worker performs HTTP before deleting the item so it holds no write lock during the call. Make the external operation idempotent because a failure after a successful HTTP response can cause the work item to be retried. +Defer the HTTP call to a separate session. When the external operation must correspond to a committed database change, insert an outbox work item in the same transaction as that change and process committed outbox rows with a recurring job queue entry. The change and work item then commit or roll back together, and the worker performs HTTP before deleting the item so it holds no write lock during the call. The separate retry-safety requirement is covered by `job-queue-external-effects-must-be-idempotent.md`. A directly created scheduled task is suitable only when its work is independent of the caller's commit. An immediately ready task can run concurrently with the caller, so it must not assume that the caller's writes are already committed. Do **not** use `Commit()` as a general remedy: it irrevocably commits all prior writes in the current transaction, so any subsequent failure cannot roll them back. `Commit()` is appropriate only at top-level entry points where partial persistence is intentional and understood. diff --git a/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.bad.al b/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.bad.al new file mode 100644 index 0000000..fbd0b39 --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.bad.al @@ -0,0 +1,11 @@ +codeunit 50113 "Job Queue Category Bad" +{ + procedure ConfigureJobsForSharedExclusiveResource(var SalesPostingJob: Record "Job Queue Entry"; var PurchasePostingJob: Record "Job Queue Entry"; ExclusiveResourceId: Text[250]) + begin + // Both jobs update the same posting resources, but nothing prevents overlap. + SalesPostingJob.Validate("Parameter String", ExclusiveResourceId); + PurchasePostingJob.Validate("Parameter String", ExclusiveResourceId); + SalesPostingJob.Validate("Job Queue Category Code", ''); + PurchasePostingJob.Validate("Job Queue Category Code", ''); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.good.al b/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.good.al new file mode 100644 index 0000000..f77200b --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.good.al @@ -0,0 +1,18 @@ +codeunit 50113 "Job Queue Category Good" +{ + procedure ConfigureJobsForSharedExclusiveResource(var SalesPostingJob: Record "Job Queue Entry"; var PurchasePostingJob: Record "Job Queue Entry"; ExclusiveResourceId: Text[250]) + var + JobQueueCategory: Record "Job Queue Category"; + begin + if not JobQueueCategory.Get('POSTING') then begin + JobQueueCategory.Code := 'POSTING'; + JobQueueCategory.Insert(); + end; + + // The shared category lets only one conflicting posting job run at a time. + SalesPostingJob.Validate("Parameter String", ExclusiveResourceId); + PurchasePostingJob.Validate("Parameter String", ExclusiveResourceId); + SalesPostingJob.Validate("Job Queue Category Code", 'POSTING'); + PurchasePostingJob.Validate("Job Queue Category Code", 'POSTING'); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.md b/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.md new file mode 100644 index 0000000..d92647e --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: performance +keywords: [job-queue, category-code, concurrency, waiting, serialization, locking] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Use a job queue category to serialize conflicting jobs + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +Different job queue entries can run at the same time. When two jobs update the same exclusive resource, concurrent execution can cause lock contention, deadlocks, or conflicting results. Within one company, entries with the same Job Queue Category Code are serialized: while one runs, another entry in that category waits. + +## Best Practice + +Assign the same non-empty Job Queue Category Code to job queue entries in the same company that must not overlap, regardless of which codeunit they run. Define categories around the shared resource or exclusivity requirement, not merely around object names. Leave independent jobs in different categories so they can still run concurrently. A category does not serialize work across companies or environments, or coordinate workers outside the job queue dispatcher. Protect shared external or cross-company resources with a separate application-level locking mechanism. + +See sample: `job-queue-category-code-serializes-conflicting-jobs.good.al`. + +## Anti Pattern + +Creating or configuring multiple job queue entries that update the same exclusive resource while leaving their Job Queue Category Code empty or different. Do not flag jobs merely because they touch the same tables; the rule applies when their operation requires mutual exclusion. + +See sample: `job-queue-category-code-serializes-conflicting-jobs.bad.al`. \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.bad.al b/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.bad.al new file mode 100644 index 0000000..8f92f10 --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.bad.al @@ -0,0 +1,57 @@ +table 50112 "Queued Export Bad" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Entry No."; Integer) + { + AutoIncrement = true; + } + field(2; Payload; Text[250]) + { + } + } + + keys + { + key(PK; "Entry No.") + { + Clustered = true; + } + } +} + +codeunit 50112 "Queued Export Worker Bad" +{ + TableNo = "Job Queue Entry"; + + trigger OnRun() + var + QueuedExport: Record "Queued Export Bad"; + Client: HttpClient; + Content: HttpContent; + Response: HttpResponseMessage; + begin + if not QueuedExport.FindFirst() then + exit; + + Content.WriteFrom(QueuedExport.Payload); + Client.Post('https://example.local/exports', Content, Response); + if not Response.IsSuccessStatusCode() then + Error('Export failed with HTTP status %1.', Response.HttpStatusCode()); + + // If this local step fails, the external export exists but this row is retried. + UpdateLocalStatus(); + FinalizeExport(QueuedExport); + end; + + local procedure UpdateLocalStatus() + begin + end; + + local procedure FinalizeExport(var QueuedExport: Record "Queued Export Bad") + begin + QueuedExport.Delete(); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.good.al b/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.good.al new file mode 100644 index 0000000..d161089 --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.good.al @@ -0,0 +1,65 @@ +table 50112 "Queued Export Good" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Entry No."; Integer) + { + AutoIncrement = true; + } + field(2; Payload; Text[250]) + { + } + } + + keys + { + key(PK; "Entry No.") + { + Clustered = true; + } + } + +} + +codeunit 50112 "Queued Export Worker Good" +{ + TableNo = "Job Queue Entry"; + + trigger OnRun() + var + QueuedExport: Record "Queued Export Good"; + Client: HttpClient; + Content: HttpContent; + ContentHeaders: HttpHeaders; + JsonPayload: JsonObject; + RequestBody: Text; + Response: HttpResponseMessage; + begin + if not QueuedExport.FindFirst() then + exit; + + JsonPayload.Add('idempotencyKey', Format(QueuedExport.SystemId)); + JsonPayload.Add('payload', QueuedExport.Payload); + JsonPayload.WriteTo(RequestBody); + + Content.WriteFrom(RequestBody); + Content.GetHeaders(ContentHeaders); + ContentHeaders.Clear(); + ContentHeaders.Add('Content-Type', 'application/json'); + Client.Post('https://example.local/exports', Content, Response); + if not Response.IsSuccessStatusCode() then + Error('Export failed with HTTP status %1.', Response.HttpStatusCode()); + + // The external service must atomically create a record only when idempotencyKey + // does not exist. When the key already exists, it must return the existing record + // without repeating the side effect. + UpdateLocalStatus(); + QueuedExport.Delete(); + end; + + local procedure UpdateLocalStatus() + begin + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.md b/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.md new file mode 100644 index 0000000..a5932df --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: performance +keywords: [job-queue, idempotency, retry, outbox, httpclient, external-effect] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Job queue external effects must be idempotent + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +A job queue handler can successfully create something in an external system and then fail while updating Business Central. Business Central rolls back its database changes, but it cannot roll back the external request. The same work can later run again through configured retries, recurrence, rescheduling, or manual restart. Without a way for the external system to recognize the repeated request, a later run can create a duplicate shipment, payment, notification, or other side effect. + +## Best Practice + +Use a stable request ID that exists before the job queue processes the outbox row. For example, include the outbox record's `SystemId` as an `idempotencyKey` value in the JSON body of every POST attempt. The external service must enforce uniqueness on that value: when it receives the key again, it returns the existing record instead of creating another one. Delete the outbox row only after the external call and all required local updates succeed. + +A `Processed` flag set after the external call does not solve this failure window. If a later AL error rolls back that flag, the outbox row again looks unprocessed even though the external operation already happened. + +See sample: `job-queue-external-effects-must-be-idempotent.good.al`. + +## Anti Pattern + +Sending a state-changing request from a job queue handler with no stable request ID understood by the external API. Specifically, look for this sequence: read an outbox row, call `HttpClient.Post` or another side-effecting API, update or delete local data, and propagate an error after which the same outbox row can be processed again. The key may be part of the request body, URI, headers, or an existing business key; a naturally idempotent remote operation is already safe and should not be flagged. + +See sample: `job-queue-external-effects-must-be-idempotent.bad.al`. \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.bad.al b/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.bad.al new file mode 100644 index 0000000..eecfeaf --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.bad.al @@ -0,0 +1,17 @@ +codeunit 50110 "Job Queue UI Bad" +{ + TableNo = "Job Queue Entry"; + + trigger OnRun() + begin + if not Confirm('Process the queued export now?') then + exit; + + ProcessExport(Rec."Parameter String"); + Message('The queued export completed.'); + end; + + local procedure ProcessExport(ParameterString: Text) + begin + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.good.al b/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.good.al new file mode 100644 index 0000000..490720e --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.good.al @@ -0,0 +1,14 @@ +codeunit 50110 "Job Queue UI Good" +{ + TableNo = "Job Queue Entry"; + + trigger OnRun() + begin + Rec.TestField("Parameter String"); + ProcessExport(Rec."Parameter String"); + end; + + local procedure ProcessExport(ParameterString: Text) + begin + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.md b/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.md new file mode 100644 index 0000000..f780ab5 --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: performance +keywords: [job-queue, background-session, guiallowed, confirm, runmodal, client-callback] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Job queue handlers must not require user interaction + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +A job queue handler runs in a background session with no client UI. Calls that require a client callback, such as `Confirm`, `Page.RunModal`, `Report.RunModal`, upload, or download, can stop the job with a non-retriable callback error. `Message` is suppressed and logged by the server, so it cannot communicate a result to the user who scheduled the job. + +## Best Practice + +Make a dedicated job queue entry point non-interactive. Validate parameters and data in AL, persist business-visible status when needed, and let failures propagate to the job queue log. If one procedure genuinely serves both foreground and background callers, isolate optional UI-only behavior behind `GuiAllowed`; do not use the guard to silently skip a decision that the operation requires. + +See sample: `job-queue-handlers-must-not-require-ui.good.al`. + +## Anti Pattern + +Calling `Confirm`, `Page.Run`, `Page.RunModal`, `Report.Run`, `Report.RunModal`, `Hyperlink`, `File.Upload`, or `File.Download` from a codeunit run by the job queue. Another signal is using `Message` as the only success or failure notification: no user is attached to receive it. + +See sample: `job-queue-handlers-must-not-require-ui.bad.al`. \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.bad.al b/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.bad.al new file mode 100644 index 0000000..550506a --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.bad.al @@ -0,0 +1,23 @@ +codeunit 50111 "Job Queue Failure Bad" +{ + TableNo = "Job Queue Entry"; + + trigger OnRun() + begin + if not TryProcessCustomer(Rec."Parameter String") then + exit; + end; + + [TryFunction] + local procedure TryProcessCustomer(CustomerNo: Code[20]) + var + Customer: Record Customer; + begin + Customer.Get(CustomerNo); + ProcessCustomer(Customer); + end; + + local procedure ProcessCustomer(Customer: Record Customer) + begin + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.good.al b/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.good.al new file mode 100644 index 0000000..8a99875 --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.good.al @@ -0,0 +1,16 @@ +codeunit 50111 "Job Queue Failure Good" +{ + TableNo = "Job Queue Entry"; + + trigger OnRun() + var + Customer: Record Customer; + begin + Customer.Get(Rec."Parameter String"); + ProcessCustomer(Customer); + end; + + local procedure ProcessCustomer(Customer: Record Customer) + begin + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.md b/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.md new file mode 100644 index 0000000..1c7b83f --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: performance +keywords: [job-queue, error-propagation, tryfunction, retry, dispatcher, job-queue-log] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Job queue handlers must propagate execution failures + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +The job queue dispatcher can mark an entry as failed, record the error, and apply its configured retry behavior only when the handler terminates with an error. A handler that catches a failed `TryFunction` or Boolean-returning operation and then returns normally reports success to the dispatcher, even though its work did not complete. + +## Best Practice + +Let an error that invalidates the whole run propagate out of the job queue entry point. Add context only when it helps an operator diagnose the failure and does not expose sensitive data. Per-item failures may be collected deliberately, but the batch must persist or emit an observable aggregate outcome instead of silently treating incomplete work as success. + +See sample: `job-queue-handlers-must-propagate-failures.good.al`. + +## Anti Pattern + +Calling a `TryFunction`, `Codeunit.Run`, or another Boolean-returning operation from a job queue handler and using `exit` or normal fall-through on failure without recording an intentional partial-success outcome. The dispatcher sees a successful return, so the entry's status and log do not represent the failed work and configured retries are not applied. + +See sample: `job-queue-handlers-must-propagate-failures.bad.al`. \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.bad.al b/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.bad.al new file mode 100644 index 0000000..434f2b9 --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.bad.al @@ -0,0 +1,18 @@ +codeunit 50114 "Job Queue On Hold Bad" +{ + TableNo = "Job Queue Entry"; + + trigger OnRun() + begin + repeat + if not ProcessNextBatch() then + exit; + Rec.Get(Rec.ID); + until Rec.Status = Rec.Status::"On Hold"; + end; + + local procedure ProcessNextBatch(): Boolean + begin + exit(false); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.good.al b/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.good.al new file mode 100644 index 0000000..b924297 --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.good.al @@ -0,0 +1,49 @@ +table 50114 "Job Cancellation Control" +{ + DataClassification = SystemMetadata; + + fields + { + field(1; "Job Queue Entry ID"; Guid) + { + } + field(2; "Stop Requested"; Boolean) + { + } + } + + keys + { + key(PK; "Job Queue Entry ID") + { + Clustered = true; + } + } +} + +codeunit 50114 "Job Queue On Hold Good" +{ + TableNo = "Job Queue Entry"; + + trigger OnRun() + begin + while not IsStopRequested(Rec.ID) do + if not ProcessNextBatch() then + exit; + end; + + local procedure IsStopRequested(JobQueueEntryId: Guid): Boolean + var + JobCancellationControl: Record "Job Cancellation Control"; + begin + if not JobCancellationControl.Get(JobQueueEntryId) then + exit(false); + + exit(JobCancellationControl."Stop Requested"); + end; + + local procedure ProcessNextBatch(): Boolean + begin + exit(false); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.md b/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.md new file mode 100644 index 0000000..6eec05c --- /dev/null +++ b/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: performance +keywords: [job-queue, on-hold, cancellation, in-process, long-running, stop-request] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Putting a job queue entry on hold does not stop its current run + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +The On Hold status prevents a job queue entry from starting again, but it does not cancel a run that is already in process. A long-running handler continues until it completes, fails, reaches a cancellation point implemented by the application, or its session is stopped externally. + +## Best Practice + +Use On Hold to pause future scheduling. When a long-running operation must support graceful cancellation, store a separate application-owned stop request and check it before every bounded unit of work, including the first. Exit only at a point where completed work and the checkpoint are consistent. The code that resumes scheduling must clear the stop request before restarting the job. Use administrative session termination only when graceful cancellation is impossible. + +See sample: `job-queue-on-hold-does-not-stop-running-work.good.al`. + +## Anti Pattern + +Polling the job queue entry's Status field from inside its handler and expecting a change to On Hold to cancel the active run. The status controls scheduling, not cooperative cancellation, so the handler can continue processing despite the operator's action. + +See sample: `job-queue-on-hold-does-not-stop-running-work.bad.al`. \ No newline at end of file diff --git a/microsoft/knowledge/performance/oncompanyopen-subscribers-must-not-do-io.md b/microsoft/knowledge/performance/oncompanyopen-subscribers-must-not-do-io.md index e8da1c5..95ac3d7 100644 --- a/microsoft/knowledge/performance/oncompanyopen-subscribers-must-not-do-io.md +++ b/microsoft/knowledge/performance/oncompanyopen-subscribers-must-not-do-io.md @@ -17,7 +17,7 @@ application-area: [all] ## Best Practice -Keep company-open subscribers to cheap in-memory work: set a flag, enqueue a job-queue entry, or `TaskScheduler.CreateTask`. Perform HTTP and large SQL after the session is running, in that background work. +Keep company-open subscribers to cheap in-memory work: set a flag, enqueue a job-queue entry, or `TaskScheduler.CreateTask`. Perform HTTP and large SQL after the session is running, in that background work. When the subscriber can run repeatedly, use `store-scheduled-task-id-to-avoid-duplicate-tasks.md` to avoid creating the same logical task more than once. See sample: [`oncompanyopen-subscribers-must-not-do-io.good.al`](oncompanyopen-subscribers-must-not-do-io.good.al). diff --git a/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.bad.al b/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.bad.al new file mode 100644 index 0000000..d692317 --- /dev/null +++ b/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.bad.al @@ -0,0 +1,15 @@ +codeunit 50115 "Scheduled Task Duplicate Bad" +{ + procedure EnsureCleanupTask() + begin + // Every call creates another task for the same cleanup work. + TaskScheduler.CreateTask(Codeunit::"Scheduled Cleanup Work Bad", 0, true, CompanyName()); + end; +} + +codeunit 50116 "Scheduled Cleanup Work Bad" +{ + trigger OnRun() + begin + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.good.al b/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.good.al new file mode 100644 index 0000000..df52c62 --- /dev/null +++ b/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.good.al @@ -0,0 +1,23 @@ +codeunit 50115 "Scheduled Task Duplicate Good" +{ + internal procedure EnsureCleanupTask() + var + TaskId: Guid; + StoredTaskId: Text; + begin + if IsolatedStorage.Get('CleanupTaskId', DataScope::Company, StoredTaskId) then + if Evaluate(TaskId, StoredTaskId) then + if TaskScheduler.TaskExists(TaskId) then + exit; + + TaskId := TaskScheduler.CreateTask(Codeunit::"Scheduled Cleanup Work Good", 0, true, CompanyName()); + IsolatedStorage.Set('CleanupTaskId', Format(TaskId), DataScope::Company); + end; +} + +codeunit 50116 "Scheduled Cleanup Work Good" +{ + trigger OnRun() + begin + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.md b/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.md new file mode 100644 index 0000000..600c671 --- /dev/null +++ b/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: performance +keywords: [task-scheduler, scheduled-task, taskexists, duplicate-task, createtask, guid] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Store the scheduled task ID to avoid duplicate tasks + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +Every call to `TaskScheduler.CreateTask` creates a new scheduled task and returns its unique GUID. Repeating setup or lifecycle code without retaining that GUID can create multiple tasks for the same logical work, consuming scheduler capacity and running the work more than once. + +## Best Practice + +Persist the GUID returned by `CreateTask` at the same scope as the logical task. Before creating a replacement, parse the stored GUID and call `TaskScheduler.TaskExists`; create and store a new task only when the previous task no longer exists. `TaskExists` checks one GUID, not whether an equivalent codeunit is already scheduled, so callers that can schedule concurrently still need serialization around this check-and-create sequence. + +See sample: `store-scheduled-task-id-to-avoid-duplicate-tasks.good.al`. + +## Anti Pattern + +Calling `TaskScheduler.CreateTask` every time initialization, login, setup, or another repeatable path runs while ignoring its return value. Each invocation creates another independent task even when an equivalent task is already pending. + +See sample: `store-scheduled-task-id-to-avoid-duplicate-tasks.bad.al`. \ No newline at end of file diff --git a/microsoft/skills/review/al-performance-review.md b/microsoft/skills/review/al-performance-review.md index 664f20d..7829d70 100644 --- a/microsoft/skills/review/al-performance-review.md +++ b/microsoft/skills/review/al-performance-review.md @@ -39,7 +39,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially tables, pages with SourceTable bindings, reports, queries, and codeunits performing record iteration. - The changed procedures and triggers, weighted toward those that perform loops, Find/FindSet/FindFirst calls, CalcFields, SetAutoCalcFields, CalcSums, FlowField access, Commit calls, checkpoint helpers, record copying, RecordRef conversion, Modify/Delete calls, or cross-table navigation. -- Tokens extracted from the diff that relate to data access and hot-path costs (`SetRange`, `SetFilter`, `SetLoadFields`, `SetCurrentKey`, `FindSet`, `ReadIsolation`, `LockTable`, `ModifyAll`, `DeleteAll`, `Modify`, `Delete`, `Commit`, `checkpoint`, `Copy`, `RecordRef`, `GetTable`, `TextBuilder`, `Dictionary`, `temporary`, `repeat`, `until`, `CalcFields`, `SetAutoCalcFields`, `CalcSums`, `FlowField`, `Visible`). +- Tokens extracted from the diff that relate to data access, hot-path costs, and background scheduling (`SetRange`, `SetFilter`, `SetLoadFields`, `SetCurrentKey`, `FindSet`, `ReadIsolation`, `LockTable`, `ModifyAll`, `DeleteAll`, `Modify`, `Delete`, `Commit`, `checkpoint`, `Copy`, `RecordRef`, `GetTable`, `TextBuilder`, `Dictionary`, `temporary`, `repeat`, `until`, `CalcFields`, `SetAutoCalcFields`, `CalcSums`, `FlowField`, `Visible`, `Job Queue Entry`, `Job Queue Category Code`, `Confirm`, `RunModal`, `GuiAllowed`, `TryFunction`, `Codeunit.Run`, `HttpClient`, `Status`, `On Hold`, `stop request`, `TaskScheduler.CreateTask`, `TaskScheduler.TaskExists`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. @@ -52,6 +52,12 @@ Apply these targeted cues even when simple token overlap would rank the article - Worklist `avoid-cloning-records-before-modify-delete-in-loops.md` when an iteration calls `Copy` or `RecordRef.GetTable` before `Modify`/`Delete`, or passes the iterated record without `var` to a helper that writes that record. Do not worklist it from `Modify`, `Delete`, or `RecordRef` alone; exclude a direct write on the iterator, a read-only copy, a temporary record, a different target table, and a `RecordRef` opened and iterated directly. - Worklist `use-tryfunction-for-error-catching-not-rollback.md` only when writes occur inside a try method and the code or surrounding flow expects an error to roll them back. A bare try-method call whose Boolean result is ignored belongs exclusively to `error-handling/ignored-tryfunction-return-disables-try-semantics.md`; do not worklist the performance article from that call shape alone. - For `LockTable` in a pure read helper, select exactly one owner. Use `do-not-locktable-in-read-only-procedure.md` when the helper needs no stronger isolation and should remove the lock. Use `prefer-readisolation-over-locktable-for-reads.md` instead when the code explicitly requires committed-read semantics and `ReadIsolation` is the replacement. Never emit both findings for the same call. +- Worklist `job-queue-handlers-must-not-require-ui.md` when a codeunit run by the job queue calls `Confirm`, `Page.Run`, `Page.RunModal`, `Report.Run`, `Report.RunModal`, `Hyperlink`, `File.Upload`, or `File.Download`, or uses `Message` as its only success or failure notification. Exclude optional UI-only behavior guarded by `GuiAllowed`; do not exclude a guard that silently skips a decision required by the operation. +- Worklist `job-queue-handlers-must-propagate-failures.md` when a codeunit run by the job queue handles a failed `TryFunction`, `Codeunit.Run`, or another Boolean-returning operation with `exit` or normal fall-through, causing the dispatcher to observe success. Exclude intentional partial-success handling that persists or emits an observable aggregate outcome. A bare try-method call whose Boolean result is ignored remains owned exclusively by `error-handling/ignored-tryfunction-return-disables-try-semantics.md`. +- Worklist `job-queue-external-effects-must-be-idempotent.md` when rerunnable job queue work reads an outbox row, performs a state-changing external request, then updates or deletes local data without sending a stable request ID understood by the external system. Exclude naturally idempotent operations and requests whose body, URI, headers, or business key lets the external service return the existing result instead of repeating the side effect. +- Worklist `job-queue-on-hold-does-not-stop-running-work.md` when a running job queue handler polls the entry's `Status` or `On Hold` value as a cancellation signal. Exclude application-owned stop requests that are checked before every bounded unit of work, including the first, when completed work and its checkpoint remain consistent and resume logic clears the request. +- Worklist `job-queue-category-code-serializes-conflicting-jobs.md` when two or more job queue entries in the same company are shown by the changed context to require mutual exclusion but have empty or different Job Queue Category Codes. Do not infer a conflict merely because jobs touch the same tables, and do not recommend a category to coordinate across companies, environments, or workers outside the job queue dispatcher. +- Worklist `store-scheduled-task-id-to-avoid-duplicate-tasks.md` when `TaskScheduler.CreateTask` runs from initialization, login, setup, or another repeatable path without persisting its returned GUID and checking it with `TaskScheduler.TaskExists` before creating a replacement. Exclude one-shot creation and correctly persisted check-before-create flows; concurrent callers still require serialization around that sequence. These targeted inclusions and exclusions override generic token overlap. Do not retain an excluded article solely because the diff contains one of its keywords. diff --git a/tools/Test-ReviewFixtures.ps1 b/tools/Test-ReviewFixtures.ps1 index c4b0bf1..8cf019f 100644 --- a/tools/Test-ReviewFixtures.ps1 +++ b/tools/Test-ReviewFixtures.ps1 @@ -195,12 +195,42 @@ foreach ($domain in $leafDomains) { } $override = if ($overrides.ContainsKey($domain)) { $overrides[$domain] } else { $null } - $selectedArticle = $null - if ($override -and ($override.PSObject.Properties.Name -contains 'article')) { - $articleName = [string]$override.article + $hasArticleOverride = $override -and ($override.PSObject.Properties.Name -contains 'article') + $hasArticlesOverride = $override -and ($override.PSObject.Properties.Name -contains 'articles') + if ($hasArticleOverride -and $hasArticlesOverride) { + $problems.Add("${domain}: override must specify either 'article' or 'articles', not both.") | Out-Null + continue + } + + $articleNames = @() + if ($hasArticlesOverride) { + $articleNames = @($override.articles) + if (-not $articleNames.Count) { + $problems.Add("${domain}: override 'articles' must contain at least one article.") | Out-Null + continue + } + } elseif ($hasArticleOverride) { + $articleNames = @($override.article) + } else { + $articleNames = @($articles | Select-Object -First 1 | ForEach-Object BaseName) + } + + $selectedArticles = [System.Collections.Generic.List[object]]::new() + $seenArticleNames = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase) + foreach ($articleNameValue in $articleNames) { + if ($articleNameValue -isnot [string] -or [string]::IsNullOrWhiteSpace([string]$articleNameValue)) { + $problems.Add("${domain}: override article names must be non-empty strings.") | Out-Null + continue + } + $articleName = [string]$articleNameValue if ($articleName.EndsWith('.md')) { $articleName = [System.IO.Path]::GetFileNameWithoutExtension($articleName) } + if (-not $seenArticleNames.Add($articleName)) { + $problems.Add("${domain}: override contains duplicate article: $articleName.md") | Out-Null + continue + } + $selectedArticle = $articles | Where-Object BaseName -eq $articleName | Select-Object -First 1 if (-not $selectedArticle) { $articleExists = @( @@ -218,32 +248,41 @@ foreach ($domain in $leafDomains) { } continue } - } else { - $selectedArticle = $articles | Select-Object -First 1 + $selectedArticles.Add($selectedArticle) | Out-Null } - if (-not $selectedArticle) { - $problems.Add("${domain}: no article has both .good.al and .bad.al companion samples.") | Out-Null + if (-not $selectedArticles.Count) { + if (-not $articleNames.Count) { + $problems.Add("${domain}: no article has both .good.al and .bad.al companion samples.") | Out-Null + } continue } - $articlePath = [string]$selectedArticle.ArticlePath - $sampleDirectory = (Split-Path -Parent $articlePath).Replace('\', '/') $context = if ($override -and ($override.PSObject.Properties.Name -contains 'context')) { [string]$override.context } else { $null } - foreach ($kind in 'bad', 'good') { - $case = [pscustomobject]@{ - id = "$domain-$kind" - domain = $domain - input = "$sampleDirectory/$($selectedArticle.BaseName).$kind.al" - expected = if ($kind -eq 'bad') { @($articlePath) } else { @() } + for ($articleIndex = 0; $articleIndex -lt $selectedArticles.Count; $articleIndex++) { + $selectedArticle = $selectedArticles[$articleIndex] + $articlePath = [string]$selectedArticle.ArticlePath + $sampleDirectory = (Split-Path -Parent $articlePath).Replace('\', '/') + foreach ($kind in 'bad', 'good') { + $caseId = if ($articleIndex -eq 0) { + "$domain-$kind" + } else { + "$domain-$($selectedArticle.BaseName)-$kind" + } + $case = [pscustomobject]@{ + id = $caseId + domain = $domain + input = "$sampleDirectory/$($selectedArticle.BaseName).$kind.al" + expected = if ($kind -eq 'bad') { @($articlePath) } else { @() } + } + if ($context) { + $case | Add-Member -NotePropertyName context -NotePropertyValue $context + } + $caseList.Add($case) | Out-Null } - if ($context) { - $case | Add-Member -NotePropertyName context -NotePropertyValue $context - } - $caseList.Add($case) | Out-Null } } $cases = @($caseList) From 852a6762857cdd2a13d675ea0245e24471914e95 Mon Sep 17 00:00:00 2001 From: dayland <48474707+dayland@users.noreply.github.com> Date: Tue, 15 Sep 2026 09:32:40 +0200 Subject: [PATCH 07/35] Fix Job Queue sample links (#184) Use the required READ-convention Markdown links so knowledge retrieval can associate all new samples with their articles. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: dayland Copilot-Session: 76eb42c4-2acd-4f9c-a898-f4a44f9d46f7 --- .../job-queue-category-code-serializes-conflicting-jobs.md | 4 ++-- .../job-queue-external-effects-must-be-idempotent.md | 4 ++-- .../performance/job-queue-handlers-must-not-require-ui.md | 4 ++-- .../performance/job-queue-handlers-must-propagate-failures.md | 4 ++-- .../job-queue-on-hold-does-not-stop-running-work.md | 4 ++-- .../store-scheduled-task-id-to-avoid-duplicate-tasks.md | 4 ++-- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.md b/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.md index d92647e..190fb5e 100644 --- a/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.md +++ b/microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.md @@ -19,10 +19,10 @@ Different job queue entries can run at the same time. When two jobs update the s Assign the same non-empty Job Queue Category Code to job queue entries in the same company that must not overlap, regardless of which codeunit they run. Define categories around the shared resource or exclusivity requirement, not merely around object names. Leave independent jobs in different categories so they can still run concurrently. A category does not serialize work across companies or environments, or coordinate workers outside the job queue dispatcher. Protect shared external or cross-company resources with a separate application-level locking mechanism. -See sample: `job-queue-category-code-serializes-conflicting-jobs.good.al`. +See sample: [`job-queue-category-code-serializes-conflicting-jobs.good.al`](job-queue-category-code-serializes-conflicting-jobs.good.al). ## Anti Pattern Creating or configuring multiple job queue entries that update the same exclusive resource while leaving their Job Queue Category Code empty or different. Do not flag jobs merely because they touch the same tables; the rule applies when their operation requires mutual exclusion. -See sample: `job-queue-category-code-serializes-conflicting-jobs.bad.al`. \ No newline at end of file +See sample: [`job-queue-category-code-serializes-conflicting-jobs.bad.al`](job-queue-category-code-serializes-conflicting-jobs.bad.al). \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.md b/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.md index a5932df..66bb11b 100644 --- a/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.md +++ b/microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.md @@ -21,10 +21,10 @@ Use a stable request ID that exists before the job queue processes the outbox ro A `Processed` flag set after the external call does not solve this failure window. If a later AL error rolls back that flag, the outbox row again looks unprocessed even though the external operation already happened. -See sample: `job-queue-external-effects-must-be-idempotent.good.al`. +See sample: [`job-queue-external-effects-must-be-idempotent.good.al`](job-queue-external-effects-must-be-idempotent.good.al). ## Anti Pattern Sending a state-changing request from a job queue handler with no stable request ID understood by the external API. Specifically, look for this sequence: read an outbox row, call `HttpClient.Post` or another side-effecting API, update or delete local data, and propagate an error after which the same outbox row can be processed again. The key may be part of the request body, URI, headers, or an existing business key; a naturally idempotent remote operation is already safe and should not be flagged. -See sample: `job-queue-external-effects-must-be-idempotent.bad.al`. \ No newline at end of file +See sample: [`job-queue-external-effects-must-be-idempotent.bad.al`](job-queue-external-effects-must-be-idempotent.bad.al). \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.md b/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.md index f780ab5..5987270 100644 --- a/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.md +++ b/microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.md @@ -19,10 +19,10 @@ A job queue handler runs in a background session with no client UI. Calls that r Make a dedicated job queue entry point non-interactive. Validate parameters and data in AL, persist business-visible status when needed, and let failures propagate to the job queue log. If one procedure genuinely serves both foreground and background callers, isolate optional UI-only behavior behind `GuiAllowed`; do not use the guard to silently skip a decision that the operation requires. -See sample: `job-queue-handlers-must-not-require-ui.good.al`. +See sample: [`job-queue-handlers-must-not-require-ui.good.al`](job-queue-handlers-must-not-require-ui.good.al). ## Anti Pattern Calling `Confirm`, `Page.Run`, `Page.RunModal`, `Report.Run`, `Report.RunModal`, `Hyperlink`, `File.Upload`, or `File.Download` from a codeunit run by the job queue. Another signal is using `Message` as the only success or failure notification: no user is attached to receive it. -See sample: `job-queue-handlers-must-not-require-ui.bad.al`. \ No newline at end of file +See sample: [`job-queue-handlers-must-not-require-ui.bad.al`](job-queue-handlers-must-not-require-ui.bad.al). \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.md b/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.md index 1c7b83f..361fc7d 100644 --- a/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.md +++ b/microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.md @@ -19,10 +19,10 @@ The job queue dispatcher can mark an entry as failed, record the error, and appl Let an error that invalidates the whole run propagate out of the job queue entry point. Add context only when it helps an operator diagnose the failure and does not expose sensitive data. Per-item failures may be collected deliberately, but the batch must persist or emit an observable aggregate outcome instead of silently treating incomplete work as success. -See sample: `job-queue-handlers-must-propagate-failures.good.al`. +See sample: [`job-queue-handlers-must-propagate-failures.good.al`](job-queue-handlers-must-propagate-failures.good.al). ## Anti Pattern Calling a `TryFunction`, `Codeunit.Run`, or another Boolean-returning operation from a job queue handler and using `exit` or normal fall-through on failure without recording an intentional partial-success outcome. The dispatcher sees a successful return, so the entry's status and log do not represent the failed work and configured retries are not applied. -See sample: `job-queue-handlers-must-propagate-failures.bad.al`. \ No newline at end of file +See sample: [`job-queue-handlers-must-propagate-failures.bad.al`](job-queue-handlers-must-propagate-failures.bad.al). \ No newline at end of file diff --git a/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.md b/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.md index 6eec05c..b0411a8 100644 --- a/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.md +++ b/microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.md @@ -19,10 +19,10 @@ The On Hold status prevents a job queue entry from starting again, but it does n Use On Hold to pause future scheduling. When a long-running operation must support graceful cancellation, store a separate application-owned stop request and check it before every bounded unit of work, including the first. Exit only at a point where completed work and the checkpoint are consistent. The code that resumes scheduling must clear the stop request before restarting the job. Use administrative session termination only when graceful cancellation is impossible. -See sample: `job-queue-on-hold-does-not-stop-running-work.good.al`. +See sample: [`job-queue-on-hold-does-not-stop-running-work.good.al`](job-queue-on-hold-does-not-stop-running-work.good.al). ## Anti Pattern Polling the job queue entry's Status field from inside its handler and expecting a change to On Hold to cancel the active run. The status controls scheduling, not cooperative cancellation, so the handler can continue processing despite the operator's action. -See sample: `job-queue-on-hold-does-not-stop-running-work.bad.al`. \ No newline at end of file +See sample: [`job-queue-on-hold-does-not-stop-running-work.bad.al`](job-queue-on-hold-does-not-stop-running-work.bad.al). \ No newline at end of file diff --git a/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.md b/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.md index 600c671..1e64c32 100644 --- a/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.md +++ b/microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.md @@ -19,10 +19,10 @@ Every call to `TaskScheduler.CreateTask` creates a new scheduled task and return Persist the GUID returned by `CreateTask` at the same scope as the logical task. Before creating a replacement, parse the stored GUID and call `TaskScheduler.TaskExists`; create and store a new task only when the previous task no longer exists. `TaskExists` checks one GUID, not whether an equivalent codeunit is already scheduled, so callers that can schedule concurrently still need serialization around this check-and-create sequence. -See sample: `store-scheduled-task-id-to-avoid-duplicate-tasks.good.al`. +See sample: [`store-scheduled-task-id-to-avoid-duplicate-tasks.good.al`](store-scheduled-task-id-to-avoid-duplicate-tasks.good.al). ## Anti Pattern Calling `TaskScheduler.CreateTask` every time initialization, login, setup, or another repeatable path runs while ignoring its return value. Each invocation creates another independent task even when an equivalent task is already pending. -See sample: `store-scheduled-task-id-to-avoid-duplicate-tasks.bad.al`. \ No newline at end of file +See sample: [`store-scheduled-task-id-to-avoid-duplicate-tasks.bad.al`](store-scheduled-task-id-to-avoid-duplicate-tasks.bad.al). \ No newline at end of file From b74967bc5b7a454eae19d6a1250199afd869f064 Mon Sep 17 00:00:00 2001 From: dayland <48474707+dayland@users.noreply.github.com> Date: Tue, 15 Sep 2026 10:27:40 +0200 Subject: [PATCH 08/35] Add machine-readable review contracts (#182) Generate a deterministic action-skill index from frontmatter, publish structural schemas for orchestration and findings, and validate flat review composition in CI. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: dayland Copilot-Session: 76eb42c4-2acd-4f9c-a898-f4a44f9d46f7 --- .github/scripts/Test-SkillIndex.ps1 | 240 +++++++++++++++++++++ .github/scripts/validate_frontmatter.py | 41 +++- .github/workflows/skill-index.yml | 18 ++ microsoft/skills/review/al-code-review.md | 5 + schemas/findings-report.schema.json | 159 ++++++++++++++ schemas/skill-index.schema.json | 84 ++++++++ skills/do.md | 12 ++ tools/Build-SkillIndex.ps1 | 247 ++++++++++++++++++++++ 8 files changed, 803 insertions(+), 3 deletions(-) create mode 100644 .github/scripts/Test-SkillIndex.ps1 create mode 100644 .github/workflows/skill-index.yml create mode 100644 schemas/findings-report.schema.json create mode 100644 schemas/skill-index.schema.json create mode 100644 tools/Build-SkillIndex.ps1 diff --git a/.github/scripts/Test-SkillIndex.ps1 b/.github/scripts/Test-SkillIndex.ps1 new file mode 100644 index 0000000..839042f --- /dev/null +++ b/.github/scripts/Test-SkillIndex.ps1 @@ -0,0 +1,240 @@ +<# +.SYNOPSIS + Validates the BCQuality action-skill index generator and shared schemas. +#> +[CmdletBinding()] +param( + [string] $Root = (Resolve-Path (Join-Path -Path $PSScriptRoot -ChildPath '..' '..')) +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' +$Root = (Resolve-Path -LiteralPath $Root).Path + +function Assert-ThrowsLike { + param( + [scriptblock] $Action, + [string] $Pattern + ) + + try { + & $Action + } + catch { + if ($_.Exception.Message -like $Pattern) { + return + } + throw "Expected error like '$Pattern', received: $($_.Exception.Message)" + } + throw "Expected error like '$Pattern', but no error was thrown." +} + +$generator = Join-Path $Root 'tools/Build-SkillIndex.ps1' +$indexSchema = Join-Path $Root 'schemas/skill-index.schema.json' +$reportSchema = Join-Path $Root 'schemas/findings-report.schema.json' +foreach ($path in $generator, $indexSchema, $reportSchema) { + if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { + throw "Required contract file not found: $path" + } +} + +$tmp = Join-Path ([IO.Path]::GetTempPath()) ("skillindex_" + [guid]::NewGuid().ToString('N')) +New-Item -ItemType Directory -Path $tmp -Force | Out-Null +try { + $first = Join-Path $tmp 'first.json' + $second = Join-Path $tmp 'second.json' + & $generator -BCQualityRoot $Root -IndexPath $first | Out-Null + & $generator -BCQualityRoot $Root -IndexPath $second | Out-Null + + $normalize = { + param([string] $Path) + return ((Get-Content -LiteralPath $Path -Raw) -replace '"generatedAt":"[^"]*"', '"generatedAt":""') + } + if ((& $normalize $first) -ne (& $normalize $second)) { + throw 'Skill index is not deterministic beyond generatedAt.' + } + + $raw = Get-Content -LiteralPath $first -Raw + if (-not ($raw | Test-Json -SchemaFile $indexSchema -ErrorAction Stop)) { + throw 'Generated skill index does not satisfy schemas/skill-index.schema.json.' + } + + $index = $raw | ConvertFrom-Json + $skills = @($index.skills) + if ($index.skillCount -ne $skills.Count) { + throw "skillCount is $($index.skillCount), but the index contains $($skills.Count) records." + } + + $paths = @($skills.path) + $duplicates = @($paths | Group-Object | Where-Object Count -gt 1) + if ($duplicates.Count) { + throw "Duplicate skill paths: $($duplicates.Name -join ', ')" + } + foreach ($path in $paths) { + if (-not (Test-Path -LiteralPath (Join-Path $Root $path) -PathType Leaf)) { + throw "Indexed skill does not exist: $path" + } + } + + $expectedLeaves = @( + 'microsoft/skills/review/al-performance-review.md', + 'microsoft/skills/review/al-security-review.md', + 'microsoft/skills/review/al-privacy-review.md', + 'microsoft/skills/review/al-upgrade-review.md', + 'microsoft/skills/review/al-style-review.md', + 'microsoft/skills/review/al-ui-review.md', + 'microsoft/skills/review/al-error-handling-review.md', + 'microsoft/skills/review/al-events-review.md', + 'microsoft/skills/review/al-interfaces-review.md', + 'microsoft/skills/review/al-breaking-changes-review.md', + 'microsoft/skills/review/al-web-services-review.md', + 'microsoft/skills/review/al-testing-review.md', + 'microsoft/skills/review/al-data-modeling-review.md', + 'microsoft/skills/review/al-query-review.md', + 'microsoft/skills/review/al-appsource-review.md', + 'microsoft/skills/review/al-telemetry-review.md' + ) + $review = @($skills | Where-Object id -eq 'al-code-review') + if ($review.Count -ne 1) { + throw "Expected exactly one al-code-review record, found $($review.Count)." + } + if ((@($review[0].subSkills) -join "`n") -cne ($expectedLeaves -join "`n")) { + throw 'al-code-review subSkills did not preserve the declared 16-leaf order.' + } + foreach ($leafPath in $expectedLeaves) { + $leaf = @($skills | Where-Object path -ceq $leafPath) + if ($leaf.Count -ne 1 -or @($leaf[0].subSkills).Count -ne 0) { + throw "Expected '$leafPath' to resolve to exactly one leaf action skill." + } + } + + $minimalReport = @{ + skill = @{ id = 'al-style-review'; version = 1 } + outcome = 'completed' + summary = @{ + counts = @{ blocker = 0; major = 0; minor = 0; info = 0 } + coverage = @{ 'worklist-size' = 0; 'items-evaluated' = 0 } + } + findings = @() + suppressed = @() + } | ConvertTo-Json -Depth 8 + if (-not ($minimalReport | Test-Json -SchemaFile $reportSchema -ErrorAction Stop)) { + throw 'Minimal findings report does not satisfy schemas/findings-report.schema.json.' + } + + $reviewSkillText = Get-Content -LiteralPath ( + Join-Path -Path $Root -ChildPath 'microsoft/skills/review/al-code-review.md' + ) -Raw + $reportExamples = [regex]::Matches($reviewSkillText, '(?s)```json\s*(\{.*?\})\s*```') + if ($reportExamples.Count -ne 2) { + throw "Expected two al-code-review JSON examples, found $($reportExamples.Count)." + } + foreach ($example in $reportExamples) { + if (-not ($example.Groups[1].Value | Test-Json -SchemaFile $reportSchema -ErrorAction Stop)) { + throw 'An al-code-review output example does not satisfy schemas/findings-report.schema.json.' + } + } + + $fixtureRoot = Join-Path -Path $tmp -ChildPath 'fixture' + $fixtureSkills = Join-Path -Path $fixtureRoot -ChildPath 'microsoft/skills/review' + New-Item -ItemType Directory -Path $fixtureSkills -Force | Out-Null + $leaf = @' +--- +kind: action-skill +id: al-leaf-review +version: 1 +title: Leaf +description: Test leaf. +inputs: [file-path] +outputs: [findings-report] +--- + +# Leaf + +## Source +Source. +## Relevance +Relevance. +## Worklist +Worklist. +## Action +Action. +## Output +Output. +'@ + Set-Content -LiteralPath (Join-Path $fixtureSkills 'al-leaf-review.md') -Value $leaf -Encoding utf8NoBOM + + $duplicateSuper = @' +--- +kind: action-skill +id: al-code-review +version: 1 +title: Review +description: Test super-skill. +inputs: [file-path] +outputs: [findings-report] +sub-skills: + - microsoft/skills/review/al-leaf-review.md + - microsoft/skills/review/al-leaf-review.md +--- + +# Review + +## Source +Source. +## Relevance +Relevance. +## Worklist +Worklist. +## Action +Action. +## Output +Output. +'@ + $superPath = Join-Path $fixtureSkills 'al-code-review.md' + Set-Content -LiteralPath $superPath -Value $duplicateSuper -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*duplicate sub-skill*' -Action { + & $generator -BCQualityRoot $fixtureRoot -IndexPath (Join-Path $tmp 'invalid.json') + } + + $nestedLeaf = $leaf.Replace('id: al-leaf-review', 'id: al-nested-review').Replace( + 'outputs: [findings-report]', + "outputs: [findings-report]`nsub-skills:`n - microsoft/skills/review/al-leaf-review.md" + ) + Set-Content -LiteralPath (Join-Path $fixtureSkills 'al-nested-review.md') -Value $nestedLeaf -Encoding utf8NoBOM + $nestedSuper = @' +--- +kind: action-skill +id: al-code-review +version: 1 +title: Review +description: Test super-skill. +inputs: [file-path] +outputs: [findings-report] +sub-skills: + - microsoft/skills/review/al-nested-review.md +--- + +# Review + +## Source +Source. +## Relevance +Relevance. +## Worklist +Worklist. +## Action +Action. +## Output +Output. +'@ + Set-Content -LiteralPath $superPath -Value $nestedSuper -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*Nested super-skills are not supported*' -Action { + & $generator -BCQualityRoot $fixtureRoot -IndexPath (Join-Path $tmp 'nested.json') + } +} +finally { + Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue +} + +Write-Output 'Skill-index check PASSED: deterministic, schema-valid, and all 16 review leaves preserved in order.' diff --git a/.github/scripts/validate_frontmatter.py b/.github/scripts/validate_frontmatter.py index f422d53..20f33d6 100644 --- a/.github/scripts/validate_frontmatter.py +++ b/.github/scripts/validate_frontmatter.py @@ -381,6 +381,20 @@ def validate_action_skill(path: Path, parsed: Parsed, report: Report) -> None: bad = [x for x in ss if not x.endswith(".md")] if bad: report.error(path, "R20", f"sub-skills entries must end in '.md': {bad}", 1) + non_canonical = [ + x for x in ss + if "\\" in x or x.startswith("/") or ".." in Path(x).parts or x.startswith("./") + ] + if non_canonical: + report.error( + path, + "R20", + f"sub-skills entries must be canonical repo-relative paths: {non_canonical}", + 1, + ) + duplicates = sorted({x for x in ss if ss.count(x) > 1}) + if duplicates: + report.error(path, "R20", f"sub-skills contains duplicate paths: {duplicates}", 1) # R21 five required sections, in order, each exactly once heads = [h for h, _ in headings_in_order(parsed.body)] @@ -565,7 +579,13 @@ class SkillRecord: skill_id: str | None -def validate_sub_skills_registry(path: Path, fm: dict[str, Any], root: Path, report: Report) -> None: +def validate_sub_skills_registry( + path: Path, + fm: dict[str, Any], + root: Path, + action_skills_by_path: dict[str, dict[str, Any]], + report: Report, +) -> None: """R26: a super-skill's declared `sub-skills` must exactly match the `al-*-review.md` leaf files present in the same directory (set equality, ordering-agnostic). This keeps the registered leaf list the single source @@ -598,6 +618,17 @@ def validate_sub_skills_registry(path: Path, fm: dict[str, Any], root: Path, rep f"sub-skills entry is not a sibling 'al-*-review.md' leaf: {entry}", 1, ) + for entry in ss: + leaf = action_skills_by_path.get(entry) + if leaf is None: + if (root / entry).exists(): + report.error(path, "R26", f"sub-skills entry is not an action skill: {entry}", 1) + continue + if is_non_empty_list_of_str(leaf.get("sub-skills")): + report.error(path, "R26", f"nested super-skill is not permitted in v1 composition: {entry}", 1) + if leaf.get("outputs") != ["findings-report"]: + report.error(path, "R26", f"sub-skill must produce findings-report: {entry}", 1) + # Sibling leaves on disk that were never registered ('forgot to wire it up'). for leaf in sorted(leaves - declared): report.error(path, "R26", f"leaf not registered in sub-skills: {leaf}", 1) @@ -670,9 +701,13 @@ def run(root: Path) -> Report: others = [q.relative_to(root).as_posix() for q in paths if q != p] report.error(p, "R24", f"skill id '{sid}' ({kind}) is not unique; also defined in: {others}") - # Fourth pass: R26 sub-skills registry matches leaf files on disk + # Fourth pass: R26 sub-skills registry matches compatible leaf files on disk + action_skills_by_path = { + path.relative_to(root).as_posix(): fm + for path, fm in action_skill_fms + } for path, fm in action_skill_fms: - validate_sub_skills_registry(path, fm, root, report) + validate_sub_skills_registry(path, fm, root, action_skills_by_path, report) return report diff --git a/.github/workflows/skill-index.yml b/.github/workflows/skill-index.yml new file mode 100644 index 0000000..b1b8e3a --- /dev/null +++ b/.github/workflows/skill-index.yml @@ -0,0 +1,18 @@ +name: Validate skill index and report schemas + +on: + pull_request: + branches: [main] + push: + branches: [main] + +jobs: + validate-contract: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Validate skill-index generator and schemas + shell: pwsh + run: ./.github/scripts/Test-SkillIndex.ps1 -Root . diff --git a/microsoft/skills/review/al-code-review.md b/microsoft/skills/review/al-code-review.md index 9239220..9b5f739 100644 --- a/microsoft/skills/review/al-code-review.md +++ b/microsoft/skills/review/al-code-review.md @@ -41,6 +41,11 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat The sub-skills invoked by this skill are those listed in frontmatter `sub-skills`. Additional leaf skills are added by updating the `sub-skills` list. The skill does not discover sub-skills implicitly. +Hosts that orchestrate leaves mechanically SHOULD run +`tools/Build-SkillIndex.ps1` and resolve this skill by `id: al-code-review`. +The generated `subSkills` array preserves the frontmatter order and avoids +host-specific Markdown parsing. + ## Relevance A sub-skill is relevant when both of the following hold: diff --git a/schemas/findings-report.schema.json b/schemas/findings-report.schema.json new file mode 100644 index 0000000..76712f4 --- /dev/null +++ b/schemas/findings-report.schema.json @@ -0,0 +1,159 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://github.com/microsoft/BCQuality/schemas/findings-report.schema.json", + "title": "BCQuality findings report", + "type": "object", + "additionalProperties": false, + "required": ["skill", "outcome", "summary", "findings", "suppressed"], + "properties": { + "skill": { "$ref": "#/definitions/skillReference" }, + "outcome": { + "enum": ["completed", "not-applicable", "no-knowledge", "partial", "failed"] + }, + "outcome-reason": { "type": "string", "minLength": 1 }, + "summary": { "$ref": "#/definitions/summary" }, + "findings": { + "type": "array", + "items": { "$ref": "#/definitions/finding" } + }, + "suppressed": { + "type": "array", + "items": { "$ref": "#/definitions/suppressed" } + }, + "sub-results": { + "type": "array", + "items": { "$ref": "#" } + }, + "skipped-sub-skills": { + "type": "array", + "items": { "$ref": "#/definitions/skippedSubSkill" } + } + }, + "allOf": [ + { + "if": { + "properties": { + "outcome": { "enum": ["partial", "failed"] } + } + }, + "then": { "required": ["outcome-reason"] } + }, + { + "if": { + "properties": { + "outcome": { "enum": ["not-applicable", "no-knowledge", "failed"] } + } + }, + "then": { + "properties": { + "findings": { "maxItems": 0 } + } + } + } + ], + "definitions": { + "skillReference": { + "type": "object", + "additionalProperties": false, + "required": ["id", "version"], + "properties": { + "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, + "version": { "type": "integer", "minimum": 1 } + } + }, + "counts": { + "type": "object", + "additionalProperties": false, + "required": ["blocker", "major", "minor", "info"], + "properties": { + "blocker": { "type": "integer", "minimum": 0 }, + "major": { "type": "integer", "minimum": 0 }, + "minor": { "type": "integer", "minimum": 0 }, + "info": { "type": "integer", "minimum": 0 } + } + }, + "coverage": { + "type": "object", + "additionalProperties": false, + "required": ["worklist-size", "items-evaluated"], + "properties": { + "worklist-size": { "type": "integer", "minimum": 0 }, + "items-evaluated": { "type": "integer", "minimum": 0 } + } + }, + "summary": { + "type": "object", + "additionalProperties": false, + "required": ["counts", "coverage"], + "properties": { + "counts": { "$ref": "#/definitions/counts" }, + "coverage": { "$ref": "#/definitions/coverage" } + } + }, + "reference": { + "type": "object", + "additionalProperties": false, + "required": ["path"], + "properties": { + "path": { "type": "string", "minLength": 1, "pattern": "^[^\\\\]+$" }, + "sha": { "type": "string", "pattern": "^[a-fA-F0-9]{40}$" } + } + }, + "location": { + "type": "object", + "additionalProperties": false, + "required": ["file", "line"], + "properties": { + "file": { "type": "string", "minLength": 1, "pattern": "^[^\\\\]+$" }, + "line": { "type": "integer", "minimum": 1 }, + "range": { + "type": "object", + "additionalProperties": false, + "required": ["start-line", "end-line"], + "properties": { + "start-line": { "type": "integer", "minimum": 1 }, + "end-line": { "type": "integer", "minimum": 1 } + } + } + } + }, + "finding": { + "type": "object", + "additionalProperties": false, + "required": ["id", "severity", "message", "references", "confidence"], + "properties": { + "id": { "type": "string", "minLength": 1 }, + "severity": { "enum": ["blocker", "major", "minor", "info"] }, + "message": { "type": "string", "minLength": 1 }, + "location": { "$ref": "#/definitions/location" }, + "references": { + "type": "array", + "items": { "$ref": "#/definitions/reference" } + }, + "confidence": { "enum": ["high", "medium", "low"] }, + "from-sub-skill": { "type": "string", "minLength": 1 }, + "domain": { "type": "string", "minLength": 1, "pattern": "^[^\\r\\n]+$" }, + "suggested-code": { "type": "string", "minLength": 1 }, + "suggested-code-omission-reason": { "type": "string", "minLength": 1 } + } + }, + "suppressed": { + "type": "object", + "additionalProperties": false, + "required": ["reference", "reason"], + "properties": { + "reference": { "$ref": "#/definitions/reference" }, + "reason": { "enum": ["layer-precedence", "configuration"] } + } + }, + "skippedSubSkill": { + "type": "object", + "additionalProperties": false, + "required": ["skill", "reason"], + "properties": { + "skill": { "$ref": "#/definitions/skillReference" }, + "reason": { "enum": ["configuration", "not-applicable"] } + } + } + } +} diff --git a/schemas/skill-index.schema.json b/schemas/skill-index.schema.json new file mode 100644 index 0000000..01944bb --- /dev/null +++ b/schemas/skill-index.schema.json @@ -0,0 +1,84 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://github.com/microsoft/BCQuality/schemas/skill-index.schema.json", + "title": "BCQuality action-skill index", + "type": "object", + "additionalProperties": false, + "required": ["version", "generatedAt", "skillCount", "sourceSnapshot", "skills"], + "properties": { + "version": { "const": 1 }, + "generatedAt": { "type": "string", "format": "date-time" }, + "skillCount": { "type": "integer", "minimum": 0 }, + "sourceSnapshot": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, + "skills": { + "type": "array", + "items": { "$ref": "#/definitions/skill" } + } + }, + "definitions": { + "stringArray": { + "type": "array", + "items": { "type": "string", "minLength": 1 } + }, + "skill": { + "type": "object", + "additionalProperties": false, + "required": [ + "path", + "layer", + "id", + "version", + "title", + "description", + "inputs", + "outputs", + "filters", + "subSkills", + "sourceSha256" + ], + "properties": { + "path": { "type": "string", "pattern": "^(microsoft|community|custom)/skills/.+\\.md$" }, + "layer": { "enum": ["microsoft", "community", "custom"] }, + "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, + "version": { "type": "integer", "minimum": 1 }, + "title": { "type": "string", "minLength": 1 }, + "description": { "type": "string", "minLength": 1 }, + "inputs": { "$ref": "#/definitions/stringArray" }, + "outputs": { + "type": "array", + "minItems": 1, + "maxItems": 1, + "items": { "const": "findings-report" } + }, + "filters": { + "type": "object", + "additionalProperties": false, + "required": ["bc-version", "technologies", "countries", "application-area"], + "properties": { + "bc-version": { + "type": "array", + "items": { + "oneOf": [ + { "type": "integer", "minimum": 1 }, + { "type": "string", "pattern": "^(all|[1-9][0-9]*\\.\\.[1-9][0-9]*|[1-9][0-9]*\\.\\.)$" } + ] + } + }, + "technologies": { "$ref": "#/definitions/stringArray" }, + "countries": { "$ref": "#/definitions/stringArray" }, + "application-area": { "$ref": "#/definitions/stringArray" } + } + }, + "subSkills": { + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^(microsoft|community|custom)/skills/.+\\.md$" + } + }, + "sourceSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } + } + } + } +} diff --git a/skills/do.md b/skills/do.md index 9abdf58..e67faf6 100644 --- a/skills/do.md +++ b/skills/do.md @@ -106,6 +106,12 @@ Every action skill MUST contain these five sections, in order: Every action skill emits a single JSON document that conforms to this schema: +The machine-readable structural schema is +[`schemas/findings-report.schema.json`](../schemas/findings-report.schema.json). +The rules below remain authoritative for semantic checks that JSON Schema +cannot perform by itself, including summary arithmetic, reference existence, +source-scope locations, and article-body retrieval. + ```json { "skill": { "id": "string", "version": 1 }, @@ -349,6 +355,12 @@ the declared worklist order, and wait for every invocation to finish before performing any super-skill self-review or final rollup. Scheduling MUST NOT change relevance, coverage, failure, reference-integrity, or output semantics. +Orchestrators SHOULD generate `skill-index.json` with +`tools/Build-SkillIndex.ps1` and consume the super-skill's ordered `subSkills` +from that index instead of parsing Markdown. Action-skill frontmatter remains +the source of truth; the generated index conforms to +`schemas/skill-index.schema.json`. + ### Section interpretation for super-skills The five required sections still apply. Their meaning shifts from knowledge files to sub-skills: diff --git a/tools/Build-SkillIndex.ps1 b/tools/Build-SkillIndex.ps1 new file mode 100644 index 0000000..022898e --- /dev/null +++ b/tools/Build-SkillIndex.ps1 @@ -0,0 +1,247 @@ +<# +.SYNOPSIS + Builds the machine-readable BCQuality action-skill index. + +.DESCRIPTION + Action-skill frontmatter remains the source of truth. This script emits the + versioned JSON contract orchestrators consume so they do not need to parse + Markdown or duplicate composition rules. + +.PARAMETER BCQualityRoot + BCQuality repository or filtered content root. + +.PARAMETER IndexPath + Output path. Defaults to /skill-index.json. + +.OUTPUTS + Returns the number of indexed action skills. +#> +[CmdletBinding()] +param( + [string] $BCQualityRoot, + [string] $IndexPath +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +if (-not $BCQualityRoot) { + $BCQualityRoot = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path +} +if (-not (Test-Path -LiteralPath $BCQualityRoot -PathType Container)) { + throw "BCQuality root not found: $BCQualityRoot" +} +$BCQualityRoot = (Resolve-Path -LiteralPath $BCQualityRoot).Path +if (-not $IndexPath) { + $IndexPath = Join-Path $BCQualityRoot 'skill-index.json' +} + +function Get-RelativePath { + param([string] $Root, [string] $Full) + + return ($Full.Substring($Root.Length).TrimStart([char]'/', [char]'\') -replace '\\', '/') +} + +function Get-Sha256 { + param([byte[]] $Bytes) + + $sha = [Security.Cryptography.SHA256]::Create() + try { + return ([BitConverter]::ToString($sha.ComputeHash($Bytes)) -replace '-', '').ToLowerInvariant() + } + finally { + $sha.Dispose() + } +} + +function Get-ValueSha256 { + param([Parameter(Mandatory)] $Value) + + return Get-Sha256 -Bytes ([Text.Encoding]::UTF8.GetBytes( + (ConvertTo-Json -InputObject $Value -Depth 12 -Compress) + )) +} + +function ConvertFrom-SkillFrontmatter { + param( + [string] $Path, + [string] $Text + ) + + $lines = [regex]::Split($Text.TrimStart([char]0xfeff), '\r\n|\n|\r') + if ($lines.Count -lt 3 -or $lines[0].Trim() -ne '---') { + throw [IO.InvalidDataException]::new("Missing frontmatter in '$Path'.") + } + + $end = -1 + for ($i = 1; $i -lt $lines.Count; $i++) { + if ($lines[$i].Trim() -eq '---') { + $end = $i + break + } + } + if ($end -lt 0) { + throw [IO.InvalidDataException]::new("Unterminated frontmatter in '$Path'.") + } + + $frontmatter = [ordered]@{} + for ($i = 1; $i -lt $end; $i++) { + $line = $lines[$i] + if ($line -notmatch '^([a-zA-Z][\w-]*)\s*:\s*(.*)$') { + continue + } + + $key = $Matches[1] + $value = $Matches[2].Trim() + if ($value -eq '') { + $items = [System.Collections.Generic.List[string]]::new() + while ($i + 1 -lt $end -and $lines[$i + 1] -match '^\s+-\s+(.+?)\s*$') { + $i++ + $items.Add($Matches[1].Trim().Trim('"', "'")) | Out-Null + } + $frontmatter[$key] = @($items) + continue + } + + if ($value -match '^\[(.*)\]$') { + $inner = $Matches[1].Trim() + $values = [System.Collections.Generic.List[object]]::new() + if ($inner) { + foreach ($item in $inner -split '\s*,\s*') { + $normalized = $item.Trim().Trim('"', "'") + $number = 0 + if ($key -eq 'bc-version' -and [int]::TryParse($normalized, [ref]$number)) { + $values.Add($number) | Out-Null + } + else { + $values.Add($normalized) | Out-Null + } + } + } + $frontmatter[$key] = [object[]]@($values) + continue + } + + $frontmatter[$key] = $value.Trim('"', "'") + } + + return $frontmatter +} + +$records = [System.Collections.Generic.List[object]]::new() +$recordsByPath = [Collections.Generic.Dictionary[string, object]]::new([StringComparer]::Ordinal) +$sourceManifest = [System.Collections.Generic.List[object]]::new() + +foreach ($layer in 'microsoft', 'community', 'custom') { + $skillsRoot = Join-Path $BCQualityRoot (Join-Path $layer 'skills') + if (-not (Test-Path -LiteralPath $skillsRoot -PathType Container)) { + continue + } + + foreach ($file in Get-ChildItem -LiteralPath $skillsRoot -Recurse -File -Filter '*.md' | Sort-Object FullName) { + $bytes = [IO.File]::ReadAllBytes($file.FullName) + try { + $text = [Text.UTF8Encoding]::new($false, $true).GetString($bytes) + } + catch [Text.DecoderFallbackException] { + throw [IO.InvalidDataException]::new("Invalid UTF-8 in '$($file.FullName)'.", $_.Exception) + } + + $frontmatter = ConvertFrom-SkillFrontmatter -Path $file.FullName -Text $text + if ($frontmatter['kind'] -ne 'action-skill') { + continue + } + + foreach ($required in 'id', 'version', 'title', 'description', 'inputs', 'outputs') { + if (-not $frontmatter.Contains($required) -or $null -eq $frontmatter[$required] -or + ([string]$frontmatter[$required]).Trim() -eq '') { + throw [IO.InvalidDataException]::new( + "Action skill '$($file.FullName)' is missing required frontmatter '$required'." + ) + } + } + + $path = Get-RelativePath -Root $BCQualityRoot -Full $file.FullName + $sourceSha256 = Get-Sha256 -Bytes $bytes + $version = 0 + if (-not [int]::TryParse([string]$frontmatter['version'], [ref]$version) -or $version -le 0) { + throw [IO.InvalidDataException]::new("Action skill '$path' has an invalid version.") + } + + $subSkills = @() + if ($frontmatter.Contains('sub-skills')) { + $subSkills = @($frontmatter['sub-skills']) + if (-not $subSkills.Count) { + throw [IO.InvalidDataException]::new("Super-skill '$path' has an empty sub-skills list.") + } + } + + $record = [pscustomobject][ordered]@{ + path = $path + layer = $layer + id = [string]$frontmatter['id'] + version = $version + title = [string]$frontmatter['title'] + description = [string]$frontmatter['description'] + inputs = [string[]]@($frontmatter['inputs']) + outputs = [string[]]@($frontmatter['outputs']) + filters = [ordered]@{ + 'bc-version' = [object[]]$(if ($frontmatter.Contains('bc-version')) { $frontmatter['bc-version'] }) + technologies = [string[]]$(if ($frontmatter.Contains('technologies')) { $frontmatter['technologies'] }) + countries = [string[]]$(if ($frontmatter.Contains('countries')) { $frontmatter['countries'] }) + 'application-area' = [string[]]$(if ($frontmatter.Contains('application-area')) { $frontmatter['application-area'] }) + } + subSkills = [string[]]$subSkills + sourceSha256 = $sourceSha256 + } + + if (-not $recordsByPath.TryAdd($path, $record)) { + throw "Duplicate action-skill path: $path" + } + $records.Add($record) | Out-Null + $sourceManifest.Add([ordered]@{ path = $path; sha256 = $sourceSha256 }) | Out-Null + } +} + +$ids = @($records | Group-Object id | Where-Object Count -gt 1) +if ($ids.Count) { + throw "Duplicate action-skill IDs: $($ids.Name -join ', ')" +} + +foreach ($record in $records) { + $seen = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal) + foreach ($subSkillPath in @($record.subSkills)) { + if (-not $seen.Add($subSkillPath)) { + throw "Super-skill '$($record.path)' declares duplicate sub-skill '$subSkillPath'." + } + if (-not $recordsByPath.ContainsKey($subSkillPath)) { + throw "Super-skill '$($record.path)' references missing action skill '$subSkillPath'." + } + + $leaf = $recordsByPath[$subSkillPath] + if (@($leaf.subSkills).Count) { + throw "Nested super-skills are not supported: '$($record.path)' references '$subSkillPath'." + } + if (@($leaf.outputs).Count -ne 1 -or $leaf.outputs[0] -ne 'findings-report') { + throw "Sub-skill '$subSkillPath' must produce findings-report." + } + } +} + +$index = [ordered]@{ + version = 1 + generatedAt = (Get-Date).ToUniversalTime().ToString('o') + skillCount = $records.Count + sourceSnapshot = Get-ValueSha256 -Value @($sourceManifest) + skills = @($records) +} + +$parent = Split-Path -Parent $IndexPath +if ($parent -and -not (Test-Path -LiteralPath $parent)) { + New-Item -ItemType Directory -Path $parent -Force | Out-Null +} +Set-Content -LiteralPath $IndexPath -Value ( + ConvertTo-Json -InputObject $index -Depth 12 -Compress +) -Encoding utf8NoBOM + +return $records.Count From b545b22fb9173e0a1f17c3b2e02dc77ea6c92dab Mon Sep 17 00:00:00 2001 From: Stefano Demiliani <33155438+demiliani@users.noreply.github.com> Date: Tue, 15 Sep 2026 10:38:32 +0200 Subject: [PATCH 09/35] Add reporting review guidance and evaluation fixtures (#183) * knowledge(performance): add job queue reliability guidance * Address Job Queue review feedback * Address Job Queue routing review feedback * Encode job queue conflict in fixtures * Add reporting review guidance and fixtures * Fix reporting article reference --- docs/using-bcquality.md | 3 +- evaluation/review-fixtures.json | 13 ++++ ...ariable-before-independent-runmodal.bad.al | 16 +++++ ...riable-before-independent-runmodal.good.al | 17 +++++ ...rt-variable-before-independent-runmodal.md | 32 ++++++++++ ...port-break-ends-the-current-trigger.bad.al | 31 +++++++++ ...ort-break-ends-the-current-trigger.good.al | 31 +++++++++ ...rrreport-break-ends-the-current-trigger.md | 30 +++++++++ ...t-rolls-back-and-skips-onpostreport.bad.al | 27 ++++++++ ...-rolls-back-and-skips-onpostreport.good.al | 28 +++++++++ ...-quit-rolls-back-and-skips-onpostreport.md | 30 +++++++++ ...ort-skip-does-not-stop-trigger-code.bad.al | 26 ++++++++ ...rt-skip-does-not-stop-trigger-code.good.al | 28 +++++++++ ...rreport-skip-does-not-stop-trigger-code.md | 30 +++++++++ ...in-a-loop-needs-one-client-download.bad.al | 14 +++++ ...n-a-loop-needs-one-client-download.good.al | 37 +++++++++++ ...put-in-a-loop-needs-one-client-download.md | 32 ++++++++++ ...-dataitem-trigger-order-is-explicit.bad.al | 30 +++++++++ ...dataitem-trigger-order-is-explicit.good.al | 30 +++++++++ ...sion-dataitem-trigger-order-is-explicit.md | 32 ++++++++++ ...rt-triggers-run-after-base-triggers.bad.al | 31 +++++++++ ...t-triggers-run-after-base-triggers.good.al | 37 +++++++++++ ...report-triggers-run-after-base-triggers.md | 30 +++++++++ ...ew-cannot-broaden-dataitemtableview.bad.al | 26 ++++++++ ...w-cannot-broaden-dataitemtableview.good.al | 26 ++++++++ ...leview-cannot-broaden-dataitemtableview.md | 30 +++++++++ ...equestpage-returns-empty-parameters.bad.al | 17 +++++ ...questpage-returns-empty-parameters.good.al | 20 ++++++ ...runrequestpage-returns-empty-parameters.md | 30 +++++++++ microsoft/skills/review/al-code-review.md | 1 + .../skills/review/al-reporting-review.md | 63 +++++++++++++++++++ 31 files changed, 827 insertions(+), 1 deletion(-) create mode 100644 microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.bad.al create mode 100644 microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.good.al create mode 100644 microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.md create mode 100644 microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.bad.al create mode 100644 microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.good.al create mode 100644 microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.md create mode 100644 microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.bad.al create mode 100644 microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.good.al create mode 100644 microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.md create mode 100644 microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.bad.al create mode 100644 microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.good.al create mode 100644 microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.md create mode 100644 microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.bad.al create mode 100644 microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.good.al create mode 100644 microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.md create mode 100644 microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.bad.al create mode 100644 microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.good.al create mode 100644 microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.md create mode 100644 microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.bad.al create mode 100644 microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.good.al create mode 100644 microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.md create mode 100644 microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.bad.al create mode 100644 microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.good.al create mode 100644 microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.md create mode 100644 microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.bad.al create mode 100644 microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.good.al create mode 100644 microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.md create mode 100644 microsoft/skills/review/al-reporting-review.md diff --git a/docs/using-bcquality.md b/docs/using-bcquality.md index dcaddde..e55751f 100644 --- a/docs/using-bcquality.md +++ b/docs/using-bcquality.md @@ -183,7 +183,7 @@ using your normal compilation, analyzer, test, and human-review workflow. ## Coverage and limits -The Microsoft broad review composes the 16 Microsoft domains listed below. +The Microsoft broad review composes the 17 Microsoft domains listed below. The Community Agents review is a separate skill selected by the request, not a nested part of that coordinator. All current review leaves accept app folders, files, and diffs; request an Agent SDK review explicitly when that @@ -219,6 +219,7 @@ Each article describes one concern. Where samples exist, use its linked | Performance | [Performance](../microsoft/knowledge/performance/) | | Privacy | [Privacy](../microsoft/knowledge/privacy/) | | Query objects | [Query](../microsoft/knowledge/query/) | +| Reporting | [Reporting](../microsoft/knowledge/reporting/) | | Security | [Security](../microsoft/knowledge/security/) | | Style | [Style](../microsoft/knowledge/style/) | | Telemetry | [Telemetry](../microsoft/knowledge/telemetry/) | diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index 352fccf..3eeed68 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -30,6 +30,19 @@ "privacy": { "article": "no-pii-in-telemetry-message-string" }, + "reporting": { + "articles": [ + "clear-report-variable-before-independent-runmodal", + "currreport-break-ends-the-current-trigger", + "currreport-quit-rolls-back-and-skips-onpostreport", + "currreport-skip-does-not-stop-trigger-code", + "report-output-in-a-loop-needs-one-client-download", + "reportextension-dataitem-trigger-order-is-explicit", + "reportextension-report-triggers-run-after-base-triggers", + "settableview-cannot-broaden-dataitemtableview", + "stop-when-runrequestpage-returns-empty-parameters" + ] + }, "style": { "article": "label-comment-explains-placeholders" }, diff --git a/microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.bad.al b/microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.bad.al new file mode 100644 index 0000000..736ddbf --- /dev/null +++ b/microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.bad.al @@ -0,0 +1,16 @@ +codeunit 50102 "Run Customer Reports" +{ + procedure RunBlockedAndUnblockedCustomers() + var + Customer: Record Customer; + CustomerList: Report "Customer - List"; + begin + Customer.SetRange(Blocked, Customer.Blocked::All); + CustomerList.SetTableView(Customer); + CustomerList.RunModal(); + + Customer.SetRange(Blocked, Customer.Blocked::" "); + CustomerList.SetTableView(Customer); + CustomerList.RunModal(); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.good.al b/microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.good.al new file mode 100644 index 0000000..51e5a0e --- /dev/null +++ b/microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.good.al @@ -0,0 +1,17 @@ +codeunit 50102 "Run Customer Reports" +{ + procedure RunBlockedAndUnblockedCustomers() + var + Customer: Record Customer; + CustomerList: Report "Customer - List"; + begin + Customer.SetRange(Blocked, Customer.Blocked::All); + CustomerList.SetTableView(Customer); + CustomerList.RunModal(); + + Clear(CustomerList); + Customer.SetRange(Blocked, Customer.Blocked::" "); + CustomerList.SetTableView(Customer); + CustomerList.RunModal(); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.md b/microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.md new file mode 100644 index 0000000..b82c1fb --- /dev/null +++ b/microsoft/knowledge/reporting/clear-report-variable-before-independent-runmodal.md @@ -0,0 +1,32 @@ +--- +bc-version: [all] +domain: reporting +keywords: [report, runmodal, clear, settableview, instance, state, filters] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Clear a Report variable before an independent RunModal execution + +## Description + +`Report.Run()` automatically clears the report variable after execution, but `Report.RunModal()` does not. Reconfiguring and running the same variable for an independent operation can therefore retain filters and other instance state from the previous run. + +## Best Practice + +Call `Clear(ReportVariable)` before configuring a new, logically independent `RunModal()` execution on a reused report variable. No clear is required after a single execution, and retaining state is valid when the subsequent run intentionally continues with the same configuration. + +See sample: [`clear-report-variable-before-independent-runmodal.good.al`](clear-report-variable-before-independent-runmodal.good.al). + +## Anti Pattern + +Run the same report variable modally for two independent views without clearing it between runs. The second `SetTableView` can only narrow the existing report view, so filters retained by the instance can make the second result incomplete or empty. + +See sample: [`clear-report-variable-before-independent-runmodal.bad.al`](clear-report-variable-before-independent-runmodal.bad.al). + +## References + +`Report.RunModal()` method — https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/report/reportinstance-runmodal-method + +`Report.Run()` method — https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/report/reportinstance-run-method \ No newline at end of file diff --git a/microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.bad.al b/microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.bad.al new file mode 100644 index 0000000..dd88abc --- /dev/null +++ b/microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.bad.al @@ -0,0 +1,31 @@ +report 50105 "Customer Entry Review" +{ + ProcessingOnly = true; + + dataset + { + dataitem(Customer; Customer) + { + trigger OnAfterGetRecord() + var + EntryNo: Integer; + begin + repeat + EntryNo += 1; + if EntryNo = 5 then + CurrReport.Break(); + until EntryNo = 10; + + MarkCustomerReviewed(); + end; + } + } + + local procedure MarkCustomerReviewed() + begin + ReviewedCustomerCount += 1; + end; + + var + ReviewedCustomerCount: Integer; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.good.al b/microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.good.al new file mode 100644 index 0000000..c220732 --- /dev/null +++ b/microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.good.al @@ -0,0 +1,31 @@ +report 50105 "Customer Entry Review" +{ + ProcessingOnly = true; + + dataset + { + dataitem(Customer; Customer) + { + trigger OnAfterGetRecord() + var + EntryNo: Integer; + StopReview: Boolean; + begin + repeat + EntryNo += 1; + StopReview := EntryNo = 5; + until StopReview or (EntryNo = 10); + + MarkCustomerReviewed(); + end; + } + } + + local procedure MarkCustomerReviewed() + begin + ReviewedCustomerCount += 1; + end; + + var + ReviewedCustomerCount: Integer; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.md b/microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.md new file mode 100644 index 0000000..ec22ea4 --- /dev/null +++ b/microsoft/knowledge/reporting/currreport-break-ends-the-current-trigger.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: reporting +keywords: [report, currreport, break, loop, trigger, control-flow] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# CurrReport.Break ends the current trigger + +## Description + +`CurrReport.Break()` inside a report dataitem trigger does more than leave an AL loop. It terminates the current trigger and omits the current record from the dataset. The report runtime still invokes the remaining triggers for that record. Consequently, statements after the loop in the current trigger do not run, while later report triggers can still produce side effects. + +## Best Practice + +Use an explicit loop condition or the AL `break` statement when only the loop must end and the current trigger must continue. Use `CurrReport.Break()` only when ending the trigger and omitting the current record are both intended, and keep subsequent report triggers safe for that omitted record. + +See sample: [`currreport-break-ends-the-current-trigger.good.al`](currreport-break-ends-the-current-trigger.good.al). + +## Anti Pattern + +Call `CurrReport.Break()` inside a loop and rely on statements after the loop to finish processing the current record. Those statements are unreachable when the call executes, the record is omitted, and remaining report triggers still run. + +See sample: [`currreport-break-ends-the-current-trigger.bad.al`](currreport-break-ends-the-current-trigger.bad.al). + +## References + +`Report.Break()` method — https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/report/reportinstance-break-method \ No newline at end of file diff --git a/microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.bad.al b/microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.bad.al new file mode 100644 index 0000000..262ca78 --- /dev/null +++ b/microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.bad.al @@ -0,0 +1,27 @@ +report 50101 "Update Customer Review" +{ + ProcessingOnly = true; + + dataset + { + dataitem(Customer; Customer) + { + trigger OnAfterGetRecord() + begin + "Last Date Modified" := Today(); + Modify(); + + if Blocked <> Blocked::" " then + CurrReport.Quit(); + end; + } + } + + trigger OnPostReport() + begin + Message(CompletedMsg); + end; + + var + CompletedMsg: Label 'Customer review completed.'; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.good.al b/microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.good.al new file mode 100644 index 0000000..f7a50c5 --- /dev/null +++ b/microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.good.al @@ -0,0 +1,28 @@ +report 50101 "Update Customer Review" +{ + ProcessingOnly = true; + + dataset + { + dataitem(Customer; Customer) + { + trigger OnAfterGetRecord() + begin + if Blocked <> Blocked::" " then + Error(BlockedCustomerErr, "No."); + + "Last Date Modified" := Today(); + Modify(); + end; + } + } + + trigger OnPostReport() + begin + Message(CompletedMsg); + end; + + var + BlockedCustomerErr: Label 'Customer %1 is blocked.', Comment = '%1 = customer number'; + CompletedMsg: Label 'Customer review completed.'; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.md b/microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.md new file mode 100644 index 0000000..287f625 --- /dev/null +++ b/microsoft/knowledge/reporting/currreport-quit-rolls-back-and-skips-onpostreport.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: reporting +keywords: [report, currreport, quit, rollback, onpostreport, transaction, control-flow] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# CurrReport.Quit rolls back report changes and skips OnPostReport + +## Description + +`CurrReport.Quit()` aborts the report without committing database changes made during its execution. It also prevents `OnPostReport` from running. It is therefore not a normal early-return mechanism for a processing report that expects earlier writes or finalization in `OnPostReport` to survive. + +## Best Practice + +Use `CurrReport.Quit()` only when silently aborting the report, rolling back its database changes, and skipping `OnPostReport` are all intentional. When processing must stop with a failure, raise an error. When completed work and `OnPostReport` must be preserved, structure the dataitem control flow without `Quit()`. + +See sample: [`currreport-quit-rolls-back-and-skips-onpostreport.good.al`](currreport-quit-rolls-back-and-skips-onpostreport.good.al). + +## Anti Pattern + +Modify data and then call `CurrReport.Quit()` while relying on those writes or on `OnPostReport` finalization. The report exits without committing its changes and never invokes `OnPostReport`. + +See sample: [`currreport-quit-rolls-back-and-skips-onpostreport.bad.al`](currreport-quit-rolls-back-and-skips-onpostreport.bad.al). + +## References + +`Report.Quit()` method — https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/report/reportinstance-quit-method \ No newline at end of file diff --git a/microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.bad.al b/microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.bad.al new file mode 100644 index 0000000..1debd99 --- /dev/null +++ b/microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.bad.al @@ -0,0 +1,26 @@ +report 50100 "Released Customer List" +{ + ProcessingOnly = true; + + dataset + { + dataitem(Customer; Customer) + { + trigger OnAfterGetRecord() + begin + if Blocked <> Blocked::" " then + CurrReport.Skip(); + + CountIncludedCustomer(); + end; + } + } + + local procedure CountIncludedCustomer() + begin + IncludedCustomerCount += 1; + end; + + var + IncludedCustomerCount: Integer; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.good.al b/microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.good.al new file mode 100644 index 0000000..f239a2b --- /dev/null +++ b/microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.good.al @@ -0,0 +1,28 @@ +report 50100 "Released Customer List" +{ + ProcessingOnly = true; + + dataset + { + dataitem(Customer; Customer) + { + trigger OnAfterGetRecord() + begin + if Blocked <> Blocked::" " then begin + CurrReport.Skip(); + exit; + end; + + CountIncludedCustomer(); + end; + } + } + + local procedure CountIncludedCustomer() + begin + IncludedCustomerCount += 1; + end; + + var + IncludedCustomerCount: Integer; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.md b/microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.md new file mode 100644 index 0000000..d2b4e34 --- /dev/null +++ b/microsoft/knowledge/reporting/currreport-skip-does-not-stop-trigger-code.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: reporting +keywords: [report, currreport, skip, trigger, onaftergetrecord, control-flow] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# CurrReport.Skip omits the record but does not stop trigger code + +## Description + +`CurrReport.Skip()` omits the current record from the report dataset and continues processing with the next record. It does not terminate the current trigger, and the remaining triggers for the current record still run. Code placed after `Skip()` can therefore produce side effects for a record that never appears in the output. + +## Best Practice + +When no further code in the current trigger should run for a skipped record, call `CurrReport.Skip()` and then exit the trigger explicitly. Keep later record triggers safe for skipped records because the report runtime still invokes them. + +See sample: [`currreport-skip-does-not-stop-trigger-code.good.al`](currreport-skip-does-not-stop-trigger-code.good.al). + +## Anti Pattern + +Call `CurrReport.Skip()` and rely on it to bypass subsequent statements or later record triggers. The record is removed from the dataset, but those statements and triggers can still update state, write data, or perform expensive work. + +See sample: [`currreport-skip-does-not-stop-trigger-code.bad.al`](currreport-skip-does-not-stop-trigger-code.bad.al). + +## References + +`Report.Skip()` method — https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/report/reportinstance-skip-method \ No newline at end of file diff --git a/microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.bad.al b/microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.bad.al new file mode 100644 index 0000000..945c0ae --- /dev/null +++ b/microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.bad.al @@ -0,0 +1,14 @@ +codeunit 50106 "Download Customer Reports" +{ + procedure DownloadReports(var Customer: Record Customer) + var + CustomerView: Record Customer; + begin + if Customer.FindSet() then + repeat + CustomerView := Customer; + CustomerView.SetRecFilter(); + Report.Run(Report::"Customer - List", false, false, CustomerView); + until Customer.Next() = 0; + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.good.al b/microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.good.al new file mode 100644 index 0000000..dea2e7f --- /dev/null +++ b/microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.good.al @@ -0,0 +1,37 @@ +codeunit 50106 "Download Customer Reports" +{ + procedure DownloadReports(var Customer: Record Customer) + var + CustomerView: Record Customer; + CustomerList: Report "Customer - List"; + DataCompression: Codeunit "Data Compression"; + ReportTempBlob: Codeunit "Temp Blob"; + ZipTempBlob: Codeunit "Temp Blob"; + ReportInStream: InStream; + ZipInStream: InStream; + ReportOutStream: OutStream; + ZipOutStream: OutStream; + ZipFileName: Text; + begin + DataCompression.CreateZipArchive(); + if Customer.FindSet() then + repeat + Clear(CustomerList); + Clear(ReportTempBlob); + CustomerView := Customer; + CustomerView.SetRecFilter(); + CustomerList.SetTableView(CustomerView); + ReportTempBlob.CreateOutStream(ReportOutStream); + CustomerList.SaveAs('', ReportFormat::Pdf, ReportOutStream); + ReportTempBlob.CreateInStream(ReportInStream); + DataCompression.AddEntry(ReportInStream, Customer."No." + '.pdf'); + until Customer.Next() = 0; + + ZipTempBlob.CreateOutStream(ZipOutStream); + DataCompression.SaveZipArchive(ZipOutStream); + DataCompression.CloseZipArchive(); + ZipTempBlob.CreateInStream(ZipInStream); + ZipFileName := 'CustomerReports.zip'; + DownloadFromStream(ZipInStream, '', '', '*.zip', ZipFileName); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.md b/microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.md new file mode 100644 index 0000000..8aede8b --- /dev/null +++ b/microsoft/knowledge/reporting/report-output-in-a-loop-needs-one-client-download.md @@ -0,0 +1,32 @@ +--- +bc-version: [all] +domain: reporting +keywords: [report, run, saveas, downloadfromstream, web-client, loop, zip, data-compression] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Report output in a loop needs one client download + +## Description + +The Business Central Web client can deliver only one file per request. When AL generates or downloads a report file repeatedly in the same request, only the last file is delivered to the browser. Earlier report output is silently unavailable to the user even though every iteration ran. + +## Best Practice + +Generate each report into a stream, add the streams to one archive, and call `DownloadFromStream` once after the loop. A direct report run or download inside a loop is valid only when the execution context does not use the Web client or the loop is guaranteed to execute at most once. + +See sample: [`report-output-in-a-loop-needs-one-client-download.good.al`](report-output-in-a-loop-needs-one-client-download.good.al). + +## Anti Pattern + +Call `Report.Run`, `Report.RunModal`, or `DownloadFromStream` repeatedly in a loop initiated by one Web client action and expect every generated file to reach the browser. The client receives only the last download. + +See sample: [`report-output-in-a-loop-needs-one-client-download.bad.al`](report-output-in-a-loop-needs-one-client-download.bad.al). + +## References + +`File.DownloadFromStream` method — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/file/file-downloadfromstream-method + +`Data Compression` codeunit — https://learn.microsoft.com/dynamics365/business-central/application/system-application/codeunit/system.io.data-compression \ No newline at end of file diff --git a/microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.bad.al b/microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.bad.al new file mode 100644 index 0000000..7a25a12 --- /dev/null +++ b/microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.bad.al @@ -0,0 +1,30 @@ +report 50103 "Base Customer Export" +{ + ProcessingOnly = true; + + dataset + { + dataitem(Customer; Customer) + { + trigger OnPreDataItem() + begin + SetRange(Blocked, Blocked::" "); + SetRange("Country/Region Code"); + end; + } + } +} + +reportextension 50104 "Local Customer Export" extends "Base Customer Export" +{ + dataset + { + modify(Customer) + { + trigger OnBeforePreDataItem() + begin + SetFilter("Country/Region Code", '<>%1', ''); + end; + } + } +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.good.al b/microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.good.al new file mode 100644 index 0000000..52c3ebe --- /dev/null +++ b/microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.good.al @@ -0,0 +1,30 @@ +report 50103 "Base Customer Export" +{ + ProcessingOnly = true; + + dataset + { + dataitem(Customer; Customer) + { + trigger OnPreDataItem() + begin + SetRange(Blocked, Blocked::" "); + SetRange("Country/Region Code"); + end; + } + } +} + +reportextension 50104 "Local Customer Export" extends "Base Customer Export" +{ + dataset + { + modify(Customer) + { + trigger OnAfterPreDataItem() + begin + SetFilter("Country/Region Code", '<>%1', ''); + end; + } + } +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.md b/microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.md new file mode 100644 index 0000000..c149748 --- /dev/null +++ b/microsoft/knowledge/reporting/reportextension-dataitem-trigger-order-is-explicit.md @@ -0,0 +1,32 @@ +--- +bc-version: [19..] +domain: reporting +keywords: [reportextension, report, dataitem, trigger-order, onbeforepredataitem, onafterpredataitem, onbeforeaftergetrecord, onafteraftergetrecord] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Choose ReportExtension dataitem triggers by their order around the base trigger + +## Description + +ReportExtension dataitem triggers run at defined points around the corresponding base-report trigger. `OnBeforePreDataItem` and `OnBeforeAfterGetRecord` run before the base trigger; `OnAfterPreDataItem` and `OnAfterAfterGetRecord` run after it. A filter or calculated value can be overwritten when an extension uses a before-trigger even though its result must be final after base processing. + +## Best Practice + +Choose the before or after trigger from the required ordering relative to base behavior. Use an after-trigger when the extension must observe or refine the final view or value produced by the base trigger. A before-trigger is valid when the base report must consume the extension's state. + +See sample: [`reportextension-dataitem-trigger-order-is-explicit.good.al`](reportextension-dataitem-trigger-order-is-explicit.good.al). + +## Anti Pattern + +Place extension logic in a before-trigger while relying on its filter or value to survive a base trigger that can replace it. Do not report a before-trigger merely because an after-trigger exists; the defect requires visible base behavior or another reliable source showing that ordering changes the result. + +See sample: [`reportextension-dataitem-trigger-order-is-explicit.bad.al`](reportextension-dataitem-trigger-order-is-explicit.bad.al). + +## References + +`OnBeforePreDataItem` report-extension trigger — https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/triggers-auto/reportextensiondatasetmodify/devenv-onbeforepredataitem-reportextensiondatasetmodify-trigger + +`OnAfterPreDataItem` report-extension trigger — https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/triggers-auto/reportextensiondatasetmodify/devenv-onafterpredataitem-reportextensiondatasetmodify-trigger \ No newline at end of file diff --git a/microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.bad.al b/microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.bad.al new file mode 100644 index 0000000..d932f91 --- /dev/null +++ b/microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.bad.al @@ -0,0 +1,31 @@ +report 50110 "Customer Export" +{ + ProcessingOnly = true; + + dataset + { + dataitem(Customer; Customer) + { + } + } + + trigger OnPreReport() + var + ExportSetup: Record "Customer Export Setup"; + begin + ExportSetup.Get(); + ExportSetup.TestField("Export Date"); + end; +} + +reportextension 50111 "Customer Export Extension" extends "Customer Export" +{ + trigger OnPreReport() + var + ExportSetup: Record "Customer Export Setup"; + begin + ExportSetup.Get(); + ExportSetup.Validate("Export Date", Today()); + ExportSetup.Modify(true); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.good.al b/microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.good.al new file mode 100644 index 0000000..293784b --- /dev/null +++ b/microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.good.al @@ -0,0 +1,37 @@ +report 50110 "Customer Export" +{ + ProcessingOnly = true; + + dataset + { + dataitem(Customer; Customer) + { + } + } + + trigger OnPreReport() + var + ExportDate: Date; + begin + OnBeforeResolveExportDate(ExportDate); + if ExportDate = 0D then + Error(ExportDateRequiredErr); + end; + + [IntegrationEvent(false, false)] + local procedure OnBeforeResolveExportDate(var ExportDate: Date) + begin + end; + + var + ExportDateRequiredErr: Label 'An export date is required.'; +} + +codeunit 50111 "Customer Export Extension" +{ + [EventSubscriber(ObjectType::Report, Report::"Customer Export", 'OnBeforeResolveExportDate', '', false, false)] + local procedure SetExportDate(var ExportDate: Date) + begin + ExportDate := Today(); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.md b/microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.md new file mode 100644 index 0000000..414752a --- /dev/null +++ b/microsoft/knowledge/reporting/reportextension-report-triggers-run-after-base-triggers.md @@ -0,0 +1,30 @@ +--- +bc-version: [18..] +domain: reporting +keywords: [reportextension, report, trigger-order, onprereport, onpostreport, base-report, integration-event] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# ReportExtension report triggers run after base report triggers + +## Description + +`OnPreReport` and `OnPostReport` on a ReportExtension run after the corresponding triggers on the base report. An extension `OnPreReport` cannot prepare state that the base `OnPreReport` must consume, and an extension `OnPostReport` cannot affect finalization that the base `OnPostReport` has already completed. + +## Best Practice + +Use a base-report event at the required execution point when extension logic must run before or within a base trigger. Use ReportExtension `OnPreReport` and `OnPostReport` only for work that is correct after the corresponding base trigger. Report a violation only when the base trigger and extension dependency are both visible or otherwise established. + +See sample: [`reportextension-report-triggers-run-after-base-triggers.good.al`](reportextension-report-triggers-run-after-base-triggers.good.al). + +## Anti Pattern + +Initialize data in a ReportExtension `OnPreReport` and rely on the base report's `OnPreReport` to consume it, or perform extension `OnPostReport` work that the base `OnPostReport` needed beforehand. The base trigger has already run. + +See sample: [`reportextension-report-triggers-run-after-base-triggers.bad.al`](reportextension-report-triggers-run-after-base-triggers.bad.al). + +## References + +Report extension object — https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-report-ext-object \ No newline at end of file diff --git a/microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.bad.al b/microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.bad.al new file mode 100644 index 0000000..844c542 --- /dev/null +++ b/microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.bad.al @@ -0,0 +1,26 @@ +report 50107 "Selected Sales Orders" +{ + ProcessingOnly = true; + + dataset + { + dataitem(SalesHeader; "Sales Header") + { + DataItemTableView = where("Document Type" = const(Order), Status = const(Open)); + } + } +} + +codeunit 50108 "Run Selected Sales Orders" +{ + procedure RunReleasedOrders() + var + SalesHeader: Record "Sales Header"; + SelectedSalesOrders: Report "Selected Sales Orders"; + begin + SalesHeader.SetRange("Document Type", SalesHeader."Document Type"::Order); + SalesHeader.SetRange(Status, SalesHeader.Status::Released); + SelectedSalesOrders.SetTableView(SalesHeader); + SelectedSalesOrders.RunModal(); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.good.al b/microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.good.al new file mode 100644 index 0000000..5dc4f2e --- /dev/null +++ b/microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.good.al @@ -0,0 +1,26 @@ +report 50107 "Selected Sales Orders" +{ + ProcessingOnly = true; + + dataset + { + dataitem(SalesHeader; "Sales Header") + { + DataItemTableView = where("Document Type" = const(Order)); + } + } +} + +codeunit 50108 "Run Selected Sales Orders" +{ + procedure RunReleasedOrders() + var + SalesHeader: Record "Sales Header"; + SelectedSalesOrders: Report "Selected Sales Orders"; + begin + SalesHeader.SetRange("Document Type", SalesHeader."Document Type"::Order); + SalesHeader.SetRange(Status, SalesHeader.Status::Released); + SelectedSalesOrders.SetTableView(SalesHeader); + SelectedSalesOrders.RunModal(); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.md b/microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.md new file mode 100644 index 0000000..2dfc691 --- /dev/null +++ b/microsoft/knowledge/reporting/settableview-cannot-broaden-dataitemtableview.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: reporting +keywords: [report, settableview, dataitemtableview, filter, view, narrowing] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# SetTableView cannot broaden DataItemTableView + +## Description + +`Report.SetTableView()` applies the supplied record view by narrowing the view already defined by the report dataitem's `DataItemTableView`. It cannot remove or broaden a static dataitem filter. A caller that requests records excluded by `DataItemTableView` therefore produces an empty dataset rather than overriding the report filter. + +## Best Practice + +Keep only invariant restrictions in `DataItemTableView`. When callers must select among values, leave that dimension open in the static view and pass the required filter through `SetTableView`. Review this as a defect only when the report definition and caller together show a contradictory filter. + +See sample: [`settableview-cannot-broaden-dataitemtableview.good.al`](settableview-cannot-broaden-dataitemtableview.good.al). + +## Anti Pattern + +Define a static filter in `DataItemTableView` and call `SetTableView` with a mutually exclusive filter while expecting the runtime view to replace the static one. The filters are intersected and no records are selected. + +See sample: [`settableview-cannot-broaden-dataitemtableview.bad.al`](settableview-cannot-broaden-dataitemtableview.bad.al). + +## References + +`Report.SetTableView()` method — https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/report/reportinstance-settableview-method \ No newline at end of file diff --git a/microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.bad.al b/microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.bad.al new file mode 100644 index 0000000..feccfb6 --- /dev/null +++ b/microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.bad.al @@ -0,0 +1,17 @@ +codeunit 50109 "Export Customer Report" +{ + procedure ExportReport() + var + TempBlob: Codeunit "Temp Blob"; + ReportOutStream: OutStream; + RequestPageParameters: Text; + begin + RequestPageParameters := Report.RunRequestPage(Report::"Customer - List"); + TempBlob.CreateOutStream(ReportOutStream); + Report.SaveAs( + Report::"Customer - List", + RequestPageParameters, + ReportFormat::Pdf, + ReportOutStream); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.good.al b/microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.good.al new file mode 100644 index 0000000..d706a2f --- /dev/null +++ b/microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.good.al @@ -0,0 +1,20 @@ +codeunit 50109 "Export Customer Report" +{ + procedure ExportReport() + var + TempBlob: Codeunit "Temp Blob"; + ReportOutStream: OutStream; + RequestPageParameters: Text; + begin + RequestPageParameters := Report.RunRequestPage(Report::"Customer - List"); + if RequestPageParameters = '' then + exit; + + TempBlob.CreateOutStream(ReportOutStream); + Report.SaveAs( + Report::"Customer - List", + RequestPageParameters, + ReportFormat::Pdf, + ReportOutStream); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.md b/microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.md new file mode 100644 index 0000000..0cc0e71 --- /dev/null +++ b/microsoft/knowledge/reporting/stop-when-runrequestpage-returns-empty-parameters.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: reporting +keywords: [report, runrequestpage, cancel, parameters, saveas, execute, print] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Stop when RunRequestPage returns empty parameters + +## Description + +`Report.RunRequestPage()` returns an empty string when the user chooses **Cancel**. Passing that value to `Report.Execute`, `Report.Print`, or `Report.SaveAs` ignores the cancellation and can run the report with default parameters instead. + +## Best Practice + +Test the returned parameter string immediately after `RunRequestPage()` and exit when it is empty. Pass the value to `Execute`, `Print`, or `SaveAs` only after the user has confirmed the request page. + +See sample: [`stop-when-runrequestpage-returns-empty-parameters.good.al`](stop-when-runrequestpage-returns-empty-parameters.good.al). + +## Anti Pattern + +Call `RunRequestPage()` and unconditionally pass its return value to a report execution method. Choosing **Cancel** can still execute, print, or save the report. + +See sample: [`stop-when-runrequestpage-returns-empty-parameters.bad.al`](stop-when-runrequestpage-returns-empty-parameters.bad.al). + +## References + +`Report.RunRequestPage()` method — https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/report/report-runrequestpage-method \ No newline at end of file diff --git a/microsoft/skills/review/al-code-review.md b/microsoft/skills/review/al-code-review.md index 9b5f739..dc1f1db 100644 --- a/microsoft/skills/review/al-code-review.md +++ b/microsoft/skills/review/al-code-review.md @@ -25,6 +25,7 @@ sub-skills: - microsoft/skills/review/al-testing-review.md - microsoft/skills/review/al-data-modeling-review.md - microsoft/skills/review/al-query-review.md + - microsoft/skills/review/al-reporting-review.md - microsoft/skills/review/al-appsource-review.md - microsoft/skills/review/al-telemetry-review.md --- diff --git a/microsoft/skills/review/al-reporting-review.md b/microsoft/skills/review/al-reporting-review.md new file mode 100644 index 0000000..52f8f53 --- /dev/null +++ b/microsoft/skills/review/al-reporting-review.md @@ -0,0 +1,63 @@ +--- +kind: action-skill +id: al-reporting-review +version: 1 +title: AL reporting review +description: Reviews AL Report and ReportExtension code against BCQuality reporting guidance. +inputs: [pr-diff, file-path, folder-path] +outputs: [findings-report] +bc-version: [all] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# AL reporting review + +Reviews AL source changes against the `reporting` knowledge domain in BCQuality. This is a leaf action skill composed by `al-code-review`. + +## Source + +Use READ's **Bounded retrieval for review skills** workflow with `-Domain reporting`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. + +## Relevance + +Apply READ's frontmatter matching rules against the task context. Use the target version from `app.json` when available and `[al]` for technologies. Retain conditionally applicable files only when configured; cap resulting confidence at `medium` and name every unknown dimension in the finding message. + +Return `not-applicable` when the input contains no Report or ReportExtension declaration and no Report variable or method call. + +## Worklist + +Match relevant entries against changed `report` and `reportextension` objects, variables typed as `Report`, and the tokens `CurrReport`, `Skip`, `Break`, `Quit`, `Run`, `RunModal`, `RunRequestPage`, `Execute`, `Print`, `SaveAs`, `DownloadFromStream`, `Data Compression`, `SetTableView`, `DataItemTableView`, `OnPreReport`, `OnPostReport`, `OnPreDataItem`, `OnAfterGetRecord`, and report-extension dataset triggers. + +Apply this targeted check even when token overlap would rank the article below the worklist cutoff: + +- The same Report variable has two logically independent `RunModal()` executions without `Clear` before the second configuration — `clear-report-variable-before-independent-runmodal`. +- `CurrReport.Break()` is used inside an explicit loop while reachable statements after the loop are expected to finish the current trigger — `currreport-break-ends-the-current-trigger`. +- `CurrReport.Quit()` follows database writes or the report relies on `OnPostReport` finalization — `currreport-quit-rolls-back-and-skips-onpostreport`. +- `CurrReport.Skip()` is followed by reachable code in the same trigger, or later record triggers contain work that is unsafe for skipped records — `currreport-skip-does-not-stop-trigger-code`. +- A loop reachable from one Web client action calls `Report.Run`, `Report.RunModal`, or `DownloadFromStream` more than once instead of producing one archive download — `report-output-in-a-loop-needs-one-client-download`. Do not select this article when the context is non-Web or the loop is provably single-iteration. +- A ReportExtension before-trigger establishes a filter or value that visible base-trigger code subsequently replaces — `reportextension-dataitem-trigger-order-is-explicit`. Do not select this article from a before-trigger alone. +- A ReportExtension `OnPreReport` prepares state consumed by the base `OnPreReport`, or its `OnPostReport` prepares state already consumed by the base `OnPostReport` — `reportextension-report-triggers-run-after-base-triggers`. Require visible base behavior or equivalent established evidence. +- A report's `DataItemTableView` and a caller's `SetTableView` apply mutually exclusive filters to the same field — `settableview-cannot-broaden-dataitemtableview`. Require both views or equivalent direct evidence; `SetTableView` alone is not a finding. +- The value returned by `Report.RunRequestPage()` reaches `Report.Execute`, `Report.Print`, or `Report.SaveAs` without an empty-string cancellation check — `stop-when-runrequestpage-returns-empty-parameters`. + +Resolve layer conflicts per READ. When no reporting knowledge exists, emit `no-knowledge`; when knowledge exists but no article matches the changed report code, emit `completed` with no findings. + +## Action + +Evaluate every worklist article against the diff's report control flow and surrounding triggers. + +- Emit `major` for an unambiguous Anti Pattern that causes incorrect output, persisted side effects, or lost work. +- Emit `minor` when code contradicts a Best Practice but the effect depends on unseen report or caller context. +- Do not emit applicability-only information. A reporting article produces a finding only when changed code violates its normative guidance. + +Set confidence to `high` for locally visible control flow and `medium` when base-report behavior, callers, or missing context affect the conclusion. Domain-scoped agent findings follow DO's precision bar and remain capped at `minor`/`medium`. + +Provide `suggested-code` only when the replacement is complete, local, and unambiguous. Otherwise set `suggested-code-omission-reason`. + +Outcome selection follows DO: `completed`, `no-knowledge`, `not-applicable`, `partial`, or `failed`. + +## Output + +Output conforms to the DO findings-report contract. Every finding this skill emits MUST set `findings[].domain` to `"Reporting"`. \ No newline at end of file From d24dc7b14b39624e8b2160dbca73d66140106e4c Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Tue, 15 Sep 2026 10:45:35 +0200 Subject: [PATCH 10/35] Fix reporting skill index expectation (#185) Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/scripts/Test-SkillIndex.ps1 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/scripts/Test-SkillIndex.ps1 b/.github/scripts/Test-SkillIndex.ps1 index 839042f..ed07204 100644 --- a/.github/scripts/Test-SkillIndex.ps1 +++ b/.github/scripts/Test-SkillIndex.ps1 @@ -91,6 +91,7 @@ try { 'microsoft/skills/review/al-testing-review.md', 'microsoft/skills/review/al-data-modeling-review.md', 'microsoft/skills/review/al-query-review.md', + 'microsoft/skills/review/al-reporting-review.md', 'microsoft/skills/review/al-appsource-review.md', 'microsoft/skills/review/al-telemetry-review.md' ) @@ -99,7 +100,7 @@ try { throw "Expected exactly one al-code-review record, found $($review.Count)." } if ((@($review[0].subSkills) -join "`n") -cne ($expectedLeaves -join "`n")) { - throw 'al-code-review subSkills did not preserve the declared 16-leaf order.' + throw 'al-code-review subSkills did not preserve the declared 17-leaf order.' } foreach ($leafPath in $expectedLeaves) { $leaf = @($skills | Where-Object path -ceq $leafPath) @@ -237,4 +238,4 @@ finally { Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue } -Write-Output 'Skill-index check PASSED: deterministic, schema-valid, and all 16 review leaves preserved in order.' +Write-Output 'Skill-index check PASSED: deterministic, schema-valid, and all 17 review leaves preserved in order.' From b7617fb48a01c9f41116e37edaede3daed424236 Mon Sep 17 00:00:00 2001 From: waldo Date: Tue, 15 Sep 2026 12:34:28 +0200 Subject: [PATCH 11/35] knowledge(events): ChangeCompany leaves triggers and trigger-event subscribers running in the calling company (#152) * knowledge(events): ChangeCompany leaves triggers and trigger-event subscribers running in the calling company ChangeCompany redirects only the data access of a record variable; Learn states that triggers still run in the current company. The database trigger events are raised on every database operation and only pass RunTrigger to the subscriber, so Insert(false) after ChangeCompany still runs every subscriber in the calling company. Generated code either assumes the record 'becomes' a target-company record, or switches RunTrigger off and hand-copies the trigger logic, leaving the subscribers writing to the wrong company; none of the tested runs reached StartSession with the company parameter. Co-Authored-By: Claude Fable 5.1 * knowledge(events): qualify StartSession async semantics and fix concurrency-unsafe sample key Addresses PR #152 review: StartSession is a fire-and-forget background session (Ok reports only whether it started, not whether the codeunit succeeded, and errors inside it do not propagate), so the Best Practice now scopes the recommendation and calls out the durable status/error channel a synchronous-success write needs. The good sample's FindLast()+1 entry-number pattern raced under concurrent background sessions; switched to AutoIncrement, which the platform guarantees is unique across concurrent transactions. Co-Authored-By: Claude Sonnet 5 * knowledge(events): serialize the setup-counter increment; promote article and wire the review skill PR #152 round 3 (JesperSchulz): - The good sample's OnAfterInsertEvent subscriber still raced on the shared "Transfer Setup Good" singleton (Get/increment/Modify); AutoIncrement only protected the request key. Added TransferSetup.LockTable() before Get() to serialize concurrent background sessions. - Promoted changecompany-runs-triggers-in-the-calling-company from community/knowledge/events/ to microsoft/knowledge/events/, and wired ChangeCompany/StartSession/RunTrigger tokens plus a targeted detection cue into microsoft/skills/review/al-events-review.md so a diff containing the anti-pattern reliably worklists this article, preserving the documented RunTrigger=false hand-off exception. Co-Authored-By: Claude Sonnet 5 --------- Co-authored-by: waldo1001 <12088142+waldo1001@users.noreply.github.com> Co-authored-by: Claude Fable 5.1 --- ...uns-triggers-in-the-calling-company.bad.al | 91 +++++++++++++++++++ ...ns-triggers-in-the-calling-company.good.al | 84 +++++++++++++++++ ...ny-runs-triggers-in-the-calling-company.md | 42 +++++++++ microsoft/skills/review/al-events-review.md | 3 +- 4 files changed, 219 insertions(+), 1 deletion(-) create mode 100644 microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.bad.al create mode 100644 microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.good.al create mode 100644 microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.md diff --git a/microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.bad.al b/microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.bad.al new file mode 100644 index 0000000..7b8e7d5 --- /dev/null +++ b/microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.bad.al @@ -0,0 +1,91 @@ +codeunit 50100 "Transfer Request Bad" +{ + // Self-contained demonstration of the anti pattern. Not derived from base-app source. + procedure RequestFromCompany(TargetCompany: Text[30]; ItemNo: Code[20]; Quantity: Decimal) + var + TransferRequest: Record "Transfer Request Bad"; + TransferSetup: Record "Transfer Setup Bad"; + begin + TransferRequest.ChangeCompany(TargetCompany); + TransferSetup.ChangeCompany(TargetCompany); + TransferSetup.Get(); + + TransferRequest.Init(); + TransferRequest."Entry No." := NextEntryNo(TargetCompany); + TransferRequest."Item No." := ItemNo; + TransferRequest.Quantity := Quantity; + // OnInsert is skipped below, so the default is copied by hand from the target company's setup. + TransferRequest."Location Code" := TransferSetup."Default Location Code"; + // The OnAfterInsertEvent subscriber still fires, in the calling company, and grows the caller's counter. + TransferRequest.Insert(false); + + TransferSetup."Open Requests" += 1; + TransferSetup.Modify(); + end; + + local procedure NextEntryNo(TargetCompany: Text[30]): Integer + var + LastRequest: Record "Transfer Request Bad"; + begin + LastRequest.ChangeCompany(TargetCompany); + if LastRequest.FindLast() then + exit(LastRequest."Entry No." + 1); + exit(1); + end; +} + +table 50100 "Transfer Request Bad" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Entry No."; Integer) { } + field(2; "Item No."; Code[20]) { } + field(3; Quantity; Decimal) { } + field(4; "Location Code"; Code[10]) { } + } + + keys + { + key(PK; "Entry No.") { Clustered = true; } + } + + trigger OnInsert() + var + TransferSetup: Record "Transfer Setup Bad"; + begin + TransferSetup.Get(); + "Location Code" := TransferSetup."Default Location Code"; + end; +} + +table 50101 "Transfer Setup Bad" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Primary Key"; Code[10]) { } + field(2; "Default Location Code"; Code[10]) { } + field(3; "Open Requests"; Integer) { } + } + + keys + { + key(PK; "Primary Key") { Clustered = true; } + } +} + +codeunit 50101 "Transfer Request Count Bad" +{ + [EventSubscriber(ObjectType::Table, Database::"Transfer Request Bad", OnAfterInsertEvent, '', false, false)] + local procedure CountOpenRequest(var Rec: Record "Transfer Request Bad"; RunTrigger: Boolean) + var + TransferSetup: Record "Transfer Setup Bad"; + begin + TransferSetup.Get(); + TransferSetup."Open Requests" += 1; + TransferSetup.Modify(); + end; +} diff --git a/microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.good.al b/microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.good.al new file mode 100644 index 0000000..dd92d9d --- /dev/null +++ b/microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.good.al @@ -0,0 +1,84 @@ +codeunit 50100 "Transfer Request Good" +{ + // Self-contained demonstration of the best practice. Not derived from base-app source. + procedure RequestFromCompany(TargetCompany: Text[30]; ItemNo: Code[20]; Quantity: Decimal) + var + TransferRequest: Record "Transfer Request Good"; + SessionId: Integer; + begin + TransferRequest.Init(); + TransferRequest."Item No." := ItemNo; + TransferRequest.Quantity := Quantity; + // The insert runs inside TargetCompany, so OnInsert and the subscriber read that company's setup. + StartSession(SessionId, Codeunit::"Transfer Request Create Good", TargetCompany, TransferRequest); + end; +} + +codeunit 50102 "Transfer Request Create Good" +{ + TableNo = "Transfer Request Good"; + + trigger OnRun() + begin + // "Entry No." is AutoIncrement, so concurrent background sessions in TargetCompany never race on the same value. + Rec.Insert(true); + end; +} + +table 50100 "Transfer Request Good" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Entry No."; Integer) { AutoIncrement = true; } + field(2; "Item No."; Code[20]) { } + field(3; Quantity; Decimal) { } + field(4; "Location Code"; Code[10]) { } + } + + keys + { + key(PK; "Entry No.") { Clustered = true; } + } + + trigger OnInsert() + var + TransferSetup: Record "Transfer Setup Good"; + begin + TransferSetup.Get(); + "Location Code" := TransferSetup."Default Location Code"; + end; +} + +table 50101 "Transfer Setup Good" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Primary Key"; Code[10]) { } + field(2; "Default Location Code"; Code[10]) { } + field(3; "Open Requests"; Integer) { } + } + + keys + { + key(PK; "Primary Key") { Clustered = true; } + } +} + +codeunit 50101 "Transfer Request Count Good" +{ + [EventSubscriber(ObjectType::Table, Database::"Transfer Request Good", OnAfterInsertEvent, '', false, false)] + local procedure CountOpenRequest(var Rec: Record "Transfer Request Good"; RunTrigger: Boolean) + var + TransferSetup: Record "Transfer Setup Good"; + begin + // Serializes the read-modify-write so concurrent background sessions don't lose an increment. + TransferSetup.LockTable(); + TransferSetup.Get(); + TransferSetup."Open Requests" += 1; + TransferSetup.Modify(); + end; +} diff --git a/microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.md b/microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.md new file mode 100644 index 0000000..4a524f4 --- /dev/null +++ b/microsoft/knowledge/events/changecompany-runs-triggers-in-the-calling-company.md @@ -0,0 +1,42 @@ +--- +bc-version: [all] +domain: events +keywords: [changecompany, cross-company, runtrigger, trigger-event, subscriber, onafterinsertevent, insert, startsession, multi-company] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# ChangeCompany leaves triggers and trigger-event subscribers running in the calling company + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +`ChangeCompany` redirects the data access of one record variable to another company's table. Execution context does not move with it: Microsoft Learn states that triggers still run in the current company, not in the company passed to `ChangeCompany`. Code that knows this usually reaches for `Insert(false)` and copies the trigger's work by hand from the target company's setup. That closes only half of the gap. The runtime raises the database trigger events (`OnBeforeInsertEvent`, `OnAfterInsertEvent`, and their modify, delete, and rename counterparts) on every database operation and only passes the `RunTrigger` flag to the subscriber, so every subscriber that does not exit on `RunTrigger = false` still runs, in the calling company, against the calling company's setup, number series, and companion tables. The row lands in the target company, the side effects land in the caller, and nothing reports an error. The per-row cost of the call is a separate concern, see `changecompany-in-loop-drops-caches`. + +## Best Practice + +Use `ChangeCompany` to read. Access rights in the target company are still enforced, so reads are safe. When the goal is business data in another company, run the code in that company: `StartSession` takes a company name and runs a codeunit there, so triggers, validation, and subscribers all execute with the target company as their context. `StartSession` is a background session, not a synchronous call: the `Ok` return value reports only whether the session started, not whether the codeunit's work inside it succeeded, the caller's transaction does not extend into it, and an error raised there does not come back to the caller — it has to be logged or telemetered from inside that session. Reach for `StartSession` only for work the caller does not need to confirm before it continues; a write whose success the caller must know synchronously needs a durable status or error channel (a field the caller polls, a job queue with retry) rather than a bare `StartSession` call. Learn notes that a background session costs as much as a user session to start, so batch the work rather than starting one session per row, or let the target company process a hand-off row on its own schedule. A direct cross-company write is acceptable only as such a hand-off into a table the writing extension owns, whose triggers do not read company data and whose trigger-event subscribers exit when `RunTrigger` is false, using `Insert(false)`, `Modify(false)`, or `Delete(false)`, and never `Validate`. + +See sample: [`changecompany-runs-triggers-in-the-calling-company.good.al`](changecompany-runs-triggers-in-the-calling-company.good.al). + +## Anti Pattern + +An `Insert`, `Modify`, `Delete`, or `Validate` on a record variable after `ChangeCompany()`, on a table whose triggers or trigger-event subscribers read setup, consume a number series, or write companion rows. With `RunTrigger = true` the trigger code fills the row from the caller's setup. With `RunTrigger = false` the trigger code is skipped, but the subscribers still fire in the caller, so a counter, log, or companion row maintained by a subscriber is written in the wrong company, and a caller that also updates the target by hand counts twice. + +Detection signal: a record variable that has had `ChangeCompany` called on it with a company name and is later used with `Insert`, `Modify`, `Delete`, or `Validate`, where the table is not owned by the extension, or has triggers that read company data, or has trigger-event subscribers that do not exit on `RunTrigger = false`. Do not flag reads after `ChangeCompany`; writes with `RunTrigger = false` into an owned table whose triggers do not read company data and whose subscribers exit on `RunTrigger = false`; or `ChangeCompany()` without an argument, which points the variable back at the current company. + +See sample: [`changecompany-runs-triggers-in-the-calling-company.bad.al`](changecompany-runs-triggers-in-the-calling-company.bad.al). + +## See also + +- Record.ChangeCompany method, Remarks — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/record/record-changecompany-method +- Record.Insert(Boolean) method, RunTrigger — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/record/record-insert-boolean-method +- Record.Delete method, RunTrigger defaults to false — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/record/record-delete-method +- OnInsert (Table) trigger, Remarks — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/triggers-auto/table/devenv-oninsert-table-trigger +- Event types, Database trigger events and order of event execution — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-event-types +- OnAfterInsertEvent trigger event, RunTrigger parameter — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/triggers-auto/events/table/devenv-onafterinsertevent-table-trigger +- Session.StartSession method, Company parameter, Remarks (background session, no UI), and Return Value (`Ok` reports whether the session started, not whether the codeunit's work succeeded) — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/session/session-startsession-integer-integer-string-table-method +- AL error handling, error handling strategies: an error inside a rolled-back transaction is logged from a background session or telemetry, it does not return to the caller — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-al-error-handling +- AutoIncrement property, Remarks: "if several transactions are performed at the same time, they will each be assigned a different number" — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/properties/devenv-autoincrement-property diff --git a/microsoft/skills/review/al-events-review.md b/microsoft/skills/review/al-events-review.md index 68bcdb0..b257d3d 100644 --- a/microsoft/skills/review/al-events-review.md +++ b/microsoft/skills/review/al-events-review.md @@ -39,7 +39,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially codeunits that publish events or host event subscribers, posting/release/validation routines that should expose extension points, and test codeunits that bind subscribers. - The changed procedures and triggers, weighted toward event publisher methods, methods carrying the `[EventSubscriber(...)]` attribute, routines that raise `OnBefore`/`OnAfter` events, and any procedure that calls `BindSubscription`/`UnbindSubscription`. -- Tokens extracted from the diff that relate to events and the publish/subscribe model (`IntegrationEvent`, `BusinessEvent`, `InternalEvent`, `EventSubscriber`, `IsHandled`, `BindSubscription`, `UnbindSubscription`, `EventSubscriberInstance`, `OnBefore`, `OnAfter`, `Manual`, `IncludeSender`, `GlobalVarAccess`, `Isolated`, `local`, `internal`, `Sender`, `this`, `RecordRef`, `xRec`, `temporary`, `Temp`, `repeat`). +- Tokens extracted from the diff that relate to events and the publish/subscribe model (`IntegrationEvent`, `BusinessEvent`, `InternalEvent`, `EventSubscriber`, `IsHandled`, `BindSubscription`, `UnbindSubscription`, `EventSubscriberInstance`, `OnBefore`, `OnAfter`, `Manual`, `IncludeSender`, `GlobalVarAccess`, `Isolated`, `local`, `internal`, `Sender`, `this`, `RecordRef`, `xRec`, `temporary`, `Temp`, `repeat`, `ChangeCompany`, `StartSession`, `RunTrigger`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. @@ -65,6 +65,7 @@ The following targeted checks map diff signals to specific `events` articles. Tr - A `RecordRef` event parameter, or a passed-through `xRec`, where a concrete typed record fits — `avoid-loosely-typed-event-parameters`. - A `var IsHandled` added to a pre-existing event rather than introduced through a new `OnBefore` publisher — `do-not-add-ishandled-to-an-existing-event`. - An `if IsHandled then exit;` whose skipped body performs posting, ledger-entry creation, number-series consumption, or integrity/permission validation — `do-not-bypass-critical-operations-with-ishandled`. +- A record variable that had `ChangeCompany()` called on it and is later used with `Insert`, `Modify`, `Delete`, or `Validate`, where the table is not owned by the extension, has triggers that read company data, or has trigger-event subscribers that do not exit on `RunTrigger = false` — `changecompany-runs-triggers-in-the-calling-company`. Do not match a read-only use after `ChangeCompany`, a write with `RunTrigger = false` into an extension-owned table whose triggers do not read company data and whose trigger-event subscribers exit on `RunTrigger = false`, or the parameterless `ChangeCompany()` reset. ## Action From 861f53dd97fcc25cc797e79902884c7bbb612178 Mon Sep 17 00:00:00 2001 From: Stefano Demiliani <33155438+demiliani@users.noreply.github.com> Date: Tue, 15 Sep 2026 12:51:15 +0200 Subject: [PATCH 12/35] Add query filter semantics guidance (#186) --- evaluation/review-fixtures.json | 8 ++++ ...er-cannot-be-overwritten-at-runtime.bad.al | 39 +++++++++++++++++++ ...r-cannot-be-overwritten-at-runtime.good.al | 38 ++++++++++++++++++ ...filter-cannot-be-overwritten-at-runtime.md | 30 ++++++++++++++ ...ilter-overwrites-query-columnfilter.bad.al | 37 ++++++++++++++++++ ...lter-overwrites-query-columnfilter.good.al | 38 ++++++++++++++++++ ...setfilter-overwrites-query-columnfilter.md | 30 ++++++++++++++ microsoft/skills/review/al-query-review.md | 8 ++-- 8 files changed, 225 insertions(+), 3 deletions(-) create mode 100644 microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.bad.al create mode 100644 microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.good.al create mode 100644 microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.md create mode 100644 microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.bad.al create mode 100644 microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.good.al create mode 100644 microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.md diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index 3eeed68..90c42c6 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -30,6 +30,14 @@ "privacy": { "article": "no-pii-in-telemetry-message-string" }, + "query": { + "articles": [ + "dataitemtablefilter-cannot-be-overwritten-at-runtime", + "reopening-query-resets-cursor-but-keeps-filters", + "set-query-filters-before-open", + "setfilter-overwrites-query-columnfilter" + ] + }, "reporting": { "articles": [ "clear-report-variable-before-independent-runmodal", diff --git a/microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.bad.al b/microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.bad.al new file mode 100644 index 0000000..67012eb --- /dev/null +++ b/microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.bad.al @@ -0,0 +1,39 @@ +query 50428 "Static Query Filter Bad" +{ + QueryType = Normal; + + elements + { + dataitem(SalesHeader; "Sales Header") + { + DataItemTableFilter = Status = const(Open); + + column(DocumentNo; "No.") + { + } + filter(StatusFilter; Status) + { + } + } + } +} + +codeunit 50429 "Static Query Filter Bad" +{ + procedure ReadReleasedOrders() + var + SalesHeader: Record "Sales Header"; + SalesHeaderQuery: Query "Static Query Filter Bad"; + begin + // This is combined with Status = Open and returns no rows. + SalesHeaderQuery.SetRange(StatusFilter, SalesHeader.Status::Released); + SalesHeaderQuery.Open(); + while SalesHeaderQuery.Read() do + ProcessOrder(SalesHeaderQuery.DocumentNo); + SalesHeaderQuery.Close(); + end; + + local procedure ProcessOrder(DocumentNo: Code[20]) + begin + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.good.al b/microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.good.al new file mode 100644 index 0000000..d095330 --- /dev/null +++ b/microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.good.al @@ -0,0 +1,38 @@ +query 50430 "Static Query Filter Good" +{ + QueryType = Normal; + + elements + { + dataitem(SalesHeader; "Sales Header") + { + DataItemTableFilter = "Document Type" = const(Order); + + column(DocumentNo; "No.") + { + } + filter(StatusFilter; Status) + { + } + } + } +} + +codeunit 50431 "Static Query Filter Good" +{ + procedure ReadReleasedOrders() + var + SalesHeader: Record "Sales Header"; + SalesHeaderQuery: Query "Static Query Filter Good"; + begin + SalesHeaderQuery.SetRange(StatusFilter, SalesHeader.Status::Released); + SalesHeaderQuery.Open(); + while SalesHeaderQuery.Read() do + ProcessOrder(SalesHeaderQuery.DocumentNo); + SalesHeaderQuery.Close(); + end; + + local procedure ProcessOrder(DocumentNo: Code[20]) + begin + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.md b/microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.md new file mode 100644 index 0000000..6a96db1 --- /dev/null +++ b/microsoft/knowledge/query/dataitemtablefilter-cannot-be-overwritten-at-runtime.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: query +keywords: [query, dataitemtablefilter, setfilter, setrange, static-filter, filter-precedence] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# DataItemTableFilter cannot be overwritten at runtime + +## Description + +`DataItemTableFilter` defines a static filter on a Query dataitem. A runtime `SetFilter` or `SetRange` on the same source field does not replace that filter. The static and runtime filters are combined with AND, so contradictory values produce an empty dataset instead of broadening or replacing the query definition. + +## Best Practice + +Keep only invariant restrictions in `DataItemTableFilter`. Expose caller-selectable fields through a column or filter row and apply their values with `SetFilter` or `SetRange` before `Open()`. When both filter types intentionally target the same field, ensure their intersection represents the required dataset. + +See sample: [`dataitemtablefilter-cannot-be-overwritten-at-runtime.good.al`](dataitemtablefilter-cannot-be-overwritten-at-runtime.good.al). + +## Anti Pattern + +Define a static filter in `DataItemTableFilter`, then apply a contradictory runtime filter to the same source field while expecting the runtime filter to replace the static one. Both filters remain effective and the query returns no rows. + +See sample: [`dataitemtablefilter-cannot-be-overwritten-at-runtime.bad.al`](dataitemtablefilter-cannot-be-overwritten-at-runtime.bad.al). + +## References + +Filtering in Query objects — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-query-filters \ No newline at end of file diff --git a/microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.bad.al b/microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.bad.al new file mode 100644 index 0000000..f286334 --- /dev/null +++ b/microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.bad.al @@ -0,0 +1,37 @@ +query 50432 "Column Query Filter Bad" +{ + QueryType = Normal; + + elements + { + dataitem(SalesLine; "Sales Line") + { + column(DocumentNo; "Document No.") + { + } + column(LineQuantity; Quantity) + { + ColumnFilter = LineQuantity = filter(> 0); + } + } + } +} + +codeunit 50433 "Column Query Filter Bad" +{ + procedure ReadSmallPositiveLines() + var + SalesLineQuery: Query "Column Query Filter Bad"; + begin + // This replaces > 0, so negative quantities are also returned. + SalesLineQuery.SetFilter(LineQuantity, '<100'); + SalesLineQuery.Open(); + while SalesLineQuery.Read() do + ProcessLine(SalesLineQuery.DocumentNo, SalesLineQuery.LineQuantity); + SalesLineQuery.Close(); + end; + + local procedure ProcessLine(DocumentNo: Code[20]; Quantity: Decimal) + begin + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.good.al b/microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.good.al new file mode 100644 index 0000000..49353e6 --- /dev/null +++ b/microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.good.al @@ -0,0 +1,38 @@ +query 50434 "Column Query Filter Good" +{ + QueryType = Normal; + + elements + { + dataitem(SalesLine; "Sales Line") + { + DataItemTableFilter = Quantity = filter(> 0); + + column(DocumentNo; "Document No.") + { + } + column(LineQuantity; Quantity) + { + } + } + } +} + +codeunit 50435 "Column Query Filter Good" +{ + procedure ReadSmallPositiveLines() + var + SalesLineQuery: Query "Column Query Filter Good"; + begin + // This combines with the invariant Quantity > 0 dataitem filter. + SalesLineQuery.SetFilter(LineQuantity, '<100'); + SalesLineQuery.Open(); + while SalesLineQuery.Read() do + ProcessLine(SalesLineQuery.DocumentNo, SalesLineQuery.LineQuantity); + SalesLineQuery.Close(); + end; + + local procedure ProcessLine(DocumentNo: Code[20]; Quantity: Decimal) + begin + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.md b/microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.md new file mode 100644 index 0000000..9f9dd7a --- /dev/null +++ b/microsoft/knowledge/query/setfilter-overwrites-query-columnfilter.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: query +keywords: [query, columnfilter, setfilter, setrange, filter-precedence, runtime-filter] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# SetFilter and SetRange overwrite Query ColumnFilter + +## Description + +`ColumnFilter` on a Query column or filter row defines a dynamic filter. A runtime `SetFilter` or `SetRange` on that same column or filter row replaces the `ColumnFilter`; it does not combine the two conditions. Rows excluded by the declarative filter can therefore reappear when the runtime filter omits that restriction. + +## Best Practice + +Place invariant restrictions in `DataItemTableFilter`, which runtime filters cannot overwrite. When a `ColumnFilter` is intentionally replaceable, make each runtime `SetFilter` or `SetRange` express the complete required condition before `Open()`. + +See sample: [`setfilter-overwrites-query-columnfilter.good.al`](setfilter-overwrites-query-columnfilter.good.al). + +## Anti Pattern + +Apply `SetFilter` or `SetRange` to a column or filter row and rely on its existing `ColumnFilter` to remain effective. The runtime call replaces that filter and can admit rows that the query definition appeared to exclude. + +See sample: [`setfilter-overwrites-query-columnfilter.bad.al`](setfilter-overwrites-query-columnfilter.bad.al). + +## References + +Filtering in Query objects — https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-query-filters \ No newline at end of file diff --git a/microsoft/skills/review/al-query-review.md b/microsoft/skills/review/al-query-review.md index c52ddd8..e97a20a 100644 --- a/microsoft/skills/review/al-query-review.md +++ b/microsoft/skills/review/al-query-review.md @@ -32,22 +32,24 @@ Match relevant entries against changed `query` objects, variables typed as `Quer The following targeted checks cover every current `query` article: +- A `DataItemTableFilter` and a runtime `SetFilter` or `SetRange` constrain the same source field incompatibly, while the runtime call is intended to replace or broaden the static filter — `dataitemtablefilter-cannot-be-overwritten-at-runtime`. - `SetFilter` or `SetRange` occurs after `Open()` without a new `Open()` before the next `Read()` — `set-query-filters-before-open`. +- A runtime `SetFilter` or `SetRange` replaces a `ColumnFilter` on the same column or filter row, while later code relies on the declarative restriction remaining effective — `setfilter-overwrites-query-columnfilter`. - An already-open query is opened again as if that advanced the cursor, or a query variable is reused for an independent operation without `Clear` even though old filters must not carry over — `reopening-query-resets-cursor-but-keeps-filters`. Resolve layer conflicts per READ. When no query knowledge exists, emit `no-knowledge`; when knowledge exists but no article matches the changed Query usage, emit `completed` with no findings. ## Action -Evaluate every worklist article against the diff's Query call order and surrounding control flow. +Evaluate every worklist article against the Query definition, the diff's call order, and surrounding control flow. For filter-precedence findings, require both the declarative filter and the runtime call to be visible, and require local evidence that replacement, broadening, or retention of the original filter is intended. -- Emit `major` for an unambiguous Anti Pattern that can close the dataset, restart processing, or retain an unintended filter. +- Emit `major` for an unambiguous Anti Pattern that can close the dataset, restart processing, retain an unintended filter, produce an empty intersection, or admit rows excluded by an overwritten filter. - Emit `minor` when code contradicts a Best Practice but the resulting behavior depends on unseen control flow. - Do not emit applicability-only information. A Query article produces a finding only when the changed code violates its normative guidance. Set confidence to `high` for a locally visible call sequence and `medium` when aliases, helper calls, or missing context obscure the sequence. Domain-scoped agent findings follow DO's precision bar and remain capped at `minor`/`medium`. -Provide `suggested-code` only when moving a filter before `Open()` or adding `Clear` is a complete, local, unambiguous replacement. Otherwise set `suggested-code-omission-reason`. +Provide `suggested-code` only when moving a filter before `Open()`, adding `Clear`, moving an invariant restriction to `DataItemTableFilter`, or composing the complete runtime filter is a complete, local, unambiguous replacement. Otherwise set `suggested-code-omission-reason`. Outcome selection follows DO: `completed`, `no-knowledge`, `not-applicable`, `partial`, or `failed`. From 2c45021cb37d6b60f33ebb945fa88e4ac71462b2 Mon Sep 17 00:00:00 2001 From: Djordje Cenic Date: Tue, 15 Sep 2026 13:16:53 +0200 Subject: [PATCH 13/35] Add security knowledge: validate unauthenticated endpoint responses New remedial article for spotting when AL calls an endpoint that does not authenticate itself to the client (bare HttpClient.Get, blank SOAP SecretText, post-DisableHttpsCheck HTTP) and requires the response to be size-, schema-, and request/response-integrity-validated before it is trusted. Includes the BC-specific false-positive clarifications (platform buffers the full body, so an in-AL size check after buffering is correct; no DNS-rebinding/bounded-read demand; HTTPS not always enforceable) plus good/bad AL samples. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ...unauthenticated-response-before-use.bad.al | 23 ++++++++++ ...nauthenticated-response-before-use.good.al | 46 +++++++++++++++++++ ...ate-unauthenticated-response-before-use.md | 22 +++++++++ 3 files changed, 91 insertions(+) create mode 100644 microsoft/knowledge/security/validate-unauthenticated-response-before-use.bad.al create mode 100644 microsoft/knowledge/security/validate-unauthenticated-response-before-use.good.al create mode 100644 microsoft/knowledge/security/validate-unauthenticated-response-before-use.md diff --git a/microsoft/knowledge/security/validate-unauthenticated-response-before-use.bad.al b/microsoft/knowledge/security/validate-unauthenticated-response-before-use.bad.al new file mode 100644 index 0000000..ee0d25e --- /dev/null +++ b/microsoft/knowledge/security/validate-unauthenticated-response-before-use.bad.al @@ -0,0 +1,23 @@ +codeunit 50541 "Sec Sample UnauthResp Bad" +{ + procedure IsVatNumberValid(RequestedCountryCode: Text; RequestedVatNumber: Text): Boolean + var + HttpClient: HttpClient; + Response: HttpResponseMessage; + JsonResponse: JsonObject; + JsonToken: JsonToken; + Content: Text; + begin + // Anti-pattern: the endpoint is unauthenticated, yet the response is trusted with no + // size cap, no schema check, and no request-to-response integrity check. + HttpClient.Get('http://vat-service.example/check?cc=' + RequestedCountryCode + '&vat=' + RequestedVatNumber, Response); + Response.Content().ReadAs(Content); + JsonResponse.ReadFrom(Content); + + // Trusts valid=true for ANY input: a spoofed or MITM response that omits the echoed + // countryCode/vatNumber is accepted as valid for whatever number was requested. + if JsonResponse.Get('valid', JsonToken) then + exit(JsonToken.AsValue().AsBoolean()); + exit(false); + end; +} diff --git a/microsoft/knowledge/security/validate-unauthenticated-response-before-use.good.al b/microsoft/knowledge/security/validate-unauthenticated-response-before-use.good.al new file mode 100644 index 0000000..2c3e437 --- /dev/null +++ b/microsoft/knowledge/security/validate-unauthenticated-response-before-use.good.al @@ -0,0 +1,46 @@ +codeunit 50540 "Sec Sample UnauthResp Good" +{ + // The public VAT validation service does not authenticate itself to us (no OAuth, no + // certificate, plain HTTP), so its response must be validated before it is trusted. + procedure IsVatNumberValid(RequestedCountryCode: Text; RequestedVatNumber: Text): Boolean + var + HttpClient: HttpClient; + Response: HttpResponseMessage; + JsonResponse: JsonObject; + JsonToken: JsonToken; + Content: Text; + ResponseCountryCode: Text; + ResponseVatNumber: Text; + begin + HttpClient.Get('http://vat-service.example/check?cc=' + RequestedCountryCode + '&vat=' + RequestedVatNumber, Response); + if not Response.IsSuccessStatusCode() then + exit(false); + + Response.Content().ReadAs(Content); + + // 1) Size cap - the platform already buffered the whole body; reject abnormally large payloads. + if StrLen(Content) > 4096 then + Error('The VAT validation response exceeded the maximum allowed size and was rejected.'); + + // 2) Schema - require the expected scalar fields, not just a truthy flag. + if not JsonResponse.ReadFrom(Content) then + Error('The VAT validation response was not in the expected format and was rejected.'); + if not JsonResponse.Get('countryCode', JsonToken) then + Error('The VAT validation response did not include the requested identifiers and was rejected.'); + ResponseCountryCode := JsonToken.AsValue().AsText(); + if not JsonResponse.Get('vatNumber', JsonToken) then + Error('The VAT validation response did not include the requested identifiers and was rejected.'); + ResponseVatNumber := JsonToken.AsValue().AsText(); + + // 3) Integrity - the echoed identifiers must match the request, so a valid=true payload + // with the identifiers stripped cannot be accepted for an arbitrary VAT number. + if (UpperCase(ResponseCountryCode) <> UpperCase(RequestedCountryCode)) or + (UpperCase(ResponseVatNumber) <> UpperCase(RequestedVatNumber)) + then + Error('The VAT validation response did not match the requested identifiers and was rejected.'); + + if not JsonResponse.Get('valid', JsonToken) then + exit(false); + exit(JsonToken.AsValue().AsBoolean()); + end; +} diff --git a/microsoft/knowledge/security/validate-unauthenticated-response-before-use.md b/microsoft/knowledge/security/validate-unauthenticated-response-before-use.md new file mode 100644 index 0000000..2e99e2c --- /dev/null +++ b/microsoft/knowledge/security/validate-unauthenticated-response-before-use.md @@ -0,0 +1,22 @@ +--- +bc-version: [all] +domain: security +keywords: [unauthenticated, ssrf, httpclient, soap, response-validation, integrity, size-limit, disablehttpscheck, temp-blob, vies] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Validate responses from unauthenticated endpoints before trusting them + +## Description + +When AL calls an external endpoint that does not authenticate *itself* to the client, the response is fully attacker-influenceable — cleartext MITM, a spoofed or compromised host, DNS/redirect games, or simply a misbehaving public service. Recognizing that a call is unauthenticated is the first review step, and the signals are BC-specific: a bare `HttpClient.Get`/`Post` with no `Authorization` header, no acquired OAuth token, and no client certificate; a SOAP request whose credentials are blank, such as `SOAP Web Service Request Mgt.SetGlobals(..., '', BlankSecretText)`; or any request issued after `DisableHttpsCheck()` over plain HTTP (for example the EU VIES VAT service, whose default endpoint is `http://`). Because the BC platform HTTP stack buffers the entire response body before AL is handed the stream or `Temp Blob`, the whole payload is already in memory by the time AL parses it — so the response must be range- and shape-checked in AL *before* any of it is written to tax, VAT, customer, or vendor tables. + +## Best Practice + +Before parsing or trusting a response from an unauthenticated endpoint: (1) enforce a maximum size — reject when the buffered `Temp Blob` length or `Content-Length` exceeds a small cap sized to the expected payload; (2) validate the schema/shape — require the specific scalar nodes you expect, not merely "the body contains a truthy flag"; (3) enforce request-to-response integrity — when the protocol echoes the identifiers you queried (VIES echoes `countryCode`/`vatNumber`; a public-IP service echoes an IP string), require them to be present and to match the request, so a response carrying only `valid=true` cannot be accepted for an arbitrary input; (4) on rejection raise an `Error` and record a security audit via `Audit Log.LogAuditMessage(...)` plus telemetry. See sample: `validate-unauthenticated-response-before-use.good.al`. For validating the outbound target/host, see `validate-user-configurable-urls.md`; for authenticating outbound calls, see `prefer-oauth2-over-api-keys-for-external-http-calls.md`. + +## Anti Pattern + +Feeding the parsed response straight into business logic — load the XML/JSON, read a `valid` flag or an IP-shaped substring, then `Customer.Modify()` — trusting it purely because the HTTP call returned 2xx, with no size, shape, or echoed-identifier check. Reviewers should flag an unauthenticated outbound call (no `Authorization`/OAuth/cert, blank SOAP `SecretText`, or a request after `DisableHttpsCheck`) whose response is parsed and persisted without a preceding size cap, schema check, and request-to-response integrity check. Do NOT, however, demand a streaming or bounded read that aborts the transfer mid-download, nor a resolved-IP/DNS-rebinding check: the platform buffers the full body before AL sees it and AL has no connection-time or DNS hook, so an in-AL size check necessarily runs after buffering and host-rebinding defense belongs to the platform egress layer — raising those is a false positive. HTTPS is likewise not always enforceable (VIES is HTTP by design); the mitigation there is response validation, not scheme enforcement. See sample: `validate-unauthenticated-response-before-use.bad.al`. From 58b3be23abee90269adbe434d8ae395ca8e78a30 Mon Sep 17 00:00:00 2001 From: Djordje Cenic Date: Tue, 15 Sep 2026 13:19:37 +0200 Subject: [PATCH 14/35] Name the three required checks explicitly: response size, schema compliance, content integrity Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../security/validate-unauthenticated-response-before-use.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/microsoft/knowledge/security/validate-unauthenticated-response-before-use.md b/microsoft/knowledge/security/validate-unauthenticated-response-before-use.md index 2e99e2c..27db51f 100644 --- a/microsoft/knowledge/security/validate-unauthenticated-response-before-use.md +++ b/microsoft/knowledge/security/validate-unauthenticated-response-before-use.md @@ -11,11 +11,11 @@ application-area: [all] ## Description -When AL calls an external endpoint that does not authenticate *itself* to the client, the response is fully attacker-influenceable — cleartext MITM, a spoofed or compromised host, DNS/redirect games, or simply a misbehaving public service. Recognizing that a call is unauthenticated is the first review step, and the signals are BC-specific: a bare `HttpClient.Get`/`Post` with no `Authorization` header, no acquired OAuth token, and no client certificate; a SOAP request whose credentials are blank, such as `SOAP Web Service Request Mgt.SetGlobals(..., '', BlankSecretText)`; or any request issued after `DisableHttpsCheck()` over plain HTTP (for example the EU VIES VAT service, whose default endpoint is `http://`). Because the BC platform HTTP stack buffers the entire response body before AL is handed the stream or `Temp Blob`, the whole payload is already in memory by the time AL parses it — so the response must be range- and shape-checked in AL *before* any of it is written to tax, VAT, customer, or vendor tables. +When AL calls an external endpoint that does not authenticate *itself* to the client, the response is fully attacker-influenceable — cleartext MITM, a spoofed or compromised host, DNS/redirect games, or simply a misbehaving public service. Recognizing that a call is unauthenticated is the first review step, and the signals are BC-specific: a bare `HttpClient.Get`/`Post` with no `Authorization` header, no acquired OAuth token, and no client certificate; a SOAP request whose credentials are blank, such as `SOAP Web Service Request Mgt.SetGlobals(..., '', BlankSecretText)`; or any request issued after `DisableHttpsCheck()` over plain HTTP (for example the EU VIES VAT service, whose default endpoint is `http://`). Because the BC platform HTTP stack buffers the entire response body before AL is handed the stream or `Temp Blob`, the whole payload is already in memory by the time AL parses it — so the response must pass three checks in AL — **response size**, **schema compliance**, and **content integrity** — *before* any of it is written to tax, VAT, customer, or vendor tables. ## Best Practice -Before parsing or trusting a response from an unauthenticated endpoint: (1) enforce a maximum size — reject when the buffered `Temp Blob` length or `Content-Length` exceeds a small cap sized to the expected payload; (2) validate the schema/shape — require the specific scalar nodes you expect, not merely "the body contains a truthy flag"; (3) enforce request-to-response integrity — when the protocol echoes the identifiers you queried (VIES echoes `countryCode`/`vatNumber`; a public-IP service echoes an IP string), require them to be present and to match the request, so a response carrying only `valid=true` cannot be accepted for an arbitrary input; (4) on rejection raise an `Error` and record a security audit via `Audit Log.LogAuditMessage(...)` plus telemetry. See sample: `validate-unauthenticated-response-before-use.good.al`. For validating the outbound target/host, see `validate-user-configurable-urls.md`; for authenticating outbound calls, see `prefer-oauth2-over-api-keys-for-external-http-calls.md`. +Before parsing or trusting a response from an unauthenticated endpoint, apply all three of these checks before the payload reaches business logic: (1) **Response size** — reject when the buffered `Temp Blob` length or `Content-Length` exceeds a small cap sized to the expected payload; (2) **Schema compliance** — require the specific scalar nodes/fields you expect in the expected shape, not merely "the body contains a truthy flag"; (3) **Content integrity** — when the protocol echoes the identifiers you queried (VIES echoes `countryCode`/`vatNumber`; a public-IP service echoes an IP string), require them to be present and to match the request, so a response carrying only `valid=true` cannot be accepted for an arbitrary input. On any failing check, raise an `Error` and record a security audit via `Audit Log.LogAuditMessage(...)` plus telemetry. See sample: `validate-unauthenticated-response-before-use.good.al`. For validating the outbound target/host, see `validate-user-configurable-urls.md`; for authenticating outbound calls, see `prefer-oauth2-over-api-keys-for-external-http-calls.md`. ## Anti Pattern From 5bda05492752a5954b282dbce5fef8782b8ab474 Mon Sep 17 00:00:00 2001 From: Djordje Cenic Date: Tue, 15 Sep 2026 13:48:59 +0200 Subject: [PATCH 15/35] Link samples using the READ markdown-link convention Use [\slug.good.al\](slug.good.al) form so tools/Knowledge-Retrieval.ps1 Assert-SampleLink validation passes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../security/validate-unauthenticated-response-before-use.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/microsoft/knowledge/security/validate-unauthenticated-response-before-use.md b/microsoft/knowledge/security/validate-unauthenticated-response-before-use.md index 27db51f..ca09d56 100644 --- a/microsoft/knowledge/security/validate-unauthenticated-response-before-use.md +++ b/microsoft/knowledge/security/validate-unauthenticated-response-before-use.md @@ -15,8 +15,8 @@ When AL calls an external endpoint that does not authenticate *itself* to the cl ## Best Practice -Before parsing or trusting a response from an unauthenticated endpoint, apply all three of these checks before the payload reaches business logic: (1) **Response size** — reject when the buffered `Temp Blob` length or `Content-Length` exceeds a small cap sized to the expected payload; (2) **Schema compliance** — require the specific scalar nodes/fields you expect in the expected shape, not merely "the body contains a truthy flag"; (3) **Content integrity** — when the protocol echoes the identifiers you queried (VIES echoes `countryCode`/`vatNumber`; a public-IP service echoes an IP string), require them to be present and to match the request, so a response carrying only `valid=true` cannot be accepted for an arbitrary input. On any failing check, raise an `Error` and record a security audit via `Audit Log.LogAuditMessage(...)` plus telemetry. See sample: `validate-unauthenticated-response-before-use.good.al`. For validating the outbound target/host, see `validate-user-configurable-urls.md`; for authenticating outbound calls, see `prefer-oauth2-over-api-keys-for-external-http-calls.md`. +Before parsing or trusting a response from an unauthenticated endpoint, apply all three of these checks before the payload reaches business logic: (1) **Response size** — reject when the buffered `Temp Blob` length or `Content-Length` exceeds a small cap sized to the expected payload; (2) **Schema compliance** — require the specific scalar nodes/fields you expect in the expected shape, not merely "the body contains a truthy flag"; (3) **Content integrity** — when the protocol echoes the identifiers you queried (VIES echoes `countryCode`/`vatNumber`; a public-IP service echoes an IP string), require them to be present and to match the request, so a response carrying only `valid=true` cannot be accepted for an arbitrary input. On any failing check, raise an `Error` and record a security audit via `Audit Log.LogAuditMessage(...)` plus telemetry. See sample: [`validate-unauthenticated-response-before-use.good.al`](validate-unauthenticated-response-before-use.good.al). For validating the outbound target/host, see `validate-user-configurable-urls.md`; for authenticating outbound calls, see `prefer-oauth2-over-api-keys-for-external-http-calls.md`. ## Anti Pattern -Feeding the parsed response straight into business logic — load the XML/JSON, read a `valid` flag or an IP-shaped substring, then `Customer.Modify()` — trusting it purely because the HTTP call returned 2xx, with no size, shape, or echoed-identifier check. Reviewers should flag an unauthenticated outbound call (no `Authorization`/OAuth/cert, blank SOAP `SecretText`, or a request after `DisableHttpsCheck`) whose response is parsed and persisted without a preceding size cap, schema check, and request-to-response integrity check. Do NOT, however, demand a streaming or bounded read that aborts the transfer mid-download, nor a resolved-IP/DNS-rebinding check: the platform buffers the full body before AL sees it and AL has no connection-time or DNS hook, so an in-AL size check necessarily runs after buffering and host-rebinding defense belongs to the platform egress layer — raising those is a false positive. HTTPS is likewise not always enforceable (VIES is HTTP by design); the mitigation there is response validation, not scheme enforcement. See sample: `validate-unauthenticated-response-before-use.bad.al`. +Feeding the parsed response straight into business logic — load the XML/JSON, read a `valid` flag or an IP-shaped substring, then `Customer.Modify()` — trusting it purely because the HTTP call returned 2xx, with no size, shape, or echoed-identifier check. Reviewers should flag an unauthenticated outbound call (no `Authorization`/OAuth/cert, blank SOAP `SecretText`, or a request after `DisableHttpsCheck`) whose response is parsed and persisted without a preceding size cap, schema check, and request-to-response integrity check. Do NOT, however, demand a streaming or bounded read that aborts the transfer mid-download, nor a resolved-IP/DNS-rebinding check: the platform buffers the full body before AL sees it and AL has no connection-time or DNS hook, so an in-AL size check necessarily runs after buffering and host-rebinding defense belongs to the platform egress layer — raising those is a false positive. HTTPS is likewise not always enforceable (VIES is HTTP by design); the mitigation there is response validation, not scheme enforcement. See sample: [`validate-unauthenticated-response-before-use.bad.al`](validate-unauthenticated-response-before-use.bad.al). From 450e5965e180cb5c0fa9c69e4375b081ff43de01 Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Thu, 17 Sep 2026 13:34:22 +0200 Subject: [PATCH 16/35] Add BCQuality logo and brand assets (#190) * Add BCQuality logo and brand assets Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Remove brand assets link from README Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Use horizontal logo banner in README Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Enlarge banner wordmark Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 4 ++++ docs/README.md | 5 +++++ docs/assets/bcq-logo.svg | 26 ++++++++++++++++++++++++ docs/assets/bcq-mark.svg | 22 ++++++++++++++++++++ docs/brand-assets.md | 43 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 100 insertions(+) create mode 100644 docs/assets/bcq-logo.svg create mode 100644 docs/assets/bcq-mark.svg create mode 100644 docs/brand-assets.md diff --git a/README.md b/README.md index e9e18d5..147a84c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ +

+ BCQuality logo +

+ # BCQuality Quality skills and knowledge that help AI tools make better Business Central diff --git a/docs/README.md b/docs/README.md index d9ca27b..7210cb7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,7 @@ +

+ BCQuality mark +

+ # BCQuality documentation **New to BCQuality? Start with the [quick start](../README.md#quick-start).** @@ -32,3 +36,4 @@ prerequisites for using the plugin. | [DO](../skills/do.md) | Action-skill format and structured output contract. | | [WRITE](../skills/write.md) | Knowledge-authoring rules. | | [Review evaluation](../evaluation/README.md) | Sample conventions, fixture preparation, and scoring. | +| [Brand assets](brand-assets.md) | BCQ logo files and usage guidance. | diff --git a/docs/assets/bcq-logo.svg b/docs/assets/bcq-logo.svg new file mode 100644 index 0000000..0c7aae5 --- /dev/null +++ b/docs/assets/bcq-logo.svg @@ -0,0 +1,26 @@ + + BCQuality banner logo + A blue letter Q crossed by a teal quality check beside the BCQuality wordmark. + + + + + + + + + + + + + + + + + + + + + + BCQuality + diff --git a/docs/assets/bcq-mark.svg b/docs/assets/bcq-mark.svg new file mode 100644 index 0000000..0b6c00e --- /dev/null +++ b/docs/assets/bcq-mark.svg @@ -0,0 +1,22 @@ + + BCQuality mark + A blue letter Q crossed by a teal quality check. + + + + + + + + + + + + + + + + + + + diff --git a/docs/brand-assets.md b/docs/brand-assets.md new file mode 100644 index 0000000..e578fcd --- /dev/null +++ b/docs/brand-assets.md @@ -0,0 +1,43 @@ +# BCQ brand assets + +

+ BCQuality logo +

+ +The BCQuality mark combines a **Q** with a check to represent review, +confidence, and quality. The vector artwork follows the supplied blue-to-teal +concept and connects the mark to the split-color BCQuality wordmark. A true +circular ring and square-ended 45-degree bars keep the check and Q tail aligned +at exact right angles; the check's vertical cut and the tail's horizontal cut +match the source concept. + +## Available artwork + +| Asset | Best use | +| --- | --- | +| [`bcq-logo.svg`](assets/bcq-logo.svg) | Horizontal banner with the mark and wordmark. | +| [`bcq-mark.svg`](assets/bcq-mark.svg) | Symbol without the wordmark. | + +The SVG files can be scaled without losing quality. + +## Color palette + +The artwork uses the dominant colors sampled from the supplied Business Central +logo reference. + +| Color | Hex | +| --- | --- | +| Deep blue | `#086194` | +| Blue | `#138EB7` | +| Cyan | `#17ABCB` | +| Aqua | `#2CD2CD` | +| Mint | `#57E6CB` | +| Light mint | `#9BF2C8` | + +## Usage + +- Prefer the full logo when at least 320 pixels of horizontal space is + available; use the mark at smaller sizes. +- Preserve the artwork's proportions, colors, and orientation. +- Use `BCQuality logo` as alternative text unless nearby text already names the + project, in which case the image can be decorative. From 2b96f5226d469542646d73e010c4099da46995a5 Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Thu, 17 Sep 2026 13:35:46 +0200 Subject: [PATCH 17/35] Update logo width and remove project title Reduced logo width in README and removed title. --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 147a84c..bdf10f3 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,7 @@

- BCQuality logo + BCQuality logo

-# BCQuality - Quality skills and knowledge that help AI tools make better Business Central development decisions: catch BC-specific defects, avoid misleading advice, and explain findings with references you can read. From d209cd0f73daadb1ca3b7fc9e476e6b1453c29a9 Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Thu, 17 Sep 2026 13:38:04 +0200 Subject: [PATCH 18/35] Left-align README logo (#191) * Add BCQuality logo and brand assets Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Remove brand assets link from README Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Use horizontal logo banner in README Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Enlarge banner wordmark Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bdf10f3..3f66a4e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

+

BCQuality logo

From b91443beec785606e08274dea3f402a99aaec7bd Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Thu, 17 Sep 2026 13:38:34 +0200 Subject: [PATCH 19/35] Update logo width in README Reduced logo width in README from 500 to 300 pixels. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3f66a4e..daea405 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- BCQuality logo + BCQuality logo

Quality skills and knowledge that help AI tools make better Business Central From 523fc88f877a5151d6a3a15ef52106fa8d886f90 Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Fri, 18 Sep 2026 09:05:29 +0200 Subject: [PATCH 20/35] Remove logo branding (#194) Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 4 ---- docs/README.md | 5 ----- docs/assets/bcq-logo.svg | 26 ------------------------ docs/assets/bcq-mark.svg | 22 -------------------- docs/brand-assets.md | 43 ---------------------------------------- 5 files changed, 100 deletions(-) delete mode 100644 docs/assets/bcq-logo.svg delete mode 100644 docs/assets/bcq-mark.svg delete mode 100644 docs/brand-assets.md diff --git a/README.md b/README.md index daea405..d45a5d1 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,3 @@ -

- BCQuality logo -

- Quality skills and knowledge that help AI tools make better Business Central development decisions: catch BC-specific defects, avoid misleading advice, and explain findings with references you can read. diff --git a/docs/README.md b/docs/README.md index 7210cb7..d9ca27b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,3 @@ -

- BCQuality mark -

- # BCQuality documentation **New to BCQuality? Start with the [quick start](../README.md#quick-start).** @@ -36,4 +32,3 @@ prerequisites for using the plugin. | [DO](../skills/do.md) | Action-skill format and structured output contract. | | [WRITE](../skills/write.md) | Knowledge-authoring rules. | | [Review evaluation](../evaluation/README.md) | Sample conventions, fixture preparation, and scoring. | -| [Brand assets](brand-assets.md) | BCQ logo files and usage guidance. | diff --git a/docs/assets/bcq-logo.svg b/docs/assets/bcq-logo.svg deleted file mode 100644 index 0c7aae5..0000000 --- a/docs/assets/bcq-logo.svg +++ /dev/null @@ -1,26 +0,0 @@ - - BCQuality banner logo - A blue letter Q crossed by a teal quality check beside the BCQuality wordmark. - - - - - - - - - - - - - - - - - - - - - - BCQuality - diff --git a/docs/assets/bcq-mark.svg b/docs/assets/bcq-mark.svg deleted file mode 100644 index 0b6c00e..0000000 --- a/docs/assets/bcq-mark.svg +++ /dev/null @@ -1,22 +0,0 @@ - - BCQuality mark - A blue letter Q crossed by a teal quality check. - - - - - - - - - - - - - - - - - - - diff --git a/docs/brand-assets.md b/docs/brand-assets.md deleted file mode 100644 index e578fcd..0000000 --- a/docs/brand-assets.md +++ /dev/null @@ -1,43 +0,0 @@ -# BCQ brand assets - -

- BCQuality logo -

- -The BCQuality mark combines a **Q** with a check to represent review, -confidence, and quality. The vector artwork follows the supplied blue-to-teal -concept and connects the mark to the split-color BCQuality wordmark. A true -circular ring and square-ended 45-degree bars keep the check and Q tail aligned -at exact right angles; the check's vertical cut and the tail's horizontal cut -match the source concept. - -## Available artwork - -| Asset | Best use | -| --- | --- | -| [`bcq-logo.svg`](assets/bcq-logo.svg) | Horizontal banner with the mark and wordmark. | -| [`bcq-mark.svg`](assets/bcq-mark.svg) | Symbol without the wordmark. | - -The SVG files can be scaled without losing quality. - -## Color palette - -The artwork uses the dominant colors sampled from the supplied Business Central -logo reference. - -| Color | Hex | -| --- | --- | -| Deep blue | `#086194` | -| Blue | `#138EB7` | -| Cyan | `#17ABCB` | -| Aqua | `#2CD2CD` | -| Mint | `#57E6CB` | -| Light mint | `#9BF2C8` | - -## Usage - -- Prefer the full logo when at least 320 pixels of horizontal space is - available; use the mark at smaller sizes. -- Preserve the artwork's proportions, colors, and orientation. -- Use `BCQuality logo` as alternative text unless nearby text already names the - project, in which case the image can be decorative. From 38ad6b8810440e9e78733e4c75b06fb8614db729 Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Fri, 18 Sep 2026 09:07:57 +0200 Subject: [PATCH 21/35] Add title and description to README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index d45a5d1..8bf1cc7 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# BC Quality - Don’t teach one agent. Teach the ecosystem. 🤝 + Quality skills and knowledge that help AI tools make better Business Central development decisions: catch BC-specific defects, avoid misleading advice, and explain findings with references you can read. From dd833133e05f1467e0e01c312f50508c5bd547d5 Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Mon, 21 Sep 2026 10:15:39 +0200 Subject: [PATCH 22/35] Add foundational AL developer knowledge (#195) Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- ...ize-document-defaults-in-initrecord.bad.al | 28 ++++++++++++ ...ze-document-defaults-in-initrecord.good.al | 45 +++++++++++++++++++ ...tialize-document-defaults-in-initrecord.md | 30 +++++++++++++ ...und-direction-symbols-use-magnitude.bad.al | 8 ++++ ...nd-direction-symbols-use-magnitude.good.al | 10 +++++ .../round-direction-symbols-use-magnitude.md | 30 +++++++++++++ .../guard-interface-casts-with-is.bad.al | 20 +++++++++ .../guard-interface-casts-with-is.good.al | 24 ++++++++++ .../guard-interface-casts-with-is.md | 30 +++++++++++++ ...oup-respects-lookup-page-visibility.bad.al | 9 ++++ ...up-respects-lookup-page-visibility.good.al | 20 +++++++++ ...ldgroup-respects-lookup-page-visibility.md | 30 +++++++++++++ ...ropagation-both-refreshes-main-page.bad.al | 26 +++++++++++ ...opagation-both-refreshes-main-page.good.al | 27 +++++++++++ ...atepropagation-both-refreshes-main-page.md | 30 +++++++++++++ ...on-meaning-depends-on-execution-context.md | 26 +++++++++++ ...and-upgrade-codeunits-have-no-order.bad.al | 28 ++++++++++++ ...nd-upgrade-codeunits-have-no-order.good.al | 18 ++++++++ ...all-and-upgrade-codeunits-have-no-order.md | 30 +++++++++++++ .../skills/review/al-data-modeling-review.md | 4 +- .../skills/review/al-interfaces-review.md | 3 +- microsoft/skills/review/al-ui-review.md | 7 ++- microsoft/skills/review/al-upgrade-review.md | 4 +- 23 files changed, 483 insertions(+), 4 deletions(-) create mode 100644 microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.bad.al create mode 100644 microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.good.al create mode 100644 microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.md create mode 100644 microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.bad.al create mode 100644 microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.good.al create mode 100644 microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.md create mode 100644 microsoft/knowledge/interfaces/guard-interface-casts-with-is.bad.al create mode 100644 microsoft/knowledge/interfaces/guard-interface-casts-with-is.good.al create mode 100644 microsoft/knowledge/interfaces/guard-interface-casts-with-is.md create mode 100644 microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.bad.al create mode 100644 microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.good.al create mode 100644 microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.md create mode 100644 microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.bad.al create mode 100644 microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.good.al create mode 100644 microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.md create mode 100644 microsoft/knowledge/upgrade/appversion-meaning-depends-on-execution-context.md create mode 100644 microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.bad.al create mode 100644 microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.good.al create mode 100644 microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.md diff --git a/microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.bad.al b/microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.bad.al new file mode 100644 index 0000000..0c87bb2 --- /dev/null +++ b/microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.bad.al @@ -0,0 +1,28 @@ +table 50603 "Sample Order Header Bad" +{ + fields + { + field(1; "No."; Code[20]) + { + DataClassification = CustomerContent; + } + field(2; "Document Date"; Date) + { + DataClassification = CustomerContent; + } + } + + trigger OnInsert() + var + SalesSetup: Record "Sales & Receivables Setup"; + NoSeries: Codeunit "No. Series"; + begin + "Document Date" := WorkDate(); + + if "No." = '' then begin + SalesSetup.Get(); + SalesSetup.TestField("Order Nos."); + "No." := NoSeries.GetNextNo(SalesSetup."Order Nos."); + end; + end; +} diff --git a/microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.good.al b/microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.good.al new file mode 100644 index 0000000..355d3d5 --- /dev/null +++ b/microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.good.al @@ -0,0 +1,45 @@ +table 50602 "Sample Order Header Good" +{ + fields + { + field(1; "No."; Code[20]) + { + DataClassification = CustomerContent; + } + field(2; "Document Date"; Date) + { + DataClassification = CustomerContent; + } + } + + trigger OnInsert() + var + SalesSetup: Record "Sales & Receivables Setup"; + NoSeries: Codeunit "No. Series"; + begin + if "No." = '' then begin + SalesSetup.Get(); + SalesSetup.TestField("Order Nos."); + "No." := NoSeries.GetNextNo(SalesSetup."Order Nos."); + end; + + InitRecord(); + end; + + procedure InitRecord() + begin + OnBeforeInitRecord(Rec); + "Document Date" := WorkDate(); + OnAfterInitRecord(Rec); + end; + + [IntegrationEvent(false, false)] + local procedure OnBeforeInitRecord(var SampleOrderHeader: Record "Sample Order Header Good") + begin + end; + + [IntegrationEvent(false, false)] + local procedure OnAfterInitRecord(var SampleOrderHeader: Record "Sample Order Header Good") + begin + end; +} diff --git a/microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.md b/microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.md new file mode 100644 index 0000000..e83a6d3 --- /dev/null +++ b/microsoft/knowledge/data-modeling/initialize-document-defaults-in-initrecord.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [document-header, initrecord, number-series, default-values, oninsert, initialization] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Initialize document defaults in `InitRecord` after assigning the number + +## Description + +Business Central document headers assign their number series first and then call an `InitRecord` procedure that owns the remaining business defaults, such as posting and document dates. Keeping that sequence and extensibility point makes initialization consistent for every creation path and lets extensions subscribe around one documented operation. Defaults scattered across page triggers or unrelated helpers can differ between UI, API, test, and background creation. + +## Best Practice + +In the document table's insert path, assign the document number and then call `InitRecord`. Keep the default assignments in that procedure and expose narrow before/after events when other extensions must participate. + +See sample: [`initialize-document-defaults-in-initrecord.good.al`](initialize-document-defaults-in-initrecord.good.al). + +## Anti Pattern + +Assigning document defaults in a page trigger, or scattering them directly through `OnInsert` with no `InitRecord` boundary. Non-page creation paths can then miss the defaults, and extensions have no stable initialization hook. + +See sample: [`initialize-document-defaults-in-initrecord.bad.al`](initialize-document-defaults-in-initrecord.bad.al). + +## Reference + +[Use the InitRecord function](https://learn.microsoft.com/en-us/training/modules/use-document-standards-business-central/3-use-initrecord-function) diff --git a/microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.bad.al b/microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.bad.al new file mode 100644 index 0000000..f8e11cc --- /dev/null +++ b/microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.bad.al @@ -0,0 +1,8 @@ +codeunit 50601 "Directed Rounding Bad" +{ + procedure FloorAmount(Value: Decimal; Precision: Decimal): Decimal + begin + // For negative values, '<' rounds toward zero rather than toward negative infinity. + exit(Round(Value, Precision, '<')); + end; +} diff --git a/microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.good.al b/microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.good.al new file mode 100644 index 0000000..cd8a80f --- /dev/null +++ b/microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.good.al @@ -0,0 +1,10 @@ +codeunit 50600 "Directed Rounding Good" +{ + procedure RoundAmount(Value: Decimal; Precision: Decimal; IncreaseMagnitude: Boolean): Decimal + begin + if IncreaseMagnitude then + exit(Round(Value, Precision, '>')); + + exit(Round(Value, Precision, '<')); + end; +} diff --git a/microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.md b/microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.md new file mode 100644 index 0000000..260905d --- /dev/null +++ b/microsoft/knowledge/data-modeling/round-direction-symbols-use-magnitude.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [round, rounding, direction, precision, negative-decimal, amount] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# `Round` direction symbols follow magnitude, not mathematical ordering + +## Description + +AL's `Round(Number, Precision, Direction)` uses `'>'` to round away from zero and `'<'` to round toward zero. For a negative value this reverses mathematical ordering: `Round(-1234.56789, 0.001, '<')` returns `-1234.567`, while direction `'>'` returns `-1234.568`. Code that treats the symbols as mathematical ceiling and floor produces sign-dependent amount errors, commonly on credit documents and negative adjustments. + +## Best Practice + +Choose the direction from the business meaning: `'>'` increases absolute magnitude and `'<'` decreases absolute magnitude for both positive and negative values. Include positive and negative cases whenever a directed rounding rule is tested. + +See sample: [`round-direction-symbols-use-magnitude.good.al`](round-direction-symbols-use-magnitude.good.al). + +## Anti Pattern + +Using `'<'` as a mathematical floor or `'>'` as a mathematical ceiling. The result looks correct for positive amounts but moves in the opposite mathematical direction for negative amounts. + +See sample: [`round-direction-symbols-use-magnitude.bad.al`](round-direction-symbols-use-magnitude.bad.al). + +## Reference + +[Use the Round function](https://learn.microsoft.com/en-us/training/modules/use-document-standards-business-central/4a-use-round-function) diff --git a/microsoft/knowledge/interfaces/guard-interface-casts-with-is.bad.al b/microsoft/knowledge/interfaces/guard-interface-casts-with-is.bad.al new file mode 100644 index 0000000..4fd98be --- /dev/null +++ b/microsoft/knowledge/interfaces/guard-interface-casts-with-is.bad.al @@ -0,0 +1,20 @@ +interface "I Quote Amount Bad" +{ + procedure GetAmount(): Decimal; +} + +interface "I Quote Date Bad" +{ + procedure GetDate(): Date; +} + +codeunit 50611 "Quote Reader Bad" +{ + procedure GetDate(Quote: Interface "I Quote Amount Bad"): Date + var + DatedQuote: Interface "I Quote Date Bad"; + begin + DatedQuote := Quote as "I Quote Date Bad"; + exit(DatedQuote.GetDate()); + end; +} diff --git a/microsoft/knowledge/interfaces/guard-interface-casts-with-is.good.al b/microsoft/knowledge/interfaces/guard-interface-casts-with-is.good.al new file mode 100644 index 0000000..f58a19d --- /dev/null +++ b/microsoft/knowledge/interfaces/guard-interface-casts-with-is.good.al @@ -0,0 +1,24 @@ +interface "I Quote Amount Good" +{ + procedure GetAmount(): Decimal; +} + +interface "I Quote Date Good" +{ + procedure GetDate(): Date; +} + +codeunit 50610 "Quote Reader Good" +{ + procedure TryGetDate(Quote: Interface "I Quote Amount Good"; var QuoteDate: Date): Boolean + var + DatedQuote: Interface "I Quote Date Good"; + begin + if not (Quote is "I Quote Date Good") then + exit(false); + + DatedQuote := Quote as "I Quote Date Good"; + QuoteDate := DatedQuote.GetDate(); + exit(true); + end; +} diff --git a/microsoft/knowledge/interfaces/guard-interface-casts-with-is.md b/microsoft/knowledge/interfaces/guard-interface-casts-with-is.md new file mode 100644 index 0000000..ad9c38e --- /dev/null +++ b/microsoft/knowledge/interfaces/guard-interface-casts-with-is.md @@ -0,0 +1,30 @@ +--- +bc-version: [25..] +domain: interfaces +keywords: [interface, is-operator, as-operator, type-test, cast, variant, runtime-error] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Guard optional interface casts with `is` + +## Description + +From runtime 15.0, AL can type-test an interface or `Variant` with `is` and cast it to another interface with `as`. The test is non-throwing, but `as` raises a runtime error when the underlying codeunit does not implement the target interface. This matters when an extended capability is optional or implementations can come from other extensions. + +## Best Practice + +Use `is` to establish that the value supports the target interface before using `as`. Cast directly only where the target implementation is an invariant guaranteed by the surrounding contract. + +See sample: [`guard-interface-casts-with-is.good.al`](guard-interface-casts-with-is.good.al). + +## Anti Pattern + +Using `as` unconditionally for an optional extended interface. An otherwise valid implementation of the base interface then fails at runtime merely because it does not implement the additional contract. + +See sample: [`guard-interface-casts-with-is.bad.al`](guard-interface-casts-with-is.bad.al). + +## Reference + +[Understand type testing and casting operators for interfaces](https://learn.microsoft.com/en-us/training/modules/business-central-interfaces/type-testing) diff --git a/microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.bad.al b/microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.bad.al new file mode 100644 index 0000000..78602b4 --- /dev/null +++ b/microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.bad.al @@ -0,0 +1,9 @@ +tableextension 50622 "Ship-to Dropdown Bad" extends "Ship-to Address" +{ + fieldgroups + { + addlast(DropDown; "Address 2") + { + } + } +} diff --git a/microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.good.al b/microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.good.al new file mode 100644 index 0000000..c8a8c28 --- /dev/null +++ b/microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.good.al @@ -0,0 +1,20 @@ +tableextension 50620 "Ship-to Dropdown Good" extends "Ship-to Address" +{ + fieldgroups + { + addlast(DropDown; "Address 2") + { + } + } +} + +pageextension 50621 "Ship-to Lookup Good" extends "Ship-to Address List" +{ + layout + { + modify("Address 2") + { + Visible = true; + } + } +} diff --git a/microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.md b/microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.md new file mode 100644 index 0000000..afa2c34 --- /dev/null +++ b/microsoft/knowledge/ui/dropdown-fieldgroup-respects-lookup-page-visibility.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: ui +keywords: [fieldgroup, dropdown, addlast, lookup-page, visible, tableextension, pageextension] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# A `DropDown` field remains hidden when its lookup-page control is hidden + +## Description + +A tableextension can append a field to the `DropDown` field group with `addlast`, but the client still omits that field when its control on the underlying lookup page has `Visible = false`. Changing only the table field group therefore compiles while producing no visible UI change. The field-group name is case-sensitive and must be written as `DropDown`. + +## Best Practice + +When adding a hidden field to a `DropDown` field group, also extend the page used for the lookup and make that field control visible. Verify the actual lookup page rather than assuming the table definition alone controls the drop-down. + +See sample: [`dropdown-fieldgroup-respects-lookup-page-visibility.good.al`](dropdown-fieldgroup-respects-lookup-page-visibility.good.al). + +## Anti Pattern + +Adding the field with `addlast(DropDown; ...)` while leaving its lookup-page control hidden, then expecting the field to appear in the drop-down. + +See sample: [`dropdown-fieldgroup-respects-lookup-page-visibility.bad.al`](dropdown-fieldgroup-respects-lookup-page-visibility.bad.al). + +## Reference + +[Add a new FieldGroup to an existing table](https://learn.microsoft.com/en-us/training/modules/extend-modify-existing-table/add-field-group) diff --git a/microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.bad.al b/microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.bad.al new file mode 100644 index 0000000..f5d2b2b --- /dev/null +++ b/microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.bad.al @@ -0,0 +1,26 @@ +page 50631 "Sample Order Bad" +{ + PageType = Document; + SourceTable = "Sales Header"; + + layout + { + area(Content) + { + group(General) + { + field(Amount; Rec.Amount) + { + ApplicationArea = All; + ToolTip = 'Specifies the total amount of the order.'; + } + } + part(Lines; "Sales Order Subform") + { + ApplicationArea = All; + SubPageLink = "Document Type" = field("Document Type"), + "Document No." = field("No."); + } + } + } +} diff --git a/microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.good.al b/microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.good.al new file mode 100644 index 0000000..3462098 --- /dev/null +++ b/microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.good.al @@ -0,0 +1,27 @@ +page 50630 "Sample Order Good" +{ + PageType = Document; + SourceTable = "Sales Header"; + + layout + { + area(Content) + { + group(General) + { + field(Amount; Rec.Amount) + { + ApplicationArea = All; + ToolTip = 'Specifies the total amount of the order.'; + } + } + part(Lines; "Sales Order Subform") + { + ApplicationArea = All; + SubPageLink = "Document Type" = field("Document Type"), + "Document No." = field("No."); + UpdatePropagation = Both; + } + } + } +} diff --git a/microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.md b/microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.md new file mode 100644 index 0000000..3ce676b --- /dev/null +++ b/microsoft/knowledge/ui/updatepropagation-both-refreshes-main-page.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: ui +keywords: [updatepropagation, page-part, subpage, main-page, refresh, flowfield, document-lines] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Use `UpdatePropagation = Both` when line edits must refresh the main page + +## Description + +A page part does not automatically refresh its parent page when the subpage changes. `UpdatePropagation = Subpage` updates only the part; `Both` also refreshes the main page. Without `Both`, header totals, FlowFields, and FactBoxes that depend on edited lines can remain stale until another user action refreshes the page. + +## Best Practice + +Set `UpdatePropagation = Both` on a part when edits in that subpage must immediately update values rendered by the main page. Leave propagation at `Subpage` when the parent has no dependent presentation to avoid unnecessary refreshes. + +See sample: [`updatepropagation-both-refreshes-main-page.good.al`](updatepropagation-both-refreshes-main-page.good.al). + +## Anti Pattern + +Displaying a line-dependent total on the main page while the editable lines part updates only itself. The persisted values can be correct while the parent page continues to show an old total. + +See sample: [`updatepropagation-both-refreshes-main-page.bad.al`](updatepropagation-both-refreshes-main-page.bad.al). + +## Reference + +[Set different control properties](https://learn.microsoft.com/en-us/training/modules/work-with-pages/8-controls) diff --git a/microsoft/knowledge/upgrade/appversion-meaning-depends-on-execution-context.md b/microsoft/knowledge/upgrade/appversion-meaning-depends-on-execution-context.md new file mode 100644 index 0000000..61e7422 --- /dev/null +++ b/microsoft/knowledge/upgrade/appversion-meaning-depends-on-execution-context.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: upgrade +keywords: [appversion, dataversion, moduleinfo, install-codeunit, upgrade-codeunit, version-context] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# `ModuleInfo.AppVersion` changes meaning with execution context + +## Description + +`ModuleInfo.AppVersion()` is the installed version during normal operation, the version being installed inside install code, and the target version inside upgrade code. It is therefore not the source data version during an upgrade. In upgrade code, `DataVersion()` describes the version of the existing data, whether from the currently installed app or the version most recently uninstalled. + +## Best Practice + +Interpret `AppVersion()` as the code package entering the context and `DataVersion()` as the existing data state. Prefer upgrade tags for controlling individual migration steps; when version information is needed for diagnostics or preconditions, name variables so target app version and source data version cannot be confused. + +## Anti Pattern + +Reading `AppVersion()` from an upgrade codeunit and treating it as the version being upgraded from. The comparison actually observes the target package and can skip or misroute migration logic. + +## Reference + +[Create proper installation and upgrade codeunits](https://learn.microsoft.com/en-us/training/modules/easy-application-upgrade/3-installation-upgrade-codeunits) diff --git a/microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.bad.al b/microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.bad.al new file mode 100644 index 0000000..2a92d11 --- /dev/null +++ b/microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.bad.al @@ -0,0 +1,28 @@ +codeunit 50641 "Sample Upgrade Part One" +{ + Subtype = Upgrade; + + trigger OnUpgradePerCompany() + begin + CreateUpgradeState(); + end; + + local procedure CreateUpgradeState() + begin + end; +} + +codeunit 50642 "Sample Upgrade Part Two" +{ + Subtype = Upgrade; + + trigger OnUpgradePerCompany() + begin + // This can run before Part One; object IDs do not sequence upgrade codeunits. + MigrateDataThatRequiresUpgradeState(); + end; + + local procedure MigrateDataThatRequiresUpgradeState() + begin + end; +} diff --git a/microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.good.al b/microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.good.al new file mode 100644 index 0000000..42346a8 --- /dev/null +++ b/microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.good.al @@ -0,0 +1,18 @@ +codeunit 50640 "Sample Upgrade Good" +{ + Subtype = Upgrade; + + trigger OnUpgradePerCompany() + begin + CreateUpgradeState(); + MigrateDependentData(); + end; + + local procedure CreateUpgradeState() + begin + end; + + local procedure MigrateDependentData() + begin + end; +} diff --git a/microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.md b/microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.md new file mode 100644 index 0000000..b11a842 --- /dev/null +++ b/microsoft/knowledge/upgrade/install-and-upgrade-codeunits-have-no-order.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: upgrade +keywords: [install-codeunit, upgrade-codeunit, execution-order, subtype-install, subtype-upgrade, sequencing] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Separate install or upgrade codeunits have no execution order + +## Description + +An extension can contain multiple `Install` or `Upgrade` codeunits, but Business Central does not guarantee the order in which codeunits of the same subtype execute. Upgrade trigger phases are ordered globally, yet one codeunit's `OnUpgradePerCompany` must not assume another codeunit's same-phase trigger already ran. Object ID and source-file order do not provide sequencing. + +## Best Practice + +Keep separate install or upgrade codeunits independent. When two steps have a real dependency, coordinate them from one owning trigger in the required order; use upgrade tags to make each completed step idempotent. + +See sample: [`install-and-upgrade-codeunits-have-no-order.good.al`](install-and-upgrade-codeunits-have-no-order.good.al). + +## Anti Pattern + +Splitting dependent steps into separate codeunits and relying on names, object IDs, or declaration order. The dependent codeunit can run first and fail or observe partially migrated data. + +See sample: [`install-and-upgrade-codeunits-have-no-order.bad.al`](install-and-upgrade-codeunits-have-no-order.bad.al). + +## Reference + +[Create proper installation and upgrade codeunits](https://learn.microsoft.com/en-us/training/modules/easy-application-upgrade/3-installation-upgrade-codeunits) diff --git a/microsoft/skills/review/al-data-modeling-review.md b/microsoft/skills/review/al-data-modeling-review.md index 05dcd0b..3fca8ec 100644 --- a/microsoft/skills/review/al-data-modeling-review.md +++ b/microsoft/skills/review/al-data-modeling-review.md @@ -39,7 +39,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially `* Setup` singleton tables and Card pages, custom master tables, tableextensions that add master-data fields, and document or journal lines that reference a master. - The changed fields, keys, triggers, and procedures, weighted toward `Primary Key`, `No.`, `No. Series`, `Blocked`, `Last Date Modified`, `OnInsert`, `OnModify`, `OnRename`, reference-field `OnValidate`, and posting validation. -- Tokens extracted from the diff that relate to data modeling (`setup`, `master`, `Primary Key`, `Code[10]`, `Code[20]`, `AutoIncrement`, `SystemId`, `No.`, `No. Series`, `NoSeriesManagement`, `Codeunit "No. Series"`, `GetNextNo`, `IsManual`, `TestManual`, `Blocked`, `TestField`, `Last Date Modified`, `Today`, `WorkDate`, `InsertAllowed`, `DeleteAllowed`, `PageType = Card`, `OnOpenPage`, `GetRecordOnce`, `OnInsert`, `OnModify`, `OnRename`, `TableRelation`, `tableextension`, `enumextension`, `Media`, `MediaSet`, `Item`, `Count`). +- Tokens extracted from the diff that relate to data modeling (`setup`, `master`, `Primary Key`, `Code[10]`, `Code[20]`, `AutoIncrement`, `SystemId`, `No.`, `No. Series`, `NoSeriesManagement`, `Codeunit "No. Series"`, `GetNextNo`, `IsManual`, `TestManual`, `Blocked`, `TestField`, `Last Date Modified`, `Today`, `WorkDate`, `InsertAllowed`, `DeleteAllowed`, `PageType = Card`, `OnOpenPage`, `GetRecordOnce`, `OnInsert`, `OnModify`, `OnRename`, `InitRecord`, `Round`, `Precision`, `Direction`, `TableRelation`, `tableextension`, `enumextension`, `Media`, `MediaSet`, `Item`, `Count`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. When the diff contains no data-modeling changes by any of the above signals, return `outcome: "not-applicable"` without evaluating files. @@ -52,6 +52,8 @@ The following targeted checks cover every current `data-modeling` article. Treat - A master table adds or changes `Last Date Modified`, `OnModify`, or `OnRename`, but the non-editable field is not assigned `Today()` in both triggers — `set-last-date-modified-in-onmodify-and-onrename`. - A `tableextension` appends a conditional `TableRelation` as if it overrides an earlier unconditional relation, or relation branches are otherwise designed without accounting for additive top-down evaluation — `table-relation-extensions-are-additive-and-top-down`. - A `Media` or `MediaSet` field is assigned directly between different table types or different field IDs instead of registering each shared item with `MediaSet.Insert` — `share-mediaset-items-with-insert-not-field-assignment`. +- A custom document header assigns defaults outside an `InitRecord` boundary, calls `InitRecord` before assigning its number, or places UI-independent defaults only in a page trigger — `initialize-document-defaults-in-initrecord`. +- Directed `Round` calls use `'<'` as mathematical floor or `'>'` as mathematical ceiling, especially where negative amounts are possible — `round-direction-symbols-use-magnitude`. Once the candidate worklist is known, resolve layer-precedence conflicts per READ. Drop lower-precedence files whose normative guidance (`## Best Practice` or `## Anti Pattern`) directly contradicts a higher-precedence candidate, and record each dropped file in `suppressed` with `reason: "layer-precedence"`. Files that would have been candidates but are hidden because their layer is disabled in consumer configuration are recorded with `reason: "configuration"`. Files that never became candidates are NOT recorded in `suppressed`. diff --git a/microsoft/skills/review/al-interfaces-review.md b/microsoft/skills/review/al-interfaces-review.md index f5d65cd..1c38be7 100644 --- a/microsoft/skills/review/al-interfaces-review.md +++ b/microsoft/skills/review/al-interfaces-review.md @@ -39,7 +39,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially `interface` objects, codeunits and enums declared with the `implements` keyword, and consumers that declare or assign an `Interface` variable. - The changed procedures and triggers, weighted toward factory or dispatch routines that resolve a variant to behaviour, setter-injection procedures that take an `Interface` parameter, and `case`-over-enum blocks that select between strategies. -- Tokens extracted from the diff that relate to interfaces and enum-backed implementation (`interface`, `extends`, `implements`, `Implementation`, `DefaultImplementation`, `UnknownValueImplementation`, `enum`, `Extensible`, `Interface`, `case`, and the `case of` anti-pattern signal — a `case` over an enum value whose branches choose between variant computations). +- Tokens extracted from the diff that relate to interfaces and enum-backed implementation (`interface`, `extends`, `implements`, `Implementation`, `DefaultImplementation`, `UnknownValueImplementation`, `enum`, `Extensible`, `Interface`, `Variant`, `is`, `as`, `case`, and the `case of` anti-pattern signal — a `case` over an enum value whose branches choose between variant computations). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. @@ -54,6 +54,7 @@ The following targeted checks map diff signals to specific `interfaces` articles - `DefaultImplementation` used as the only fallback where a persisted ordinal may no longer match any declared enum value, or a persisted enum lacks `UnknownValueImplementation` on BC18 or later — `handle-unknown-enum-ordinals-with-unknownvalueimplementation`. - A method added directly to an interface that exists in the baseline, instead of adding a BC25+ interface that `extends` it or a versioned sibling for older targets — `extend-published-interfaces-dont-edit-them`. - A declared enum value with no `Implementation` and no enum-level `DefaultImplementation` — `set-defaultimplementation-on-enum`. +- An `Interface` or `Variant` is cast with `as` to an optional extended interface without first establishing support with `is` — `guard-interface-casts-with-is`. For `set-defaultimplementation-on-enum`, inspect the complete containing enum before emitting. An enum-level `DefaultImplementation = = ;` conclusively covers every declared value that omits its own `Implementation`; do not flag such a value and do not replace the intentional fallback with a per-value mapping. diff --git a/microsoft/skills/review/al-ui-review.md b/microsoft/skills/review/al-ui-review.md index 8ffd731..8c35f49 100644 --- a/microsoft/skills/review/al-ui-review.md +++ b/microsoft/skills/review/al-ui-review.md @@ -41,10 +41,15 @@ Narrow the relevant files to the subset that applies to the changes under review - **UI-file filter.** UI review applies to files declaring `page`, `pageextension`, or `pagecustomization`, and to JavaScript/CSS/HTML that implements a control add-in's rendering or Business Central communication. When the diff contains no such files, return `outcome: "not-applicable"` without evaluating knowledge files. - For each relevant knowledge file, compute overlap against changed page declarations and control add-in files, weighted toward `Caption`, `ToolTip`, `AboutTitle`, `AboutText`, `OptionCaption`, `ShowCaption`, `InstructionalText`, `GridLayout`, `Style`, `StyleExpr`, promoted action definitions, field importance, page background tasks, DOM creation, ARIA attributes, keyboard/focus handlers, packaged-resource AJAX, and calls from JavaScript into AL. -- Tokens extracted from the diff (`Caption`, `ToolTip`, `AboutTitle`, `AboutText`, `PageType`, `ShowCaption`, `InstructionalText`, `grid`, `fixed`, `GridLayout`, `Style`, `StyleExpr`, `Importance`, `Promoted`, `Additional`, `area(Promoted)`, `actionref`, `PromotedCategory`, `PromotedOnly`, `PromotedIsBig`, `ShowAs`, `SplitButton`, `EnqueueBackgroundTask`, `OnAfterGetCurrRecord`, `OnAfterGetRecord`, `OnPageBackgroundTaskCompleted`, `OnPageBackgroundTaskError`, `RunPageBackgroundTask`, `Favorable`, `Unfavorable`, `Ambiguous`, `cuegroup`, `controladdin`, `control-add-in`, `usercontrol`, `aria-`, `tabindex`, `keydown`, `focus`, `innerHTML`, `createElement`, `packaged-resource`, `ajax`, `$.get`, `$.ajax`, `XMLHttpRequest`, `xhrFields`, `withCredentials`, `withcredentials`, `InvokeExtensibilityMethod`, `invokeextensibilitymethod`, `skipIfBusy`, `successCallback`, `success-callback`, `errorCallback`, `setInterval`, `JSON.stringify`, `payload`, `throttling`, `reduced-functionality`, `ClientServicesMaxUploadSize`, `&`, `Specifies`, `Message(`, `Confirm(`, `Error(` in a page context, `Disabled`, `Invalid`, `Whitelist`, `Blacklist`, trailing punctuation patterns on captions). +- Tokens extracted from the diff (`Caption`, `ToolTip`, `AboutTitle`, `AboutText`, `PageType`, `ShowCaption`, `InstructionalText`, `grid`, `fixed`, `GridLayout`, `Style`, `StyleExpr`, `Importance`, `Promoted`, `Additional`, `area(Promoted)`, `actionref`, `PromotedCategory`, `PromotedOnly`, `PromotedIsBig`, `ShowAs`, `SplitButton`, `fieldgroups`, `DropDown`, `UpdatePropagation`, `EnqueueBackgroundTask`, `OnAfterGetCurrRecord`, `OnAfterGetRecord`, `OnPageBackgroundTaskCompleted`, `OnPageBackgroundTaskError`, `RunPageBackgroundTask`, `Favorable`, `Unfavorable`, `Ambiguous`, `cuegroup`, `controladdin`, `control-add-in`, `usercontrol`, `aria-`, `tabindex`, `keydown`, `focus`, `innerHTML`, `createElement`, `packaged-resource`, `ajax`, `$.get`, `$.ajax`, `XMLHttpRequest`, `xhrFields`, `withCredentials`, `withcredentials`, `InvokeExtensibilityMethod`, `invokeextensibilitymethod`, `skipIfBusy`, `successCallback`, `success-callback`, `errorCallback`, `setInterval`, `JSON.stringify`, `payload`, `throttling`, `reduced-functionality`, `ClientServicesMaxUploadSize`, `&`, `Specifies`, `Message(`, `Confirm(`, `Error(` in a page context, `Disabled`, `Invalid`, `Whitelist`, `Blacklist`, trailing punctuation patterns on captions). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed page element. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. +Apply these high-signal mappings before fuzzy topic ranking: + +- A tableextension adds a field to `DropDown` while the corresponding lookup-page control remains `Visible = false` — `dropdown-fieldgroup-respects-lookup-page-visibility`. +- An editable page part affects a total, FlowField, or FactBox on the parent but does not set `UpdatePropagation = Both` — `updatepropagation-both-refreshes-main-page`. + Once the candidate worklist is known, resolve layer-precedence conflicts per READ and record suppressions. When the post-conflict worklist is empty because no applicable UI knowledge exists, or because configuration suppressed every candidate, emit `outcome: "no-knowledge"`. When the worklist is empty because no applicable UI knowledge matched the page changes, emit `outcome: "completed"` with an empty `findings` array. diff --git a/microsoft/skills/review/al-upgrade-review.md b/microsoft/skills/review/al-upgrade-review.md index 94851a3..9ae61f8 100644 --- a/microsoft/skills/review/al-upgrade-review.md +++ b/microsoft/skills/review/al-upgrade-review.md @@ -39,10 +39,12 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially codeunits with `Subtype = Upgrade` or `Subtype = Install`, tables and tableextensions adding or changing fields, enums and enumextensions, and objects under `Hybrid*`/`Migration`/`Upgrade` namespaces. - The changed triggers and procedures, weighted toward `OnCheckPreconditionsPerCompany`/`PerDatabase`, `OnUpgradePerCompany`/`PerDatabase`, `OnValidateUpgradePerCompany`/`PerDatabase`, `OnInstallAppPerCompany`/`PerDatabase`, the `OnGetPerCompanyUpgradeTags`/`OnGetPerDatabaseUpgradeTags` subscribers, and helper procedures transitively reachable from those entry points. -- Tokens extracted from the diff that relate to upgrade concerns (`Subtype = Upgrade`, `Subtype = Install`, `Upgrade Tag`, `HasUpgradeTag`, `SetUpgradeTag`, `OnCheckPreconditions`, `OnUpgrade`, `OnValidateUpgrade`, `OnInstallApp`, `DataTransfer`, `CopyFields`, `Insert`, `Modify`, `Delete`, `Rename`, `InitValue`, `ObsoleteState`, `ObsoleteReason`, `ObsoleteTag`, `DataVersion`, `ExecutionContext`, `PrimaryKey`, `key(`, `field(`, `value(`, `enum`, `enumextension`, `HybridSL`, `HybridGP`, `HybridBC`, `HybridBaseDeployment`). +- Tokens extracted from the diff that relate to upgrade concerns (`Subtype = Upgrade`, `Subtype = Install`, `Upgrade Tag`, `HasUpgradeTag`, `SetUpgradeTag`, `OnCheckPreconditions`, `OnUpgrade`, `OnValidateUpgrade`, `OnInstallApp`, `DataTransfer`, `CopyFields`, `Insert`, `Modify`, `Delete`, `Rename`, `InitValue`, `ObsoleteState`, `ObsoleteReason`, `ObsoleteTag`, `ModuleInfo`, `AppVersion`, `DataVersion`, `NavApp.GetCurrentModuleInfo`, `ExecutionContext`, `PrimaryKey`, `key(`, `field(`, `value(`, `enum`, `enumextension`, `HybridSL`, `HybridGP`, `HybridBC`, `HybridBaseDeployment`). - For each `OnCheckPreconditions...` and `OnValidateUpgrade...` trigger, build the best available call graph from surrounding unchanged source as well as changed hunks, tracing resolved calls through reachable local or internal helpers. Worklist the check-only rule when a database write occurs either directly in the trigger or in any helper procedure reachable from it. Writes include `Insert`, `Modify`, `ModifyAll`, `Delete`, `DeleteAll`, `Rename`, and `DataTransfer`. Also perform the reverse check when a PR changes a writing helper body: worklist the rule when that helper is invoked directly or transitively by an unchanged check or validation trigger. - Treat a direct write or a fully resolved call chain as high-confidence evidence. When cross-object dispatch, unavailable declarations, or an incomplete call graph prevents proving the complete chain, cap confidence at `medium`, name the unresolved edge in the finding, and do not claim a violation without a resolved path from a check or validation trigger to a write. - Worklist the install-versus-upgrade rule when migration helpers are reachable only from an install codeunit. +- Worklist `install-and-upgrade-codeunits-have-no-order.md` when a change adds multiple install or upgrade codeunits whose same-phase triggers share state or depend on one another. +- Worklist `appversion-meaning-depends-on-execution-context.md` when install or upgrade code branches on `ModuleInfo.AppVersion()` or confuses it with `DataVersion()`. A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. When the diff contains no upgrade-related changes by any of the above signals, return `outcome: "not-applicable"` without evaluating files. From d38377b85e4ba995d822981bdd7f8d381547026a Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Mon, 21 Sep 2026 10:16:07 +0200 Subject: [PATCH 23/35] Clarify locale-safe DateFormula Evaluate inputs (#193) * Clarify locale-safe DateFormula Evaluate inputs Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Normalize DateFormula article sections Keep the analyzer-gap explanation in Description and its scoped probe evidence in References, without a novel Validation section. Normative guidance and fixtures are unchanged. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- evaluation/review-fixtures.json | 5 ++- ...needs-language-independent-literals.bad.al | 18 +++++++++ ...eeds-language-independent-literals.good.al | 18 +++++++++ ...ate-needs-language-independent-literals.md | 38 +++++++++++++++++++ microsoft/skills/review/al-style-review.md | 10 +++-- 5 files changed, 84 insertions(+), 5 deletions(-) create mode 100644 microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.bad.al create mode 100644 microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.good.al create mode 100644 microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.md diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index 90c42c6..e52a653 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -52,7 +52,10 @@ ] }, "style": { - "article": "label-comment-explains-placeholders" + "articles": [ + "label-comment-explains-placeholders", + "dateformula-evaluate-needs-language-independent-literals" + ] }, "telemetry": { "article": "telemetry-event-id-stable-unique" diff --git a/microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.bad.al b/microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.bad.al new file mode 100644 index 0000000..c520ee0 --- /dev/null +++ b/microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.bad.al @@ -0,0 +1,18 @@ +codeunit 50102 "Bad Review Scheduling" +{ + procedure NextReviewDate(Interval: DateFormula; ReferenceDate: Date): Date + begin + if Format(Interval) = '' then + Evaluate(Interval, '1W'); + + exit(CalcDate(Interval, ReferenceDate)); + end; + + procedure NextReviewFromUserInput(UserFormulaText: Text; ReferenceDate: Date): Date + var + Interval: DateFormula; + begin + Evaluate(Interval, UserFormulaText); + exit(NextReviewDate(Interval, ReferenceDate)); + end; +} diff --git a/microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.good.al b/microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.good.al new file mode 100644 index 0000000..ee07dbe --- /dev/null +++ b/microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.good.al @@ -0,0 +1,18 @@ +codeunit 50101 "Good Review Scheduling" +{ + procedure NextReviewDate(Interval: DateFormula; ReferenceDate: Date): Date + begin + if Format(Interval) = '' then + Evaluate(Interval, '<1W>'); + + exit(CalcDate(Interval, ReferenceDate)); + end; + + procedure NextReviewFromUserInput(UserFormulaText: Text; ReferenceDate: Date): Date + var + Interval: DateFormula; + begin + Evaluate(Interval, UserFormulaText); + exit(NextReviewDate(Interval, ReferenceDate)); + end; +} diff --git a/microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.md b/microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.md new file mode 100644 index 0000000..91fcfe5 --- /dev/null +++ b/microsoft/knowledge/style/dateformula-evaluate-needs-language-independent-literals.md @@ -0,0 +1,38 @@ +--- +bc-version: [all] +domain: style +keywords: [dateformula, evaluate, calcdate, date-expression, language-independent, multilanguage, global-language] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Parse DateFormula constants with language-independent input + +## Description + +A `DateFormula` stores a formula in a language-independent representation, but `Evaluate` must first interpret its text input. Declaring the destination as `DateFormula` does not make an English literal such as `1W` independent of the session language: French uses `S` for weeks. Passing the resulting typed variable to `CalcDate` satisfies that call's CodeCop AA0462 argument requirement, but cannot repair a parsing failure that already happened in `Evaluate`. + +## Best Practice + +For an application-defined formula in a normal two-argument `Evaluate` call, use the generic units inside angle brackets, such as `<1W>`. Apply this at the text-to-`DateFormula` boundary, including a visible constant passed through a helper. A label's `Locked = true` prevents translation of its text; it does not make unbracketed English units language independent. + +Preserve genuinely localized input: text entered by the user, or already formatted for the same session language, should be parsed in that language. Do not blindly wrap that text in angle brackets. Already invariant `<...>` literals, explicit import-format conversions, a typed formula passed to `CalcDate`, and `Format(Interval) = ''` checks are not findings without an unsafe constant at the parsing boundary. + +See sample: [`dateformula-evaluate-needs-language-independent-literals.good.al`](dateformula-evaluate-needs-language-independent-literals.good.al). + +## Anti Pattern + +A hard-coded, language-fixed formula such as `1W` flows into a normal two-argument `Evaluate` whose destination is known to be `DateFormula`, and the application expects that default to work across session languages. Require the destination type and constant provenance; an arbitrary `Evaluate` call or dynamic text parameter is not enough. The resulting code can compile and work in English while failing when the same default is first needed in another language. + +Do not report direct `CalcDate` text arguments under this article: CodeCop AA0462 already owns the requirement for a typed formula or angle-bracketed text there. Its typed-argument check does not establish that an earlier `Evaluate` parsed language-independent input. + +See sample: [`dateformula-evaluate-needs-language-independent-literals.bad.al`](dateformula-evaluate-needs-language-independent-literals.bad.al). + +## References + +[DateFormula data type](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/dateformula/dateformula-data-type) and [CalcDate language behavior](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/system/system-calcdate-dateformula-date-method). + +[CodeCop AA0462](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/analyzers/codecop-aa0462) defines the separate direct-`CalcDate` check. In a CodeCop compilation probe against BC28.5 symbols, the direct text control produced AA0462; `Evaluate(Interval, '1W')` followed by typed `CalcDate` did not. + +[BaseApp retention scheduling](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/System/RetentionPolicy/RetentionPolicyScheduler.Codeunit.al#L73-L97) initializes a typed formula with an invariant literal. diff --git a/microsoft/skills/review/al-style-review.md b/microsoft/skills/review/al-style-review.md index 2703c87..5b0b6b6 100644 --- a/microsoft/skills/review/al-style-review.md +++ b/microsoft/skills/review/al-style-review.md @@ -3,7 +3,7 @@ kind: action-skill id: al-style-review version: 1 title: AL style review -description: Reviews AL source changes against naming, labelling, and code-convention guidance from BCQuality. +description: Reviews AL source changes against naming, labelling, localization, and code-convention guidance from BCQuality. inputs: [pr-diff, file-path, folder-path] outputs: [findings-report] bc-version: [all] @@ -16,7 +16,7 @@ application-area: [all] Reviews AL source changes against the `style` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`. -Style findings cover AL conventions that require contextual judgment — API page naming, temporary-variable prefixes, label semantics, named invocations, `FieldCaption`/`TableCaption` in user messages, error-parameter handling, and file naming. Mechanical compiler and analyzer rules are intentionally outside this skill; run the consuming app's configured analyzers separately. +Style findings cover AL conventions that require contextual judgment — API page naming, temporary-variable prefixes, label semantics, date-formula localization, named invocations, `FieldCaption`/`TableCaption` in user messages, error-parameter handling, and file naming. Mechanical compiler and analyzer rules are intentionally outside this skill; run the consuming app's configured analyzers separately. An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract. @@ -40,8 +40,8 @@ Discard files that are not applicable. Retain conditionally applicable files onl Narrow the relevant files to the subset that applies to the changes under review. For each relevant file, compute overlap against: - Changed AL objects — especially API pages (`PageType = API`), tables and pages declaring Labels/TextConsts, codeunits issuing `Error`/`Message`/`Confirm`, and any file whose name violates the `..al` convention. -- Changed declarations, weighted toward `: Label '...'`, `: TextConst '...'`, temporary record variables, error-handling call sites, and API declarations. -- Tokens extracted from the diff (`Label`, `TextConst`, `Locked`, `Comment`, `MaxLength`, `temporary`, `APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `DelayedInsert`, `FieldCaption`, `TableCaption`, `FieldName`, `TableName`, `Page.RunModal`, `Report.Run`, `StrSubstNo`). +- Changed declarations, weighted toward `: Label '...'`, `: TextConst '...'`, temporary record variables, `DateFormula` declarations and their `Evaluate` call sites, error-handling call sites, and API declarations. +- Tokens extracted from the diff (`Label`, `TextConst`, `Locked`, `Comment`, `MaxLength`, `temporary`, `DateFormula`, `Evaluate`, `CalcDate`, `APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `DelayedInsert`, `FieldCaption`, `TableCaption`, `FieldName`, `TableName`, `Page.RunModal`, `Report.Run`, `StrSubstNo`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object or declaration. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. @@ -50,6 +50,8 @@ Do not worklist `temporary-variable-temp-prefix.md` for an event publisher param Apply these high-signal mappings before fuzzy topic ranking: - A `Label` or `TextConst` contains multiple or ambiguous placeholders but has no `Comment`, or its Comment does not explain every placeholder — `label-comment-explains-placeholders.md`. A single placeholder whose meaning is explicit in the text, such as `Customer %1`, is allowed without a Comment and must not be flagged. +- A normal two-argument `Evaluate` has a resolved `DateFormula` destination and a hard-coded non-angle-bracket date-formula literal, directly or through a visible constant — `dateformula-evaluate-needs-language-independent-literals.md`. Do not use this cue for dynamic/localized external input, already invariant `<...>` input, or direct `CalcDate(Text, ...)` calls. + Once the candidate worklist is known, resolve layer-precedence conflicts per READ and record suppressions. When the post-conflict worklist is empty because no applicable style knowledge exists, or because configuration suppressed every candidate, emit `outcome: "no-knowledge"`. When the worklist is empty because no applicable style knowledge matched the changes, emit `outcome: "completed"` with an empty `findings` array. From bec8890b7ea8d84e6632abb3f25a22b169a034fa Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Mon, 21 Sep 2026 10:16:44 +0200 Subject: [PATCH 24/35] Add SCM functional knowledge domain (#192) * Add SCM functional knowledge domain Introduce nine source-backed rules with original AL sample pairs, bounded SCM review routing, and complete positive/clean evaluation coverage. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Normalize SCM knowledge and review ownership Align article and AL sample conventions, keep BC facts separate from review mechanics, and clarify reciprocal Finance ownership without bespoke shared test assertions. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/scripts/Test-SkillIndex.ps1 | 7 +- README.md | 11 +- docs/using-bcquality.md | 22 +++- evaluation/README.md | 10 ++ evaluation/review-fixtures.json | 13 ++ ...ions-through-reservation-management.bad.al | 13 ++ ...ons-through-reservation-management.good.al | 14 ++ ...rvations-through-reservation-management.md | 38 ++++++ ...tions-through-the-standard-workflow.bad.al | 47 +++++++ ...ions-through-the-standard-workflow.good.al | 31 +++++ ...n-actions-through-the-standard-workflow.md | 43 +++++++ ...plications-through-posting-routines.bad.al | 33 +++++ ...lications-through-posting-routines.good.al | 40 ++++++ ...m-applications-through-posting-routines.md | 39 ++++++ ...edger-changes-through-item-journals.bad.al | 32 +++++ ...dger-changes-through-item-journals.good.al | 20 +++ ...em-ledger-changes-through-item-journals.md | 42 ++++++ ...tion-through-the-item-journal-batch.bad.al | 17 +++ ...ion-through-the-item-journal-batch.good.al | 16 +++ ...aluation-through-the-item-journal-batch.md | 38 ++++++ ...ough-shipment-and-receipt-codeunits.bad.al | 22 ++++ ...ugh-shipment-and-receipt-codeunits.good.al | 32 +++++ ...-through-shipment-and-receipt-codeunits.md | 41 ++++++ ...se-adjustments-with-the-item-ledger.bad.al | 37 ++++++ ...e-adjustments-with-the-item-ledger.good.al | 42 ++++++ ...ehouse-adjustments-with-the-item-ledger.md | 40 ++++++ ...hrough-source-reservation-codeunits.bad.al | 30 +++++ ...rough-source-reservation-codeunits.good.al | 20 +++ ...ng-through-source-reservation-codeunits.md | 41 ++++++ ...te-aware-availability-for-promising.bad.al | 21 +++ ...e-aware-availability-for-promising.good.al | 27 ++++ ...e-date-aware-availability-for-promising.md | 39 ++++++ microsoft/skills/review/al-code-review.md | 1 + microsoft/skills/review/al-scm-review.md | 121 ++++++++++++++++++ 34 files changed, 1030 insertions(+), 10 deletions(-) create mode 100644 microsoft/knowledge/scm/cancel-reservations-through-reservation-management.bad.al create mode 100644 microsoft/knowledge/scm/cancel-reservations-through-reservation-management.good.al create mode 100644 microsoft/knowledge/scm/cancel-reservations-through-reservation-management.md create mode 100644 microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.bad.al create mode 100644 microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.good.al create mode 100644 microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.md create mode 100644 microsoft/knowledge/scm/change-item-applications-through-posting-routines.bad.al create mode 100644 microsoft/knowledge/scm/change-item-applications-through-posting-routines.good.al create mode 100644 microsoft/knowledge/scm/change-item-applications-through-posting-routines.md create mode 100644 microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.bad.al create mode 100644 microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.good.al create mode 100644 microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.md create mode 100644 microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.bad.al create mode 100644 microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.good.al create mode 100644 microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.md create mode 100644 microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.bad.al create mode 100644 microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.good.al create mode 100644 microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.md create mode 100644 microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.bad.al create mode 100644 microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.good.al create mode 100644 microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.md create mode 100644 microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.bad.al create mode 100644 microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.good.al create mode 100644 microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.md create mode 100644 microsoft/knowledge/scm/use-date-aware-availability-for-promising.bad.al create mode 100644 microsoft/knowledge/scm/use-date-aware-availability-for-promising.good.al create mode 100644 microsoft/knowledge/scm/use-date-aware-availability-for-promising.md create mode 100644 microsoft/skills/review/al-scm-review.md diff --git a/.github/scripts/Test-SkillIndex.ps1 b/.github/scripts/Test-SkillIndex.ps1 index ed07204..5354370 100644 --- a/.github/scripts/Test-SkillIndex.ps1 +++ b/.github/scripts/Test-SkillIndex.ps1 @@ -93,14 +93,15 @@ try { 'microsoft/skills/review/al-query-review.md', 'microsoft/skills/review/al-reporting-review.md', 'microsoft/skills/review/al-appsource-review.md', - 'microsoft/skills/review/al-telemetry-review.md' + 'microsoft/skills/review/al-telemetry-review.md', + 'microsoft/skills/review/al-scm-review.md' ) $review = @($skills | Where-Object id -eq 'al-code-review') if ($review.Count -ne 1) { throw "Expected exactly one al-code-review record, found $($review.Count)." } if ((@($review[0].subSkills) -join "`n") -cne ($expectedLeaves -join "`n")) { - throw 'al-code-review subSkills did not preserve the declared 17-leaf order.' + throw "al-code-review subSkills did not preserve the declared $($expectedLeaves.Count)-leaf order." } foreach ($leafPath in $expectedLeaves) { $leaf = @($skills | Where-Object path -ceq $leafPath) @@ -238,4 +239,4 @@ finally { Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue } -Write-Output 'Skill-index check PASSED: deterministic, schema-valid, and all 17 review leaves preserved in order.' +Write-Output "Skill-index check PASSED: deterministic, schema-valid, and all $($expectedLeaves.Count) review leaves preserved in order." diff --git a/README.md b/README.md index 8bf1cc7..9aaea9a 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,8 @@ the review can still discover knowledge by reading the folders. ## Scope -Today's curated content focuses on **technical AL code review**. It augments +Today's curated content covers **technical AL code review** and a focused +**Supply Chain Management (SCM)** functional domain. It augments the agent's judgment; it is not an exhaustive BC manual or a substitute for compilation, analyzers, tests, or human review. See [coverage and limits](docs/using-bcquality.md#coverage-and-limits) for the @@ -82,9 +83,11 @@ available domains and the difference between a folder review and a comparison. Mechanical issues already enforced by the AL compiler or standard analyzers are intentionally left to those deterministic tools rather than duplicated here. -Functional areas such as Finance, Supply Chain Management, Manufacturing, Jobs, -Warehousing, and Service, and technologies such as PowerShell, pipelines, and -Power Platform, remain valid future scope, **not current coverage claims**. +The [SCM domain](microsoft/knowledge/scm/) covers selected inventory, costing, +reservation, tracking, and warehouse/posting workflows, not exhaustive supply +chain validation. Broader functional coverage such as Finance, Manufacturing, +Jobs, and Service, and technologies such as PowerShell, pipelines, and Power +Platform, remain valid future scope, **not current coverage claims**. ## What's in this repo diff --git a/docs/using-bcquality.md b/docs/using-bcquality.md index e55751f..2af08be 100644 --- a/docs/using-bcquality.md +++ b/docs/using-bcquality.md @@ -85,6 +85,7 @@ branch names with ones in your project. | Uncommitted changes | Use the installed al-code-review skill to review my staged and unstaged tracked changes against HEAD, without changing files. Identify any untracked AL files not included in that diff. | | Branch changes | Use the installed al-code-review skill to review changes on this branch since its merge base with `origin/main`. Exclude uncommitted changes and do not edit files. | | Focused review | Use the installed al-code-review skill to review performance in the app in this folder, without changing files. Return the complete performance findings report. | +| Supply chain code | Use the installed al-code-review skill to review SCM posting, inventory, reservations, item tracking, and warehouse workflows in this app folder, without changing files. Return the complete Supply Chain Management findings report. | | Agent SDK code | Use the installed al-code-review skill to review Agent SDK implementation and usage in this app folder, without changing files. Return the complete Agents findings report. | For Git comparisons, the named base ref must exist locally. If it is missing, @@ -183,7 +184,7 @@ using your normal compilation, analyzer, test, and human-review workflow. ## Coverage and limits -The Microsoft broad review composes the 17 Microsoft domains listed below. +The Microsoft broad review composes the Microsoft domains listed below. The Community Agents review is a separate skill selected by the request, not a nested part of that coordinator. All current review leaves accept app folders, files, and diffs; request an Agent SDK review explicitly when that @@ -193,8 +194,22 @@ Available knowledge is **not** a promise that every rule will run. Selection depends on the task, target context, enabled layers, and source evidence. A whole-folder review is a current-state snapshot: detecting a published API removal or another comparison-only regression requires an actual baseline. -The corpus is technical AL guidance, not exhaustive functional validation or -AppSource certification. +The corpus combines technical AL guidance with targeted functional-domain +invariants, not exhaustive functional validation or AppSource certification. + +The SCM leaf owns selected inventory/value, application, reservation, tracking, +and warehouse/posting invariants. It prunes unrelated AL using the actual +tables, codeunits, fields, and operations in scope; an item caption or a broad +`ApplicationArea` alone is not an SCM review signal. Missing workflow context +must not be replaced with an assumed posting defect. Manufacturing, assembly, +planning, and other supply-chain areas are covered only where an article +explicitly names the shared interface or invariant. + +SCM owns Item/Value/Capacity/Warehouse and inventory-application posting +records. Pure G/L, customer/vendor/detailed/VAT and financial-only posting +mutations belong to Finance, even when that domain is not enabled. Equivalent +findings for one inventory-originated posting bypass have one SCM primary +owner; distinct independent financial defects remain separate. BCQuality intentionally does not duplicate mechanical diagnostics already enforced by the AL compiler or standard analyzers. Run the consuming app's @@ -222,6 +237,7 @@ Each article describes one concern. Where samples exist, use its linked | Reporting | [Reporting](../microsoft/knowledge/reporting/) | | Security | [Security](../microsoft/knowledge/security/) | | Style | [Style](../microsoft/knowledge/style/) | +| Supply Chain Management | [SCM](../microsoft/knowledge/scm/) | | Telemetry | [Telemetry](../microsoft/knowledge/telemetry/) | | Testing | [Testing](../microsoft/knowledge/testing/) | | User interface | [UI](../microsoft/knowledge/ui/) | diff --git a/evaluation/README.md b/evaluation/README.md index 2125ce3..05b5e52 100644 --- a/evaluation/README.md +++ b/evaluation/README.md @@ -6,6 +6,16 @@ The evaluation is convention-driven. The harness discovers every `/skills Model-facing preparation hashes case IDs, neutralizes `Good`/`Bad` object-name tokens, and removes full-line sample comments so neither the article slug, domain, nor expected outcome reveals the answer. +The SCM `articles` override deliberately selects every rule in the initial +functional domain, producing nine positive cases and nine clean controls. +Business context is executable: document/status `TestField` guards, +calculated-revaluation fields, source-transfer base quantities, warehouse +reconciliation steps, and additional-demand promising parameters survive +neutralization. Do not move those preconditions into comments or generic +"posting" helper names; removing them can turn a real defect into a valid +alternative workflow. The clean pairs exercise the supported APIs selected by +the same routing cues, not merely unrelated code that contains no SCM tokens. + ## Validate the corpus ```powershell diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index e52a653..2d03940 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -51,6 +51,19 @@ "stop-when-runrequestpage-returns-empty-parameters" ] }, + "scm": { + "articles": [ + "post-item-ledger-changes-through-item-journals", + "post-revaluation-through-the-item-journal-batch", + "change-item-applications-through-posting-routines", + "cancel-reservations-through-reservation-management", + "transfer-item-tracking-through-source-reservation-codeunits", + "reconcile-warehouse-adjustments-with-the-item-ledger", + "post-transfers-through-shipment-and-receipt-codeunits", + "use-date-aware-availability-for-promising", + "carry-out-requisition-actions-through-the-standard-workflow" + ] + }, "style": { "articles": [ "label-comment-explains-placeholders", diff --git a/microsoft/knowledge/scm/cancel-reservations-through-reservation-management.bad.al b/microsoft/knowledge/scm/cancel-reservations-through-reservation-management.bad.al new file mode 100644 index 0000000..248f3a4 --- /dev/null +++ b/microsoft/knowledge/scm/cancel-reservations-through-reservation-management.bad.al @@ -0,0 +1,13 @@ +codeunit 50106 "SCM Cancel Reservation Bad" +{ + procedure CancelSalesReservation(ReservationEntryNo: Integer) + var + ReservationEntry: Record "Reservation Entry"; + begin + ReservationEntry.Get(ReservationEntryNo, false); + ReservationEntry.TestField("Source Type", Database::"Sales Line"); + ReservationEntry.TestField("Reservation Status", ReservationEntry."Reservation Status"::Reservation); + + ReservationEntry.Delete(true); + end; +} diff --git a/microsoft/knowledge/scm/cancel-reservations-through-reservation-management.good.al b/microsoft/knowledge/scm/cancel-reservations-through-reservation-management.good.al new file mode 100644 index 0000000..3d5849d --- /dev/null +++ b/microsoft/knowledge/scm/cancel-reservations-through-reservation-management.good.al @@ -0,0 +1,14 @@ +codeunit 50107 "SCM Cancel Reservation Good" +{ + procedure CancelSalesReservation(ReservationEntryNo: Integer) + var + ReservationEntry: Record "Reservation Entry"; + ReservationEngineMgt: Codeunit "Reservation Engine Mgt."; + begin + ReservationEntry.Get(ReservationEntryNo, false); + ReservationEntry.TestField("Source Type", Database::"Sales Line"); + ReservationEntry.TestField("Reservation Status", ReservationEntry."Reservation Status"::Reservation); + + ReservationEngineMgt.CancelReservation(ReservationEntry); + end; +} diff --git a/microsoft/knowledge/scm/cancel-reservations-through-reservation-management.md b/microsoft/knowledge/scm/cancel-reservations-through-reservation-management.md new file mode 100644 index 0000000..1df3b12 --- /dev/null +++ b/microsoft/knowledge/scm/cancel-reservations-through-reservation-management.md @@ -0,0 +1,38 @@ +--- +bc-version: [all] +domain: scm +keywords: [reservation-entry, cancelreservation, reservation-engine-mgt, reservation-status, order-tracking, disallow-cancellation] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Cancel reservations through reservation management + +## Description + +Persistent `"Reservation Entry"` rows are not disposable allocation markers. Reservation and Tracking links use an entry-number pair with opposite `Positive` values, while Surplus and Prospect entries can legitimately be unpaired. Cancelling a binding reservation must handle its counterpart and any remaining item tracking or order tracking, not just remove a row. + +## Best Practice + +Explicit cancellation of an existing binding reservation uses `"Reservation Engine Mgt.".CancelReservation`. It checks the reservation status and `"Disallow Cancellation"`, handles the counterpart, and preserves or retracks the remaining source quantities as appropriate. Source-line quantity changes have their own source-specific reservation management path. + +Not every Reservation Entry has a partner or identical lot/serial values on both sides: Surplus/Prospect entries and supported late-binding scenarios have different relationships. Temporary buffers, engine-owned updates, and supported publisher metadata are not independent cancellation. Cancelling a reservation is also different from intentionally removing an item-tracking assignment. + +The samples retrieve the negative side of a persistent sales-line reservation and cancel only the binding. They do not delete the sales line or remove its tracking specifications. + +See sample: [`cancel-reservations-through-reservation-management.good.al`](cancel-reservations-through-reservation-management.good.al). + +## Anti Pattern + +`Delete(true)`, `DeleteAll`, or a status/source rewrite on persistent `"Reservation Entry"` records does not perform binding-reservation cancellation. Even deleting both sides can discard tracking that should survive and omit retracking. + +Normal processing of temporary Prospect/Surplus buffers is outside that cancellation workflow, and an unpaired row is not intrinsically an orphan. + +See sample: [`cancel-reservations-through-reservation-management.bad.al`](cancel-reservations-through-reservation-management.bad.al). + +## References + +- [Reservation, order tracking, and action messaging](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-reservation-order-tracking-and-action-messaging) +- [Item tracking and reservations](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-item-tracking-and-reservations) +- [BaseApp reservation cancellation](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Tracking/ReservationEngineMgt.Codeunit.al#L51-L90) diff --git a/microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.bad.al b/microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.bad.al new file mode 100644 index 0000000..7bc4df8 --- /dev/null +++ b/microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.bad.al @@ -0,0 +1,47 @@ +codeunit 50116 "SCM Requisition Action Bad" +{ + procedure CarryOutAcceptedNewPurchase(TemplateName: Code[10]; BatchName: Code[10]; LineNo: Integer; OrderDate: Date; PostingDate: Date; ReceiptDate: Date; CutoffDate: Date) + var + RequisitionLine: Record "Requisition Line"; + PurchaseHeader: Record "Purchase Header"; + PurchaseLine: Record "Purchase Line"; + begin + if (OrderDate = 0D) or (PostingDate = 0D) or (ReceiptDate = 0D) or (CutoffDate = 0D) then + Error(PlanningDatesErr); + RequisitionLine.Get(TemplateName, BatchName, LineNo); + RequisitionLine.TestField(Type, RequisitionLine.Type::Item); + RequisitionLine.TestField("Replenishment System", RequisitionLine."Replenishment System"::Purchase); + RequisitionLine.TestField("Action Message", RequisitionLine."Action Message"::New); + RequisitionLine.TestField("Accept Action Message", true); + RequisitionLine.TestField("Demand Type", Database::"Sales Line"); + RequisitionLine.TestField("Demand Order No."); + RequisitionLine.TestField("Vendor No."); + RequisitionLine.SetRecFilter(); + + PurchaseHeader.Init(); + PurchaseHeader."Document Type" := PurchaseHeader."Document Type"::Order; + PurchaseHeader.Insert(true); + PurchaseHeader.Validate("Buy-from Vendor No.", RequisitionLine."Vendor No."); + PurchaseHeader.Validate("Order Date", OrderDate); + PurchaseHeader.Validate("Posting Date", PostingDate); + PurchaseHeader.Validate("Expected Receipt Date", ReceiptDate); + PurchaseHeader.Modify(true); + + PurchaseLine.Init(); + PurchaseLine."Document Type" := PurchaseHeader."Document Type"; + PurchaseLine."Document No." := PurchaseHeader."No."; + PurchaseLine."Line No." := 10000; + PurchaseLine.Validate(Type, PurchaseLine.Type::Item); + PurchaseLine.Validate("No.", RequisitionLine."No."); + PurchaseLine.Validate("Location Code", RequisitionLine."Location Code"); + PurchaseLine.Validate("Variant Code", RequisitionLine."Variant Code"); + PurchaseLine.Validate("Unit of Measure Code", RequisitionLine."Unit of Measure Code"); + PurchaseLine.Validate(Quantity, RequisitionLine.Quantity); + PurchaseLine.Insert(true); + + RequisitionLine.Delete(true); + end; + + var + PlanningDatesErr: Label 'Supply explicit order, posting, receipt, and cutoff dates.'; +} diff --git a/microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.good.al b/microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.good.al new file mode 100644 index 0000000..c09ea65 --- /dev/null +++ b/microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.good.al @@ -0,0 +1,31 @@ +codeunit 50117 "SCM Requisition Action Good" +{ + procedure CarryOutAcceptedNewPurchase(TemplateName: Code[10]; BatchName: Code[10]; LineNo: Integer; OrderDate: Date; PostingDate: Date; ReceiptDate: Date; CutoffDate: Date) + var + RequisitionLine: Record "Requisition Line"; + PurchaseHeaderDefaults: Record "Purchase Header"; + ReqWkshMakeOrder: Codeunit "Req. Wksh.-Make Order"; + begin + if (OrderDate = 0D) or (PostingDate = 0D) or (ReceiptDate = 0D) or (CutoffDate = 0D) then + Error(PlanningDatesErr); + RequisitionLine.Get(TemplateName, BatchName, LineNo); + RequisitionLine.TestField(Type, RequisitionLine.Type::Item); + RequisitionLine.TestField("Replenishment System", RequisitionLine."Replenishment System"::Purchase); + RequisitionLine.TestField("Action Message", RequisitionLine."Action Message"::New); + RequisitionLine.TestField("Accept Action Message", true); + RequisitionLine.TestField("Demand Type", Database::"Sales Line"); + RequisitionLine.TestField("Demand Order No."); + RequisitionLine.TestField("Vendor No."); + RequisitionLine.SetRecFilter(); + + PurchaseHeaderDefaults."Order Date" := OrderDate; + PurchaseHeaderDefaults."Posting Date" := PostingDate; + PurchaseHeaderDefaults."Expected Receipt Date" := ReceiptDate; + ReqWkshMakeOrder.Set(PurchaseHeaderDefaults, CutoffDate, false); + ReqWkshMakeOrder.SetSuppressCommit(true); + ReqWkshMakeOrder.CarryOutBatchAction(RequisitionLine); + end; + + var + PlanningDatesErr: Label 'Supply explicit order, posting, receipt, and cutoff dates.'; +} diff --git a/microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.md b/microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.md new file mode 100644 index 0000000..88f68bd --- /dev/null +++ b/microsoft/knowledge/scm/carry-out-requisition-actions-through-the-standard-workflow.md @@ -0,0 +1,43 @@ +--- +bc-version: [all] +domain: scm +keywords: [requisition-line, action-message, accept-action-message, req-wksh-make-order, carryoutbatchaction, demand-order-no, planning-flexibility] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Carry out requisition actions through the standard workflow + +## Description + +A requisition/planning line is a pending change to a supply/demand network, not just a template for a purchase line. Carry-out interprets New, change-quantity, reschedule, and cancel actions, preserves referenced supply and planning flexibility, and moves reservation/tracking ownership before finalizing the proposal. Creating a plausible purchase order and deleting the requisition line can leave new supply unrelated to the demand that caused it. + +## Best Practice + +Requisition batch carry-out initializes `"Req. Wksh.-Make Order"` with `Set` and invokes `CarryOutBatchAction` on the intended accepted lines. Order/posting/receipt defaults are separate from the ending-order-date cutoff, and worksheet/batch/line filters define the selection. A plain `Run` or a single order-line insertion helper is not a replacement for this batch initialization and finalization. + +The standard `"Carry Out Action"` dispatch handles broader planning output and its configured purchase, transfer, assembly, or manufacturing choices. Each action's supply change and source-specific reservation transfer precede proposal finalization; not every action creates a new purchase order. + +Ordinary manual purchase creation that does not consume planning output is outside this rule. Users may reject or delete unwanted proposals without creating supply; temporary planning simulations, pre-carry-out enrichment, and engine-owned cleanup are also legitimate. `Delete(true)` on a requisition line is not intrinsically a defect. + +The samples select an existing accepted New/Purchase item proposal with sales-demand context. Dates are explicit, the source selection remains bounded, and the clean sample leaves order creation and reservation handoff to the standard workflow; it is not a complete planning-run generator. + +See sample: [`carry-out-requisition-actions-through-the-standard-workflow.good.al`](carry-out-requisition-actions-through-the-standard-workflow.good.al). + +## Anti Pattern + +Manually creating or changing supply from a subset of an accepted persistent `"Requisition Line"`, then deleting or marking that proposal handled, skips the standard carry-out/source-reservation handoff. Purchase-field validation and the requisition delete trigger do not first move the proposal's demand links to the new purchase line. + +Deleting an unwanted suggestion or creating an ordinary purchase order without consuming planning output is a separate operation. The standard carry-out engine's own insert/delete sequence participates in the source handoff rather than replacing it. + +See sample: [`carry-out-requisition-actions-through-the-standard-workflow.bad.al`](carry-out-requisition-actions-through-the-standard-workflow.bad.al). + +## References + +- [Perform planning action messages](https://learn.microsoft.com/en-us/dynamics365/business-central/production-how-to-run-mps-and-mrp#to-perform-action-messages) +- [Planning functionality](https://learn.microsoft.com/en-us/dynamics365/business-central/production-about-planning-functionality) +- [Reservation, order tracking, and action messaging](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-reservation-order-tracking-and-action-messaging) +- [BaseApp carry-out caller and date defaults](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Requisition/CarryOutActionMsgReq.Report.al#L116-L133) +- [Batch initialization and selection](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Requisition/ReqWkshMakeOrder.Codeunit.al#L116-L215) +- [Reservation handoff before supply finalization](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Requisition/ReqWkshMakeOrder.Codeunit.al#L663-L743) diff --git a/microsoft/knowledge/scm/change-item-applications-through-posting-routines.bad.al b/microsoft/knowledge/scm/change-item-applications-through-posting-routines.bad.al new file mode 100644 index 0000000..f0239db --- /dev/null +++ b/microsoft/knowledge/scm/change-item-applications-through-posting-routines.bad.al @@ -0,0 +1,33 @@ +codeunit 50104 "SCM Item Application Bad" +{ + procedure ChangeSalesQuantityApplication(ApplicationEntryNo: Integer; NewInboundEntryNo: Integer) + var + ItemApplicationEntry: Record "Item Application Entry"; + OutboundItemLedgerEntry: Record "Item Ledger Entry"; + InboundItemLedgerEntry: Record "Item Ledger Entry"; + begin + ItemApplicationEntry.Get(ApplicationEntryNo); + ItemApplicationEntry.TestField(Quantity); + ItemApplicationEntry.TestField("Inbound Item Entry No."); + ItemApplicationEntry.TestField("Outbound Item Entry No."); + ItemApplicationEntry.TestField("Transferred-from Entry No.", 0); + if ItemApplicationEntry.CostApplication() then + Error(QuantityApplicationErr); + OutboundItemLedgerEntry.Get(ItemApplicationEntry."Outbound Item Entry No."); + OutboundItemLedgerEntry.TestField("Entry Type", OutboundItemLedgerEntry."Entry Type"::Sale); + OutboundItemLedgerEntry.TestField(Positive, false); + OutboundItemLedgerEntry.TestField("Drop Shipment", false); + OutboundItemLedgerEntry.TestField(Correction, false); + InboundItemLedgerEntry.Get(NewInboundEntryNo); + InboundItemLedgerEntry.TestField(Positive, true); + InboundItemLedgerEntry.TestField("Item No.", OutboundItemLedgerEntry."Item No."); + InboundItemLedgerEntry.TestField("Variant Code", OutboundItemLedgerEntry."Variant Code"); + InboundItemLedgerEntry.TestField("Location Code", OutboundItemLedgerEntry."Location Code"); + + ItemApplicationEntry."Inbound Item Entry No." := NewInboundEntryNo; + ItemApplicationEntry.Modify(true); + end; + + var + QuantityApplicationErr: Label 'Select an ordinary quantity application, not a cost application.'; +} diff --git a/microsoft/knowledge/scm/change-item-applications-through-posting-routines.good.al b/microsoft/knowledge/scm/change-item-applications-through-posting-routines.good.al new file mode 100644 index 0000000..e176aad --- /dev/null +++ b/microsoft/knowledge/scm/change-item-applications-through-posting-routines.good.al @@ -0,0 +1,40 @@ +codeunit 50105 "SCM Item Application Good" +{ + procedure ChangeSalesQuantityApplication(ApplicationEntryNo: Integer; NewInboundEntryNo: Integer) + var + ItemApplicationEntry: Record "Item Application Entry"; + OutboundItemLedgerEntry: Record "Item Ledger Entry"; + InboundItemLedgerEntry: Record "Item Ledger Entry"; + ItemJnlPostLine: Codeunit "Item Jnl.-Post Line"; + OutboundEntryNo: Integer; + begin + ItemApplicationEntry.Get(ApplicationEntryNo); + ItemApplicationEntry.TestField(Quantity); + ItemApplicationEntry.TestField("Inbound Item Entry No."); + ItemApplicationEntry.TestField("Outbound Item Entry No."); + ItemApplicationEntry.TestField("Transferred-from Entry No.", 0); + if ItemApplicationEntry.CostApplication() then + Error(QuantityApplicationErr); + OutboundEntryNo := ItemApplicationEntry."Outbound Item Entry No."; + OutboundItemLedgerEntry.Get(OutboundEntryNo); + OutboundItemLedgerEntry.TestField("Entry Type", OutboundItemLedgerEntry."Entry Type"::Sale); + OutboundItemLedgerEntry.TestField(Positive, false); + OutboundItemLedgerEntry.TestField("Drop Shipment", false); + OutboundItemLedgerEntry.TestField(Correction, false); + InboundItemLedgerEntry.Get(NewInboundEntryNo); + InboundItemLedgerEntry.TestField(Positive, true); + InboundItemLedgerEntry.TestField("Item No.", OutboundItemLedgerEntry."Item No."); + InboundItemLedgerEntry.TestField("Variant Code", OutboundItemLedgerEntry."Variant Code"); + InboundItemLedgerEntry.TestField("Location Code", OutboundItemLedgerEntry."Location Code"); + + ItemJnlPostLine.UnApply(ItemApplicationEntry); + OutboundItemLedgerEntry.Get(OutboundEntryNo); + ItemJnlPostLine.ReApply(OutboundItemLedgerEntry, NewInboundEntryNo); + ItemJnlPostLine.RedoApplications(); + ItemJnlPostLine.CostAdjust(); + ItemJnlPostLine.ClearApplicationLog(); + end; + + var + QuantityApplicationErr: Label 'Select an ordinary quantity application, not a cost application.'; +} diff --git a/microsoft/knowledge/scm/change-item-applications-through-posting-routines.md b/microsoft/knowledge/scm/change-item-applications-through-posting-routines.md new file mode 100644 index 0000000..5b5443e --- /dev/null +++ b/microsoft/knowledge/scm/change-item-applications-through-posting-routines.md @@ -0,0 +1,39 @@ +--- +bc-version: [all] +domain: scm +keywords: [item-application-entry, inbound-item-entry-no, unapply, reapply, redoapplications, costadjust, application-worksheet] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Change item applications through posting routines + +## Description + +An `"Item Application Entry"` connects quantity application to cost flow; changing its inbound entry number is not merely fixing a foreign key. Unapplication/reapplication also affects ledger remaining quantities, open states, valuation, and entries needing cost adjustment. Direct edits can leave a plausible application row attached to inconsistent inventory and costs. + +## Best Practice + +The Application Worksheet provides the interactive correction workflow. A narrowly controlled programmatic correction of an ordinary quantity application uses the same `"Item Jnl.-Post Line"` instance for `UnApply`, a reload of the affected outbound item entry, and `ReApply` to the compatible inbound entry. Its finalization lifecycle includes `RedoApplications`, `CostAdjust`, and `ClearApplicationLog`. + +The posting routines enforce inventory-period, correction, transfer, and drop-shipment restrictions. Entries with `"Transferred-from Entry No."`, outbound transfers, and special application types are outside the ordinary-sales sample's scope. Application-check bypasses remove those protections, and the worksheet's multi-step recovery flags belong to its UI lifecycle rather than a standalone transaction. + +`CostAdjust` honors automatic-cost-adjustment setup; calling it does not mean all costs are settled when adjustment is disabled or deferred. Scheduled/manual adjustment remains necessary in those configurations. Temporary application projections, extension metadata, and source-document reservation/order-tracking changes are not edits to the persistent item-application graph. + +See sample: [`change-item-applications-through-posting-routines.good.al`](change-item-applications-through-posting-routines.good.al). + +## Anti Pattern + +Independent `Modify`, `Delete`, or replacement `Insert` operations on persistent `"Item Application Entry"` rows can repoint a receipt/shipment application without updating remaining quantities or cost propagation. Valid item numbers, matching quantities, and running table triggers do not complete reapplication. + +Omitting finalization or committing between unapply and reapply exposes an incomplete replacement. The standard posting/application workflow's internal table writes differ because they participate in that lifecycle. + +See sample: [`change-item-applications-through-posting-routines.bad.al`](change-item-applications-through-posting-routines.bad.al). + +## References + +- [Item application design](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-item-application) +- [Cost adjustment design](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-cost-adjustment) +- [BaseApp application finalization sequence](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Ledger/ApplicationWorksheet.Page.al#L495-L503) +- [BaseApp reapplication and cost-adjustment lifecycle](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Posting/ItemJnlPostLine.Codeunit.al#L5464-L5538) diff --git a/microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.bad.al b/microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.bad.al new file mode 100644 index 0000000..1187f96 --- /dev/null +++ b/microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.bad.al @@ -0,0 +1,32 @@ +codeunit 50100 "SCM Stock Adjustment Bad" +{ + procedure PostPreparedPositiveAdjustment(ItemJournalLine: Record "Item Journal Line"; NewEntryNo: Integer) + var + ItemLedgerEntry: Record "Item Ledger Entry"; + begin + ItemJournalLine.TestField("Entry Type", ItemJournalLine."Entry Type"::"Positive Adjmt."); + ItemJournalLine.TestField("Value Entry Type", ItemJournalLine."Value Entry Type"::"Direct Cost"); + ItemJournalLine.TestField("Item No."); + ItemJournalLine.TestField("Posting Date"); + ItemJournalLine.TestField("Quantity (Base)"); + if ItemJournalLine."Quantity (Base)" < 0 then + Error(PositiveQuantityErr); + + ItemLedgerEntry.Init(); + ItemLedgerEntry."Entry No." := NewEntryNo; + ItemLedgerEntry."Item No." := ItemJournalLine."Item No."; + ItemLedgerEntry."Entry Type" := ItemJournalLine."Entry Type"; + ItemLedgerEntry."Posting Date" := ItemJournalLine."Posting Date"; + ItemLedgerEntry."Document No." := ItemJournalLine."Document No."; + ItemLedgerEntry."Location Code" := ItemJournalLine."Location Code"; + ItemLedgerEntry."Variant Code" := ItemJournalLine."Variant Code"; + ItemLedgerEntry.Quantity := ItemJournalLine."Quantity (Base)"; + ItemLedgerEntry."Remaining Quantity" := ItemLedgerEntry.Quantity; + ItemLedgerEntry.Positive := true; + ItemLedgerEntry.Open := true; + ItemLedgerEntry.Insert(true); + end; + + var + PositiveQuantityErr: Label 'The prepared adjustment must increase inventory.'; +} diff --git a/microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.good.al b/microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.good.al new file mode 100644 index 0000000..3e7866a --- /dev/null +++ b/microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.good.al @@ -0,0 +1,20 @@ +codeunit 50101 "SCM Stock Adjustment Good" +{ + procedure PostPreparedPositiveAdjustment(var ItemJournalLine: Record "Item Journal Line") + var + ItemJnlPostLine: Codeunit "Item Jnl.-Post Line"; + begin + ItemJournalLine.TestField("Entry Type", ItemJournalLine."Entry Type"::"Positive Adjmt."); + ItemJournalLine.TestField("Value Entry Type", ItemJournalLine."Value Entry Type"::"Direct Cost"); + ItemJournalLine.TestField("Item No."); + ItemJournalLine.TestField("Posting Date"); + ItemJournalLine.TestField("Quantity (Base)"); + if ItemJournalLine."Quantity (Base)" < 0 then + Error(PositiveQuantityErr); + + ItemJnlPostLine.RunWithCheck(ItemJournalLine); + end; + + var + PositiveQuantityErr: Label 'The prepared adjustment must increase inventory.'; +} diff --git a/microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.md b/microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.md new file mode 100644 index 0000000..0df6dac --- /dev/null +++ b/microsoft/knowledge/scm/post-item-ledger-changes-through-item-journals.md @@ -0,0 +1,42 @@ +--- +bc-version: [all] +domain: scm +keywords: [item-ledger-entry, value-entry, item-journal-line, item-jnl-post-line, runwithcheck, inventory-posting] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Post item ledger changes through item journals + +## Description + +An item ledger entry is not an independently insertable stock balance. Posting connects its quantity to item applications, reservations, tracking, and one or more value entries; expected cost, invoicing, revaluation, and later cost adjustment can produce different value entries for the same item entry. Running a table's insert trigger does not run this posting workflow or its configured inventory-to-G/L integration. + +## Best Practice + +The posting entry point for a prepared standalone item-journal movement is `"Item Jnl.-Post Line".RunWithCheck`. Persisted journal batches use `"Item Jnl.-Post Batch"`; sales, purchase, transfer, assembly, and production transactions retain their owning document/posting orchestration. Those workflows create the ledger, value, and application records together with their required checks. + +Supported posting events enrich validated journal/source data within the owning workflow. Read-only ledger queries, temporary ledger previews, extension-owned metadata fields, and publisher parameters consumed by the poster are not independent ledger posting. A temporary item-journal buffer can still produce persistent entries when passed to a posting codeunit. A publisher's `var` parameter or `IsHandled` flag alone does not supply the missing quantity/cost coordination; the normal engine's own inserts operate within that coordination. + +Not every value entry points to an item ledger entry: capacity and production WIP have their own supported posting relationships. Assembly and manufacturing posting retain order/component/routing and capacity context; one bare output/consumption call is not full order completion. + +The clean sample takes an already prepared positive-adjustment journal line. It is not a substitute for journal preparation, batch revaluation, warehouse reconciliation, or source-document posting. + +See sample: [`post-item-ledger-changes-through-item-journals.good.al`](post-item-ledger-changes-through-item-journals.good.al). + +## Anti Pattern + +Independent inserts/deletes of persistent `"Item Ledger Entry"` or `"Value Entry"` transaction rows, or overwrites of posted quantity, remaining quantity, application identity, or cost amounts, bypass the coordinated receipt, shipment, adjustment, or cost-correction workflow. `Insert(true)`, `Modify(true)`, and balanced-looking quantities do not supply that orchestration: stock can change without the corresponding application/value graph, or downstream cost flow can remain stale. + +A table declaration or custom annotation-field update does not change inventory quantities or costs and is outside this transaction-state concern. + +See sample: [`post-item-ledger-changes-through-item-journals.bad.al`](post-item-ledger-changes-through-item-journals.bad.al). + +## References + +- [Inventory posting design](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-inventory-posting) +- [Item application design](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-item-application) +- [BaseApp item-journal posting entry point](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Posting/ItemJnlPostLine.Codeunit.al#L162-L179) +- [Assembly-order posting context](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-assembly-order-posting) +- [Production-order posting context](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-production-order-posting) diff --git a/microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.bad.al b/microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.bad.al new file mode 100644 index 0000000..df450cc --- /dev/null +++ b/microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.bad.al @@ -0,0 +1,17 @@ +codeunit 50102 "SCM Revaluation Batch Bad" +{ + procedure PostCalculatedRevaluationBatch(TemplateName: Code[10]; BatchName: Code[10]) + var + ItemJournalLine: Record "Item Journal Line"; + ItemJnlPostLine: Codeunit "Item Jnl.-Post Line"; + begin + ItemJournalLine.SetRange("Journal Template Name", TemplateName); + ItemJournalLine.SetRange("Journal Batch Name", BatchName); + ItemJournalLine.FindSet(); + repeat + ItemJournalLine.TestField("Value Entry Type", ItemJournalLine."Value Entry Type"::Revaluation); + ItemJournalLine.TestField("Inventory Value Per"); + ItemJnlPostLine.RunWithCheck(ItemJournalLine); + until ItemJournalLine.Next() = 0; + end; +} diff --git a/microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.good.al b/microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.good.al new file mode 100644 index 0000000..810fad5 --- /dev/null +++ b/microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.good.al @@ -0,0 +1,16 @@ +codeunit 50103 "SCM Revaluation Batch Good" +{ + procedure PostCalculatedRevaluationBatch(TemplateName: Code[10]; BatchName: Code[10]) + var + ItemJournalLine: Record "Item Journal Line"; + ItemJnlPostBatch: Codeunit "Item Jnl.-Post Batch"; + begin + ItemJournalLine.SetRange("Journal Template Name", TemplateName); + ItemJournalLine.SetRange("Journal Batch Name", BatchName); + ItemJournalLine.FindFirst(); + ItemJournalLine.TestField("Value Entry Type", ItemJournalLine."Value Entry Type"::Revaluation); + ItemJournalLine.TestField("Inventory Value Per"); + + ItemJnlPostBatch.Run(ItemJournalLine); + end; +} diff --git a/microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.md b/microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.md new file mode 100644 index 0000000..9730c2d --- /dev/null +++ b/microsoft/knowledge/scm/post-revaluation-through-the-item-journal-batch.md @@ -0,0 +1,38 @@ +--- +bc-version: [all] +domain: scm +keywords: [revaluation, inventory-value-per, partial-revaluation, item-jnl-post-batch, item-journal-line, runwithcheck, standard-cost] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Post calculated revaluation through the item journal batch + +## Description + +A calculated revaluation line with nonblank `"Inventory Value Per"` represents an aggregate, not a finalized posting against one item ledger entry. Codeunit `"Item Jnl.-Post Batch"` distributes that value over eligible entries, handles rounding, and coordinates Item/SKU standard-cost updates. Calling the line poster directly skips that batch work even though the input is a valid `"Item Journal Line"`. + +## Best Practice + +Posting a prepared revaluation batch through `"Item Jnl.-Post Batch"` preserves the calculated line's valuation date, aggregation scope, location/variant filters, and revaluation fields. The batch expands summarized values into per-entry postings and checks that the eligible inventory has not changed; for partial revaluation it also rechecks remaining quantity before posting. + +The public `"Item Jnl.-Post Line".RunWithCheck` API does not replace that orchestration. It remains legitimate for finalized individual-entry revaluation lines within a workflow that already supplies the necessary checks; the batch itself uses the line poster. Ordinary quantity journals and finalized per-entry revaluations are distinct from this summarized/partial-revaluation case. + +The samples explicitly require `"Value Entry Type" = Revaluation` and a nonblank `"Inventory Value Per"` in an existing calculated journal batch. They demonstrate posting, not how to calculate a new valuation or choose a standard cost. + +See sample: [`post-revaluation-through-the-item-journal-batch.good.al`](post-revaluation-through-the-item-journal-batch.good.al). + +## Anti Pattern + +A loop that sends calculated aggregate revaluation lines straight to `"Item Jnl.-Post Line"` skips distribution over the underlying item entries. A partial-revaluation workflow without the remaining-quantity recheck can post a valuation against inventory that no longer matches the calculation. + +Directly editing existing `"Value Entry"` cost amounts or the Item's unit cost does not repair those allocation and adjustment relationships. Their correction belongs to the revaluation/cost-adjustment workflow. + +See sample: [`post-revaluation-through-the-item-journal-batch.bad.al`](post-revaluation-through-the-item-journal-batch.bad.al). + +## References + +- [Revaluation design](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-revaluation) +- [Inventory posting design](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-inventory-posting) +- [BaseApp summarized revaluation and remaining-quantity checks](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Posting/ItemJnlPostBatch.Codeunit.al#L510-L714) diff --git a/microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.bad.al b/microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.bad.al new file mode 100644 index 0000000..2e14920 --- /dev/null +++ b/microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.bad.al @@ -0,0 +1,22 @@ +codeunit 50112 "SCM Transfer Posting Bad" +{ + procedure ShipTransferOrder(TransferOrderNo: Code[20]; var ItemJournalLine: Record "Item Journal Line") + var + TransferHeader: Record "Transfer Header"; + Location: Record Location; + ItemJnlPostLine: Codeunit "Item Jnl.-Post Line"; + begin + TransferHeader.Get(TransferOrderNo); + TransferHeader.TestField("Direct Transfer", false); + TransferHeader.TestField("In-Transit Code"); + Location.Get(TransferHeader."Transfer-from Code"); + Location.TestField("Require Shipment", false); + ItemJournalLine.TestField("Entry Type", ItemJournalLine."Entry Type"::Transfer); + ItemJournalLine.TestField("Location Code", TransferHeader."Transfer-from Code"); + ItemJournalLine.TestField("New Location Code", TransferHeader."In-Transit Code"); + + ItemJnlPostLine.RunWithCheck(ItemJournalLine); + TransferHeader."Last Shipment No." := ItemJournalLine."Document No."; + TransferHeader.Modify(true); + end; +} diff --git a/microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.good.al b/microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.good.al new file mode 100644 index 0000000..8507c99 --- /dev/null +++ b/microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.good.al @@ -0,0 +1,32 @@ +codeunit 50113 "SCM Transfer Posting Good" +{ + procedure ShipTransferOrder(TransferOrderNo: Code[20]) + var + TransferHeader: Record "Transfer Header"; + Location: Record Location; + TransferOrderPostShipment: Codeunit "TransferOrder-Post Shipment"; + begin + TransferHeader.Get(TransferOrderNo); + TransferHeader.TestField("Direct Transfer", false); + TransferHeader.TestField("In-Transit Code"); + Location.Get(TransferHeader."Transfer-from Code"); + Location.TestField("Require Shipment", false); + + TransferOrderPostShipment.Run(TransferHeader); + end; + + procedure ReceiveTransferOrder(TransferOrderNo: Code[20]) + var + TransferHeader: Record "Transfer Header"; + Location: Record Location; + TransferOrderPostReceipt: Codeunit "TransferOrder-Post Receipt"; + begin + TransferHeader.Get(TransferOrderNo); + TransferHeader.TestField("Direct Transfer", false); + TransferHeader.TestField("In-Transit Code"); + Location.Get(TransferHeader."Transfer-to Code"); + Location.TestField("Require Receive", false); + + TransferOrderPostReceipt.Run(TransferHeader); + end; +} diff --git a/microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.md b/microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.md new file mode 100644 index 0000000..b541dba --- /dev/null +++ b/microsoft/knowledge/scm/post-transfers-through-shipment-and-receipt-codeunits.md @@ -0,0 +1,41 @@ +--- +bc-version: [all] +domain: scm +keywords: [transfer-header, transfer-line, transferorder-post-shipment, transferorder-post-receipt, in-transit-code, last-shipment-no, item-application-entry] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Post transfers through shipment and receipt codeunits + +## Description + +A two-step transfer order preserves a continuous quantity, reservation, and cost/application lineage from the source through in-transit to the destination. Its shipment and receipt workflows also own posted documents and derived lines for partial receipt. Posting an item-journal movement and manually marking a transfer header or line as shipped is not equivalent, even if the total quantities balance. + +## Best Practice + +A prepared non-direct transfer order without required warehouse documents uses `"TransferOrder-Post Shipment".Run` at shipment and `"TransferOrder-Post Receipt".Run` at receipt, with the actual `"Transfer Header"`. Validated source quantities to ship/receive prepare the operation; posted quantity counters are results of posting. + +Required warehouse shipment or receipt enters the warehouse document posting workflow, which invokes the transfer poster with its real source context. Direct transfers have their configured standard workflow; the two-step sample's in-transit guard is not a universal requirement. + +Standalone item reclassification journals and bin movements are legitimate separate operations, not completion of an existing transfer order. Tracking/application splits and average-cost handling mean transfers do not have one fixed item-entry count or a nonzero `"Transferred-from Entry No."` on every application. + +See sample: [`post-transfers-through-shipment-and-receipt-codeunits.good.al`](post-transfers-through-shipment-and-receipt-codeunits.good.al). + +## Anti Pattern + +Ad-hoc item postings, independent positive/negative adjustments, manually created posted-transfer rows, and direct shipment/receipt-counter changes cannot substitute for transfer-order posting. Updating `"Last Shipment No."` after a bare item-journal call does not create the posted shipment, source-line progress, or transfer application lineage. + +Changing an existing item ledger entry's location or inventing application links does not repair that missing workflow. Metadata enrichment within the normal shipment/receipt or direct-transfer workflow is distinct from replacing the posting operation. + +See sample: [`post-transfers-through-shipment-and-receipt-codeunits.bad.al`](post-transfers-through-shipment-and-receipt-codeunits.bad.al). + +## References + +- [Transfer inventory between locations](https://learn.microsoft.com/en-us/dynamics365/business-central/inventory-how-transfer-between-locations) +- [Item application design](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-item-application) +- [Cost adjustment design](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-cost-adjustment) +- [BaseApp shipment journal/source linkage](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Transfer/TransferOrderPostShipment.Codeunit.al#L292-L336) +- [Partial-receipt derived-line handling](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Transfer/TransferOrderPostReceipt.Codeunit.al#L457-L529) +- [Transfer application and average-cost branches](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Posting/ItemJnlPostLine.Codeunit.al#L1911-L1976) diff --git a/microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.bad.al b/microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.bad.al new file mode 100644 index 0000000..97c7cb4 --- /dev/null +++ b/microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.bad.al @@ -0,0 +1,37 @@ +codeunit 50110 "SCM Warehouse Adjustment Bad" +{ + procedure ReconcileRegisteredWarehouseAdjustment(ItemNo: Code[20]; LocationCode: Code[10]; TemplateName: Code[10]; BatchName: Code[10]; PostingDate: Date; DocumentNo: Code[20]): Boolean + var + Item: Record Item; + ItemJournalBatch: Record "Item Journal Batch"; + ItemJournalLine: Record "Item Journal Line"; + Location: Record Location; + CalculateWhseAdjustment: Report "Calculate Whse. Adjustment"; + begin + Location.Get(LocationCode); + Location.TestField("Directed Put-away and Pick", true); + Location.TestField("Adjustment Bin Code"); + ItemJournalBatch.Get(TemplateName, BatchName); + ItemJournalLine.SetRange("Journal Template Name", TemplateName); + ItemJournalLine.SetRange("Journal Batch Name", BatchName); + if not ItemJournalLine.IsEmpty() then + Error(EmptyBatchErr); + + Item.Get(ItemNo); + Item.SetRecFilter(); + Item.SetRange("Location Filter", LocationCode); + ItemJournalLine."Journal Template Name" := TemplateName; + ItemJournalLine."Journal Batch Name" := BatchName; + CalculateWhseAdjustment.SetItemJnlLine(ItemJournalLine); + CalculateWhseAdjustment.SetTableView(Item); + CalculateWhseAdjustment.InitializeRequest(PostingDate, DocumentNo); + CalculateWhseAdjustment.SetHideValidationDialog(true); + CalculateWhseAdjustment.UseRequestPage(false); + CalculateWhseAdjustment.RunModal(); + + exit(true); + end; + + var + EmptyBatchErr: Label 'Use an empty, dedicated item journal batch for warehouse reconciliation.'; +} diff --git a/microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.good.al b/microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.good.al new file mode 100644 index 0000000..469ed2d --- /dev/null +++ b/microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.good.al @@ -0,0 +1,42 @@ +codeunit 50111 "SCM Warehouse Adjustment Good" +{ + procedure ReconcileRegisteredWarehouseAdjustment(ItemNo: Code[20]; LocationCode: Code[10]; TemplateName: Code[10]; BatchName: Code[10]; PostingDate: Date; DocumentNo: Code[20]): Boolean + var + Item: Record Item; + ItemJournalBatch: Record "Item Journal Batch"; + ItemJournalLine: Record "Item Journal Line"; + Location: Record Location; + CalculateWhseAdjustment: Report "Calculate Whse. Adjustment"; + ItemJnlPostBatch: Codeunit "Item Jnl.-Post Batch"; + begin + Location.Get(LocationCode); + Location.TestField("Directed Put-away and Pick", true); + Location.TestField("Adjustment Bin Code"); + ItemJournalBatch.Get(TemplateName, BatchName); + ItemJournalLine.SetRange("Journal Template Name", TemplateName); + ItemJournalLine.SetRange("Journal Batch Name", BatchName); + if not ItemJournalLine.IsEmpty() then + Error(EmptyBatchErr); + + Item.Get(ItemNo); + Item.SetRecFilter(); + Item.SetRange("Location Filter", LocationCode); + ItemJournalLine."Journal Template Name" := TemplateName; + ItemJournalLine."Journal Batch Name" := BatchName; + CalculateWhseAdjustment.SetItemJnlLine(ItemJournalLine); + CalculateWhseAdjustment.SetTableView(Item); + CalculateWhseAdjustment.InitializeRequest(PostingDate, DocumentNo); + CalculateWhseAdjustment.SetHideValidationDialog(true); + CalculateWhseAdjustment.UseRequestPage(false); + CalculateWhseAdjustment.RunModal(); + + if ItemJournalLine.FindFirst() then begin + ItemJournalLine.TestField("Warehouse Adjustment", true); + ItemJnlPostBatch.Run(ItemJournalLine); + end; + exit(true); + end; + + var + EmptyBatchErr: Label 'Use an empty, dedicated item journal batch for warehouse reconciliation.'; +} diff --git a/microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.md b/microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.md new file mode 100644 index 0000000..06230e7 --- /dev/null +++ b/microsoft/knowledge/scm/reconcile-warehouse-adjustments-with-the-item-ledger.md @@ -0,0 +1,40 @@ +--- +bc-version: [all] +domain: scm +keywords: [warehouse-adjustment, calculate-whse-adjustment, adjustment-bin-code, directed-put-away-and-pick, item-journal-line, warehouse-entry] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Reconcile warehouse adjustments with the item ledger + +## Description + +At a Directed Put-away and Pick location, registering an ordinary warehouse quantity or physical-inventory adjustment and synchronizing it to inventory are distinct steps. The warehouse registration balances quantity through the adjustment bin. An additional ordinary item-journal increase/decrease is not the same as consuming that pending warehouse adjustment. + +## Best Practice + +After warehouse registration, `"Calculate Whse. Adjustment"` prepares item-journal lines for the intended item/location and batch; `"Item Jnl.-Post Batch"` posts those lines. The calculation derives the reconciliation by location, variant, units of measure, and tracking, marks the lines `"Warehouse Adjustment"`, and accounts for already prepared unposted adjustments. + +Reconciliation is separate from source-document posting: warehouse receipts/shipments use their document workflows. Intentional warehouse-only staging is valid when a separately owned reconciliation step completes the process; registration need not perform both phases in one call. + +Bin movements need not change total inventory, and warehouse tracking/expiration reclassification has a standard batch path that can also post item-journal entries. Standard reclassification and basic-location item adjustments are not this ordinary advanced-warehouse quantity-adjustment case. + +The samples start after warehouse quantity registration and report whether inventory reconciliation completed. The clean sample calculates and posts into an empty dedicated batch; it is not a complete warehouse physical-count workflow. + +See sample: [`reconcile-warehouse-adjustments-with-the-item-ledger.good.al`](reconcile-warehouse-adjustments-with-the-item-ledger.good.al). + +## Anti Pattern + +A manually mirrored ordinary item-journal line does not reconcile a registered advanced-warehouse quantity adjustment. Likewise, a reconciliation function that returns completion after only registration or adjustment calculation leaves any generated adjustment lines unposted. Calculation prepares journal lines; it does not post them. + +Invented positive/negative quantities or flipping `"Warehouse Adjustment"` on an arbitrary line does not establish the required relationship to the adjustment-bin balance and tracked quantities. That relationship comes from the calculation step. + +See sample: [`reconcile-warehouse-adjustments-with-the-item-ledger.bad.al`](reconcile-warehouse-adjustments-with-the-item-ledger.bad.al). + +## References + +- [Synchronize adjusted warehouse entries with item ledger entries](https://learn.microsoft.com/en-us/dynamics365/business-central/inventory-how-count-adjust-reclassify#to-synchronize-the-adjusted-warehouse-entries-with-the-related-item-ledger-entries) +- [BaseApp warehouse-adjustment calculation](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Warehouse/Journal/CalculateWhseAdjustment.Report.al#L298-L384) +- [Warehouse reclassification exception](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Warehouse/Journal/WhseJnlRegisterBatch.Codeunit.al#L196-L210) diff --git a/microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.bad.al b/microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.bad.al new file mode 100644 index 0000000..89368cf --- /dev/null +++ b/microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.bad.al @@ -0,0 +1,30 @@ +codeunit 50108 "SCM Tracking Transfer Bad" +{ + procedure TransferBlanketOrderTracking(var SourceBlanketOrderLine: Record "Sales Line"; var DestinationSalesOrderLine: Record "Sales Line"; QuantityBaseToTransfer: Decimal) + var + ReservationEntry: Record "Reservation Entry"; + begin + SourceBlanketOrderLine.TestField("Document Type", SourceBlanketOrderLine."Document Type"::"Blanket Order"); + SourceBlanketOrderLine.TestField(Type, SourceBlanketOrderLine.Type::Item); + DestinationSalesOrderLine.TestField("Document Type", DestinationSalesOrderLine."Document Type"::Order); + DestinationSalesOrderLine.TestField(Type, DestinationSalesOrderLine.Type::Item); + DestinationSalesOrderLine.TestField("No.", SourceBlanketOrderLine."No."); + if QuantityBaseToTransfer <= 0 then + Error(PositiveQuantityErr); + + ReservationEntry.SetRange("Source Type", Database::"Sales Line"); + ReservationEntry.SetRange("Source Subtype", SourceBlanketOrderLine."Document Type".AsInteger()); + ReservationEntry.SetRange("Source ID", SourceBlanketOrderLine."Document No."); + ReservationEntry.SetRange("Source Ref. No.", SourceBlanketOrderLine."Line No."); + ReservationEntry.SetRange(Positive, false); + ReservationEntry.FindFirst(); + ReservationEntry."Source Subtype" := DestinationSalesOrderLine."Document Type".AsInteger(); + ReservationEntry."Source ID" := DestinationSalesOrderLine."Document No."; + ReservationEntry."Source Ref. No." := DestinationSalesOrderLine."Line No."; + ReservationEntry.Validate("Quantity (Base)", -QuantityBaseToTransfer); + ReservationEntry.Modify(true); + end; + + var + PositiveQuantityErr: Label 'The base quantity to transfer must be positive.'; +} diff --git a/microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.good.al b/microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.good.al new file mode 100644 index 0000000..a655b34 --- /dev/null +++ b/microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.good.al @@ -0,0 +1,20 @@ +codeunit 50109 "SCM Tracking Transfer Good" +{ + procedure TransferBlanketOrderTracking(var SourceBlanketOrderLine: Record "Sales Line"; var DestinationSalesOrderLine: Record "Sales Line"; QuantityBaseToTransfer: Decimal) + var + SalesLineReserve: Codeunit "Sales Line-Reserve"; + begin + SourceBlanketOrderLine.TestField("Document Type", SourceBlanketOrderLine."Document Type"::"Blanket Order"); + SourceBlanketOrderLine.TestField(Type, SourceBlanketOrderLine.Type::Item); + DestinationSalesOrderLine.TestField("Document Type", DestinationSalesOrderLine."Document Type"::Order); + DestinationSalesOrderLine.TestField(Type, DestinationSalesOrderLine.Type::Item); + DestinationSalesOrderLine.TestField("No.", SourceBlanketOrderLine."No."); + if QuantityBaseToTransfer <= 0 then + Error(PositiveQuantityErr); + + SalesLineReserve.TransferSaleLineToSalesLine(SourceBlanketOrderLine, DestinationSalesOrderLine, QuantityBaseToTransfer); + end; + + var + PositiveQuantityErr: Label 'The base quantity to transfer must be positive.'; +} diff --git a/microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.md b/microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.md new file mode 100644 index 0000000..8bc42cc --- /dev/null +++ b/microsoft/knowledge/scm/transfer-item-tracking-through-source-reservation-codeunits.md @@ -0,0 +1,41 @@ +--- +bc-version: [all] +domain: scm +keywords: [reservation-entry, tracking-specification, sales-line-reserve, transfersalelinetosalesline, transferreserventry, copyitemtracking, quantity-base] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Transfer item tracking through source reservation codeunits + +## Description + +Moving lot/serial tracking between document lines is a source-ownership operation, not a copy of visible tracking fields. Partial movement must retain the old source's remainder, destination units of measure, quantities to handle/invoice, status, sign, and any reservation counterpart. Repointing a `"Reservation Entry"` loses this coordination; inserting a `"Tracking Specification"` row alone does not book the destination's source tracking. + +## Best Practice + +Reservation codeunits provide source-specific tracking workflows. For the tracking portion of blanket-sales-order or quote conversion to a sales order, `"Sales Line-Reserve".TransferSaleLineToSalesLine` takes the existing source line, prepared destination line, and quantity to transfer in **base units**. It delegates the source/status and quantity movement to `"Create Reserv. Entry".TransferReservEntry`. + +The caller still owns document conversion and destination-line preparation; this method does not create a sales order. The source and destination must have compatible item, variant, location, and source identity. Purchases, transfers, assembly, and production have their own source-specific wrappers rather than sharing the sales conversion contract. + +`"Item Tracking Management".CopyItemTracking` serves a different purpose: it creates Prospect copies, not a transfer of reservation ownership. That is valid for its intended copy workflow. Temporary Tracking Specification processing and persisted historical tracking specifications are also normal; the working/historic representation differs from the current source booking. + +See sample: [`transfer-item-tracking-through-source-reservation-codeunits.good.al`](transfer-item-tracking-through-source-reservation-codeunits.good.al). + +## Anti Pattern + +Direct rewrites of persistent `"Reservation Entry"` source type/subtype, ID, reference number, or quantities do not perform the source-line conversion or partial tracking-transfer workflow. Changing only `"Quantity (Base)"` and source keys can drop the remainder or leave the other tracking/reservation quantities attached to the wrong source. + +A tracking copy cannot replace movement of an existing binding reservation. Legitimate Prospect copying, temporary tracking buffers, historical tracking reads, and source-specific engine calls serve distinct purposes and are not independent reservation transfers. + +See sample: [`transfer-item-tracking-through-source-reservation-codeunits.bad.al`](transfer-item-tracking-through-source-reservation-codeunits.bad.al). + +## References + +- [Item Tracking Lines window design](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-item-tracking-lines-window) +- [Active versus historic item-tracking entries](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-active-versus-historic-item-tracking-entries) +- [Item tracking and reservations](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-item-tracking-and-reservations) +- [BaseApp sales tracking transfer](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Sales/Document/SalesLineReserve.Codeunit.al#L532-L578) +- [Base-unit conversion caller](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Sales/Document/BlanketSalesOrdertoOrder.Codeunit.al#L195-L198) +- [Prospect-copy API](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Tracking/ItemTrackingManagement.Codeunit.al#L575-L657) diff --git a/microsoft/knowledge/scm/use-date-aware-availability-for-promising.bad.al b/microsoft/knowledge/scm/use-date-aware-availability-for-promising.bad.al new file mode 100644 index 0000000..b90f932 --- /dev/null +++ b/microsoft/knowledge/scm/use-date-aware-availability-for-promising.bad.al @@ -0,0 +1,21 @@ +codeunit 50114 "SCM Additional Promise Bad" +{ + procedure CanPromiseAdditionalDemand(ItemNo: Code[20]; LocationCode: Code[10]; VariantCode: Code[10]; ShipmentDate: Date; RequestedAdditionalQuantityBase: Decimal; LookaheadDateFormula: DateFormula): Boolean + var + Item: Record Item; + begin + if (ShipmentDate = 0D) or (RequestedAdditionalQuantityBase <= 0) then + Error(DemandInputErr); + Item.Get(ItemNo); + Item.TestField(Type, Item.Type::Inventory); + Item.SetRange("Location Filter", LocationCode); + Item.SetRange("Variant Filter", VariantCode); + Item.SetRange("Date Filter", 0D, ShipmentDate); + + Item.CalcFields(Inventory); + exit(Item.Inventory >= RequestedAdditionalQuantityBase); + end; + + var + DemandInputErr: Label 'Enter a shipment date and a positive additional base quantity.'; +} diff --git a/microsoft/knowledge/scm/use-date-aware-availability-for-promising.good.al b/microsoft/knowledge/scm/use-date-aware-availability-for-promising.good.al new file mode 100644 index 0000000..b33ee79 --- /dev/null +++ b/microsoft/knowledge/scm/use-date-aware-availability-for-promising.good.al @@ -0,0 +1,27 @@ +codeunit 50115 "SCM Additional Promise Good" +{ + procedure CanPromiseAdditionalDemand(ItemNo: Code[20]; LocationCode: Code[10]; VariantCode: Code[10]; ShipmentDate: Date; RequestedAdditionalQuantityBase: Decimal; LookaheadDateFormula: DateFormula): Boolean + var + Item: Record Item; + AvailableToPromise: Codeunit "Available to Promise"; + GrossRequirement: Decimal; + ScheduledReceipt: Decimal; + PromisableQuantityBase: Decimal; + begin + if (ShipmentDate = 0D) or (RequestedAdditionalQuantityBase <= 0) then + Error(DemandInputErr); + Item.Get(ItemNo); + Item.TestField(Type, Item.Type::Inventory); + Item.SetRange("Location Filter", LocationCode); + Item.SetRange("Variant Filter", VariantCode); + Item.SetRange("Date Filter", 0D, ShipmentDate); + + PromisableQuantityBase := AvailableToPromise.CalcQtyAvailableToPromise( + Item, GrossRequirement, ScheduledReceipt, ShipmentDate, + Enum::"Analysis Period Type"::Day, LookaheadDateFormula); + exit(PromisableQuantityBase >= RequestedAdditionalQuantityBase); + end; + + var + DemandInputErr: Label 'Enter a shipment date and a positive additional base quantity.'; +} diff --git a/microsoft/knowledge/scm/use-date-aware-availability-for-promising.md b/microsoft/knowledge/scm/use-date-aware-availability-for-promising.md new file mode 100644 index 0000000..a182a94 --- /dev/null +++ b/microsoft/knowledge/scm/use-date-aware-availability-for-promising.md @@ -0,0 +1,39 @@ +--- +bc-version: [all] +domain: scm +keywords: [available-to-promise, calcqtyavailabletopromise, inventory, shipment-date, gross-requirement, scheduled-receipt, location-filter, variant-filter] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Use date-aware availability for promising + +## Description + +`Item.Inventory` is an on-hand quantity, not an available-to-promise answer. Promising additional demand must account for the requested date, location and variant, reservations, scheduled receipts, existing requirements, and demand within the configured lookahead. An on-hand comparison can promise inventory already committed elsewhere and miss incoming supply. + +## Best Practice + +For additional demand not already recorded on a source line, `"Available to Promise".CalcQtyAvailableToPromise` uses the Item's location/variant filters, date range ending on the shipment date, and configured period/lookahead horizon. Its result and the additional quantity are compared in base units. A fresh calculation context or the codeunit's recalculation support avoids carrying cached quantities between unrelated items or requests. + +The source-aware order-promising/availability workflow accounts for an existing sales line's own quantity or delta; applying an additional-demand calculation to that line can double-count it. Assembly and production requirements/supply likewise participate in the standard availability context, not just a sales-only stock subtraction. + +An ATP result is not a reservation or a guarantee of warehouse pickability. Lot/serial constraints, bins, warehouse activity, and later concurrent changes still need their own checks. Conversely, an on-hand display, valuation report, or deliberately immediate-stock-only check can use `Item.Inventory`: it answers a different business question from ATP. + +See sample: [`use-date-aware-availability-for-promising.good.al`](use-date-aware-availability-for-promising.good.al). + +## Anti Pattern + +`CalcFields(Inventory)` or an equivalent item-ledger quantity sum used as the complete decision for a dated additional-demand promise ignores existing demand and incoming supply, even with location/variant filters. An Inventory FlowField read for an on-hand display has no such promising contract. + +Losing location, variant, date, or source-line context changes the calculation's business meaning. Another supported workflow that preserves the same availability semantics does not have to call this exact API. + +See sample: [`use-date-aware-availability-for-promising.bad.al`](use-date-aware-availability-for-promising.bad.al). + +## References + +- [Calculate order-promising dates](https://learn.microsoft.com/en-us/dynamics365/business-central/sales-how-to-calculate-order-promising-dates) +- [Availability in the warehouse](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-availability-in-the-warehouse) +- [BaseApp ATP calculation](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Availability/AvailabletoPromise.Codeunit.al#L52-L184) +- [Forward-demand lookahead](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Inventory/Availability/AvailabletoPromise.Codeunit.al#L295-L356) diff --git a/microsoft/skills/review/al-code-review.md b/microsoft/skills/review/al-code-review.md index dc1f1db..7cfe07b 100644 --- a/microsoft/skills/review/al-code-review.md +++ b/microsoft/skills/review/al-code-review.md @@ -28,6 +28,7 @@ sub-skills: - microsoft/skills/review/al-reporting-review.md - microsoft/skills/review/al-appsource-review.md - microsoft/skills/review/al-telemetry-review.md + - microsoft/skills/review/al-scm-review.md --- # AL code review diff --git a/microsoft/skills/review/al-scm-review.md b/microsoft/skills/review/al-scm-review.md new file mode 100644 index 0000000..a434529 --- /dev/null +++ b/microsoft/skills/review/al-scm-review.md @@ -0,0 +1,121 @@ +--- +kind: action-skill +id: al-scm-review +version: 1 +title: AL Supply Chain Management review +description: Reviews SCM inventory costing, item application, reservations, order tracking, item tracking, warehouse, transfer, and planning workflows in AL. +inputs: [pr-diff, file-path, folder-path] +outputs: [findings-report] +bc-version: [all] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# AL Supply Chain Management review + +Reviews AL source against the `scm` knowledge domain. This leaf invokes no +sub-skills and is composed by `al-code-review`. For a folder, inspect every +relevant AL file; a folder supplies no historical baseline. + +## Source + +Apply Relevance's source gate before retrieval. For a relevant scope, use READ's +**Bounded retrieval for review skills** with `-Domain scm` and +`-Technologies @('al')`. Consume every catalog page across enabled layers, +preserving exact paths and applicability. Select from metadata, then read only +worklisted complete articles. Entry owns index preparation; the leaf does not +rebuild. Unavailable/invalid helpers or indexes use READ's bounded native-read +fallback, never a success-shaped empty result. + +## Relevance + +Resolve changed record/codeunit types, source tables, publishers and calls. +Gate on code that mutates or posts inventory, application, reservation, +tracking, warehouse, transfer or planning state, or makes a supply/demand +availability decision. Stock displays and other read-only queries without +that decision do not pass the gate. Names, comments, captions, an `Item` +reference or a broad `ApplicationArea` alone are not signals. +If no SCM surface remains, return `not-applicable` with zero coverage +and no article-body retrieval; in mixed diffs, retain only relevant procedures +and their visible supporting context. + +SCM owns `"Item Ledger Entry"`, `"Value Entry"`, `"Capacity Ledger Entry"`, +`"Warehouse Entry"` and inventory posting/application records. Pure `"G/L Entry"`, +`"Cust. Ledger Entry"`, `"Vendor Ledger Entry"`, `"Detailed Cust. Ledg. Entry"`, +`"Detailed Vendor Ledg. Entry"`, `"VAT Entry"` and financial-only posting +mutations belong to Finance. They remain outside SCM even if Finance is absent +or disabled; do not reclaim them as SCM agent findings. Ownership is not a +claim that every owned surface already has a dedicated article. + +Apply READ's frontmatter filters using the target BC major version from +application dependency/host context (not the extension version), AL, known +localization and actual task/object application areas. Omitted context stays +unknown, not `[all]`; unknown areas alone do not exclude codeunits/subscribers. +Retain conditional articles only when configured, cap their findings at +`medium`, and name every unknown dimension. + +## Worklist + +Extract resolved object/type names, quoted fields, methods, enum members and +publishers. Normalize these and catalog keywords by lowercasing invariantly, +replacing punctuation/whitespace runs with one hyphen and trimming hyphens: +`"Item Ledger Entry"` becomes `item-ledger-entry`; `RunWithCheck` becomes +`runwithcheck`. Match whole tokens/phrases, not identifier substrings. + +Select matching keywords or catalog topics only for the same source surface +**and operation**. The following cues resolve slugs to actual enabled catalog +paths; they select articles, not findings. Facts and exceptions stay in articles. + +| Changed source surface and operation | Article slug | +| --- | --- | +| `"Item Ledger Entry"`/`"Value Entry"` transaction writes, or a standalone item-journal quantity/value posting entry point | `post-item-ledger-changes-through-item-journals` | +| Revaluation `"Item Journal Line"` with `"Inventory Value Per"` or `"Partial Revaluation"`, and its line/batch posting calls | `post-revaluation-through-the-item-journal-batch` | +| `"Item Application Entry"` relationship/quantity mutation, or `UnApply`, `ReApply`, `RedoApplications`, `CostAdjust` in an application-correction flow | `change-item-applications-through-posting-routines` | +| Binding-reservation cancellation: `"Reservation Entry"` status, delete/quantity/source edits, `CancelReservation`, or source reservation-lifecycle calls | `cancel-reservations-through-reservation-management` | +| Tracking source conversion/partial movement: `"Sales Line-Reserve"`, `TransferSaleLineToSalesLine`, `TransferReservEntry`, `CopyItemTracking`, or `"Reservation Entry"`/`"Tracking Specification"` source/quantity writes | `transfer-item-tracking-through-source-reservation-codeunits` | +| Registered warehouse quantity/physical-adjustment synchronization, `"Directed Put-away and Pick"`, `"Adjustment Bin Code"`, `"Warehouse Adjustment"`, or `"Calculate Whse. Adjustment"` and the resulting item-journal posting | `reconcile-warehouse-adjustments-with-the-item-ledger` | +| `"Transfer Header"`/`"Transfer Line"` shipment/receipt completion, transfer posting publishers, in-transit/document-link changes, or item-journal posting presented as transfer-order completion | `post-transfers-through-shipment-and-receipt-codeunits` | +| `Inventory`, `CalcQtyAvailableToPromise`, or stock sums used in a dated supply/demand promise, including changed location/variant/date filters and source-demand context | `use-date-aware-availability-for-promising` | +| `"Requisition Line"` action-message execution, accepted planning suggestions, `"Req. Wksh.-Make Order"`, `CarryOutBatchAction`, or linked supply creation/change plus requisition-line deletion | `carry-out-requisition-actions-through-the-standard-workflow` | + +Route clean supported calls through the same cues, not just suspicious writes. +Resolve actual normative conflicts per READ, preserving additive layers and +recording `layer-precedence`/`configuration` suppressions, not noncandidates. +Retrieve exact paths in ordinal chunks of at most eight, consume every +continuation, and never impose a top-eight cutoff. Samples use exact READ links. + +## Action + +Evaluate every opened article's normative facts, scope and exclusions against +visible persistence, caller contract, document state and operation. Emit only +concrete violations with business consequences and supported remediation; a +declaration, valid alternative or unseen caller is not evidence of a defect. + +- Use `major` for material SCM defects, `minor` for narrower best-practice + conflicts, and `blocker` only for an article-established platform guarantee. + Applicability alone produces no finding. High confidence requires unambiguous + evidence and known applicability; inference/conditional applicability caps it + at `medium`. +- Apply DO's single-owner deduplication. Equivalent findings for the same + inventory-originated posting bypass and correction have one SCM primary + owner, even when financial records are downstream. Prefer the most specific + SCM article and retain other applicable references as supporting evidence. + Distinct independent financial defects remain Finance; do not duplicate them. +- Agent findings stay strictly SCM-scoped under DO's precision bar, with + `references: []`, an `agent:` id and `minor`/`medium` ceilings. Generic AL and + other domains' concerns remain outside this leaf. +- Supply literal `suggested-code` only for a complete, local, unambiguous fix, + not a sample call that omits workflow setup/source identity. Explain omitted + mechanical-looking fixes with `suggested-code-omission-reason`. + +Outcome selection follows DO, including accurate coverage and reasons for +`partial`/`failed`. No surviving applicable corpus is `no-knowledge`; an existing +corpus with no matching operation is `completed` with an empty worklist. + +## Output + +Output conforms to the DO findings-report contract and shared schema. Every +finding MUST set `domain` to `"Supply Chain Management"`. Knowledge-backed ids +equal the primary opened article's exact catalog path. The coordinator, not +this leaf, sets `from-sub-skill`. From 07e324ddbc42597c479e041e06a7833740e05d0f Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Mon, 21 Sep 2026 10:20:41 +0200 Subject: [PATCH 25/35] Add source-verified Finance knowledge and review domain (#57) * Add Finance posting domain-knowledge pilot Adds three atomic domain-rule knowledge files under community/knowledge/finance/ as a pilot for Type-A (normative) Business Central domain knowledge: post through the posting engine, treat posted ledger entries as immutable, and treat the Dimension Set ID as the source of truth for dimensions. Includes a good/bad AL sample pair for the posting rule. These encode BC-specific invariants that LLMs reliably get wrong, fitting the existing remedial/atomic knowledge grain with no schema or contract changes. Passes the repo frontmatter validator and is discovered by the knowledge index. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Clarify editable operational fields on posted ledger entries Addresses review feedback from @JeremyVyska on PR #57: the immutability rule applies to financial content, not the whole entry. Reframes the Description around financial content and gives the operational-field exception (payment/application data, on-hold, applies-to, communication fields edited via CustEntry-Edit/VendEntry-Edit and the ledger entry pages) its own paragraph in Best Practice instead of understating it as a narrow set. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Expand Finance pilot into a source-verified review domain Move Finance knowledge to the Microsoft-owned layer, add nine scoped rules with eighteen AL samples, and register bounded Finance review with complete paired evaluation coverage. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Fix Finance review applicability and ownership boundaries Remove application-area gating and later VAT-field dependencies, align dynamic shared conventions, separate SCM ownership, and keep journal examples focused on the intended invariant. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Remove logo branding (#194) Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Add title and description to README * Add foundational AL developer knowledge (#195) Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Clarify locale-safe DateFormula Evaluate inputs (#193) * Clarify locale-safe DateFormula Evaluate inputs Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Normalize DateFormula article sections Keep the analyzer-gap explanation in Description and its scoped probe evidence in References, without a novel Validation section. Normative guidance and fixtures are unchanged. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Add SCM functional knowledge domain (#192) * Add SCM functional knowledge domain Introduce nine source-backed rules with original AL sample pairs, bounded SCM review routing, and complete positive/clean evaluation coverage. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Normalize SCM knowledge and review ownership Align article and AL sample conventions, keep BC facts separate from review mechanics, and clarify reciprocal Finance ownership without bespoke shared test assertions. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/scripts/Test-SkillIndex.ps1 | 3 +- docs/using-bcquality.md | 11 ++ evaluation/README.md | 12 ++ evaluation/review-fixtures.json | 14 ++ ...tries-through-application-codeunits.bad.al | 33 ++++ ...ries-through-application-codeunits.good.al | 31 ++++ ...r-entries-through-application-codeunits.md | 37 +++++ ...ledger-due-dates-through-entry-edit.bad.al | 21 +++ ...edger-due-dates-through-entry-edit.good.al | 21 +++ ...nge-ledger-due-dates-through-entry-edit.md | 35 +++++ .../do-not-edit-shared-dimension-sets.bad.al | 14 ++ .../do-not-edit-shared-dimension-sets.good.al | 18 +++ .../do-not-edit-shared-dimension-sets.md | 35 +++++ ...ify-or-delete-posted-ledger-entries.bad.al | 32 ++++ ...fy-or-delete-posted-ledger-entries.good.al | 32 ++++ ...-modify-or-delete-posted-ledger-entries.md | 37 +++++ ...mal-vat-journal-amount-includes-vat.bad.al | 54 +++++++ ...al-vat-journal-amount-includes-vat.good.al | 54 +++++++ .../normal-vat-journal-amount-includes-vat.md | 37 +++++ ...r-entries-through-posting-codeunits.bad.al | 60 +++++++ ...-entries-through-posting-codeunits.good.al | 29 ++++ ...edger-entries-through-posting-codeunits.md | 38 +++++ ...erve-journal-batch-document-balance.bad.al | 53 +++++++ ...rve-journal-batch-document-balance.good.al | 49 ++++++ ...preserve-journal-batch-document-balance.md | 35 +++++ ...-transactions-by-transaction-number.bad.al | 18 +++ ...transactions-by-transaction-number.good.al | 18 +++ ...erse-transactions-by-transaction-number.md | 34 ++++ ...dimensions-as-dimension-set-entries.bad.al | 20 +++ ...imensions-as-dimension-set-entries.good.al | 19 +++ ...ite-dimensions-as-dimension-set-entries.md | 34 ++++ microsoft/skills/review/al-code-review.md | 1 + microsoft/skills/review/al-finance-review.md | 146 ++++++++++++++++++ 33 files changed, 1084 insertions(+), 1 deletion(-) create mode 100644 microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.bad.al create mode 100644 microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.good.al create mode 100644 microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.md create mode 100644 microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.bad.al create mode 100644 microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.good.al create mode 100644 microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.md create mode 100644 microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.bad.al create mode 100644 microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.good.al create mode 100644 microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.md create mode 100644 microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.bad.al create mode 100644 microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.good.al create mode 100644 microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.md create mode 100644 microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.bad.al create mode 100644 microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.good.al create mode 100644 microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.md create mode 100644 microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.bad.al create mode 100644 microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.good.al create mode 100644 microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.md create mode 100644 microsoft/knowledge/finance/preserve-journal-batch-document-balance.bad.al create mode 100644 microsoft/knowledge/finance/preserve-journal-batch-document-balance.good.al create mode 100644 microsoft/knowledge/finance/preserve-journal-batch-document-balance.md create mode 100644 microsoft/knowledge/finance/reverse-transactions-by-transaction-number.bad.al create mode 100644 microsoft/knowledge/finance/reverse-transactions-by-transaction-number.good.al create mode 100644 microsoft/knowledge/finance/reverse-transactions-by-transaction-number.md create mode 100644 microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.bad.al create mode 100644 microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.good.al create mode 100644 microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.md create mode 100644 microsoft/skills/review/al-finance-review.md diff --git a/.github/scripts/Test-SkillIndex.ps1 b/.github/scripts/Test-SkillIndex.ps1 index 5354370..b694a5b 100644 --- a/.github/scripts/Test-SkillIndex.ps1 +++ b/.github/scripts/Test-SkillIndex.ps1 @@ -94,7 +94,8 @@ try { 'microsoft/skills/review/al-reporting-review.md', 'microsoft/skills/review/al-appsource-review.md', 'microsoft/skills/review/al-telemetry-review.md', - 'microsoft/skills/review/al-scm-review.md' + 'microsoft/skills/review/al-scm-review.md', + 'microsoft/skills/review/al-finance-review.md' ) $review = @($skills | Where-Object id -eq 'al-code-review') if ($review.Count -ne 1) { diff --git a/docs/using-bcquality.md b/docs/using-bcquality.md index 2af08be..b65fcb0 100644 --- a/docs/using-bcquality.md +++ b/docs/using-bcquality.md @@ -211,6 +211,16 @@ mutations belong to Finance, even when that domain is not enabled. Equivalent findings for one inventory-originated posting bypass have one SCM primary owner; distinct independent financial defects remain separate. +The Finance leaf reviews journal posting, financial ledger changes, +applications, and posting-linked dimension handling. It prunes unrelated code +at the leaf rather than changing broad-review orchestration. Finance articles +use `application-area: [all]` so missing application-area context does not +weaken applicable findings; resolved records and operations supply the +narrowing. Finance owns financial ledgers, not Item, Value, Capacity, Warehouse, +or inventory-application records owned by SCM. It also does not own generic +custom-table or master Default Dimension wiring. Request a focused "Finance +posting review" when only this domain is needed. + BCQuality intentionally does not duplicate mechanical diagnostics already enforced by the AL compiler or standard analyzers. Run the consuming app's normal compiler and analyzer pipeline alongside review and authoring. Knowledge @@ -230,6 +240,7 @@ Each article describes one concern. Where samples exist, use its linked | Data modeling | [Data modeling](../microsoft/knowledge/data-modeling/) | | Error handling | [Error handling](../microsoft/knowledge/error-handling/) | | Events | [Events](../microsoft/knowledge/events/) | +| Finance | [Finance](../microsoft/knowledge/finance/) | | Interfaces | [Interfaces](../microsoft/knowledge/interfaces/) | | Performance | [Performance](../microsoft/knowledge/performance/) | | Privacy | [Privacy](../microsoft/knowledge/privacy/) | diff --git a/evaluation/README.md b/evaluation/README.md index 05b5e52..bce3208 100644 --- a/evaluation/README.md +++ b/evaluation/README.md @@ -16,6 +16,18 @@ neutralization. Do not move those preconditions into comments or generic alternative workflow. The clean pairs exercise the supported APIs selected by the same routing cues, not merely unrelated code that contains no SCM tokens. +The Finance override deliberately covers every paired Finance article, not +only the first filename. Its shared context supplies the target version and +localization but deliberately omits application area, as production callers +often do. Finance applicability must come from its source-surface gate, not +an artificial evaluation-only area hint. Scenario prerequisites live in +executable AL: the document-balance cases check the template setting, and the +VAT cases encode the imported net/VAT/gross totals and applicable VAT mode. +Do not move these prerequisites into comments that preparation removes. +Clean samples also retain supported operational edits, temporary ledger/set +buffers, legitimate entry-number APIs, and reads of individual shortcut +dimensions so these exceptions are exercised rather than blanket-excluded. + ## Validate the corpus ```powershell diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index 2d03940..3f131a5 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -13,6 +13,20 @@ "events": { "article": "reset-ishandled-only-when-the-value-can-carry-over" }, + "finance": { + "articles": [ + "apply-ledger-entries-through-application-codeunits", + "change-ledger-due-dates-through-entry-edit", + "do-not-edit-shared-dimension-sets", + "do-not-modify-or-delete-posted-ledger-entries", + "normal-vat-journal-amount-includes-vat", + "post-ledger-entries-through-posting-codeunits", + "preserve-journal-batch-document-balance", + "reverse-transactions-by-transaction-number", + "write-dimensions-as-dimension-set-entries" + ], + "context": "Target Business Central 28, worldwide standard application (w1). Review each file as an independent source input." + }, "interfaces": { "article": "set-defaultimplementation-on-enum" }, diff --git a/microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.bad.al b/microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.bad.al new file mode 100644 index 0000000..1e605d3 --- /dev/null +++ b/microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.bad.al @@ -0,0 +1,33 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50104 "Customer Settlement Actions" +{ + procedure RequestApplication(CustomerEntryNo: Integer) + var + CustomerEntry: Record "Cust. Ledger Entry"; + begin + RequireInteractiveSession(); + CustomerEntry.Get(CustomerEntryNo); + CustomerEntry.TestField(Open, true); + CustomerEntry.Open := false; + CustomerEntry.Modify(true); + end; + + procedure RequestUnapplication(CustomerEntryNo: Integer) + var + DetailedCustomerEntry: Record "Detailed Cust. Ledg. Entry"; + begin + RequireInteractiveSession(); + DetailedCustomerEntry.SetRange("Cust. Ledger Entry No.", CustomerEntryNo); + DetailedCustomerEntry.SetRange("Entry Type", DetailedCustomerEntry."Entry Type"::Application); + DetailedCustomerEntry.ModifyAll(Unapplied, true); + end; + + local procedure RequireInteractiveSession() + begin + if not GuiAllowed() then + Error(InteractiveSessionErr); + end; + + var + InteractiveSessionErr: Label 'Request settlement from an interactive session.'; +} diff --git a/microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.good.al b/microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.good.al new file mode 100644 index 0000000..b33e2d2 --- /dev/null +++ b/microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.good.al @@ -0,0 +1,31 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50104 "Customer Settlement Actions" +{ + procedure RequestApplication(CustomerEntryNo: Integer) + var + CustomerEntry: Record "Cust. Ledger Entry"; + CustomerApplication: Codeunit "CustEntry-Apply Posted Entries"; + begin + RequireInteractiveSession(); + CustomerEntry.Get(CustomerEntryNo); + CustomerEntry.TestField(Open, true); + CustomerApplication.ApplyCustEntryFormEntry(CustomerEntry); + end; + + procedure RequestUnapplication(CustomerEntryNo: Integer) + var + CustomerApplication: Codeunit "CustEntry-Apply Posted Entries"; + begin + RequireInteractiveSession(); + CustomerApplication.UnApplyCustLedgEntry(CustomerEntryNo); + end; + + local procedure RequireInteractiveSession() + begin + if not GuiAllowed() then + Error(InteractiveSessionErr); + end; + + var + InteractiveSessionErr: Label 'Request settlement from an interactive session.'; +} diff --git a/microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.md b/microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.md new file mode 100644 index 0000000..11f78cd --- /dev/null +++ b/microsoft/knowledge/finance/apply-ledger-entries-through-application-codeunits.md @@ -0,0 +1,37 @@ +--- +bc-version: [all] +domain: finance +keywords: [cust-ledger-entry, vendor-ledger-entry, detailed-ledger-entry, remaining-amount, application, unapplication, open, closed-by-entry-no] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Apply and unapply entries through the application workflow, not status flags + +## Description + +Customer/vendor settlement is a posting operation involving detailed ledger entries, not just a change to `Open` on the main entry. Remaining amounts are calculated from detailed entries. Unapplication posts correcting entries and handles application-derived effects such as discounts and currency gains/losses; deleting details or changing `Unapplied` cannot reproduce that history. + +## Best Practice + +Use `"CustEntry-Apply Posted Entries"` / `"VendEntry-Apply Posted Entries"` and the supported application or unapplication workflow. Let it check application dates, entry state, and application ordering. The `ApplyCustEntryFormEntry` / `ApplyVendEntryFormEntry` and `UnApply...LedgEntry` methods are **interactive**: users select and confirm the operation. They are not unattended "mark paid" APIs. + +For programmatic posting, use the target version's public `Apply` / `PostUnApply...` APIs with properly prepared selection and `Apply Unapply Parameters`; handle cancellation and the workflow's transaction/commit behavior. `"Applying Entry"`, `"Applies-to ID"`, and `"Amount to Apply"` are legitimate application-preparation fields. Do not report their writes alone, temporary buffers, supported posting/compression internals, or unrelated operational/extension fields. + +See sample: [`apply-ledger-entries-through-application-codeunits.good.al`](apply-ledger-entries-through-application-codeunits.good.al). + +## Anti Pattern + +Implement customer/vendor payment matching, settlement, or reopening by directly persisting `Open`, `"Closed by Entry No."`, closure amounts/dates, or detailed-entry unapplication flags, or by deleting/rewriting detailed application amounts. Require confirmed writes to existing non-temporary customer/vendor or detailed customer/vendor entries and settlement intent. Item/inventory application records belong to SCM, not this rule. Do not suggest assigning a `Remaining Amount` FlowField as a fix. + +This article owns fabricated application state. Use the [posted-financial-content rule](do-not-modify-or-delete-posted-ledger-entries.md) for original accounting-value corrections, not a second finding prescribing the same application fix. + +See sample: [`apply-ledger-entries-through-application-codeunits.bad.al`](apply-ledger-entries-through-application-codeunits.bad.al). + +## References + +- [Apply and unapply customer transactions](https://learn.microsoft.com/en-us/dynamics365/business-central/receivables-how-apply-sales-transactions-manually). +- [Apply and unapply vendor transactions](https://learn.microsoft.com/en-us/dynamics365/business-central/payables-how-apply-purchase-transactions-manually). +- [BCApps: customer application workflow](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Sales/Receivables/CustEntryApplyPostedEntries.Codeunit.al). +- [BCApps: vendor application workflow](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Purchases/Payables/VendEntryApplyPostedEntries.Codeunit.al). diff --git a/microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.bad.al b/microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.bad.al new file mode 100644 index 0000000..7a7bec6 --- /dev/null +++ b/microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.bad.al @@ -0,0 +1,21 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50105 "Update Ledger Due Dates" +{ + procedure UpdateCustomerDueDate(EntryNo: Integer; NewDueDate: Date) + var + CustomerEntry: Record "Cust. Ledger Entry"; + begin + CustomerEntry.Get(EntryNo); + CustomerEntry.Validate("Due Date", NewDueDate); + CustomerEntry.Modify(true); + end; + + procedure UpdateVendorDueDate(EntryNo: Integer; NewDueDate: Date) + var + VendorEntry: Record "Vendor Ledger Entry"; + begin + VendorEntry.Get(EntryNo); + VendorEntry.Validate("Due Date", NewDueDate); + VendorEntry.Modify(true); + end; +} diff --git a/microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.good.al b/microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.good.al new file mode 100644 index 0000000..540548e --- /dev/null +++ b/microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.good.al @@ -0,0 +1,21 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50105 "Update Ledger Due Dates" +{ + procedure UpdateCustomerDueDate(EntryNo: Integer; NewDueDate: Date) + var + CustomerEntry: Record "Cust. Ledger Entry"; + begin + CustomerEntry.Get(EntryNo); + CustomerEntry.Validate("Due Date", NewDueDate); + Codeunit.Run(Codeunit::"Cust. Entry-Edit", CustomerEntry); + end; + + procedure UpdateVendorDueDate(EntryNo: Integer; NewDueDate: Date) + var + VendorEntry: Record "Vendor Ledger Entry"; + begin + VendorEntry.Get(EntryNo); + VendorEntry.Validate("Due Date", NewDueDate); + Codeunit.Run(Codeunit::"Vend. Entry-Edit", VendorEntry); + end; +} diff --git a/microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.md b/microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.md new file mode 100644 index 0000000..aca7b76 --- /dev/null +++ b/microsoft/knowledge/finance/change-ledger-due-dates-through-entry-edit.md @@ -0,0 +1,35 @@ +--- +bc-version: [all] +domain: finance +keywords: [due-date, initial-entry-due-date, cust-entry-edit, vend-entry-edit, detailed-ledger-entry, aging] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Change posted customer/vendor due dates through the entry-edit workflow + +## Description + +A posted customer or vendor due date is supported editable operational data, but it is also represented by `Initial Entry Due Date` on related detailed ledger entries. Validating `Due Date` and calling `Modify(true)` on the main entry does not perform all synchronization done by `"Cust. Entry-Edit"` or `"Vend. Entry-Edit"`. The main entry and due-date-based analysis can otherwise disagree. + +## Best Practice + +Fetch the existing entry, validate the proposed `Due Date`, and pass the changed record to the corresponding entry-edit codeunit, as the standard ledger pages do. Field validation enforces entry-state rules; the editor persists the supported change and synchronizes related detailed entries. Preserve both steps rather than treating table triggers as equivalent to the edit workflow. + +This is a due-date synchronization rule, not a prohibition on all operational edits after posting. Exclude temporary buffers, extension-only fields, supported editor internals, and code that demonstrably performs the equivalent synchronization under the supported workflow. Check the actual table/routine instead of assuming every `*Entry-Edit` accepts the same fields. + +See sample: [`change-ledger-due-dates-through-entry-edit.good.al`](change-ledger-due-dates-through-entry-edit.good.al). + +## Anti Pattern + +Change `Due Date` on an existing non-temporary `Cust. Ledger Entry` or `Vendor Ledger Entry` and persist it with `Modify`, `Modify(true)`, or `ModifyAll` without the edit workflow or equivalent related-entry update. A preceding `Validate("Due Date", ...)` is not sufficient evidence of synchronization. + +See sample: [`change-ledger-due-dates-through-entry-edit.bad.al`](change-ledger-due-dates-through-entry-edit.bad.al). + +## References + +- [Cust. Entry-Edit API](https://learn.microsoft.com/en-us/dynamics365/business-central/application/base-application/codeunit/microsoft.sales.receivables.cust.-entry-edit). +- [Vend. Entry-Edit API](https://learn.microsoft.com/en-us/dynamics365/business-central/application/base-application/codeunit/microsoft.purchases.payables.vend.-entry-edit). +- [BCApps: customer due-date synchronization](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Sales/Receivables/CustEntryEdit.Codeunit.al). +- [BCApps: vendor due-date synchronization](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Purchases/Payables/VendEntryEdit.Codeunit.al). diff --git a/microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.bad.al b/microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.bad.al new file mode 100644 index 0000000..2c5761c --- /dev/null +++ b/microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.bad.al @@ -0,0 +1,14 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50103 "Change Journal Dimension" +{ + procedure ChangeExistingDimension(TemplateName: Code[10]; BatchName: Code[10]; LineNo: Integer; DimensionCode: Code[20]; NewValue: Code[20]) + var + JournalLine: Record "Gen. Journal Line"; + DimensionSetEntry: Record "Dimension Set Entry"; + begin + JournalLine.Get(TemplateName, BatchName, LineNo); + DimensionSetEntry.Get(JournalLine."Dimension Set ID", DimensionCode); + DimensionSetEntry.Validate("Dimension Value Code", NewValue); + DimensionSetEntry.Modify(); + end; +} diff --git a/microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.good.al b/microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.good.al new file mode 100644 index 0000000..72d09b3 --- /dev/null +++ b/microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.good.al @@ -0,0 +1,18 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50103 "Change Journal Dimension" +{ + procedure ChangeExistingDimension(TemplateName: Code[10]; BatchName: Code[10]; LineNo: Integer; DimensionCode: Code[20]; NewValue: Code[20]) + var + JournalLine: Record "Gen. Journal Line"; + TempDimensionSetEntry: Record "Dimension Set Entry" temporary; + DimensionManagement: Codeunit DimensionManagement; + begin + JournalLine.Get(TemplateName, BatchName, LineNo); + DimensionManagement.GetDimensionSet(TempDimensionSetEntry, JournalLine."Dimension Set ID"); + TempDimensionSetEntry.Get(JournalLine."Dimension Set ID", DimensionCode); + TempDimensionSetEntry.Validate("Dimension Value Code", NewValue); + TempDimensionSetEntry.Modify(); + JournalLine.Validate("Dimension Set ID", DimensionManagement.GetDimensionSetID(TempDimensionSetEntry)); + JournalLine.Modify(true); + end; +} diff --git a/microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.md b/microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.md new file mode 100644 index 0000000..97b29f2 --- /dev/null +++ b/microsoft/knowledge/finance/do-not-edit-shared-dimension-sets.md @@ -0,0 +1,35 @@ +--- +bc-version: [all] +domain: finance +keywords: [dimension-set-entry, dimension-value-id, getdimensionset, getdimensionsetid, posted-dimensions, temporary] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Change a transaction's dimension set reference, not a shared set's membership + +## Description + +The same `Dimension Set ID` can be referenced by an unposted journal line and by many already-posted entries. Editing or deleting the persisted set's dimension/value rows therefore changes the meaning of unrelated transactions, including posting history. The dimension-set search tree also relies on those combinations remaining stable; a set is not a mutable child collection owned by one journal line. + +## Best Practice + +To change an unposted transaction's dimensions, load its set into a **temporary** `Dimension Set Entry` buffer with `DimensionManagement.GetDimensionSet`, change the buffer, and obtain a reusable ID with `GetDimensionSetID`. Validate dimension values in the buffer so `Dimension Value ID` matches the chosen value. Store the resulting ID on the transaction and synchronize its projections through that record's supported dimension validation. + +For already-posted G/L dimensions, use the supported dimension-correction workflow rather than changing shared rows. Read-only access, temporary buffers, and standard maintenance of projection metadata such as `Global Dimension No.` are not membership changes. This rule protects dimension sets reached from general-journal, financial-document, or Finance-ledger flows. It does not own Item, Value, Capacity, Warehouse, or inventory-application record writes, or prescribe custom-table/default-dimension wiring. + +See sample: [`do-not-edit-shared-dimension-sets.good.al`](do-not-edit-shared-dimension-sets.good.al). + +## Anti Pattern + +Follow a general-journal, financial-document, or Finance-ledger `Dimension Set ID` to a **persistent** `Dimension Set Entry` and modify, rename, or delete its dimension/value membership in order to change that one transaction. Inspect `IsTemporary` guards, aliases, and the fields written before reporting: the same operations on a temporary working copy are expected. + +See sample: [`do-not-edit-shared-dimension-sets.bad.al`](do-not-edit-shared-dimension-sets.bad.al). + +## References + +- [Dimension set entries overview](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-dimension-set-entries-overview). +- [Supported G/L dimension correction](https://learn.microsoft.com/en-us/dynamics365/business-central/finance-troubleshooting-correcting-dimensions). +- [DimensionManagement API](https://learn.microsoft.com/en-us/dynamics365/business-central/application/base-application/codeunit/microsoft.finance.dimension.dimensionmanagement). +- [BCApps: Dimension Set Entry and its set-ID resolver](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Finance/Dimension/DimensionSetEntry.Table.al). diff --git a/microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.bad.al b/microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.bad.al new file mode 100644 index 0000000..7160785 --- /dev/null +++ b/microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.bad.al @@ -0,0 +1,32 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50101 "Correct Posted Transaction" +{ + procedure RequestTransactionReversal(EntryNo: Integer) + var + GLEntry: Record "G/L Entry"; + begin + if not GuiAllowed() then + Error(InteractiveSessionErr); + GLEntry.Get(EntryNo); + GLEntry.TestField("Transaction No."); + GLEntry.Amount := -GLEntry.Amount; + GLEntry.Modify(true); + end; + + procedure UpdateDescription(EntryNo: Integer; NewDescription: Text[100]) + var + GLEntry: Record "G/L Entry"; + begin + GLEntry.Get(EntryNo); + GLEntry.Description := NewDescription; + Codeunit.Run(Codeunit::"G/L Entry-Edit", GLEntry); + end; + + procedure ClearSimulation(var TempGLEntry: Record "G/L Entry" temporary) + begin + TempGLEntry.DeleteAll(); + end; + + var + InteractiveSessionErr: Label 'Request the reversal from an interactive session.'; +} diff --git a/microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.good.al b/microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.good.al new file mode 100644 index 0000000..1aa2c8f --- /dev/null +++ b/microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.good.al @@ -0,0 +1,32 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50101 "Correct Posted Transaction" +{ + procedure RequestTransactionReversal(EntryNo: Integer) + var + GLEntry: Record "G/L Entry"; + ReversalEntry: Record "Reversal Entry"; + begin + if not GuiAllowed() then + Error(InteractiveSessionErr); + GLEntry.Get(EntryNo); + GLEntry.TestField("Transaction No."); + ReversalEntry.ReverseTransaction(GLEntry."Transaction No."); + end; + + procedure UpdateDescription(EntryNo: Integer; NewDescription: Text[100]) + var + GLEntry: Record "G/L Entry"; + begin + GLEntry.Get(EntryNo); + GLEntry.Description := NewDescription; + Codeunit.Run(Codeunit::"G/L Entry-Edit", GLEntry); + end; + + procedure ClearSimulation(var TempGLEntry: Record "G/L Entry" temporary) + begin + TempGLEntry.DeleteAll(); + end; + + var + InteractiveSessionErr: Label 'Request the reversal from an interactive session.'; +} diff --git a/microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.md b/microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.md new file mode 100644 index 0000000..33a8029 --- /dev/null +++ b/microsoft/knowledge/finance/do-not-modify-or-delete-posted-ledger-entries.md @@ -0,0 +1,37 @@ +--- +bc-version: [all] +domain: finance +keywords: [g-l-entry, ledger-entry, reversal, audit-trail, correction, financial-content, entry-edit] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Correct posted financial content through posting workflows, not row surgery + +## Description + +Changing a posted entry's original amount, account, posting date, or tax amounts in place does not correct the related ledger, register, or source document. Deleting one erroneous row has the same problem. Business Central provides reversing and correcting posting workflows that retain the relationship between the original transaction and its correction; this is not a blanket prohibition on every write to a posted table. + +## Best Practice + +Use a supported transaction/register reversal, credit memo, or correcting journal appropriate to the original posting and its current state. Request the standard reversal workflow rather than negating a single row or setting `Reversed` yourself. Let that workflow enforce eligibility; do not change source or application fields to make a rejected reversal pass. + +Supported operational edits are deliberate exceptions: for example, `"G/L Entry-Edit"` supports description changes, and `"Cust. Entry-Edit"` / `"Vend. Entry-Edit"` handle their table-specific editable fields. [Due-date synchronization](change-ledger-due-dates-through-entry-edit.md), [application/unapplication](apply-ledger-entries-through-application-codeunits.md), G/L dimension correction, and supported date compression have their own workflows. Do not flag their standard implementations, temporary simulation buffers, or extension-only metadata updates as financial row surgery. A subscriber is not exempt merely because it runs inside a supported workflow: inspect the fields it actually changes. + +This rule covers G/L, customer/vendor/detailed, VAT, and financial-posting/register records. Item, Value, Capacity, Warehouse, inventory-application, and other inventory-posting records are SCM concerns. The financial-row leg of one inventory-posting bypass is outside this rule when the same inventory correction resolves it; an independently actionable financial defect remains in scope regardless of the containing module's name. + +See sample: [`do-not-modify-or-delete-posted-ledger-entries.good.al`](do-not-modify-or-delete-posted-ledger-entries.good.al). + +## Anti Pattern + +Persist a change to original financial content, delete posted rows, or fabricate reversal flags/links to repair or undo a transaction outside the supported correction/maintenance workflow. Require an existing, non-temporary Finance-owned record and evidence of the fields or rows affected; a `Modify` token or `*Ledger Entry` name alone is insufficient. Settlement-state writes belong to the application article rather than a duplicate finding here. + +See sample: [`do-not-modify-or-delete-posted-ledger-entries.bad.al`](do-not-modify-or-delete-posted-ledger-entries.bad.al). + +## References + +- [Reverse journal postings](https://learn.microsoft.com/en-us/dynamics365/business-central/finance-how-reverse-journal-posting). +- [Correct G/L dimensions](https://learn.microsoft.com/en-us/dynamics365/business-central/finance-troubleshooting-correcting-dimensions). +- [BCApps: G/L Entry-Edit](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Finance/GeneralLedger/Ledger/GLEntryEdit.Codeunit.al). +- [BCApps: supported customer-ledger date compression](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Sales/Receivables/DateCompressCustomerLedger.Report.al). diff --git a/microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.bad.al b/microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.bad.al new file mode 100644 index 0000000..50ac8ff --- /dev/null +++ b/microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.bad.al @@ -0,0 +1,54 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50108 "Import Purchase Journal Total" +{ + procedure ImportExampleTotal(TemplateName: Code[10]; BatchName: Code[10]; LineNo: Integer) + var + JournalLine: Record "Gen. Journal Line"; + VATPostingSetup: Record "VAT Posting Setup"; + GeneralLedgerSetup: Record "General Ledger Setup"; + SourceInvoice: JsonObject; + NetToken: JsonToken; + VATToken: JsonToken; + GrossToken: JsonToken; + ImportedNet: Decimal; + ImportedVAT: Decimal; + ImportedGross: Decimal; + begin + SourceInvoice.ReadFrom('{"netAmount":100,"vatAmount":25,"grossAmount":125}'); + SourceInvoice.Get('netAmount', NetToken); + SourceInvoice.Get('vatAmount', VATToken); + SourceInvoice.Get('grossAmount', GrossToken); + ImportedNet := NetToken.AsValue().AsDecimal(); + ImportedVAT := VATToken.AsValue().AsDecimal(); + ImportedGross := GrossToken.AsValue().AsDecimal(); + if ImportedGross <> ImportedNet + ImportedVAT then + Error(TotalsErr); + + JournalLine.Get(TemplateName, BatchName, LineNo); + JournalLine.TestField("Account Type", JournalLine."Account Type"::"G/L Account"); + JournalLine.TestField("Bal. Account Type", JournalLine."Bal. Account Type"::"G/L Account"); + JournalLine.TestField("Account No."); + JournalLine.TestField("Bal. Account No."); + JournalLine.TestField("Currency Code", ''); + JournalLine.TestField("Gen. Posting Type", JournalLine."Gen. Posting Type"::Purchase); + JournalLine.TestField("VAT Posting", JournalLine."VAT Posting"::"Automatic VAT Entry"); + JournalLine.TestField("VAT Calculation Type", JournalLine."VAT Calculation Type"::"Normal VAT"); + JournalLine.TestField("VAT %", 25); + JournalLine.TestField("VAT Difference", 0); + JournalLine.TestField("Bal. Gen. Posting Type", JournalLine."Bal. Gen. Posting Type"::" "); + JournalLine.TestField("Bal. VAT %", 0); + VATPostingSetup.Get(JournalLine."VAT Bus. Posting Group", JournalLine."VAT Prod. Posting Group"); + VATPostingSetup.TestField("VAT Calculation Type", VATPostingSetup."VAT Calculation Type"::"Normal VAT"); + VATPostingSetup.TestField("VAT %", 25); + VATPostingSetup.TestField("Unrealized VAT Type", VATPostingSetup."Unrealized VAT Type"::" "); + GeneralLedgerSetup.Get(); + GeneralLedgerSetup.TestField("Additional Reporting Currency", ''); + GeneralLedgerSetup.TestField("Amount Rounding Precision", 0.01); + + JournalLine.Validate(Amount, ImportedNet); + JournalLine.Modify(true); + end; + + var + TotalsErr: Label 'The invoice total must equal its net amount plus VAT.'; +} diff --git a/microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.good.al b/microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.good.al new file mode 100644 index 0000000..961e234 --- /dev/null +++ b/microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.good.al @@ -0,0 +1,54 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50108 "Import Purchase Journal Total" +{ + procedure ImportExampleTotal(TemplateName: Code[10]; BatchName: Code[10]; LineNo: Integer) + var + JournalLine: Record "Gen. Journal Line"; + VATPostingSetup: Record "VAT Posting Setup"; + GeneralLedgerSetup: Record "General Ledger Setup"; + SourceInvoice: JsonObject; + NetToken: JsonToken; + VATToken: JsonToken; + GrossToken: JsonToken; + ImportedNet: Decimal; + ImportedVAT: Decimal; + ImportedGross: Decimal; + begin + SourceInvoice.ReadFrom('{"netAmount":100,"vatAmount":25,"grossAmount":125}'); + SourceInvoice.Get('netAmount', NetToken); + SourceInvoice.Get('vatAmount', VATToken); + SourceInvoice.Get('grossAmount', GrossToken); + ImportedNet := NetToken.AsValue().AsDecimal(); + ImportedVAT := VATToken.AsValue().AsDecimal(); + ImportedGross := GrossToken.AsValue().AsDecimal(); + if ImportedGross <> ImportedNet + ImportedVAT then + Error(TotalsErr); + + JournalLine.Get(TemplateName, BatchName, LineNo); + JournalLine.TestField("Account Type", JournalLine."Account Type"::"G/L Account"); + JournalLine.TestField("Bal. Account Type", JournalLine."Bal. Account Type"::"G/L Account"); + JournalLine.TestField("Account No."); + JournalLine.TestField("Bal. Account No."); + JournalLine.TestField("Currency Code", ''); + JournalLine.TestField("Gen. Posting Type", JournalLine."Gen. Posting Type"::Purchase); + JournalLine.TestField("VAT Posting", JournalLine."VAT Posting"::"Automatic VAT Entry"); + JournalLine.TestField("VAT Calculation Type", JournalLine."VAT Calculation Type"::"Normal VAT"); + JournalLine.TestField("VAT %", 25); + JournalLine.TestField("VAT Difference", 0); + JournalLine.TestField("Bal. Gen. Posting Type", JournalLine."Bal. Gen. Posting Type"::" "); + JournalLine.TestField("Bal. VAT %", 0); + VATPostingSetup.Get(JournalLine."VAT Bus. Posting Group", JournalLine."VAT Prod. Posting Group"); + VATPostingSetup.TestField("VAT Calculation Type", VATPostingSetup."VAT Calculation Type"::"Normal VAT"); + VATPostingSetup.TestField("VAT %", 25); + VATPostingSetup.TestField("Unrealized VAT Type", VATPostingSetup."Unrealized VAT Type"::" "); + GeneralLedgerSetup.Get(); + GeneralLedgerSetup.TestField("Additional Reporting Currency", ''); + GeneralLedgerSetup.TestField("Amount Rounding Precision", 0.01); + + JournalLine.Validate(Amount, ImportedGross); + JournalLine.Modify(true); + end; + + var + TotalsErr: Label 'The invoice total must equal its net amount plus VAT.'; +} diff --git a/microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.md b/microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.md new file mode 100644 index 0000000..6dda9ef --- /dev/null +++ b/microsoft/knowledge/finance/normal-vat-journal-amount-includes-vat.md @@ -0,0 +1,37 @@ +--- +bc-version: [all] +domain: finance +keywords: [normal-vat, automatic-vat-entry, gross-amount, net-amount, vat-posting-setup, gen-journal-line, purchase] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Supply a VAT-inclusive journal Amount for automatic Normal VAT + +## Description + +For a general-journal line using **Automatic VAT Entry** and **Normal VAT**, `Amount` includes VAT. The posting engine extracts tax from that total; it does not add tax to a VAT-exclusive expense imported into `Amount`. An LCY invoice with net 100 and VAT 25 therefore needs a journal total of 125, not 100. + +## Best Practice + +Map the source's VAT-inclusive total to journal `Amount` in this posting mode. Establish the intended account and posting-group combination before validating the final amount. Account-derived VAT defaults depend on `Copy VAT Setup to Jnl. Lines`; do not assume account selection always supplies the intended configuration. + +Require the actual input contract and calculation mode, not just a variable named `NetAmount`. The examples encode source net, VAT, and gross values plus a 25% Normal-VAT setup check. They target an LCY G/L purchase with 0.01 amount rounding and without balancing-side VAT, additional reporting currency, VAT differences, or unrealized VAT. Other calculation types, Manual VAT Entry, reverse charge, Full VAT, sales/use tax, unrealized tax, and other currency/rounding contexts need their own analysis; this is not a universal gross-up formula or country-specific tax advice. + +The concern is the supplied transaction total, not its deductible/non-deductible allocation. Non-deductible VAT features can change the allocation of that total, not turn the source's net amount into its gross amount. Do not infer a particular expense or deductible-VAT split from this rule. The samples therefore do not depend on later-version non-deductible-VAT fields. + +See sample: [`normal-vat-journal-amount-includes-vat.good.al`](normal-vat-journal-amount-includes-vat.good.al). + +## Anti Pattern + +In the demonstrated automatic Normal-VAT configuration, put a provably VAT-exclusive source amount into journal `Amount` while expecting posting to add tax. An amount assignment alone, unknown setup, or a suggestive variable name is insufficient. Do not report the correctly supplied gross amount or automatically rewrite tax calculations outside this scope. + +See sample: [`normal-vat-journal-amount-includes-vat.bad.al`](normal-vat-journal-amount-includes-vat.bad.al). + +## References + +- [VAT posting setup combinations](https://learn.microsoft.com/en-us/dynamics365/business-central/finance-setup-vat#combine-vat-posting-groups-in-vat-posting-setups). +- [BCApps: journal amount validation](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Finance/GeneralLedger/Journal/GenJournalLine.Table.al). +- [BCApps: Normal VAT extraction during posting](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Finance/GeneralLedger/Posting/GenJnlPostLine.Codeunit.al). +- [BCApps: journal VAT amount regression cases](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/Tests/VAT/ERMVATOnGenJournalLine.Codeunit.al). diff --git a/microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.bad.al b/microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.bad.al new file mode 100644 index 0000000..948976b --- /dev/null +++ b/microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.bad.al @@ -0,0 +1,60 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50100 "Post Transfer Journal" +{ + procedure PostTransferBatch(TemplateName: Code[10]; BatchName: Code[10]) + var + JournalLine: Record "Gen. Journal Line"; + LastGLEntry: Record "G/L Entry"; + NextEntryNo: Integer; + begin + JournalLine.SetRange("Journal Template Name", TemplateName); + JournalLine.SetRange("Journal Batch Name", BatchName); + if JournalLine.Count() <> 1 then + Error(SingleTransferErr); + JournalLine.FindFirst(); + JournalLine.TestField("Account Type", JournalLine."Account Type"::"G/L Account"); + JournalLine.TestField("Bal. Account Type", JournalLine."Bal. Account Type"::"G/L Account"); + JournalLine.TestField("Account No."); + JournalLine.TestField("Bal. Account No."); + JournalLine.TestField("Posting Date"); + JournalLine.TestField("Document No."); + JournalLine.TestField(Amount); + JournalLine.TestField("Currency Code", ''); + JournalLine.TestField("Gen. Posting Type", JournalLine."Gen. Posting Type"::" "); + JournalLine.TestField("Bal. Gen. Posting Type", JournalLine."Bal. Gen. Posting Type"::" "); + + LastGLEntry.LockTable(); + if LastGLEntry.FindLast() then + NextEntryNo := LastGLEntry."Entry No." + 1 + else + NextEntryNo := 1; + InsertLedgerRow(JournalLine, NextEntryNo, JournalLine."Account No.", JournalLine.Amount); + InsertLedgerRow(JournalLine, NextEntryNo + 1, JournalLine."Bal. Account No.", -JournalLine.Amount); + end; + + local procedure InsertLedgerRow(JournalLine: Record "Gen. Journal Line"; EntryNo: Integer; AccountNo: Code[20]; Amount: Decimal) + var + GLEntry: Record "G/L Entry"; + begin + GLEntry.Init(); + GLEntry."Entry No." := EntryNo; + GLEntry."G/L Account No." := AccountNo; + GLEntry."Posting Date" := JournalLine."Posting Date"; + GLEntry."Document Type" := JournalLine."Document Type"; + GLEntry."Document No." := JournalLine."Document No."; + GLEntry."Source Code" := JournalLine."Source Code"; + GLEntry."Journal Batch Name" := JournalLine."Journal Batch Name"; + GLEntry."Dimension Set ID" := JournalLine."Dimension Set ID"; + GLEntry."Global Dimension 1 Code" := JournalLine."Shortcut Dimension 1 Code"; + GLEntry."Global Dimension 2 Code" := JournalLine."Shortcut Dimension 2 Code"; + GLEntry.Amount := Amount; + if Amount > 0 then + GLEntry."Debit Amount" := Amount + else + GLEntry."Credit Amount" := -Amount; + GLEntry.Insert(true); + end; + + var + SingleTransferErr: Label 'Use a journal batch containing exactly one self-balancing G/L transfer.'; +} diff --git a/microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.good.al b/microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.good.al new file mode 100644 index 0000000..4d3bee3 --- /dev/null +++ b/microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.good.al @@ -0,0 +1,29 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50100 "Post Transfer Journal" +{ + procedure PostTransferBatch(TemplateName: Code[10]; BatchName: Code[10]) + var + JournalLine: Record "Gen. Journal Line"; + PostBatch: Codeunit "Gen. Jnl.-Post Batch"; + begin + JournalLine.SetRange("Journal Template Name", TemplateName); + JournalLine.SetRange("Journal Batch Name", BatchName); + if JournalLine.Count() <> 1 then + Error(SingleTransferErr); + JournalLine.FindFirst(); + JournalLine.TestField("Account Type", JournalLine."Account Type"::"G/L Account"); + JournalLine.TestField("Bal. Account Type", JournalLine."Bal. Account Type"::"G/L Account"); + JournalLine.TestField("Account No."); + JournalLine.TestField("Bal. Account No."); + JournalLine.TestField("Posting Date"); + JournalLine.TestField("Document No."); + JournalLine.TestField(Amount); + JournalLine.TestField("Currency Code", ''); + JournalLine.TestField("Gen. Posting Type", JournalLine."Gen. Posting Type"::" "); + JournalLine.TestField("Bal. Gen. Posting Type", JournalLine."Bal. Gen. Posting Type"::" "); + PostBatch.Run(JournalLine); + end; + + var + SingleTransferErr: Label 'Use a journal batch containing exactly one self-balancing G/L transfer.'; +} diff --git a/microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.md b/microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.md new file mode 100644 index 0000000..aefb6bb --- /dev/null +++ b/microsoft/knowledge/finance/post-ledger-entries-through-posting-codeunits.md @@ -0,0 +1,38 @@ +--- +bc-version: [all] +domain: finance +keywords: [g-l-entry, ledger-entry, gen-jnl-post-line, gen-jnl-post-batch, journal-line, register, insert] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Create financial ledger entries through the owning posting engine + +## Description + +Standard financial ledger entries are outputs of posting, not independent rows an extension manufactures. Even two manually inserted G/L rows with balanced amounts bypass posting checks, register bookkeeping, and transaction/source relationships. `G/L Entry.Insert(true)` runs the table trigger; it does not invoke the posting engine. + +## Best Practice + +Use the owning document or journal posting workflow. For a normal persisted general-journal batch, use `"Gen. Jnl.-Post Batch"`; the example posts an existing batch containing one self-balancing, non-VAT G/L transfer. Let posting allocate entries and maintain the register rather than reconstructing its tables. + +`"Gen. Jnl.-Post Line".RunWithCheck` is appropriate for a complete journal line inside a correctly owned posting lifecycle, but it does not invent a balancing account or document number, allocate numbering merely from `Posting No. Series`, or replace [batch document-balancing policy](preserve-journal-batch-document-balance.md). The line codeunit is stateful; its checked wrapper owns its start/continue/finish work. Normal batch posting owns its numbering and commits by default; do not imply these entry points are transaction-neutral. + +Exclude temporary buffers and the standard engine's own insertion points. A checked parent may legitimately use `RunWithoutCheck`; do not replace it without inspecting that parent. This rule owns `G/L Entry`, `Cust. Ledger Entry`, `Vendor Ledger Entry`, their detailed customer/vendor entries, `VAT Entry`, and financial-posting/register records, not a custom table merely named `Ledger Entry` or a supported, specifically reviewed migration/repair workflow. + +`Item Ledger Entry`, `Value Entry`, Capacity/Warehouse entries, `Item Application Entry`, and other inventory-posting records are SCM concerns, not this rule's financial-ledger scope. That exclusion includes the financial-row leg of a single inventory-posting bypass when restoring the inventory workflow corrects the whole operation. Distinct, independently actionable financial defects remain in scope. + +See sample: [`post-ledger-entries-through-posting-codeunits.good.al`](post-ledger-entries-through-posting-codeunits.good.al). + +## Anti Pattern + +Create posted financial effects by directly inserting the Finance-owned records named above outside their owning posting workflow. Resolve the actual record type, operation, and lifecycle; do not match `*Ledger Entry` as a wildcard. Balanced debit/credit values, copied dimensions, `Insert(true)`, and a lock around entry-number allocation do not turn raw inserts into a complete posting. + +See sample: [`post-ledger-entries-through-posting-codeunits.bad.al`](post-ledger-entries-through-posting-codeunits.bad.al). + +## References + +- [Posting engine structure](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-posting-engine-structure). +- [Gen. Jnl.-Post Line API](https://learn.microsoft.com/en-us/dynamics365/business-central/application/base-application/codeunit/microsoft.finance.generalledger.posting.gen.-jnl.-post-line). +- [BCApps: posting lifecycle and register maintenance](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Finance/GeneralLedger/Posting/GenJnlPostLine.Codeunit.al). diff --git a/microsoft/knowledge/finance/preserve-journal-batch-document-balance.bad.al b/microsoft/knowledge/finance/preserve-journal-batch-document-balance.bad.al new file mode 100644 index 0000000..1d5b5b3 --- /dev/null +++ b/microsoft/knowledge/finance/preserve-journal-batch-document-balance.bad.al @@ -0,0 +1,53 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50107 "Post Journal Allocation" +{ + procedure PostAllocation(TemplateName: Code[10]; BatchName: Code[10]; DebitAccount: Code[20]; CreditAccount: Code[20]; PostingDate: Date) + var + JournalTemplate: Record "Gen. Journal Template"; + JournalBatch: Record "Gen. Journal Batch"; + JournalLine: Record "Gen. Journal Line"; + LineToPost: Record "Gen. Journal Line"; + PostLine: Codeunit "Gen. Jnl.-Post Line"; + begin + JournalTemplate.Get(TemplateName); + JournalTemplate.TestField(Recurring, false); + JournalTemplate.TestField("Force Doc. Balance", true); + JournalTemplate.TestField("Source Code"); + JournalBatch.Get(TemplateName, BatchName); + JournalBatch.TestField("No. Series", ''); + JournalBatch.TestField("Posting No. Series", ''); + JournalLine.SetRange("Journal Template Name", TemplateName); + JournalLine.SetRange("Journal Batch Name", BatchName); + if not JournalLine.IsEmpty() then + Error(EmptyBatchErr); + + AddAllocationLine(JournalTemplate, BatchName, 10000, DebitAccount, PostingDate, 'ALLOC-A', 90); + AddAllocationLine(JournalTemplate, BatchName, 20000, CreditAccount, PostingDate, 'ALLOC-B', -90); + JournalLine.FindSet(); + repeat + LineToPost := JournalLine; + PostLine.RunWithCheck(LineToPost); + until JournalLine.Next() = 0; + end; + + local procedure AddAllocationLine(JournalTemplate: Record "Gen. Journal Template"; BatchName: Code[10]; LineNo: Integer; AccountNo: Code[20]; PostingDate: Date; DocumentNo: Code[20]; LineAmount: Decimal) + var + JournalLine: Record "Gen. Journal Line"; + begin + JournalLine.Init(); + JournalLine."Journal Template Name" := JournalTemplate.Name; + JournalLine."Journal Batch Name" := BatchName; + JournalLine."Line No." := LineNo; + JournalLine."Source Code" := JournalTemplate."Source Code"; + JournalLine.Validate("Posting Date", PostingDate); + JournalLine.Validate("Document No.", DocumentNo); + JournalLine.Validate("Account Type", JournalLine."Account Type"::"G/L Account"); + JournalLine.Validate("Account No.", AccountNo); + JournalLine.Validate("Gen. Posting Type", JournalLine."Gen. Posting Type"::" "); + JournalLine.Validate(Amount, LineAmount); + JournalLine.Insert(true); + end; + + var + EmptyBatchErr: Label 'Use an empty journal batch for this allocation.'; +} diff --git a/microsoft/knowledge/finance/preserve-journal-batch-document-balance.good.al b/microsoft/knowledge/finance/preserve-journal-batch-document-balance.good.al new file mode 100644 index 0000000..beff7f4 --- /dev/null +++ b/microsoft/knowledge/finance/preserve-journal-batch-document-balance.good.al @@ -0,0 +1,49 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50107 "Post Journal Allocation" +{ + procedure PostAllocation(TemplateName: Code[10]; BatchName: Code[10]; DebitAccount: Code[20]; CreditAccount: Code[20]; PostingDate: Date) + var + JournalTemplate: Record "Gen. Journal Template"; + JournalBatch: Record "Gen. Journal Batch"; + JournalLine: Record "Gen. Journal Line"; + PostBatch: Codeunit "Gen. Jnl.-Post Batch"; + begin + JournalTemplate.Get(TemplateName); + JournalTemplate.TestField(Recurring, false); + JournalTemplate.TestField("Force Doc. Balance", true); + JournalTemplate.TestField("Source Code"); + JournalBatch.Get(TemplateName, BatchName); + JournalBatch.TestField("No. Series", ''); + JournalBatch.TestField("Posting No. Series", ''); + JournalLine.SetRange("Journal Template Name", TemplateName); + JournalLine.SetRange("Journal Batch Name", BatchName); + if not JournalLine.IsEmpty() then + Error(EmptyBatchErr); + + AddAllocationLine(JournalTemplate, BatchName, 10000, DebitAccount, PostingDate, 'ALLOC-A', 90); + AddAllocationLine(JournalTemplate, BatchName, 20000, CreditAccount, PostingDate, 'ALLOC-A', -90); + JournalLine.FindFirst(); + PostBatch.Run(JournalLine); + end; + + local procedure AddAllocationLine(JournalTemplate: Record "Gen. Journal Template"; BatchName: Code[10]; LineNo: Integer; AccountNo: Code[20]; PostingDate: Date; DocumentNo: Code[20]; LineAmount: Decimal) + var + JournalLine: Record "Gen. Journal Line"; + begin + JournalLine.Init(); + JournalLine."Journal Template Name" := JournalTemplate.Name; + JournalLine."Journal Batch Name" := BatchName; + JournalLine."Line No." := LineNo; + JournalLine."Source Code" := JournalTemplate."Source Code"; + JournalLine.Validate("Posting Date", PostingDate); + JournalLine.Validate("Document No.", DocumentNo); + JournalLine.Validate("Account Type", JournalLine."Account Type"::"G/L Account"); + JournalLine.Validate("Account No.", AccountNo); + JournalLine.Validate("Gen. Posting Type", JournalLine."Gen. Posting Type"::" "); + JournalLine.Validate(Amount, LineAmount); + JournalLine.Insert(true); + end; + + var + EmptyBatchErr: Label 'Use an empty journal batch for this allocation.'; +} diff --git a/microsoft/knowledge/finance/preserve-journal-batch-document-balance.md b/microsoft/knowledge/finance/preserve-journal-batch-document-balance.md new file mode 100644 index 0000000..b3079ac --- /dev/null +++ b/microsoft/knowledge/finance/preserve-journal-batch-document-balance.md @@ -0,0 +1,35 @@ +--- +bc-version: [all] +domain: finance +keywords: [force-doc-balance, gen-journal-template, gen-jnl-post-batch, runwithcheck, document-no, posting-date, balancing] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Preserve the journal batch's document-balancing policy + +## Description + +A balanced G/L total does not prove that a general-journal batch satisfies its template's document-balancing policy. `"Gen. Jnl.-Post Batch"` checks balances at posting-date boundaries and, when the **journal template's** `Force Doc. Balance` is enabled, document-type/document-number boundaries. A loop over `"Gen. Jnl.-Post Line".RunWithCheck` does not reproduce these batch-level checks. + +## Best Practice + +Post normal persisted general-journal batches through their owning batch workflow. Keep balancing lines in the appropriate document/date group when the template requires it. The examples use two LCY G/L lines: opposite amounts under different document numbers are not a document-balanced transfer when `Force Doc. Balance` is true; the good example groups them under one document and retains the batch checks. + +Do not claim every document must always balance: when that template option is false, the supported workflow can allow document imbalance while still checking the required aggregate balances. Standalone self-balancing line posting and purpose-built posting engines that demonstrably own equivalent aggregate policies are not prohibited. A `RunWithCheck` call or loop alone is not sufficient evidence of a defect. + +See sample: [`preserve-journal-batch-document-balance.good.al`](preserve-journal-batch-document-balance.good.al). + +## Anti Pattern + +Replace a normal persisted journal batch's posting path with per-line posting or only an aggregate-total check, bypassing a demonstrated template/document/date policy. For the document-imbalance finding, require evidence that `Force Doc. Balance` applies and that separate document groups can be unbalanced; do not infer the setting from its name or a comment alone. + +See sample: [`preserve-journal-batch-document-balance.bad.al`](preserve-journal-batch-document-balance.bad.al). + +## References + +- [Work with general journals](https://learn.microsoft.com/en-us/dynamics365/business-central/ui-work-general-journals). +- [Gen. Jnl.-Post Batch API](https://learn.microsoft.com/en-us/dynamics365/business-central/application/base-application/codeunit/microsoft.finance.generalledger.posting.gen.-jnl.-post-batch). +- [BCApps: batch balance checks](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Finance/GeneralLedger/Posting/GenJnlPostBatch.Codeunit.al). +- [BCApps: document-balance option regression cases](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/Tests/General%20Journal/ERMTestMultipleGenJnlLines.Codeunit.al). diff --git a/microsoft/knowledge/finance/reverse-transactions-by-transaction-number.bad.al b/microsoft/knowledge/finance/reverse-transactions-by-transaction-number.bad.al new file mode 100644 index 0000000..9f5d311 --- /dev/null +++ b/microsoft/knowledge/finance/reverse-transactions-by-transaction-number.bad.al @@ -0,0 +1,18 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50106 "Reverse Selected Posting" +{ + procedure RequestReversal(SelectedEntryNo: Integer) + var + GLEntry: Record "G/L Entry"; + ReversalEntry: Record "Reversal Entry"; + begin + if not GuiAllowed() then + Error(InteractiveSessionErr); + GLEntry.Get(SelectedEntryNo); + GLEntry.TestField("Transaction No."); + ReversalEntry.ReverseTransaction(GLEntry."Entry No."); + end; + + var + InteractiveSessionErr: Label 'Request the reversal from an interactive session.'; +} diff --git a/microsoft/knowledge/finance/reverse-transactions-by-transaction-number.good.al b/microsoft/knowledge/finance/reverse-transactions-by-transaction-number.good.al new file mode 100644 index 0000000..392d3cd --- /dev/null +++ b/microsoft/knowledge/finance/reverse-transactions-by-transaction-number.good.al @@ -0,0 +1,18 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50106 "Reverse Selected Posting" +{ + procedure RequestReversal(SelectedEntryNo: Integer) + var + GLEntry: Record "G/L Entry"; + ReversalEntry: Record "Reversal Entry"; + begin + if not GuiAllowed() then + Error(InteractiveSessionErr); + GLEntry.Get(SelectedEntryNo); + GLEntry.TestField("Transaction No."); + ReversalEntry.ReverseTransaction(GLEntry."Transaction No."); + end; + + var + InteractiveSessionErr: Label 'Request the reversal from an interactive session.'; +} diff --git a/microsoft/knowledge/finance/reverse-transactions-by-transaction-number.md b/microsoft/knowledge/finance/reverse-transactions-by-transaction-number.md new file mode 100644 index 0000000..296d902 --- /dev/null +++ b/microsoft/knowledge/finance/reverse-transactions-by-transaction-number.md @@ -0,0 +1,34 @@ +--- +bc-version: [all] +domain: finance +keywords: [reversetransaction, reverseregister, transaction-no, entry-no, reversal-entry, g-l-register] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Pass the transaction number, not a ledger-entry number, to ReverseTransaction + +## Description + +`Reversal Entry.ReverseTransaction` expects a **transaction number**, while `ReverseRegister` expects a **G/L register number**. Neither parameter means a ledger `Entry No.`. All are integers, so the compiler accepts the wrong identity; a coincidentally matching integer can select another transaction instead of the posting the user intended to reverse. + +## Best Practice + +When starting from a `G/L Entry`, fetch that entry and pass **its** `Transaction No.` to `Reversal Entry.ReverseTransaction`, as the sample does. The same identity distinction applies to customer/vendor ledger entries when using their supported transaction-reversal path. If the starting point is a G/L register, use `Reversal Entry.ReverseRegister` with that register's number. The interactive workflow collects the participating entries and validates reversal eligibility before the user posts the reversal. + +Do not infer eligibility from `Open` alone or bypass a rejection by changing origin, application, or reversal fields. The supported path depends on source and state; some postings require unapplication or a correcting document first. A request to reverse is not a guarantee that reversal will be permitted. This rule concerns the two named `Reversal Entry` APIs, not routines such as `UnApplyCustLedgEntry` that legitimately accept a ledger entry number. + +See sample: [`reverse-transactions-by-transaction-number.good.al`](reverse-transactions-by-transaction-number.good.al). + +## Anti Pattern + +Pass a ledger entry's `Entry No.` or a register number into `ReverseTransaction`, or pass a ledger-entry/transaction number into `ReverseRegister`. Require visible value provenance, not merely a suspicious variable name or an arbitrary integer. A correctly sourced transaction number is valid even when the variable is poorly named. + +See sample: [`reverse-transactions-by-transaction-number.bad.al`](reverse-transactions-by-transaction-number.bad.al). + +## References + +- [Reversal Entry API](https://learn.microsoft.com/en-us/dynamics365/business-central/application/base-application/table/microsoft.finance.generalledger.reversal.reversal-entry). +- [Reverse journal postings](https://learn.microsoft.com/en-us/dynamics365/business-central/finance-how-reverse-journal-posting). +- [BCApps: reversal entry selection](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Finance/GeneralLedger/Reversal/ReversalEntry.Table.al). diff --git a/microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.bad.al b/microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.bad.al new file mode 100644 index 0000000..f54d42b --- /dev/null +++ b/microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.bad.al @@ -0,0 +1,20 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50102 "Copy Journal Dimensions" +{ + procedure CopyAllLineDimensions(TemplateName: Code[10]; BatchName: Code[10]; SourceLineNo: Integer; TargetLineNo: Integer) + var + SourceLine: Record "Gen. Journal Line"; + TargetLine: Record "Gen. Journal Line"; + begin + SourceLine.Get(TemplateName, BatchName, SourceLineNo); + TargetLine.Get(TemplateName, BatchName, TargetLineNo); + TargetLine."Shortcut Dimension 1 Code" := SourceLine."Shortcut Dimension 1 Code"; + TargetLine."Shortcut Dimension 2 Code" := SourceLine."Shortcut Dimension 2 Code"; + TargetLine.Modify(true); + end; + + procedure HasShortcutDimension1(JournalLine: Record "Gen. Journal Line"; DimensionValue: Code[20]): Boolean + begin + exit(JournalLine."Shortcut Dimension 1 Code" = DimensionValue); + end; +} diff --git a/microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.good.al b/microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.good.al new file mode 100644 index 0000000..330c0de --- /dev/null +++ b/microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.good.al @@ -0,0 +1,19 @@ +// Demonstration only; independently authored, not copied from BaseApp. +codeunit 50102 "Copy Journal Dimensions" +{ + procedure CopyAllLineDimensions(TemplateName: Code[10]; BatchName: Code[10]; SourceLineNo: Integer; TargetLineNo: Integer) + var + SourceLine: Record "Gen. Journal Line"; + TargetLine: Record "Gen. Journal Line"; + begin + SourceLine.Get(TemplateName, BatchName, SourceLineNo); + TargetLine.Get(TemplateName, BatchName, TargetLineNo); + TargetLine.Validate("Dimension Set ID", SourceLine."Dimension Set ID"); + TargetLine.Modify(true); + end; + + procedure HasShortcutDimension1(JournalLine: Record "Gen. Journal Line"; DimensionValue: Code[20]): Boolean + begin + exit(JournalLine."Shortcut Dimension 1 Code" = DimensionValue); + end; +} diff --git a/microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.md b/microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.md new file mode 100644 index 0000000..0764f20 --- /dev/null +++ b/microsoft/knowledge/finance/write-dimensions-as-dimension-set-entries.md @@ -0,0 +1,34 @@ +--- +bc-version: [all] +domain: finance +keywords: [dimension-set-id, shortcut-dimension, global-dimension, journal-line, posting, copy-dimensions] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Copy complete posting dimension sets, not only shortcut projections + +## Description + +When a journal line or posting document inherits dimensions, its `Dimension Set ID` identifies the complete combination of `Dimension Set Entry` rows. Global and shortcut dimensions expose selected dimensions, not the complete set; the eight shortcut dimensions are not a limit on set membership. Copying only these projections can leave the destination's posting dimensions unchanged or silently lose dimensions outside the shortcuts. + +## Best Practice + +For an intentional **complete** dimension transfer, copy the source set ID and synchronize the destination's projections through its supported validation or dimension-management routine. On `Gen. Journal Line`, `Validate("Dimension Set ID", SourceSetID)` updates the two shortcut fields. Do not assume another table has the same validation trigger. + +When line-specific dimensions must survive a header change, use the appropriate set-combination or delta routine instead of blindly replacing the line's entire set. Reading or filtering a known global dimension is legitimate; it is not a claim to enumerate every dimension. This rule owns transfers through general-journal and financial-document posting records, not writes to Item, Value, Capacity, Warehouse, or inventory-application records owned by SCM. Generic custom-table or master `Default Dimension` wiring belongs to data modeling. + +See sample: [`write-dimensions-as-dimension-set-entries.good.al`](write-dimensions-as-dimension-set-entries.good.al). + +## Anti Pattern + +A routine intended to copy **all** posting dimensions copies only global/shortcut codes, or assigns a set ID without synchronizing the destination's stored projections. Require evidence of a complete-transfer intent and inspect surrounding validation; an explicit change to one selected dimension or a read-only filter is not this defect. + +See sample: [`write-dimensions-as-dimension-set-entries.bad.al`](write-dimensions-as-dimension-set-entries.bad.al). + +## References + +- [Dimension set entries overview](https://learn.microsoft.com/en-us/dynamics365/business-central/design-details-dimension-set-entries-overview). +- [DimensionManagement API](https://learn.microsoft.com/en-us/dynamics365/business-central/application/base-application/codeunit/microsoft.finance.dimension.dimensionmanagement). +- [BCApps: Gen. Journal Line dimension validation](https://github.com/microsoft/BCApps/blob/8f7a04cb0db8aa96cb97e055c45c61aead49e280/src/Layers/W1/BaseApp/Finance/GeneralLedger/Journal/GenJournalLine.Table.al). diff --git a/microsoft/skills/review/al-code-review.md b/microsoft/skills/review/al-code-review.md index 7cfe07b..df476f3 100644 --- a/microsoft/skills/review/al-code-review.md +++ b/microsoft/skills/review/al-code-review.md @@ -29,6 +29,7 @@ sub-skills: - microsoft/skills/review/al-appsource-review.md - microsoft/skills/review/al-telemetry-review.md - microsoft/skills/review/al-scm-review.md + - microsoft/skills/review/al-finance-review.md --- # AL code review diff --git a/microsoft/skills/review/al-finance-review.md b/microsoft/skills/review/al-finance-review.md new file mode 100644 index 0000000..06090b1 --- /dev/null +++ b/microsoft/skills/review/al-finance-review.md @@ -0,0 +1,146 @@ +--- +kind: action-skill +id: al-finance-review +version: 1 +title: AL Finance review +description: Reviews financial journal posting, ledger corrections, applications, VAT handling, and posting-linked dimensions against BCQuality Finance guidance. +inputs: [pr-diff, file-path, folder-path] +outputs: [findings-report] +bc-version: [all] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# AL Finance review + +Reviews the `finance` knowledge domain. This is a leaf action skill composed by +`al-code-review`; it invokes no other skills. Application-area metadata does +not gate Finance coverage; resolved source records and operations do. + +## Source + +Apply the source-surface gate in Relevance before retrieving knowledge. +If it passes, use READ's **Bounded retrieval for review skills** workflow with +`-Domain finance`. Consume every catalog page across enabled layers, preserving +each exact path and applicability metadata. Do not select a top-k catalog or +deduplicate by basename. Open complete bodies only for exact Worklist paths, +in stable chunks of at most eight, consuming every continuation. If the helper +or prepared index is unavailable or invalid, use READ's explicit path-discovery +and bounded native-read fallback; a retrieval error is not an empty corpus. + +## Relevance + +Apply READ's frontmatter matching rules using only known task dimensions. +Use the target application version from `app.json` when available; do not invent +a country or application area from a filename or UI `ApplicationArea` token. +Retain conditional articles only when configured, cap resulting confidence at +`medium`, and name every unknown dimension in the finding. + +Inspect the supplied AL scope and its enclosing declarations. Admit only +changed executable behavior involving at least one of these surfaces: + +- General-journal construction or posting, journal-batch processing, or an + event subscriber whose resolved publisher is in the financial posting path. +- Writes or correction/application/reversal calls involving `G/L Entry`, + `Cust. Ledger Entry`, `Vendor Ledger Entry`, `Detailed Cust. Ledg. Entry`, + `Detailed Vendor Ledg. Entry`, `VAT Entry`, or financial-posting/G/L-register + records. +- Dimension transfer or dimension-set mutation connected by visible data flow + to an existing general journal, financial posting document, or Finance-owned + ledger record. + +Exclude `Item Ledger Entry`, `Value Entry`, Capacity/Warehouse entries, +`Item Application Entry`, and other inventory-posting records owned by SCM. +Do not adopt their findings when the SCM skill is absent or disabled. For one +inventory-originated posting bypass, equivalent findings have one SCM primary +owner; distinct independent financial defects remain Finance. Classify the +operation and actual record, not an inventory/finance word in a module name. + +Return `not-applicable` when none is present. Imports, object names, comments, +read-only ledger displays, generic `Amount`/`Date`/`Open` fields, and calls to +`DimensionManagement` without posting-linked context do not establish relevance. +For a diff, retain surrounding variable types, field provenance, event +attributes, and reachable helpers; do not review isolated added lines without +the context needed to classify their record or call. + +## Worklist + +Match the complete relevant catalog's keywords, titles, and descriptions to +the admitted source surfaces. Add an exact catalog path only when its concern +maps to the changed behavior; generic financial vocabulary is not enough. +The following deterministic cues must select their named articles even if +keyword ranking would otherwise omit them: + +- Persistent Finance-owned ledger inserts reached from extension posting + code — `post-ledger-entries-through-posting-codeunits`. +- Persisted general-journal lines posted through a line-codeunit loop or custom + aggregate check, with visible template/document/date balancing context — + `preserve-journal-batch-document-balance`. +- Imported net/tax/gross values mapped into `Gen. Journal Line.Amount`, with + evidence of the VAT posting mode and posting-setup combination — + `normal-vat-journal-amount-includes-vat`. +- Persisted original Finance accounting-value changes, deletion of Finance rows, or + fabricated reversal flags/links — `do-not-modify-or-delete-posted-ledger-entries`. +- Customer/vendor settlement/reopening code writing `Open`, closure fields, + detailed customer/vendor application amounts, or unapplication flags — + `apply-ledger-entries-through-application-codeunits`. +- A due-date change persisted on an existing customer/vendor ledger entry — + `change-ledger-due-dates-through-entry-edit`. +- A `Reversal Entry.ReverseTransaction` or `ReverseRegister` argument with + visible ledger-entry, transaction, or register provenance — + `reverse-transactions-by-transaction-number`. +- A complete Finance posting-dimension transfer represented by shortcut/global + fields or a `Dimension Set ID` assignment — + `write-dimensions-as-dimension-set-entries`. +- A dimension/value membership change on `Dimension Set Entry`, reached from + a general-journal/financial-document/Finance-ledger set ID — + `do-not-edit-shared-dimension-sets`. + +These are retrieval cues, not findings. Use the selected articles' normative +exceptions and ownership boundaries to classify standard workflows, temporary +records, operational edits, and extension fields. Do not select a Finance +ledger rule from `*Ledger Entry` or `Insert`/`Modify` alone. Finance does not +own SCM records, generic custom-table/master dimension wiring, number-series +API migration, or general AL validation, locking, transaction, and event-style +advice. Do not add those concerns as Finance agent findings. + +Resolve actual normative conflicts across layers per READ and record suppressed +candidates per DO. Keep every remaining exact path in a stable worklist. +Return `no-knowledge` if no applicable Finance knowledge survives filtering or +configuration; return `completed` with no findings when applicable knowledge +exists but no article matches the admitted changes. + +## Action + +Evaluate every worklist article in full against the changed behavior and its +surrounding control flow. Establish record type, existing versus newly prepared +state, temporariness, fields actually persisted, argument provenance, and the +posting/edit API boundary before emitting a finding. Do not infer a financial +defect from a method name, missing external setup, or unsupported speculation +about callers. + +Use the most specific article for the correction: application-state, due-date, +and shared-dimension findings must not also become generic posted-row findings +for the same change. Do not emit an equivalent Finance finding for the +financial-row leg of one SCM-owned inventory posting bypass; evaluate a +distinct financial defect only when its corrective action is independent. +Emit `major` for a demonstrated financial-correctness +violation and reserve `blocker` for directly evidenced destructive corruption +under DO's severity rules. Applicability alone produces no finding. + +Set `high` confidence only for established source evidence and known matching +context. Domain-scoped agent findings follow DO's precision bar and remain +capped at `minor`/`medium`; do not broaden this pass into other AL domains. +Provide literal `suggested-code` for complete, local, unambiguous fixes. +Otherwise give `suggested-code-omission-reason`, particularly when selecting +the correct posting workflow requires business context. + +Follow DO's acceptance gate and outcome rules. Report `partial` rather than +silently dropping worklist items when a budget is reached, and `failed` for an +unrecoverable retrieval or evaluation error. + +## Output + +Output conforms to the DO findings-report contract. Every finding this skill +emits MUST set `findings[].domain` to `"Finance"`. From 0a8c9a85560204e2fe75a1180767330bcfb62581 Mon Sep 17 00:00:00 2001 From: Michael Dieringer <65093775+MichaelDieringer@users.noreply.github.com> Date: Tue, 29 Sep 2026 12:48:17 +0200 Subject: [PATCH 26/35] 18 AL/BC patterns: style, data-modeling, web-services, appsource, breaking-changes, performance, testing (#156) * 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 * 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 * 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 * 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 --- .../appsource/file-datatype-saas.bad.al | 13 +++ .../appsource/file-datatype-saas.good.al | 24 +++++ .../knowledge/appsource/file-datatype-saas.md | 28 ++++++ .../prefer-email-module.bad.al | 9 ++ .../prefer-email-module.good.al | 11 +++ .../breaking-changes/prefer-email-module.md | 28 ++++++ .../check-post-line-batch-pattern.bad.al | 22 +++++ .../check-post-line-batch-pattern.good.al | 42 +++++++++ .../check-post-line-batch-pattern.md | 28 ++++++ .../dimension-management-wiring.bad.al | 13 +++ .../dimension-management-wiring.good.al | 89 +++++++++++++++++++ .../dimension-management-wiring.md | 35 ++++++++ .../do-not-change-primary-key.bad.al | 14 +++ .../do-not-change-primary-key.good.al | 24 +++++ .../do-not-change-primary-key.md | 28 ++++++ .../testfield-required-setup-field.bad.al | 12 +++ .../testfield-required-setup-field.good.al | 9 ++ .../testfield-required-setup-field.md | 28 ++++++ .../document-report-word-layout.bad.al | 16 ++++ .../document-report-word-layout.good.al | 17 ++++ .../document-report-word-layout.md | 34 +++++++ ...ld-output-must-not-pollute-project-root.md | 24 +++++ .../style/al-identifiers-english.bad.al | 11 +++ .../style/al-identifiers-english.good.al | 11 +++ .../knowledge/style/al-identifiers-english.md | 28 ++++++ .../binary-choice-must-be-boolean.bad.al | 22 +++++ .../binary-choice-must-be-boolean.good.al | 16 ++++ .../style/binary-choice-must-be-boolean.md | 28 ++++++ ...hoice-set-must-use-enum-not-integer.bad.al | 22 +++++ ...oice-set-must-use-enum-not-integer.good.al | 17 ++++ ...ed-choice-set-must-use-enum-not-integer.md | 28 ++++++ ...al-functions-must-use-modern-casing.bad.al | 12 +++ ...l-functions-must-use-modern-casing.good.al | 12 +++ ...sic-al-functions-must-use-modern-casing.md | 28 ++++++ ...espace-must-be-verified-from-source.bad.al | 13 +++ ...space-must-be-verified-from-source.good.al | 16 ++++ .../namespace-must-be-verified-from-source.md | 28 ++++++ ...ers-require-an-addressable-variable.bad.al | 15 ++++ ...rs-require-an-addressable-variable.good.al | 17 ++++ ...ameters-require-an-addressable-variable.md | 28 ++++++ ...st-data-must-be-random-and-complete.bad.al | 14 +++ ...t-data-must-be-random-and-complete.good.al | 13 +++ .../test-data-must-be-random-and-complete.md | 30 +++++++ ...y-fields-must-be-editable-on-insert.bad.al | 27 ++++++ ...-fields-must-be-editable-on-insert.good.al | 25 ++++++ ...e-key-fields-must-be-editable-on-insert.md | 28 ++++++ ...fields-must-not-be-exposed-directly.bad.al | 24 +++++ ...ields-must-not-be-exposed-directly.good.al | 33 +++++++ ...ved-fields-must-not-be-exposed-directly.md | 28 ++++++ .../skills/review/al-appsource-review.md | 1 + .../review/al-breaking-changes-review.md | 4 +- .../skills/review/al-data-modeling-review.md | 4 + .../skills/review/al-performance-review.md | 1 + microsoft/skills/review/al-style-review.md | 12 ++- microsoft/skills/review/al-testing-review.md | 1 + .../skills/review/al-web-services-review.md | 2 + 56 files changed, 1144 insertions(+), 3 deletions(-) create mode 100644 microsoft/knowledge/appsource/file-datatype-saas.bad.al create mode 100644 microsoft/knowledge/appsource/file-datatype-saas.good.al create mode 100644 microsoft/knowledge/appsource/file-datatype-saas.md create mode 100644 microsoft/knowledge/breaking-changes/prefer-email-module.bad.al create mode 100644 microsoft/knowledge/breaking-changes/prefer-email-module.good.al create mode 100644 microsoft/knowledge/breaking-changes/prefer-email-module.md create mode 100644 microsoft/knowledge/data-modeling/check-post-line-batch-pattern.bad.al create mode 100644 microsoft/knowledge/data-modeling/check-post-line-batch-pattern.good.al create mode 100644 microsoft/knowledge/data-modeling/check-post-line-batch-pattern.md create mode 100644 microsoft/knowledge/data-modeling/dimension-management-wiring.bad.al create mode 100644 microsoft/knowledge/data-modeling/dimension-management-wiring.good.al create mode 100644 microsoft/knowledge/data-modeling/dimension-management-wiring.md create mode 100644 microsoft/knowledge/data-modeling/do-not-change-primary-key.bad.al create mode 100644 microsoft/knowledge/data-modeling/do-not-change-primary-key.good.al create mode 100644 microsoft/knowledge/data-modeling/do-not-change-primary-key.md create mode 100644 microsoft/knowledge/data-modeling/testfield-required-setup-field.bad.al create mode 100644 microsoft/knowledge/data-modeling/testfield-required-setup-field.good.al create mode 100644 microsoft/knowledge/data-modeling/testfield-required-setup-field.md create mode 100644 microsoft/knowledge/performance/document-report-word-layout.bad.al create mode 100644 microsoft/knowledge/performance/document-report-word-layout.good.al create mode 100644 microsoft/knowledge/performance/document-report-word-layout.md create mode 100644 microsoft/knowledge/style/al-build-output-must-not-pollute-project-root.md create mode 100644 microsoft/knowledge/style/al-identifiers-english.bad.al create mode 100644 microsoft/knowledge/style/al-identifiers-english.good.al create mode 100644 microsoft/knowledge/style/al-identifiers-english.md create mode 100644 microsoft/knowledge/style/binary-choice-must-be-boolean.bad.al create mode 100644 microsoft/knowledge/style/binary-choice-must-be-boolean.good.al create mode 100644 microsoft/knowledge/style/binary-choice-must-be-boolean.md create mode 100644 microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.bad.al create mode 100644 microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.good.al create mode 100644 microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.md create mode 100644 microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.bad.al create mode 100644 microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.good.al create mode 100644 microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.md create mode 100644 microsoft/knowledge/style/namespace-must-be-verified-from-source.bad.al create mode 100644 microsoft/knowledge/style/namespace-must-be-verified-from-source.good.al create mode 100644 microsoft/knowledge/style/namespace-must-be-verified-from-source.md create mode 100644 microsoft/knowledge/style/var-parameters-require-an-addressable-variable.bad.al create mode 100644 microsoft/knowledge/style/var-parameters-require-an-addressable-variable.good.al create mode 100644 microsoft/knowledge/style/var-parameters-require-an-addressable-variable.md create mode 100644 microsoft/knowledge/testing/test-data-must-be-random-and-complete.bad.al create mode 100644 microsoft/knowledge/testing/test-data-must-be-random-and-complete.good.al create mode 100644 microsoft/knowledge/testing/test-data-must-be-random-and-complete.md create mode 100644 microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.bad.al create mode 100644 microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.good.al create mode 100644 microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.md create mode 100644 microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.bad.al create mode 100644 microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.good.al create mode 100644 microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.md diff --git a/microsoft/knowledge/appsource/file-datatype-saas.bad.al b/microsoft/knowledge/appsource/file-datatype-saas.bad.al new file mode 100644 index 0000000..05ab0ff --- /dev/null +++ b/microsoft/knowledge/appsource/file-datatype-saas.bad.al @@ -0,0 +1,13 @@ +codeunit 50104 "Import File Reader" +{ + procedure ImportFile() + var + ImportFile: File; + InStream: InStream; + begin + ImportFile.WriteMode(false); + ImportFile.TextMode(true); + ImportFile.Open('C:\Import\data.txt'); // fails in SaaS — no local filesystem + ImportFile.CreateInStream(InStream); + end; +} diff --git a/microsoft/knowledge/appsource/file-datatype-saas.good.al b/microsoft/knowledge/appsource/file-datatype-saas.good.al new file mode 100644 index 0000000..8703c33 --- /dev/null +++ b/microsoft/knowledge/appsource/file-datatype-saas.good.al @@ -0,0 +1,24 @@ +codeunit 50104 "Import File Reader" +{ + procedure ImportFile() + var + TempBlob: Codeunit "Temp Blob"; + FromInStream: InStream; + ToOutStream: OutStream; + InStream: InStream; + begin + if not UploadIntoStream('All Files (*.*)|*.*', FromInStream) then + exit; + + TempBlob.CreateOutStream(ToOutStream); + CopyStream(ToOutStream, FromInStream); + + TempBlob.CreateInStream(InStream); + ParseStream(InStream); + end; + + local procedure ParseStream(var InStream: InStream) + begin + // parse InStream content here + end; +} diff --git a/microsoft/knowledge/appsource/file-datatype-saas.md b/microsoft/knowledge/appsource/file-datatype-saas.md new file mode 100644 index 0000000..f46a565 --- /dev/null +++ b/microsoft/knowledge/appsource/file-datatype-saas.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: appsource +keywords: [file-datatype, saas, onprem, uploadintostream, downloadfromstream, instream, outstream, streaming] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# The File data type's direct I/O methods are OnPrem-only + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +The classic `File` variable type — `Open`/`Create`/`Read`/`Write`/`Close` against a path on the local or server filesystem — is scoped OnPrem-only. Code targeting Business Central Online that calls `File.Open`, `File.Create`, `File.Read`, or `File.Write` fails to compile against a Cloud-scoped project; it does not compile successfully and fail or get silently skipped at runtime. Separately, and regardless of the compile-time scoping, no server/local filesystem path is available to an extension actually running in Business Central Online. + +## Best Practice + +Use the stream-based equivalents: `UploadIntoStream` to read user-selected file content into an `InStream`, and `DownloadFromStream` to write an `OutStream`'s content to a file the user saves. Stage the content in a `TempBlob` between the stream and the rest of the parsing/formatting code. + +See sample: [`file-datatype-saas.good.al`](file-datatype-saas.good.al). + +## Anti Pattern + +Opening a hardcoded or user-supplied filesystem path with the `File` variable type. This is a strong signal the code was written for on-premises only, or copied from material that predates the cloud-first streaming APIs. + +See sample: [`file-datatype-saas.bad.al`](file-datatype-saas.bad.al). diff --git a/microsoft/knowledge/breaking-changes/prefer-email-module.bad.al b/microsoft/knowledge/breaking-changes/prefer-email-module.bad.al new file mode 100644 index 0000000..78e593f --- /dev/null +++ b/microsoft/knowledge/breaking-changes/prefer-email-module.bad.al @@ -0,0 +1,9 @@ +codeunit 50103 "Order Confirmation Notifier" +{ + procedure Send(ToAddress: Text; Subject: Text; Body: Text) + var + Mail: Codeunit Mail; + begin + Mail.CreateMessage(ToAddress, '', '', Subject, Body, false, false); + end; +} diff --git a/microsoft/knowledge/breaking-changes/prefer-email-module.good.al b/microsoft/knowledge/breaking-changes/prefer-email-module.good.al new file mode 100644 index 0000000..c9a1da4 --- /dev/null +++ b/microsoft/knowledge/breaking-changes/prefer-email-module.good.al @@ -0,0 +1,11 @@ +codeunit 50103 "Order Confirmation Notifier" +{ + procedure Send(ToAddress: Text; Subject: Text; Body: Text) + var + Email: Codeunit Email; + EmailMessage: Codeunit "Email Message"; + begin + EmailMessage.Create(ToAddress, Subject, Body, true); + Email.Send(EmailMessage, Enum::"Email Scenario"::Default); + end; +} diff --git a/microsoft/knowledge/breaking-changes/prefer-email-module.md b/microsoft/knowledge/breaking-changes/prefer-email-module.md new file mode 100644 index 0000000..6c04b37 --- /dev/null +++ b/microsoft/knowledge/breaking-changes/prefer-email-module.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: breaking-changes +keywords: [email, codeunit-mail, email-message, email-scenario, email-account, smtp, sending-email] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Send email through the Email module, not Codeunit Mail (397) + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +Older AL code sends email by calling `Codeunit Mail (397)`. Business Central's current extensibility model is a different, richer object set — `Codeunit Email`, `Codeunit "Email Message"`, `enum "Email Scenario"`, and the `Email Account`/`Email Connector` interface (Microsoft 365, Current User, SMTP, or a custom connector). `Codeunit "Email Message"` is the in-memory object you build the message on; it is not itself the persisted Sent/Outbox/Draft record — that storage is managed separately once the message is queued or sent. New code built on `Codeunit Mail` inherits its SMTP-era, single-connector assumptions and leaves no Sent/Outbox trail behind. + +## Best Practice + +Build on `Codeunit Email` and `Codeunit "Email Message"`. Route the message through an `Email Scenario` so different document types can use different accounts without the calling code needing to know which account that is, and get a tracked Sent/Outbox/Draft record for free. + +See sample: [`prefer-email-module.good.al`](prefer-email-module.good.al). + +## Anti Pattern + +Calling `Codeunit Mail`'s `CreateMessage`. It still compiles and runs, but current `Codeunit Mail`'s own implementation of `CreateMessage` no longer sends anything by itself — it only raises integration events for a legacy subscriber to act on — so building new code on it means depending on whatever compatibility shim happens to still be wired up, with no first-class connector selection and no queryable Sent/Outbox/Draft record. `Send` and `GetErrorDesc` are not current members of `Codeunit Mail` at all; do not reference them. + +See sample: [`prefer-email-module.bad.al`](prefer-email-module.bad.al). diff --git a/microsoft/knowledge/data-modeling/check-post-line-batch-pattern.bad.al b/microsoft/knowledge/data-modeling/check-post-line-batch-pattern.bad.al new file mode 100644 index 0000000..0a13e1c --- /dev/null +++ b/microsoft/knowledge/data-modeling/check-post-line-batch-pattern.bad.al @@ -0,0 +1,22 @@ +codeunit 50101 "Meter Jnl.-Post" +{ + procedure Post(var MeterJnlLine: Record "Meter Journal Line") + var + MeterLedgEntry: Record "Meter Ledger Entry"; + begin + // Validation, Journal access, and posting all mixed in one routine. + if not Confirm('Post journal lines?') then + exit; + + if MeterJnlLine.FindSet() then + repeat + if MeterJnlLine.Quantity = 0 then + Error('Quantity must not be zero.'); + + MeterLedgEntry.Init(); + MeterLedgEntry.TransferFields(MeterJnlLine); + MeterLedgEntry.Insert(); + MeterJnlLine.Delete(); + until MeterJnlLine.Next() = 0; + end; +} diff --git a/microsoft/knowledge/data-modeling/check-post-line-batch-pattern.good.al b/microsoft/knowledge/data-modeling/check-post-line-batch-pattern.good.al new file mode 100644 index 0000000..6bfa93e --- /dev/null +++ b/microsoft/knowledge/data-modeling/check-post-line-batch-pattern.good.al @@ -0,0 +1,42 @@ +codeunit 50100 "Meter Jnl.-Check Line" +{ + procedure CheckLine(var MeterJnlLine: Record "Meter Journal Line") + begin + // Reads setup/dimension data only, shows no UI beyond errors. + if MeterJnlLine.Quantity = 0 then + Error('Quantity must not be zero.'); + end; +} + +codeunit 50101 "Meter Jnl.-Post Line" +{ + procedure PostLine(var MeterJnlLine: Record "Meter Journal Line") + var + MeterLedgEntry: Record "Meter Ledger Entry"; + begin + // Posts exactly one journal line; never touches the Journal table. + MeterLedgEntry.Init(); + MeterLedgEntry.TransferFields(MeterJnlLine); + MeterLedgEntry.Insert(); + end; +} + +codeunit 50102 "Meter Jnl.-Post Batch" +{ + procedure PostBatch(var MeterJnlLine: Record "Meter Journal Line") + var + CheckLine: Codeunit "Meter Jnl.-Check Line"; + PostLine: Codeunit "Meter Jnl.-Post Line"; + begin + if MeterJnlLine.FindSet() then + repeat + CheckLine.CheckLine(MeterJnlLine); + until MeterJnlLine.Next() = 0; + + if MeterJnlLine.FindSet() then + repeat + PostLine.PostLine(MeterJnlLine); + MeterJnlLine.Delete(); + until MeterJnlLine.Next() = 0; + end; +} diff --git a/microsoft/knowledge/data-modeling/check-post-line-batch-pattern.md b/microsoft/knowledge/data-modeling/check-post-line-batch-pattern.md new file mode 100644 index 0000000..e6b1229 --- /dev/null +++ b/microsoft/knowledge/data-modeling/check-post-line-batch-pattern.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [posting-routine, check-line, post-line, post-batch, companion-codeunit, yes-no-wrapper, journal] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Split posting routines into Check Line / Post Line / Post Batch + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +Business Central's own journal-based posting routines consistently follow a three-codeunit split, each with one primary responsibility — `Codeunit "Gen. Jnl.-Check Line"` / `"Gen. Jnl.-Post Line"` / `"Gen. Jnl.-Post Batch"` for the general journal, and the same `-Check Line` / `-Post Line` / `-Post Batch` shape repeated for Item, Resource, Job, Fixed Asset, Insurance, and Cost Accounting journals: `Check Line` validates one line, `Post Line` posts exactly one journal line — `Gen. Jnl.-Post Line` itself can write more than one G/L Entry per call (a balancing entry, VAT, currency rounding, deferrals), so "exactly one line" describes its input, not a one-entry-out guarantee — and `Post Batch` loops both across the journal. A document posting routine (posting one document at a time) calls `Post Line` directly and skips `Post Batch`. This is the standard shape to evaluate a new journal-based posting routine against, not a platform-enforced constraint — a routine with a genuinely different transaction/reuse shape may legitimately organize itself differently, and the three codeunits' responsibilities are a useful default split, not a guarantee that every implementation keeps them non-overlapping. But a new routine that blurs this split without a specific reason either misses functionality other code expects to call directly, or exposes an interaction surface it shouldn't. + +## Best Practice + +`Check Line` reads setup/dimension data only on its first call and shows no UI beyond errors. `Post Line` only operates on the record passed to it — never the Journal table — so it can be called directly by other posting code, including a document posting routine. `Post Batch` is the only one of the three that reads and updates the Journal table, and it is the only one invoked from the Post action on a journal page. A `-Post` document codeunit is never called directly from a page; a page calls a `-Post (Yes/No)` confirmation wrapper instead, so the same `-Post` codeunit can also run unattended from a batch-posting report. + +See sample: [`check-post-line-batch-pattern.good.al`](check-post-line-batch-pattern.good.al). + +## Anti Pattern + +A single monolithic posting codeunit that reads the Journal table, validates lines, writes ledger entries, and shows confirmation dialogs all in one procedure. It cannot be reused by another posting routine without fabricating journal records, and it cannot run unattended because it insists on user interaction. + +See sample: [`check-post-line-batch-pattern.bad.al`](check-post-line-batch-pattern.bad.al). diff --git a/microsoft/knowledge/data-modeling/dimension-management-wiring.bad.al b/microsoft/knowledge/data-modeling/dimension-management-wiring.bad.al new file mode 100644 index 0000000..8e3bce4 --- /dev/null +++ b/microsoft/knowledge/data-modeling/dimension-management-wiring.bad.al @@ -0,0 +1,13 @@ +table 50100 "Course" +{ + fields + { + field(1; "No."; Code[20]) { } + field(10; "Global Dimension 1 Code"; Code[20]) + { + // No CaptionClass, no OnValidate call into DimensionManagement. + // Accepts any value; never becomes a Default Dimension record. + TableRelation = "Dimension Value".Code; + } + } +} diff --git a/microsoft/knowledge/data-modeling/dimension-management-wiring.good.al b/microsoft/knowledge/data-modeling/dimension-management-wiring.good.al new file mode 100644 index 0000000..b5feae0 --- /dev/null +++ b/microsoft/knowledge/data-modeling/dimension-management-wiring.good.al @@ -0,0 +1,89 @@ +// Master data: Default Dimension records, no Dimension Set ID field. +table 50100 "Course" +{ + fields + { + field(1; "No."; Code[20]) { } + field(10; "Global Dimension 1 Code"; Code[20]) + { + CaptionClass = '1,1,1'; + TableRelation = "Dimension Value".Code where( + "Global Dimension No." = const(1), Blocked = const(false)); + + trigger OnValidate() + var + DimMgt: Codeunit DimensionManagement; + begin + DimMgt.ValidateDimValueCode(1, "Global Dimension 1 Code"); + DimMgt.SaveDefaultDim(Database::Course, "No.", 1, "Global Dimension 1 Code"); + end; + } + } + + trigger OnDelete() + var + DimMgt: Codeunit DimensionManagement; + begin + DimMgt.DeleteDefaultDim(Database::Course, "No."); + end; +} + +// Transactional/document data: a single Dimension Set ID, inherited from the +// related master record and overridable via shortcut dimension fields. +table 50101 "Course Registration Header" +{ + fields + { + field(1; "No."; Code[20]) { } + field(2; "Customer No."; Code[20]) + { + TableRelation = Customer; + + trigger OnValidate() + begin + UpdateDimensionSetID(); + end; + } + field(10; "Shortcut Dimension 1 Code"; Code[20]) + { + CaptionClass = '1,1,1'; + TableRelation = "Dimension Value".Code where( + "Global Dimension No." = const(1), Blocked = const(false)); + + trigger OnValidate() + var + DimMgt: Codeunit DimensionManagement; + begin + DimMgt.ValidateShortcutDimValues(1, "Shortcut Dimension 1 Code", "Dimension Set ID"); + end; + } + field(480; "Dimension Set ID"; Integer) + { + Editable = false; + TableRelation = "Dimension Set Entry"."Dimension Set ID"; + } + } + + local procedure UpdateDimensionSetID() + var + Customer: Record Customer; + DimMgt: Codeunit DimensionManagement; + DefaultDimSource: List of [Dictionary of [Integer, Code[20]]]; + GlobalDim2Code: Code[20]; + begin + // Recompute from scratch (InheritFromDimSetID = 0) whether or not the + // customer lookup succeeds. Passing the existing "Dimension Set ID" + // here would inherit dimensions from whichever record the document + // was previously linked to, and exiting early on a failed Get would + // leave that same stale data in place — both defeat the point of + // this procedure. Clearing the shortcut field and recomputing with + // an empty source list (when the customer doesn't exist) correctly + // clears the document's dimensions instead of leaving old ones. + "Shortcut Dimension 1 Code" := ''; + if Customer.Get("Customer No.") then + DimMgt.AddDimSource(DefaultDimSource, Database::Customer, "Customer No."); + "Dimension Set ID" := + DimMgt.GetDefaultDimID( + DefaultDimSource, '', "Shortcut Dimension 1 Code", GlobalDim2Code, 0, 0); + end; +} diff --git a/microsoft/knowledge/data-modeling/dimension-management-wiring.md b/microsoft/knowledge/data-modeling/dimension-management-wiring.md new file mode 100644 index 0000000..d7eec38 --- /dev/null +++ b/microsoft/knowledge/data-modeling/dimension-management-wiring.md @@ -0,0 +1,35 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [dimensions, dimensionmanagement, global-dimension, shortcut-dimension, default-dimension, validatedimvaluecode, getdefaultdimid] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Wire dimension support through DimensionManagement, not ad hoc fields + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +Adding dimension support to a custom table is not just a matter of adding a `Code[20]` field, and master tables and document/transactional tables wire into `Codeunit "Dimension Management"` through two different models — treating them as one mechanism is itself the mistake this article corrects: + +- **Master data** (a custom master table, e.g. "Course") persists **Default Dimension** records: each shortcut dimension field validates through `ValidateDimValueCode`, then the result is saved via `SaveDefaultDim`, and `DeleteDefaultDim` removes them again in `OnDelete`. Both `ValidateDimValueCode` and `SaveDefaultDim` take the shortcut dimension *number* (1-8, matching `General Ledger Setup`'s "Shortcut Dimension N Code" fields) as their first/third argument respectively — not the AL field ID of the table field being validated. The master record itself carries no `Dimension Set ID` field. +- **Transactional/document data** (a custom document or journal-line table) carries a single **`Dimension Set ID`** field — a pointer to a shared, deduplicated set of dimension values in `Dimension Set Entry`, assembled from whatever the document inherited plus whatever the user overrode. A document does not acquire that ID by calling `SaveDefaultDim`; it builds a source list with `AddDimSource` (naming the related master table and its key, e.g. `Database::Customer`), then calls `GetDefaultDimID` to compute a new `Dimension Set ID` that inherits the master's Default Dimension records. Editing a shortcut dimension field directly on the document validates through `ValidateShortcutDimValues`, which updates the same `Dimension Set ID` in place rather than writing a separate Default Dimension record. + +Skipping the model that actually matches the table's kind produces a field that looks correct in the designer but silently fails to save, validate, or carry through to postings — or, for a document, one that never picks up the customer's/vendor's own dimensions at all. + +## Best Practice + +For a master table, validate each shortcut dimension field through `ValidateDimValueCode`, save the result with `SaveDefaultDim`, and delete the matching Default Dimension records in `OnDelete`. + +For a document table, when the field that attaches the document to a master record changes (e.g. `Customer No.`), call `AddDimSource` naming that master table and key, then `GetDefaultDimID` to compute the document's new `Dimension Set ID`, inheriting the master's Default Dimension records. Pass `0` for `GetDefaultDimID`'s `InheritFromDimSetID` argument in this case — passing the document's *existing* `Dimension Set ID` instead inherits whatever dimensions were already in it, so a value the previous linked record supplied can survive into the new one even where the new record has no default for that dimension. Run this same recompute — clear the shortcut field, call `GetDefaultDimID` with no source added — when the lookup on the new key fails (blank or an invalid value), too: exiting early instead leaves the previous record's dimensions in place, which is the same staleness bug the `InheritFromDimSetID = 0` rule exists to prevent. Validate the document's own Shortcut Dimension fields through `ValidateShortcutDimValues`, which updates that same `Dimension Set ID` in place rather than persisting a separate Default Dimension record. + +See sample: [`dimension-management-wiring.good.al`](dimension-management-wiring.good.al). + +## Anti Pattern + +Adding a dimension-looking field with only a `TableRelation` to Dimension Value, and no call into `DimensionManagement` at all. The field accepts input but never becomes a real Default Dimension record, so it does not validate against blocked values and does not flow into postings. + +See sample: [`dimension-management-wiring.bad.al`](dimension-management-wiring.bad.al). diff --git a/microsoft/knowledge/data-modeling/do-not-change-primary-key.bad.al b/microsoft/knowledge/data-modeling/do-not-change-primary-key.bad.al new file mode 100644 index 0000000..cc52ae2 --- /dev/null +++ b/microsoft/knowledge/data-modeling/do-not-change-primary-key.bad.al @@ -0,0 +1,14 @@ +table 50100 "Period Stats" +{ + fields + { + field(1; "Period Start"; Date) { } + field(2; Flow; Enum "Some Flow") { } + } + keys + { + // Table already shipped with key(PK; "Period Start"). + // Adding Flow here breaks every upgrade with AS0009. + key(PK; Flow, "Period Start") { Clustered = true; } + } +} diff --git a/microsoft/knowledge/data-modeling/do-not-change-primary-key.good.al b/microsoft/knowledge/data-modeling/do-not-change-primary-key.good.al new file mode 100644 index 0000000..4739c49 --- /dev/null +++ b/microsoft/knowledge/data-modeling/do-not-change-primary-key.good.al @@ -0,0 +1,24 @@ +table 50100 "Period Stats" +{ + fields + { + field(1; "Period Start"; Date) { } + } + keys + { + key(PK; "Period Start") { Clustered = true; } + } +} + +table 50101 "Period Stats By Flow" +{ + fields + { + field(1; "Period Start"; Date) { } + field(2; Flow; Enum "Some Flow") { } + } + keys + { + key(PK; Flow, "Period Start") { Clustered = true; } + } +} diff --git a/microsoft/knowledge/data-modeling/do-not-change-primary-key.md b/microsoft/knowledge/data-modeling/do-not-change-primary-key.md new file mode 100644 index 0000000..37cb3e3 --- /dev/null +++ b/microsoft/knowledge/data-modeling/do-not-change-primary-key.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [primary-key, clustered-key, table-design, appsource, breaking-change, schema-upgrade] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Never Change a Published Table's Primary or Clustered Key Field List + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +Once a table has shipped — to AppSource, or to any customer environment that has already upgraded onto it — its primary key, and any other key marked `Clustered = true`, is frozen. This includes adding a field to the key, not only removing or reordering one: Business Central identifies existing rows by their key value, so any change to which fields compose that key invalidates every row already stored under the old shape, and the platform's upgrade validation rejects it outright (`AS0009`). This is easy to trip over because it doesn't look like the well-known "don't delete a field" mistake — the field being added is often brand new, and folding a new discriminating dimension straight into the existing key feels like the natural, un-denormalized way to model it. On an unpublished table that is correct; on a published one it is a breaking schema change regardless of which direction the field list changed, and there is no in-place fix once the upgrade is rejected, only reverting the key to its published shape. + +## Best Practice + +Leave a published table's key exactly as shipped. Model a new discriminating dimension as a separate table with its own key instead of adding a field to the existing key, and branch orchestration code by the new dimension rather than filtering one shared table on an extra key field. + +See sample: [`do-not-change-primary-key.good.al`](do-not-change-primary-key.good.al). + +## Anti Pattern + +Adding a field to a published table's primary or clustered key to distinguish a new case. This fails AppSource validation or any customer upgrade with `AS0009` as soon as rows already exist under the old key shape, whether the field is being added, removed, or reordered. + +See sample: [`do-not-change-primary-key.bad.al`](do-not-change-primary-key.bad.al). diff --git a/microsoft/knowledge/data-modeling/testfield-required-setup-field.bad.al b/microsoft/knowledge/data-modeling/testfield-required-setup-field.bad.al new file mode 100644 index 0000000..2ee7bc1 --- /dev/null +++ b/microsoft/knowledge/data-modeling/testfield-required-setup-field.bad.al @@ -0,0 +1,12 @@ +codeunit 50100 "Tax Posting Helper" +{ + procedure GetTaxAccount(var Setup: Record "Sales & Receivables Setup"): Code[20] + var + DefaultTaxAccountTxt: Label 'DEFAULT-TAX'; + begin + Setup.Get(); + if Setup."Tax Account No." <> '' then + exit(Setup."Tax Account No."); + exit(DefaultTaxAccountTxt); + end; +} diff --git a/microsoft/knowledge/data-modeling/testfield-required-setup-field.good.al b/microsoft/knowledge/data-modeling/testfield-required-setup-field.good.al new file mode 100644 index 0000000..d35db26 --- /dev/null +++ b/microsoft/knowledge/data-modeling/testfield-required-setup-field.good.al @@ -0,0 +1,9 @@ +codeunit 50100 "Tax Posting Helper" +{ + procedure GetTaxAccount(var Setup: Record "Sales & Receivables Setup"): Code[20] + begin + Setup.Get(); + Setup.TestField("Tax Account No."); + exit(Setup."Tax Account No."); + end; +} diff --git a/microsoft/knowledge/data-modeling/testfield-required-setup-field.md b/microsoft/knowledge/data-modeling/testfield-required-setup-field.md new file mode 100644 index 0000000..37ad575 --- /dev/null +++ b/microsoft/knowledge/data-modeling/testfield-required-setup-field.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [testfield, setup-table, configuration, mandatory-field, silent-fallback, correctness] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# TestField a Setup-Table Value Before Using It in a Correctness-Critical Branch + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +A procedure that reads a field from a setup or configuration table inside a branch where the surrounding logic has already decided that value is required needs to guard against it being blank. A common anti-pattern silently treats "blank" as "feature not wanted": it checks the field for emptiness and falls through to a default instead of raising an error. `Get()` succeeding on the setup record only proves the record exists, not that the specific field was ever configured, so the fallback path makes a missing configuration indistinguishable from a deliberate one — and the wrong outcome, especially in financial, tax, or compliance postings, surfaces silently rather than as a crash a tester would notice. + +## Best Practice + +Once a business rule has decided that a setup-table field's value is required for a branch to behave correctly, call `TestField` on it before use, even though a plain read would "work" by returning a blank or zero without erroring. Write a test that blanks the setup field and asserts the resulting error, so the guard itself is verified rather than merely present. + +See sample: [`testfield-required-setup-field.good.al`](testfield-required-setup-field.good.al). + +## Anti Pattern + +Reading a required setup-table field behind a presence check that falls through to a default value instead of erroring. This looks defensive because it never crashes, but it converts "administrator forgot to configure this" into "system silently did something else" — worse than a hard failure, because nobody is told anything went wrong. + +See sample: [`testfield-required-setup-field.bad.al`](testfield-required-setup-field.bad.al). diff --git a/microsoft/knowledge/performance/document-report-word-layout.bad.al b/microsoft/knowledge/performance/document-report-word-layout.bad.al new file mode 100644 index 0000000..0da274f --- /dev/null +++ b/microsoft/knowledge/performance/document-report-word-layout.bad.al @@ -0,0 +1,16 @@ +report 50105 "Sales Quote Confirmation" +{ + UsageCategory = Documents; + ApplicationArea = All; + + rendering + { + layout(RDLC) + { + Type = RDLC; + LayoutFile = './Layouts/SalesQuoteConfirmation.rdl'; + } + } + + DefaultRenderingLayout = RDLC; +} diff --git a/microsoft/knowledge/performance/document-report-word-layout.good.al b/microsoft/knowledge/performance/document-report-word-layout.good.al new file mode 100644 index 0000000..f9e5e24 --- /dev/null +++ b/microsoft/knowledge/performance/document-report-word-layout.good.al @@ -0,0 +1,17 @@ +report 50105 "Sales Quote Confirmation" +{ + UsageCategory = Documents; + ApplicationArea = All; + + rendering + { + layout(Word) + { + Type = Word; + LayoutFile = './Layouts/SalesQuoteConfirmation.docx'; + Caption = 'Word Layout'; + } + } + + DefaultRenderingLayout = Word; +} diff --git a/microsoft/knowledge/performance/document-report-word-layout.md b/microsoft/knowledge/performance/document-report-word-layout.md new file mode 100644 index 0000000..06159aa --- /dev/null +++ b/microsoft/knowledge/performance/document-report-word-layout.md @@ -0,0 +1,34 @@ +--- +bc-version: [all] +domain: performance +keywords: [report-layout, word-layout, rdlc, document-report, sandbox-app-domain, rendering] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Document reports should default to a Word layout, not RDLC + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +For a document report — an invoice, statement, order confirmation, or any report meant to be printed, emailed, or exported as a single-record document — Microsoft's own guidance recommends a `Word` rendering layout over `RDLC`: "RDL layouts can result in slower performance with document reports, regarding actions that are related to the user interface (for example, like sending emails) compared to Word layouts," and "we recommend that you design Word layouts instead of RDL" for this report shape (see Sources). This is a documented recommendation, not a universal guarantee that Word outperforms RDLC for every workload, and it does not apply to every report: tabular/list reports with heavy aggregation or calculated columns are still often a better fit for RDLC or Excel. + +## Best Practice + +For document reports, prefer a `Word` layout (`DefaultRenderingLayout = Word`) over RDLC unless specific layout requirements favor RDLC. Reserve RDLC (or Excel) for reports that represent a data listing rather than a document. + +## Sources + +- [Report Design Overview](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-report-design-overview) +- [Creating an RDL layout report](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-report-performance) +- [Troubleshooting reports / Report performance](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-reports-troubleshooting) + +See sample: [`document-report-word-layout.good.al`](document-report-word-layout.good.al). + +## Anti Pattern + +Defaulting a document report's layout to RDLC out of habit or because a template happened to use it. This inherits RDLC's sandboxed-app-domain performance cost with no benefit tied to the report's actual content or calculation needs. + +See sample: [`document-report-word-layout.bad.al`](document-report-word-layout.bad.al). diff --git a/microsoft/knowledge/style/al-build-output-must-not-pollute-project-root.md b/microsoft/knowledge/style/al-build-output-must-not-pollute-project-root.md new file mode 100644 index 0000000..4e5a57a --- /dev/null +++ b/microsoft/knowledge/style/al-build-output-must-not-pollute-project-root.md @@ -0,0 +1,24 @@ +--- +bc-version: [all] +domain: style +keywords: [build, output, alpackages, artifact-hygiene, outfolder, project-root] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Write AL Build Artifacts to an Intentional Output Location + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +An AL project's compiled `.app` file can be written to the project root by default, and current tooling explicitly supports choosing a different destination instead — `ALTool`'s `--outfolder` option and the `al_build` agent tool's `outputPath` parameter both exist for this. The problem this rule addresses is not that root-level output is technically invalid; it is agents leaving generated `.app` files scattered through arbitrary source locations, or treating a compiled artefact as if it were part of the source tree (committing it, editing around it, referencing it as a dependency by hand). + +## Best Practice + +Write build artifacts to a deliberate, dedicated output location — configured via the build tool actually in use (e.g. `ALTool --outfolder`, or an explicit `outputPath` on the agent build tool) — and add that folder to `.gitignore`. Treat a compiled `.app` as a build artifact, never as a source file to commit or hand-edit around. + +## Anti Pattern + +Letting `.app` files accumulate in arbitrary or unversioned locations without a deliberate output path, or committing compiled artefacts into source control alongside the AL files that produced them. diff --git a/microsoft/knowledge/style/al-identifiers-english.bad.al b/microsoft/knowledge/style/al-identifiers-english.bad.al new file mode 100644 index 0000000..e4d62da --- /dev/null +++ b/microsoft/knowledge/style/al-identifiers-english.bad.al @@ -0,0 +1,11 @@ +codeunit 50100 "Sales Amount Calculator" +{ + procedure BeregnTotalbeloeb(var Salgslinje: Record "Sales Line"): Decimal + var + Beloeb: Decimal; + begin + Salgslinje.CalcSums(Amount); + Beloeb := Salgslinje.Amount; + exit(Beloeb); + end; +} diff --git a/microsoft/knowledge/style/al-identifiers-english.good.al b/microsoft/knowledge/style/al-identifiers-english.good.al new file mode 100644 index 0000000..0b17ec1 --- /dev/null +++ b/microsoft/knowledge/style/al-identifiers-english.good.al @@ -0,0 +1,11 @@ +codeunit 50100 "Sales Amount Calculator" +{ + procedure CalculateTotalAmount(var SalesLine: Record "Sales Line"): Decimal + var + TotalAmount: Decimal; + begin + SalesLine.CalcSums(Amount); + TotalAmount := SalesLine.Amount; + exit(TotalAmount); + end; +} diff --git a/microsoft/knowledge/style/al-identifiers-english.md b/microsoft/knowledge/style/al-identifiers-english.md new file mode 100644 index 0000000..5feda9f --- /dev/null +++ b/microsoft/knowledge/style/al-identifiers-english.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: style +keywords: [identifiers, naming, english, captions, translation] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Write AL Identifiers in English Only + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +All AL identifiers — variables, procedures, parameters, fields, object names, enum values, and label identifiers — must be written in English, regardless of the developer's native language. Translations are handled separately through captions, tooltips, and XLIFF files, never by writing Danish, German, or other non-English identifiers directly into AL source code. This is not a stylistic preference: the public `microsoft/BCApps` codebase, maintained by engineers of many nationalities across hundreds of thousands of lines of AL, uses exclusively English identifiers, with all localization handled via caption properties and XLIFF rather than by changing identifier names. On any multi-contributor codebase, non-English identifiers make the code unreadable to contributors who don't share that language. + +## Best Practice + +Write every identifier in English, and translate developer intent rather than transliterating it — when a requirement is described in another language, the resulting variable, procedure, and field names should still read as English. Captions and tooltips may carry target-language text in the source file, with locale translations managed through XLIFF. + +See sample: [`al-identifiers-english.good.al`](al-identifiers-english.good.al). + +## Anti Pattern + +Using native-language identifiers such as a Danish variable or procedure name in AL source code, relying on the fact that the code still compiles and runs correctly. This makes the code unreadable to non-native-language contributors and mixes localization concerns into source that should stay language-neutral. + +See sample: [`al-identifiers-english.bad.al`](al-identifiers-english.bad.al). diff --git a/microsoft/knowledge/style/binary-choice-must-be-boolean.bad.al b/microsoft/knowledge/style/binary-choice-must-be-boolean.bad.al new file mode 100644 index 0000000..2201ea3 --- /dev/null +++ b/microsoft/knowledge/style/binary-choice-must-be-boolean.bad.al @@ -0,0 +1,22 @@ +table 50100 "Sales Task" +{ + fields + { + field(1; "No."; Code[20]) { } + field(10; Status; Option) + { + OptionMembers = Active,Blocked; + } + } +} + +codeunit 50100 "Sales Task Check" +{ + procedure IsOverdue(DueDate: Date): Integer + begin + // 0 = No, 1 = Yes + if DueDate < Today then + exit(1); + exit(0); + end; +} diff --git a/microsoft/knowledge/style/binary-choice-must-be-boolean.good.al b/microsoft/knowledge/style/binary-choice-must-be-boolean.good.al new file mode 100644 index 0000000..ac62b0f --- /dev/null +++ b/microsoft/knowledge/style/binary-choice-must-be-boolean.good.al @@ -0,0 +1,16 @@ +table 50100 "Sales Task" +{ + fields + { + field(1; "No."; Code[20]) { } + field(10; Blocked; Boolean) { } + } +} + +codeunit 50100 "Sales Task Check" +{ + procedure IsOverdue(DueDate: Date): Boolean + begin + exit(DueDate < Today); + end; +} diff --git a/microsoft/knowledge/style/binary-choice-must-be-boolean.md b/microsoft/knowledge/style/binary-choice-must-be-boolean.md new file mode 100644 index 0000000..ec0c4a5 --- /dev/null +++ b/microsoft/knowledge/style/binary-choice-must-be-boolean.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: style +keywords: [boolean, option, yes-no, magic-number, variable-typing, field-typing] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Binary yes/no choices must be typed as Boolean, not Option or Integer + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +When a field or variable represents a genuine true/false state — yes/no, on/off, active/inactive, blocked/not blocked — it should be typed `Boolean`. Modeling that same predicate as an `Option`/`Enum` with two members, or as an `Integer` with two magic-number values, adds a layer of indirection a reader has to resolve before understanding the code. This is about semantics, not member count: a domain concept that currently has exactly two named alternatives — Inbound/Outbound, Debit/Credit, Buy/Sell — is not automatically a Boolean in disguise. An `Enum` can be the clearer model there, including when it needs to implement an interface, preserve an existing contract, or leave room for a future third value. The distinction is whether the domain is genuinely a stable predicate, not how many states it currently has. + +## Best Practice + +Type a field or variable as `Boolean` when the domain concept is inherently a true/false state. Do not replace a meaningful two-option domain model with a Boolean solely because it currently has two values. + +See sample: [`binary-choice-must-be-boolean.good.al`](binary-choice-must-be-boolean.good.al). + +## Anti Pattern + +Modeling a yes/no choice as an `Option` with two members, or as an `Integer` with magic-number values, forces every caller to remember which value means what and leaves room for a meaningless third value. + +See sample: [`binary-choice-must-be-boolean.bad.al`](binary-choice-must-be-boolean.bad.al). diff --git a/microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.bad.al b/microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.bad.al new file mode 100644 index 0000000..77facce --- /dev/null +++ b/microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.bad.al @@ -0,0 +1,22 @@ +table 50101 "Course" +{ + fields + { + field(1; "No."; Code[20]) { } + // 1 = Beginner, 2..3 = Intermediate, 4+ = Advanced + field(10; Difficulty; Integer) { } + } +} + +codeunit 50100 "Course Level Helper" +{ + procedure LevelText(Difficulty: Integer): Text + begin + case Difficulty of + 1: + exit('Beginner'); + 2, 3: + exit('Intermediate'); + end; + end; +} diff --git a/microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.good.al b/microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.good.al new file mode 100644 index 0000000..ef0175b --- /dev/null +++ b/microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.good.al @@ -0,0 +1,17 @@ +enum 50100 "Course Difficulty" +{ + Extensible = true; + + value(0; Beginner) { } + value(1; Intermediate) { } + value(2; Advanced) { } +} + +table 50101 "Course" +{ + fields + { + field(1; "No."; Code[20]) { } + field(10; Difficulty; Enum "Course Difficulty") { } + } +} diff --git a/microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.md b/microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.md new file mode 100644 index 0000000..112b977 --- /dev/null +++ b/microsoft/knowledge/style/fixed-choice-set-must-use-enum-not-integer.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: style +keywords: [enum, option, integer, magic-number, variable-typing, field-typing] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# A fixed set of named choices must use Enum, not a raw Integer + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +When a variable or field represents a fixed set of named, mutually exclusive states — a difficulty level, a document type, a processing status — it should be typed as `Enum` (or `Option` when extending an object that still uses the legacy type). Representing that same state as a plain `Integer` and tracking the meaning of each value in a comment or in a developer's head is a magic-number anti-pattern: the compiler cannot catch an out-of-range value, and branches read as opaque numbers instead of names. This is about semantics, not member count, matching `binary-choice-must-be-boolean.md`'s own distinction: a domain concept that is genuinely a stable true/false predicate belongs in `Boolean` even if someone represents it as a two-value `Enum`, while a domain concept with exactly two current named states is not automatically a Boolean in disguise — it stays an `Enum` when the states are named alternatives rather than a yes/no flag, or when it needs to implement an interface, preserve an existing contract, or leave room for a future third value. + +## Best Practice + +Declare an `Enum` with named values and branch on the enum value, not a raw number. + +See sample: [`fixed-choice-set-must-use-enum-not-integer.good.al`](fixed-choice-set-must-use-enum-not-integer.good.al). + +## Anti Pattern + +Using a plain `Integer` field with the meaning of each value tracked only in a comment pushes the documentation of the states into something the compiler cannot check and a future maintainer cannot rely on. + +See sample: [`fixed-choice-set-must-use-enum-not-integer.bad.al`](fixed-choice-set-must-use-enum-not-integer.bad.al). diff --git a/microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.bad.al b/microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.bad.al new file mode 100644 index 0000000..755991b --- /dev/null +++ b/microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.bad.al @@ -0,0 +1,12 @@ +codeunit 50100 "Sales Task Notify" +{ + procedure NotifyUpdate(Count: Integer; CustomerNo: Code[20]) + begin + MESSAGE('%1 records updated.', Count); + + IF NOT CONFIRM('Delete %1?', FALSE, CustomerNo) THEN + EXIT; + + ERROR(STRSUBSTNO('%1 must not be blank.', CustomerNo)); + end; +} diff --git a/microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.good.al b/microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.good.al new file mode 100644 index 0000000..a8551b4 --- /dev/null +++ b/microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.good.al @@ -0,0 +1,12 @@ +codeunit 50100 "Sales Task Notify" +{ + procedure NotifyUpdate(Count: Integer; CustomerNo: Code[20]) + begin + Message('%1 records updated.', Count); + + if not Confirm('Delete %1?', false, CustomerNo) then + exit; + + Error(StrSubstNo('%1 must not be blank.', CustomerNo)); + end; +} diff --git a/microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.md b/microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.md new file mode 100644 index 0000000..761650b --- /dev/null +++ b/microsoft/knowledge/style/intrinsic-al-functions-must-use-modern-casing.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: style +keywords: [casing, intrinsic-function, built-in-function, message, error, confirm, strsubstno, legacy, c-al, pascalcase] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Intrinsic AL function calls use modern casing, not legacy ALL-CAPS + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +AL is case-insensitive, so `MESSAGE(...)`, `ERROR(...)`, `CONFIRM(...)`, and `STRSUBSTNO(...)` compile and run identically to `Message(...)`, `Error(...)`, `Confirm(...)`, and `StrSubstNo(...)`. Modern AL — Microsoft's own current samples and current reference codebases — writes intrinsic/built-in function calls in the casing Microsoft assigns to the function's declared name, typically PascalCase. This is a codebase-convention claim, not a claim about what the VS Code formatter enforces: the formatter normalizes particular syntax but is not a mechanism for recasing every intrinsic function call, so do not cite formatter behavior as the reason to follow this convention. ALL-CAPS calls are a holdover from classic C/AL and signal code that has not been modernized, even though it compiles and runs correctly. Reserved keywords such as `if`, `begin`, and `for` are a separate, already-tooled concern; intrinsic function names are identifiers, not keywords, so that tooling does not catch ALL-CAPS intrinsic function calls. + +## Best Practice + +Call intrinsic functions in their modern, PascalCase form. + +See sample: [`intrinsic-al-functions-must-use-modern-casing.good.al`](intrinsic-al-functions-must-use-modern-casing.good.al). + +## Anti Pattern + +ALL-CAPS intrinsic function calls trip no compiler error, but they are a reliable signal that a code block was copied from old C/AL material or outdated training content rather than written against current AL conventions. + +See sample: [`intrinsic-al-functions-must-use-modern-casing.bad.al`](intrinsic-al-functions-must-use-modern-casing.bad.al). diff --git a/microsoft/knowledge/style/namespace-must-be-verified-from-source.bad.al b/microsoft/knowledge/style/namespace-must-be-verified-from-source.bad.al new file mode 100644 index 0000000..0cd54b7 --- /dev/null +++ b/microsoft/knowledge/style/namespace-must-be-verified-from-source.bad.al @@ -0,0 +1,13 @@ +namespace Contoso.Extensions; + +using System.Performance; // guessed; never verified against the source file + +codeunit 50100 "Tooling Extension" +{ + procedure Run() + var + ToolingPage: Page "Some Tooling Page"; // guessed namespace; can still resolve against a stale or cached symbol package, then fail once checked against the object's current source or a freshly downloaded one + begin + ToolingPage.Run(); + end; +} diff --git a/microsoft/knowledge/style/namespace-must-be-verified-from-source.good.al b/microsoft/knowledge/style/namespace-must-be-verified-from-source.good.al new file mode 100644 index 0000000..2a8e34a --- /dev/null +++ b/microsoft/knowledge/style/namespace-must-be-verified-from-source.good.al @@ -0,0 +1,16 @@ +// Verified by reading line 1 of the source file for "Some Tooling Page": +// namespace System.Tooling; + +namespace Contoso.Extensions; + +using System.Tooling; + +codeunit 50100 "Tooling Extension" +{ + procedure Run() + var + ToolingPage: Page "Some Tooling Page"; + begin + ToolingPage.Run(); + end; +} diff --git a/microsoft/knowledge/style/namespace-must-be-verified-from-source.md b/microsoft/knowledge/style/namespace-must-be-verified-from-source.md new file mode 100644 index 0000000..52e8bbc --- /dev/null +++ b/microsoft/knowledge/style/namespace-must-be-verified-from-source.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: style +keywords: [namespace, verification, source-of-truth, using-statement] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Resolve a namespace from the referenced object's source or symbols, never by guessing + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +Since Business Central 2024 release wave 1, Microsoft's own objects are organized under a deep `Microsoft.*` namespace tree that has been renamed and restructured repeatedly. When adding a `using` directive for an existing AL object (table, codeunit, page, enum, interface, etc.), guessing its namespace from the object's name, from an older codebase, or from general familiarity produces a statement that can look plausible and still resolve to the wrong object, or fail to resolve at all, once checked against the object's actual current namespace. The reliable sources are the object's own source file (its `namespace` declaration) or, for a dependency without accessible source, its AL symbol package — not the object's name or a remembered convention. + +## Best Practice + +When referencing an existing AL object, resolve its namespace from that object's actual source file or symbol definition — never infer or invent one from its name, functional area, or naming convention. + +See sample: [`namespace-must-be-verified-from-source.good.al`](namespace-must-be-verified-from-source.good.al). + +## Anti Pattern + +Writing a `using` statement from memory, from an incomplete path, or from a plausible-looking guess. It can appear correct while actually resolving to the wrong object, or fail to resolve, once checked against stale or mismatched symbols, a different build configuration, or the object's actual current source — not because the compiler and the AL Language Server apply different namespace-resolution rules; they don't. + +See sample: [`namespace-must-be-verified-from-source.bad.al`](namespace-must-be-verified-from-source.bad.al). diff --git a/microsoft/knowledge/style/var-parameters-require-an-addressable-variable.bad.al b/microsoft/knowledge/style/var-parameters-require-an-addressable-variable.bad.al new file mode 100644 index 0000000..5c9dbe7 --- /dev/null +++ b/microsoft/knowledge/style/var-parameters-require-an-addressable-variable.bad.al @@ -0,0 +1,15 @@ +codeunit 50100 "Customer Lookup" +{ + procedure GetCustomerName(CustomerNo: Code[20]; var Name: Text[100]) + var + Customer: Record Customer; + begin + if Customer.Get(CustomerNo) then + Name := Customer.Name; + end; + + procedure Sample() + begin + GetCustomerName('10000', 'placeholder'); // compile error: literal is not addressable + end; +} diff --git a/microsoft/knowledge/style/var-parameters-require-an-addressable-variable.good.al b/microsoft/knowledge/style/var-parameters-require-an-addressable-variable.good.al new file mode 100644 index 0000000..3c20da1 --- /dev/null +++ b/microsoft/knowledge/style/var-parameters-require-an-addressable-variable.good.al @@ -0,0 +1,17 @@ +codeunit 50100 "Customer Lookup" +{ + procedure GetCustomerName(CustomerNo: Code[20]; var Name: Text[100]) + var + Customer: Record Customer; + begin + if Customer.Get(CustomerNo) then + Name := Customer.Name; + end; + + procedure Sample() + var + CustName: Text[100]; + begin + GetCustomerName('10000', CustName); + end; +} diff --git a/microsoft/knowledge/style/var-parameters-require-an-addressable-variable.md b/microsoft/knowledge/style/var-parameters-require-an-addressable-variable.md new file mode 100644 index 0000000..81f6fbb --- /dev/null +++ b/microsoft/knowledge/style/var-parameters-require-an-addressable-variable.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: style +keywords: [var-parameter, by-reference, pass-by-reference, literal, constant, compile-error, procedure-call] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# A `var` parameter must be called with a variable, never a literal or expression + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +When a procedure declares a parameter with `var`, that parameter is passed by reference: the callee writes back into the caller's own memory location. This means the argument at the call site must be an actual variable, something with an address. A string literal, a numeric constant, or a computed expression has no address to write back to, so passing one to a `var` parameter fails to compile. Before writing a call, check the callee's signature for `var` on each parameter position being supplied a literal or expression — if present, a variable declared in the caller's own scope must be used instead. + +## Best Practice + +Declare a variable in the caller's scope and pass it to the `var` parameter. + +See sample: [`var-parameters-require-an-addressable-variable.good.al`](var-parameters-require-an-addressable-variable.good.al). + +## Anti Pattern + +Passing a literal or a computed expression to a `var` parameter position fails to compile, because neither has an address the callee can write back to. + +See sample: [`var-parameters-require-an-addressable-variable.bad.al`](var-parameters-require-an-addressable-variable.bad.al). diff --git a/microsoft/knowledge/testing/test-data-must-be-random-and-complete.bad.al b/microsoft/knowledge/testing/test-data-must-be-random-and-complete.bad.al new file mode 100644 index 0000000..34c13e4 --- /dev/null +++ b/microsoft/knowledge/testing/test-data-must-be-random-and-complete.bad.al @@ -0,0 +1,14 @@ +[Test] +procedure PostsSalesOrderForCashCustomer() +var + Customer: Record Customer; + SalesHeader: Record "Sales Header"; +begin + // Assumes a 'CASH' customer already exists in the environment — + // fails on any database where it doesn't. + Customer.Get('CASH'); + LibrarySales.CreateSalesHeader( + SalesHeader, SalesHeader."Document Type"::Order, Customer."No."); + + // ... add lines, post, assert ... +end; diff --git a/microsoft/knowledge/testing/test-data-must-be-random-and-complete.good.al b/microsoft/knowledge/testing/test-data-must-be-random-and-complete.good.al new file mode 100644 index 0000000..75518f1 --- /dev/null +++ b/microsoft/knowledge/testing/test-data-must-be-random-and-complete.good.al @@ -0,0 +1,13 @@ +[Test] +procedure PostsSalesOrderForRandomCustomer() +var + Customer: Record Customer; + SalesHeader: Record "Sales Header"; +begin + // Freshly created customer, owned by this test — no assumption about what exists. + LibrarySales.CreateCustomer(Customer); + LibrarySales.CreateSalesHeader( + SalesHeader, SalesHeader."Document Type"::Order, Customer."No."); + + // ... add lines, post, assert ... +end; diff --git a/microsoft/knowledge/testing/test-data-must-be-random-and-complete.md b/microsoft/knowledge/testing/test-data-must-be-random-and-complete.md new file mode 100644 index 0000000..c78a0d5 --- /dev/null +++ b/microsoft/knowledge/testing/test-data-must-be-random-and-complete.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: testing +keywords: [testing, test-data, random, library, any] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Generate Test Data Programmatically, Never Assume Existing Records + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +A BC test company normally contains initialized system/setup data — an AL test suite should not assume an empty database, but it must be independent of unrelated business records: create the records and setup it owns rather than looking up a specific code, number, or name assumed to already exist, since that makes the test fail for reasons unrelated to the code under test. Every mandatory field on a created record also needs an actual value — leaving one blank because setup-time validation happens to allow it produces a record that doesn't reflect a real one and can fail later, elsewhere in the flow (posting, a report, a later assertion), for a reason unrelated to what the test claims to check. A short-but-valid value is not itself a defect: AL field lengths are maxima, not minimums, so a two-character value in a `Text[100]` field is fine unless the scenario specifically depends on the field's length or shape — for example, a test that verifies truncation or a format check needs a value chosen to exercise that boundary, not an arbitrary short one. + +Not every value should be generated, though. Incidental fixture data — identifiers, names, descriptions — should generally come from the standard library codeunits rather than be tied to specific existing data. But values that materially define the scenario under test — amounts, quantities, percentages, dates, thresholds, rounding precision — should stay explicit and deliberately chosen, not randomized: a rounding test needs values placed deliberately around the rounding boundary, not a random one that might miss it entirely. + +## Best Practice + +Use the standard library codeunits (`Library - ERM`, `Library - Inventory`, `Library - Sales`, `Library - Utility`) to generate incidental fixture values — they produce valid, unique-enough data via number series and controlled randomness, not a mathematical collision-free guarantee — and fill every mandatory field with correctly-sized data. Keep values that define the scenario's expected outcome explicit and fixed. Reserve hardcoded values for tests that validate an external contract itself — a fixed JSON schema, an EDIFACT message, a counterparty code — where the hardcoded value documents the specification rather than arbitrary test logic. + +See sample: [`test-data-must-be-random-and-complete.good.al`](test-data-must-be-random-and-complete.good.al). + +## Anti Pattern + +Looking up a record assumed to already exist (a hardcoded payment method or customer number) instead of creating it, or leaving a mandatory field empty because setup-time validation happens to allow it. Also an anti-pattern, narrower: using a value that doesn't satisfy a scenario's explicit length or format requirement — for example a truncation test that never actually exceeds the field it's meant to overflow. + +See sample: [`test-data-must-be-random-and-complete.bad.al`](test-data-must-be-random-and-complete.bad.al). diff --git a/microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.bad.al b/microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.bad.al new file mode 100644 index 0000000..8b8e240 --- /dev/null +++ b/microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.bad.al @@ -0,0 +1,27 @@ +page 50101 "Customer Info API" +{ + PageType = API; + APIPublisher = 'contoso'; + APIGroup = 'sales'; + APIVersion = 'v1.0'; + EntityName = 'customerInfo'; + EntitySetName = 'customerInfos'; + SourceTable = Customer; + ODataKeyFields = "No."; + InsertAllowed = true; + + layout + { + area(content) + { + repeater(General) + { + field(customerNo; Rec."No.") + { + Editable = false; // consumer must supply "No." on POST — this rejects it + } + field(name; Rec.Name) { } + } + } + } +} diff --git a/microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.good.al b/microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.good.al new file mode 100644 index 0000000..af6c5de --- /dev/null +++ b/microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.good.al @@ -0,0 +1,25 @@ +page 50101 "Customer Info API" +{ + PageType = API; + APIPublisher = 'contoso'; + APIGroup = 'sales'; + APIVersion = 'v1.0'; + EntityName = 'customerInfo'; + EntitySetName = 'customerInfos'; + SourceTable = Customer; + ODataKeyFields = "No."; + InsertAllowed = true; + DelayedInsert = true; + + layout + { + area(content) + { + repeater(General) + { + field(customerNo; Rec."No.") { } + field(name; Rec.Name) { } + } + } + } +} diff --git a/microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.md b/microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.md new file mode 100644 index 0000000..84887c1 --- /dev/null +++ b/microsoft/knowledge/web-services/api-page-key-fields-must-be-editable-on-insert.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: web-services +keywords: [api-page, key-fields, editable, insert, odata] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Keep Consumer-Provided Key Fields Editable on API Pages + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +A field listed in `ODataKeyFields` cannot have `Editable = false` when the API page allows inserts and the field's value must be supplied by the caller. Marking it read-only removes the field from the OData write schema, so a POST that includes it is rejected as an unknown property. This only applies to keys the consumer must supply — a system-generated key such as `SystemId` is a valid exception, since Business Central assigns its value automatically on insert. + +## Best Practice + +Leave every consumer-supplied key field referenced in `ODataKeyFields` without `Editable = false` on pages where `InsertAllowed = true`, so the OData layer accepts it as a writable property on POST. + +See sample: [`api-page-key-fields-must-be-editable-on-insert.good.al`](api-page-key-fields-must-be-editable-on-insert.good.al). + +## Anti Pattern + +Marking a consumer-provided key field `Editable = false`, out of habit or for perceived safety. This silently breaks create operations with a generic `BadRequest` instead of a clear validation error. + +See sample: [`api-page-key-fields-must-be-editable-on-insert.bad.al`](api-page-key-fields-must-be-editable-on-insert.bad.al). diff --git a/microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.bad.al b/microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.bad.al new file mode 100644 index 0000000..9938612 --- /dev/null +++ b/microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.bad.al @@ -0,0 +1,24 @@ +page 50102 "Project Task API" +{ + PageType = API; + APIPublisher = 'contoso'; + APIGroup = 'jobs'; + APIVersion = 'v1.0'; + EntityName = 'projectTask'; + EntitySetName = 'projectTasks'; + SourceTable = "Project Task"; + + layout + { + area(content) + { + repeater(General) + { + // "Remaining Hours" is a stored field, set inside the + // OnValidate of "Budgeted Hours" — it goes stale whenever + // "Hours Used" changes through any other path. + field(remainingHours; Rec."Remaining Hours") { } + } + } + } +} diff --git a/microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.good.al b/microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.good.al new file mode 100644 index 0000000..1ab78db --- /dev/null +++ b/microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.good.al @@ -0,0 +1,33 @@ +page 50102 "Project Task API" +{ + PageType = API; + APIPublisher = 'contoso'; + APIGroup = 'jobs'; + APIVersion = 'v1.0'; + EntityName = 'projectTask'; + EntitySetName = 'projectTasks'; + SourceTable = "Project Task"; + DelayedInsert = true; + + layout + { + area(content) + { + repeater(General) + { + field(remainingHours; RemainingHoursCalc) { } + field(budgetedHours; Rec."Budgeted Hours") { } + field(hoursUsed; Rec."Hours Used") { } + } + } + } + + trigger OnAfterGetRecord() + begin + Rec.CalcFields("Hours Used"); + RemainingHoursCalc := Rec."Budgeted Hours" - Rec."Hours Used"; + end; + + var + RemainingHoursCalc: Decimal; +} diff --git a/microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.md b/microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.md new file mode 100644 index 0000000..2d02f93 --- /dev/null +++ b/microsoft/knowledge/web-services/stored-derived-fields-must-not-be-exposed-directly.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: web-services +keywords: [api-page, derived-fields, exposure, odata] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Recalculate Stored Derived Fields Before Exposing Them on API Pages + +> Contributions welcome — open a PR to refine or extend this article. + +## Description + +A stored field whose value is derived from other fields inside an `OnValidate` trigger only updates when that specific trigger fires. If the underlying source data changes through some other path, the stored value goes stale without raising any error. Exposing such a field directly on an API page hands external consumers a snapshot that may be significantly out of date. + +## Best Practice + +Recalculate the derived value in `OnAfterGetRecord` from its authoritative source — typically a FlowField — using a page-level variable, and expose that recalculated value instead of the stale stored field. Whether to also expose the source fields is a separate design decision, not a requirement of this pattern; keep the API contract scoped to what consumers actually need. If letting the consumer verify the recalculation is itself a requirement, expose every field the calculation reads, not just one of them — a derived value with two inputs needs both exposed, or the "verification" is incomplete. + +See sample: [`stored-derived-fields-must-not-be-exposed-directly.good.al`](stored-derived-fields-must-not-be-exposed-directly.good.al). + +## Anti Pattern + +Exposing the stored field directly via `Rec`, trusting that it was kept in sync by whichever trigger last touched it. + +See sample: [`stored-derived-fields-must-not-be-exposed-directly.bad.al`](stored-derived-fields-must-not-be-exposed-directly.bad.al). diff --git a/microsoft/skills/review/al-appsource-review.md b/microsoft/skills/review/al-appsource-review.md index 3f6a221..2efc049 100644 --- a/microsoft/skills/review/al-appsource-review.md +++ b/microsoft/skills/review/al-appsource-review.md @@ -52,6 +52,7 @@ The following targeted checks cover every current `appsource` article across the - A page or report that repository context identifies as a direct user entry point omits `UsageCategory` or sets it to `None` — `set-usagecategory-on-searchable-entry-points`. Do not select this article based only on object type; exclude supporting parts, dialogs, API pages, and objects intentionally reached through another page. - A `DateTime` assignment adds or subtracts a fixed duration to represent an assumed regional offset — `do-not-hard-code-time-zone-offsets`. Require contextual evidence such as an hour-sized constant, offset-oriented name, or time-zone comment; do not flag deadlines, schedules, or elapsed-time calculations. - For BC v27 or later, `app.json` adds or changes the `help` URL to a path deeper than two levels, or a changed Copilot/context-sensitive help arrangement would ground the app under an overly broad truncated parent — `keep-copilot-help-url-to-two-path-levels`. +- Changed code declares or calls `File.Open`/`File.Create`/`File.Read`/`File.Write` in an app targeting Business Central Online — `file-datatype-saas`. Once the candidate worklist is known, resolve layer-precedence conflicts per READ. Drop lower-precedence files whose normative guidance (`## Best Practice` or `## Anti Pattern`) directly contradicts a higher-precedence candidate, and record each dropped file in `suppressed` with `reason: "layer-precedence"`. Files that would have been candidates but are hidden because their layer is disabled in consumer configuration are recorded with `reason: "configuration"`. Files that never became candidates are NOT recorded in `suppressed`. diff --git a/microsoft/skills/review/al-breaking-changes-review.md b/microsoft/skills/review/al-breaking-changes-review.md index 7f30713..5e2f3aa 100644 --- a/microsoft/skills/review/al-breaking-changes-review.md +++ b/microsoft/skills/review/al-breaking-changes-review.md @@ -50,7 +50,9 @@ The following targeted checks cover every current `breaking-changes` article: - A published procedure changes parameter count/order/type/name, `var`, return type, or array shape instead of preserving the old signature and adding an overload — `do-not-change-published-procedure-signatures`. - A public procedure/event/interface exposes a credential or other sensitive value through `Text` or an externally callable contract — `do-not-expose-sensitive-data-through-public-api`. - Code already marked obsolete is expanded with new behavior instead of routing new callers to its replacement — `do-not-modify-code-already-marked-obsolete`. -- A shipped table field is deleted, renamed, renumbered, or replaced without retaining the original field as `ObsoleteState = Pending` and migrating its data — `obsolete-table-fields-instead-of-deleting-them`. +- A shipped table field is deleted, renamed, renumbered, or replaced without retaining the original field as `ObsoleteState = Pending` and migrating its data — `obsolete-table-fields-instead-of-deleting-them`. This owns AS0005 field-name changes; do not substitute the namespace article. +- A published object's namespace changes between the base and changed source while its identity otherwise remains — `namespace-is-part-of-published-object-identity`. Do not apply it to a new, unshipped object or to an ordinary object-name change with no namespace change. +- New or changed code calls `Codeunit Mail`'s `CreateMessage`/`Send`/`GetErrorDesc` instead of `Codeunit Email`/`Codeunit "Email Message"` — `prefer-email-module`. For `obsolete-table-fields-instead-of-deleting-them`, compare the baseline ID and name before emitting. When the original field remains under the same ID and name with `ObsoleteState = Pending`, and the replacement uses a new ID, the change follows the rule and must not be flagged. diff --git a/microsoft/skills/review/al-data-modeling-review.md b/microsoft/skills/review/al-data-modeling-review.md index 3fca8ec..2318304 100644 --- a/microsoft/skills/review/al-data-modeling-review.md +++ b/microsoft/skills/review/al-data-modeling-review.md @@ -54,6 +54,10 @@ The following targeted checks cover every current `data-modeling` article. Treat - A `Media` or `MediaSet` field is assigned directly between different table types or different field IDs instead of registering each shared item with `MediaSet.Insert` — `share-mediaset-items-with-insert-not-field-assignment`. - A custom document header assigns defaults outside an `InitRecord` boundary, calls `InitRecord` before assigning its number, or places UI-independent defaults only in a page trigger — `initialize-document-defaults-in-initrecord`. - Directed `Round` calls use `'<'` as mathematical floor or `'>'` as mathematical ceiling, especially where negative amounts are possible — `round-direction-symbols-use-magnitude`. +- A new field is typed `Code`/`Text` and its `OnValidate` calls `DimensionManagement`/`DimMgt`, or a table adds Shortcut Dimension fields, a `Dimension Set ID` field, or `AddDimSource`/`GetDefaultDimID` — `dimension-management-wiring`. A master table calling `SaveDefaultDim` and a document/journal table computing its own `Dimension Set ID` are two different valid shapes; do not flag a master table for lacking a `Dimension Set ID` field or a document for lacking `SaveDefaultDim`. +- A journal-based posting codeunit is added or changed and validation, Journal-table access, ledger writes, and user-interaction (`Confirm`/dialogs) all occur in one procedure or one codeunit, rather than split across `Check Line`/`Post Line`/`Post Batch`-shaped companions — `check-post-line-batch-pattern`. A document posting routine calling `Post Line` directly without a `Post Batch` companion is not this anti-pattern. +- An existing, already-published table's `keys` block adds, removes, or reorders a field in its primary key or any `Clustered = true` key — `do-not-change-primary-key`. A new table defining its own key for the first time is not this anti-pattern; requires repository/publication context to know the table has already shipped. +- Code reads a setup/configuration-table field inside a branch that has already decided the value is required, and blank/zero is handled with a fallback to a default rather than `TestField`/an equivalent guard — `testfield-required-setup-field`. A read that is genuinely optional in that branch, or one already guarded by `TestField`, is not this anti-pattern. Once the candidate worklist is known, resolve layer-precedence conflicts per READ. Drop lower-precedence files whose normative guidance (`## Best Practice` or `## Anti Pattern`) directly contradicts a higher-precedence candidate, and record each dropped file in `suppressed` with `reason: "layer-precedence"`. Files that would have been candidates but are hidden because their layer is disabled in consumer configuration are recorded with `reason: "configuration"`. Files that never became candidates are NOT recorded in `suppressed`. diff --git a/microsoft/skills/review/al-performance-review.md b/microsoft/skills/review/al-performance-review.md index 7829d70..6109f7b 100644 --- a/microsoft/skills/review/al-performance-review.md +++ b/microsoft/skills/review/al-performance-review.md @@ -58,6 +58,7 @@ Apply these targeted cues even when simple token overlap would rank the article - Worklist `job-queue-on-hold-does-not-stop-running-work.md` when a running job queue handler polls the entry's `Status` or `On Hold` value as a cancellation signal. Exclude application-owned stop requests that are checked before every bounded unit of work, including the first, when completed work and its checkpoint remain consistent and resume logic clears the request. - Worklist `job-queue-category-code-serializes-conflicting-jobs.md` when two or more job queue entries in the same company are shown by the changed context to require mutual exclusion but have empty or different Job Queue Category Codes. Do not infer a conflict merely because jobs touch the same tables, and do not recommend a category to coordinate across companies, environments, or workers outside the job queue dispatcher. - Worklist `store-scheduled-task-id-to-avoid-duplicate-tasks.md` when `TaskScheduler.CreateTask` runs from initialization, login, setup, or another repeatable path without persisting its returned GUID and checking it with `TaskScheduler.TaskExists` before creating a replacement. Exclude one-shot creation and correctly persisted check-before-create flows; concurrent callers still require serialization around that sequence. +- A new or changed report object whose usage/name/caption identifies it as a single-record document (invoice, statement, order confirmation) sets or retains `DefaultRenderingLayout = RDLC` — `document-report-word-layout.md`. Do not worklist this from a tabular/list report with heavy aggregation or calculated columns; RDLC/Excel remains the better fit there. These targeted inclusions and exclusions override generic token overlap. Do not retain an excluded article solely because the diff contains one of its keywords. diff --git a/microsoft/skills/review/al-style-review.md b/microsoft/skills/review/al-style-review.md index 5b0b6b6..0cc747e 100644 --- a/microsoft/skills/review/al-style-review.md +++ b/microsoft/skills/review/al-style-review.md @@ -40,8 +40,8 @@ Discard files that are not applicable. Retain conditionally applicable files onl Narrow the relevant files to the subset that applies to the changes under review. For each relevant file, compute overlap against: - Changed AL objects — especially API pages (`PageType = API`), tables and pages declaring Labels/TextConsts, codeunits issuing `Error`/`Message`/`Confirm`, and any file whose name violates the `..al` convention. -- Changed declarations, weighted toward `: Label '...'`, `: TextConst '...'`, temporary record variables, `DateFormula` declarations and their `Evaluate` call sites, error-handling call sites, and API declarations. -- Tokens extracted from the diff (`Label`, `TextConst`, `Locked`, `Comment`, `MaxLength`, `temporary`, `DateFormula`, `Evaluate`, `CalcDate`, `APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `DelayedInsert`, `FieldCaption`, `TableCaption`, `FieldName`, `TableName`, `Page.RunModal`, `Report.Run`, `StrSubstNo`). +- Changed declarations, weighted toward `: Label '...'`, `: TextConst '...'`, temporary record variables, option fields, `DateFormula` declarations and their `Evaluate` call sites, error-handling call sites, API declarations, and codeunit-internal method calls. +- Tokens extracted from the diff (`Label`, `TextConst`, `Locked`, `Comment`, `MaxLength`, `temporary`, `DateFormula`, `Evaluate`, `CalcDate`, `OptionMembers`, `OptionCaption`, `APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `DelayedInsert`, `FieldCaption`, `TableCaption`, `FieldName`, `TableName`, `Page.RunModal`, `Report.Run`, `this.`, `StrSubstNo`, `namespace`, `using`, `var `). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object or declaration. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. @@ -51,6 +51,14 @@ Apply these high-signal mappings before fuzzy topic ranking: - A `Label` or `TextConst` contains multiple or ambiguous placeholders but has no `Comment`, or its Comment does not explain every placeholder — `label-comment-explains-placeholders.md`. A single placeholder whose meaning is explicit in the text, such as `Customer %1`, is allowed without a Comment and must not be flagged. - A normal two-argument `Evaluate` has a resolved `DateFormula` destination and a hard-coded non-angle-bracket date-formula literal, directly or through a visible constant — `dateformula-evaluate-needs-language-independent-literals.md`. Do not use this cue for dynamic/localized external input, already invariant `<...>` input, or direct `CalcDate(Text, ...)` calls. +- `function-call-parentheses-required.md` applies only to a zero-argument invocation written without `()`. Never worklist it from an invocation that already has parentheses or supplies arguments, including `Error(Label, Arg1, Arg2)`. +- A new `.app` build artifact appears at the project root or another unversioned/arbitrary location, or is added to source control alongside the AL source that produced it — `al-build-output-must-not-pollute-project-root.md`. A deliberate `--outfolder`/`outputPath` destination added to `.gitignore` is the compliant shape, not the signal to flag. +- A new or renamed AL identifier (variable, procedure, parameter, field, object, enum value, or label identifier) contains non-English words — `al-identifiers-english.md`. A caption, tooltip, or other user-facing text value in a non-English language is not this anti-pattern; only the identifier itself is in scope. +- A field or variable is typed `Boolean` and its two possible values are genuinely named domain alternatives (a status pair like Inbound/Outbound, Debit/Credit, Buy/Sell) rather than a true/false predicate, or an `Option`/`Enum`/`Integer` models a domain concept that is intrinsically a yes/no flag — `binary-choice-must-be-boolean.md`. The signal is a semantic mismatch between the type and the domain concept, not the current number of states. +- A field or variable is typed `Integer` with the meaning of each value tracked only in a comment, or an `Enum` with more than two members is proposed as `Boolean`-like — `fixed-choice-set-must-use-enum-not-integer.md`. Do not flag a genuinely two-state `Enum`/`Option` for having "too few" members; that overlaps `binary-choice-must-be-boolean.md` instead when the domain is a true/false predicate. +- A new `using` directive is added for an existing AL object without the diff also showing that object's own `namespace` declaration or a symbol-package lookup backing the choice — `namespace-must-be-verified-from-source.md`. Require repository/dependency context; a single new `using` line cannot itself prove whether the namespace was verified or guessed. +- An intrinsic/built-in AL function call (`MESSAGE`, `ERROR`, `CONFIRM`, `STRSUBSTNO`, etc.) is written in ALL-CAPS or another non-PascalCase form — `intrinsic-al-functions-must-use-modern-casing.md`. +- A procedure call passes a literal or a computed expression (not a caller-scope variable) to a parameter position the callee declares `var` — `var-parameters-require-an-addressable-variable.md`. This is a compile-time-guaranteed shape; flag it only when the callee's declared signature is visible in the diff or resolvable from context. Once the candidate worklist is known, resolve layer-precedence conflicts per READ and record suppressions. diff --git a/microsoft/skills/review/al-testing-review.md b/microsoft/skills/review/al-testing-review.md index c96ac83..de0c9be 100644 --- a/microsoft/skills/review/al-testing-review.md +++ b/microsoft/skills/review/al-testing-review.md @@ -51,6 +51,7 @@ The following targeted checks cover every current `testing` article. Treat each - Test fixture code manually calls `Init`/`Insert`, invents keys or prerequisite records, or bypasses available `LibrarySales`, `LibraryPurchase`, `LibraryERM`, `LibraryInventory`, `LibraryRandom`, or equivalent library codeunits — `use-library-codeunits-for-test-fixtures`. - `asserterror` is added or changed without a following `Assert.ExpectedError`, `Assert.ExpectedErrorCode`, or a purpose-built assertion such as `ExpectedTestFieldError` — `asserterror-needs-expectederror-and-code`. - A test path raises UI and `[HandlerFunctions(...)]` does not match the invoked handlers, or the test has no meaningful evidence of the UI result (for example, it treats a Boolean set before the action as proof of success) — `ui-handlers-in-tests`. A capture/reset/assert-after-`RunModal` pattern is valid. Enqueue/dequeue and `AssertEmpty` are required only when order, count, text, replies, or a scripted sequence is part of the contract. Only nonoptional handlers have to execute: a listed handler declared `[SendNotificationHandler(true)]` or `[RecallNotificationHandler(true)]` is optional by design, so do not treat it as unmatched when the run never raises the notification. +- A test's `[GIVEN]`/setup looks up a hardcoded code/number/name assumed to already exist instead of creating it, leaves a mandatory field on a created record empty, uses a value that doesn't satisfy the scenario's own explicit length/format requirement (for example a truncation test whose value never exceeds the field), or a scenario-defining value (amount, quantity, percentage, date, threshold, rounding precision) is generated/randomized instead of an explicit chosen value — `test-data-must-be-random-and-complete`. Generating incidental fixture values (identifiers, names, descriptions) via the standard library codeunits is the compliant shape, not the signal to flag, and neither is a short-but-valid value in an otherwise-unremarkable field. Once the candidate worklist is known, resolve layer-precedence conflicts per READ. Drop lower-precedence files whose normative guidance (`## Best Practice` or `## Anti Pattern`) directly contradicts a higher-precedence candidate, and record each dropped file in `suppressed` with `reason: "layer-precedence"`. Files that would have been candidates but are hidden because their layer is disabled in consumer configuration are recorded with `reason: "configuration"`. Files that never became candidates are NOT recorded in `suppressed`. diff --git a/microsoft/skills/review/al-web-services-review.md b/microsoft/skills/review/al-web-services-review.md index 19d0735..c486c88 100644 --- a/microsoft/skills/review/al-web-services-review.md +++ b/microsoft/skills/review/al-web-services-review.md @@ -40,6 +40,8 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially pages declared with `PageType = API`, API page `part` controls, queries declared with `QueryType = API`, and procedures that expose bound actions. - The changed properties and triggers, weighted toward API page metadata (`APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `ODataKeyFields`, `SourceTable`, `SourceTableTemporary`), navigation metadata (`SubPageLink`, `Multiplicity`, and visible singleton or collection semantics), CRUD guards (`InsertAllowed`, `ModifyAllowed`, `DeleteAllowed`, `Editable`), the `OnOpenPage` trigger, and `OnValidate` triggers on exposed fields. - Webhook subscriber handlers and subscription lifecycle code, especially code that creates or renews subscriptions, handles `validationToken`, schedules from `expirationDateTime`, or targets resources whose eligibility is visible in the diff. +- An API page (`PageType = API`) with `InsertAllowed = true` lists a field in `ODataKeyFields` and that same field control sets `Editable = false` — `api-page-key-fields-must-be-editable-on-insert.md`. A system-generated key such as `SystemId` marked read-only is not this anti-pattern. +- An API page exposes a field via `Rec` directly, and that field is a stored value computed from other fields inside an `OnValidate` trigger rather than a FlowField recalculated in `OnAfterGetRecord` — `stored-derived-fields-must-not-be-exposed-directly.md`. Exposing a genuine FlowField, or a value already recalculated in `OnAfterGetRecord`, is not this anti-pattern. - Tokens extracted from the diff that relate to API surface and behaviour (`PageType`, `QueryType`, `API`, `api-page`, `page-part`, `APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `ODataKeyFields`, `SystemId`, `SubPageLink`, `subpagelink`, `Multiplicity`, `multiplicity`, `Many`, `ZeroOrOne`, `SourceTableTemporary`, `Job Queue Entry`, `webhook`, `webhookSupportedResources`, `webhook-supported-resources`, `subscriptions`, `notificationUrl`, `validationToken`, `validationtoken`, `expirationDateTime`, `expirationdatetime`, `ServiceEnabled`, `WebServiceActionContext`, `SetActionResponse`, `ReadIsolation`, `IsolationLevel`, `ReadCommitted`, `InsertAllowed`, `ModifyAllowed`, `DeleteAllowed`, `Editable`, `SourceTable`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. From 186691f815c288a06cd538075729e98dc5469013 Mon Sep 17 00:00:00 2001 From: Michael Dieringer <65093775+MichaelDieringer@users.noreply.github.com> Date: Tue, 29 Sep 2026 12:49:11 +0200 Subject: [PATCH 27/35] 3 AL/BC patterns from CURABIS's internal automated-testing training material (#158) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 * 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 * 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 --- ...ocument-no-follows-last-shipping-no.bad.al | 12 +++++++ ...cument-no-follows-last-shipping-no.good.al | 13 ++++++++ ...ry-document-no-follows-last-shipping-no.md | 26 +++++++++++++++ ...guid-for-unique-test-fixture-values.bad.al | 10 ++++++ ...uid-for-unique-test-fixture-values.good.al | 21 ++++++++++++ ...rateguid-for-unique-test-fixture-values.md | 33 +++++++++++++++++++ ...ditable-to-verify-field-editability.bad.al | 27 +++++++++++++++ ...itable-to-verify-field-editability.good.al | 26 +++++++++++++++ ...ge-editable-to-verify-field-editability.md | 26 +++++++++++++++ ...le-enabled-to-verify-field-ui-state.bad.al | 14 ++++++++ ...e-enabled-to-verify-field-ui-state.good.al | 15 +++++++++ ...isible-enabled-to-verify-field-ui-state.md | 26 +++++++++++++++ .../skills/review/al-data-modeling-review.md | 5 +-- microsoft/skills/review/al-testing-review.md | 4 ++- 14 files changed, 255 insertions(+), 3 deletions(-) create mode 100644 microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.bad.al create mode 100644 microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.good.al create mode 100644 microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.md create mode 100644 microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.bad.al create mode 100644 microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.good.al create mode 100644 microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.md create mode 100644 microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.bad.al create mode 100644 microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.good.al create mode 100644 microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.md create mode 100644 microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.bad.al create mode 100644 microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.good.al create mode 100644 microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.md diff --git a/microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.bad.al b/microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.bad.al new file mode 100644 index 0000000..f068342 --- /dev/null +++ b/microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.bad.al @@ -0,0 +1,12 @@ +codeunit 50130 "Sample Item Ledger Lookup" +{ + procedure GetPostedItemLedgerEntries(var SalesHeader: Record "Sales Header"; var ItemLedgerEntry: Record "Item Ledger Entry") + var + LibrarySales: Codeunit "Library - Sales"; + InvoiceNo: Code[20]; + begin + InvoiceNo := LibrarySales.PostSalesDocument(SalesHeader, true, true); + ItemLedgerEntry.SetRange("Document No.", InvoiceNo); + if ItemLedgerEntry.FindSet() then; + end; +} diff --git a/microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.good.al b/microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.good.al new file mode 100644 index 0000000..f396d9b --- /dev/null +++ b/microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.good.al @@ -0,0 +1,13 @@ +codeunit 50130 "Sample Item Ledger Lookup" +{ + procedure GetPostedItemLedgerEntries(var SalesHeader: Record "Sales Header"; var ItemLedgerEntry: Record "Item Ledger Entry") + var + LibrarySales: Codeunit "Library - Sales"; + ShippingNo: Code[20]; + begin + LibrarySales.PostSalesDocument(SalesHeader, true, true); + ShippingNo := SalesHeader."Last Shipping No."; + ItemLedgerEntry.SetRange("Document No.", ShippingNo); + if ItemLedgerEntry.FindSet() then; + end; +} diff --git a/microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.md b/microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.md new file mode 100644 index 0000000..3b5d939 --- /dev/null +++ b/microsoft/knowledge/data-modeling/item-ledger-entry-document-no-follows-last-shipping-no.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [item-ledger-entry, document-no, last-shipping-no, ship-and-invoice, posting, sales-order] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# After Ship-and-Invoice posting, Item Ledger Entry carries the shipment document number + +## Description + +Posting a sales order with both Ship and Invoice in one call creates the Item Ledger Entry during the shipment leg of that combined post, so the entry's `Document No.` is stamped with the value assigned to the shipment — `Sales Header."Last Shipping No."` — not the posted sales invoice number the posting call returns. Code that filters Item Ledger Entry by the invoice number instead finds nothing: `SetRange`/`FindSet` simply return zero rows, with no error to signal the mistake. + +## Best Practice + +After posting a sales order with Ship and Invoice together, read `SalesHeader."Last Shipping No."` (populated during the post) and filter Item Ledger Entry by that value, not by the invoice number the posting routine returns. + +See sample: [`item-ledger-entry-document-no-follows-last-shipping-no.good.al`](item-ledger-entry-document-no-follows-last-shipping-no.good.al). + +## Anti Pattern + +Filtering Item Ledger Entry by the posted sales invoice number after a combined Ship-and-Invoice post. The filter compiles and runs without error but matches zero rows, because the entry belongs to the shipment leg of the posting, not the invoice leg. + +See sample: [`item-ledger-entry-document-no-follows-last-shipping-no.bad.al`](item-ledger-entry-document-no-follows-last-shipping-no.bad.al). diff --git a/microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.bad.al b/microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.bad.al new file mode 100644 index 0000000..c718bc7 --- /dev/null +++ b/microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.bad.al @@ -0,0 +1,10 @@ +codeunit 50132 "Sample Customer Type Library" +{ + procedure CreateCustomerType(var CustomerType: Record "Customer Type") + begin + CustomerType.Init(); + CustomerType.Code := 'TEST001'; + CustomerType.Description := 'Test Customer Type'; + CustomerType.Insert(true); + end; +} diff --git a/microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.good.al b/microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.good.al new file mode 100644 index 0000000..25a194e --- /dev/null +++ b/microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.good.al @@ -0,0 +1,21 @@ +codeunit 50132 "Sample Customer Type Library" +{ + var + LibraryUtility: Codeunit "Library - Utility"; + + procedure CreateCustomerType(var CustomerType: Record "Customer Type") + begin + CustomerType.Init(); + // Code is shorter than GenerateGUID()'s 10 characters, and this field's + // uniqueness matters, so use GenerateRandomCodeWithLength: it opens the + // real (non-temporary) table and loops until the value doesn't collide. + // GenerateRandomCode would not do this — it opens the table as temporary, + // so its own emptiness check never inspects real rows. + CustomerType.Code := + LibraryUtility.GenerateRandomCodeWithLength(CustomerType.FieldNo(Code), Database::"Customer Type", MaxStrLen(CustomerType.Code)); + // Description is long enough to hold the full GenerateGUID() value + // untruncated, and only needs to be incidental, not verified-unique. + CustomerType.Description := CopyStr(LibraryUtility.GenerateGUID(), 1, MaxStrLen(CustomerType.Description)); + CustomerType.Insert(true); + end; +} diff --git a/microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.md b/microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.md new file mode 100644 index 0000000..e06f738 --- /dev/null +++ b/microsoft/knowledge/testing/use-generateguid-for-unique-test-fixture-values.md @@ -0,0 +1,33 @@ +--- +bc-version: [all] +domain: testing +keywords: [generateguid, library-utility, test-fixtures, uniqueness, generaterandomcode, maxstrlen] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Generate unique test fixture values with LibraryUtility helpers, not hardcoded literals + +## Description + +A fixture helper that assigns a hardcoded literal to a primary-key field, or to any field the test relies on as a unique lookup identifier, collides the moment two tests, or two runs of the same test, create that fixture without cleanup — and a literal longer than the field allows raises a truncation or insert error. An ordinary descriptive field carries no such constraint: two rows with the same description do not collide on insert, and a deterministic descriptive value is often exactly what an exact-match assertion needs, so none of this applies to it. `LibraryUtility.GenerateGUID()` is not a real GUID — it is a `Code[10]` number-series value (`GU00000000`–`GU99999999`) — and it returns the full 10 characters unshortened. Truncating it yourself with `CopyStr(..., 1, MaxStrLen(ShorterField))` for a field under 10 characters is unsafe: the changing digits sit at the right end and are exactly what gets cut off, so consecutive calls into a short field can produce the same truncated value. `GenerateGUID()` is only safe as-is for a field that holds the full 10 characters. + +## Best Practice + +For a field that holds the full 10 characters, assign `LibraryUtility.GenerateGUID()` directly. For a shorter field, do not truncate a GUID yourself — but also do not assume every `LibraryUtility` helper verifies uniqueness against the real table, because they don't all behave the same way: + +- `GenerateRandomCode(FieldNo, TableNo)` opens the target table as a **temporary** `RecordRef`: the buffer starts and stays empty, so its `repeat...until RecRef.IsEmpty()` loop always exits after one iteration — despite taking `TableNo`, it never checks the real table, and it never retries even within its own call. Its value is the rightmost `FieldRef.Length` characters of `GenerateGUID()`'s sequential `GU00000000`–`GU99999999` series, so for a short field that window of digits cycles: a 1-character field repeats every 10 calls, a 2-character field every 100, and so on. It is a finite short-field namespace with a low collision *chance* within one test run — not a guarantee at any scope, unlike the table-checking helpers below. +- `GenerateRandomCodeWithLength(FieldNo, TableNo, CodeLength)` opens the real (non-temporary) table and loops until the generated value doesn't collide — a genuine verified-unique guarantee — but it returns `Code[10]` regardless of the requested `CodeLength`, so it's only useful for a field of 10 characters or fewer. +- `GenerateRandomCode20(FieldNo, TableNo)` is the same real, verified-against-the-table pattern as `GenerateRandomCodeWithLength`, sized for a `Code[20]` field. +- `GenerateRandomXMLText(Length)` performs no table lookup at all — it's a plain random-text generator, appropriate for a descriptive/incidental field where uniqueness doesn't matter, not for a value that needs to be collision-checked. + +Pick `GenerateRandomCodeWithLength`/`GenerateRandomCode20` when the test genuinely needs a code verified unique against the table; use `GenerateRandomCode`/`GenerateGUID`/`GenerateRandomXMLText` for incidental values where a low collision *chance* is enough. + +See sample: [`use-generateguid-for-unique-test-fixture-values.good.al`](use-generateguid-for-unique-test-fixture-values.good.al). + +## Anti Pattern + +Hardcoding a primary-key or unique-lookup fixture value such as `'TEST001'`, which collides across parallel or repeated test runs — a fixed descriptive value is not this anti-pattern, since the field carries no uniqueness constraint. Equally an anti-pattern: truncating `GenerateGUID()`'s result with `CopyStr(..., 1, MaxStrLen(Field))` for a field shorter than 10 characters — the truncation removes the part of the value that actually varies. + +See sample: [`use-generateguid-for-unique-test-fixture-values.bad.al`](use-generateguid-for-unique-test-fixture-values.bad.al). diff --git a/microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.bad.al b/microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.bad.al new file mode 100644 index 0000000..ddaf0ff --- /dev/null +++ b/microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.bad.al @@ -0,0 +1,27 @@ +codeunit 50134 "Sample Customer Type Edit Test" +{ + Subtype = Test; + + [Test] + procedure CustomerTypeFieldNotEditable_WhenLocked() + var + Assert: Codeunit Assert; + CustomerType: Record "Customer Type"; + CustomerTypeCard: TestPage "Customer Type Card"; + begin + // [GIVEN] a customer type record whose Locked flag is set + CustomerType.Init(); + CustomerType.Locked := true; + CustomerType.Insert(true); + + // [WHEN] the page is opened in VIEW mode — editability logic that only + // applies in edit mode is not exercised the same way + CustomerTypeCard.OpenView(); + CustomerTypeCard.GoToRecord(CustomerType); + + // [THEN] wrong function: Enabled() does not verify editability + Assert.IsFalse(CustomerTypeCard.Description.Enabled(), 'Description should not be editable while Locked is set.'); + + CustomerTypeCard.Close(); + end; +} diff --git a/microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.good.al b/microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.good.al new file mode 100644 index 0000000..d683f0b --- /dev/null +++ b/microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.good.al @@ -0,0 +1,26 @@ +codeunit 50133 "Sample Customer Type Edit Test" +{ + Subtype = Test; + + [Test] + procedure CustomerTypeFieldNotEditable_WhenLocked() + var + Assert: Codeunit Assert; + CustomerType: Record "Customer Type"; + CustomerTypeCard: TestPage "Customer Type Card"; + begin + // [GIVEN] a customer type record whose Locked flag is set + CustomerType.Init(); + CustomerType.Locked := true; + CustomerType.Insert(true); + + // [WHEN] the page is opened in edit mode on that record + CustomerTypeCard.OpenEdit(); + CustomerTypeCard.GoToRecord(CustomerType); + + // [THEN] the field's actual editable state reflects the lock + Assert.IsFalse(CustomerTypeCard.Description.Editable(), 'Description should not be editable while Locked is set.'); + + CustomerTypeCard.Close(); + end; +} diff --git a/microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.md b/microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.md new file mode 100644 index 0000000..f94c792 --- /dev/null +++ b/microsoft/knowledge/testing/use-testpage-editable-to-verify-field-editability.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: testing +keywords: [testpage, editable, openedit, ui-state, field-verification] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Verify field editability with TestPage.Editable(), opened in edit mode + +## Description + +Whether a field can actually be changed is a distinct state from whether it is shown or enabled — `Editable()` and `Enabled()` are separate `TestField` functions. Verifying editability also requires opening the `TestPage` with `OpenEdit()`, not `OpenView()`: `OpenView()` opens the page in view mode, so it does not exercise the field's own conditional editability logic the way an actual edit-mode session does. + +## Best Practice + +Open the `TestPage` with `OpenEdit()`, navigate to the relevant record, then assert against `TestPageField.Editable()` to verify whether the field can be changed under the given precondition. + +See sample: [`use-testpage-editable-to-verify-field-editability.good.al`](use-testpage-editable-to-verify-field-editability.good.al). + +## Anti Pattern + +Asserting `Enabled()` (or checking nothing at all) when the actual claim is about editability, or opening the page with `OpenView()` when the field's editability depends on business logic that only applies in edit mode. + +See sample: [`use-testpage-editable-to-verify-field-editability.bad.al`](use-testpage-editable-to-verify-field-editability.bad.al). diff --git a/microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.bad.al b/microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.bad.al new file mode 100644 index 0000000..410af39 --- /dev/null +++ b/microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.bad.al @@ -0,0 +1,14 @@ +codeunit 50131 "Sample Customer Type UI Test" +{ + Subtype = Test; + + [Test] + procedure CustomerTypeFieldIsEnabledOnCustomerCard() + var + CustomerCard: TestPage "Customer Card"; + begin + // Confirms only that the page opens - never checks the field's actual UI state + CustomerCard.OpenView(); + CustomerCard.Close(); + end; +} diff --git a/microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.good.al b/microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.good.al new file mode 100644 index 0000000..6e03c06 --- /dev/null +++ b/microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.good.al @@ -0,0 +1,15 @@ +codeunit 50131 "Sample Customer Type UI Test" +{ + Subtype = Test; + + [Test] + procedure CustomerTypeFieldIsEnabledOnCustomerCard() + var + Assert: Codeunit Assert; + CustomerCard: TestPage "Customer Card"; + begin + CustomerCard.OpenView(); + Assert.IsTrue(CustomerCard."Customer Type".Enabled(), 'Customer Type should be enabled on the Customer Card.'); + Assert.IsTrue(CustomerCard."Customer Type".Visible(), 'Customer Type should be visible on the Customer Card.'); + end; +} diff --git a/microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.md b/microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.md new file mode 100644 index 0000000..ff6bd86 --- /dev/null +++ b/microsoft/knowledge/testing/use-testpage-visible-enabled-to-verify-field-ui-state.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: testing +keywords: [testpage, visible, enabled, ui-state, headless-test, field-verification] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Verify field visibility and enabled state with TestPage.Visible()/.Enabled() + +## Description + +A UI test codeunit does not need to inspect table or page properties indirectly to confirm a field is shown or enabled under given conditions. The `TestPage` object exposes a `Visible()` and an `Enabled()` function on each field, reflecting the page's actual rendered state, callable directly from a `[Test]` procedure. `Enabled()` and `Editable()` are distinct states — this article covers visibility/enabled state specifically; see `use-testpage-editable-to-verify-field-editability.md` for verifying whether a field can actually be changed. + +## Best Practice + +Open the `TestPage`, navigate to the relevant record if needed, then assert against `TestPageField.Visible()` and `TestPageField.Enabled()` to verify the field's shown/enabled state, rather than checking an unrelated table/page property or skipping the check. + +See sample: [`use-testpage-visible-enabled-to-verify-field-ui-state.good.al`](use-testpage-visible-enabled-to-verify-field-ui-state.good.al). + +## Anti Pattern + +A test that opens the `TestPage` but never asserts against `Visible()`/`Enabled()` on the field in question — confirming only that the page opens, not that the field behaves as expected. + +See sample: [`use-testpage-visible-enabled-to-verify-field-ui-state.bad.al`](use-testpage-visible-enabled-to-verify-field-ui-state.bad.al). diff --git a/microsoft/skills/review/al-data-modeling-review.md b/microsoft/skills/review/al-data-modeling-review.md index 2318304..e58b6b0 100644 --- a/microsoft/skills/review/al-data-modeling-review.md +++ b/microsoft/skills/review/al-data-modeling-review.md @@ -16,7 +16,7 @@ application-area: [all] Reviews AL source changes against the `data-modeling` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`. -An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. Data-modeling findings are narrow by design — they apply when the review scope contains setup or master tables, their card pages, primary keys, number-series assignment, block enforcement, or audit fields. The skill returns `not-applicable` when none of those apply. +An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. Data-modeling findings are narrow by design — they apply when the review scope contains setup or master tables, their card pages, primary keys, number-series assignment, block enforcement, audit fields, dimension wiring, journal-based posting-routine structure, or Item Ledger Entry document-number lookups after a combined sales post. The skill returns `not-applicable` when none of those apply. ## Source @@ -46,6 +46,7 @@ A file enters the candidate worklist when its `keywords` intersect the extracted The following targeted checks cover every current `data-modeling` article. Treat each as a candidate-selection cue: when the signal appears in changed code, add the named article to the worklist and evaluate it in Action. - A `* Setup` table or its page changes singleton structure, uses a nonblank or generated key, permits insert/delete, uses a List page, or does not ensure the blank-keyed row exists — `setup-table-is-a-singleton`. +- Code reads `Item Ledger Entry."Document No."` (or `"Last Shipping No."`/`"Last Posting No."`) after a combined Ship+Invoice **sales** post — `item-ledger-entry-document-no-follows-last-shipping-no`. This is a sales-specific rule: purchase combined posting is Receive+Invoice and uses receiving fields such as `"Last Receiving No."`, not the shipment/document-number behavior this article describes. Do not worklist it from purchase posting code. - A custom master table changes its primary key, `No.`/`No. Series` fields, or `OnInsert` without assigning a blank `No.` from setup through a number series — `master-table-no-from-number-series-in-oninsert`. - BC v22 or later code introduces or retains `NoSeriesManagement`, `InitSeries`, `SelectSeries`, or `SetSeries`, or number assignment/manual-entry checks do not use codeunit `"No. Series"` methods such as `GetNextNo`, `IsManual`, or `TestManual` — `use-no-series-codeunit-not-noseriesmanagement`. - A master gains or changes `Blocked`, or a document line, journal line, reference-field `OnValidate`, or posting routine uses that master without `TestField(Blocked, false)` at the point of use; also cue when the check is placed only in the master's own triggers — `check-blocked-in-referencing-code-not-in-master`. @@ -87,7 +88,7 @@ Outcome selection: - `completed` — the skill evaluated every worklist item. - `no-knowledge` — no applicable data-modeling knowledge survived filtering. -- `not-applicable` — the diff touches no setup/master table, page, key, numbering, block-check, or audit-field surface. +- `not-applicable` — the diff touches no setup/master table, page, key, numbering, block-check, audit-field, dimension-wiring, posting-routine-structure, or Item-Ledger-Entry-document-number surface. - `partial` — a budget was hit before the worklist was exhausted. - `failed` — an unrecoverable error occurred. diff --git a/microsoft/skills/review/al-testing-review.md b/microsoft/skills/review/al-testing-review.md index de0c9be..6986977 100644 --- a/microsoft/skills/review/al-testing-review.md +++ b/microsoft/skills/review/al-testing-review.md @@ -39,7 +39,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially codeunits with `Subtype = Test`, test runner codeunits with `TestIsolation`, test libraries, and codeunits that define UI handlers. - The changed methods and attributes, weighted toward `[Test]`, `[TransactionModel(...)]`, `[TestPermissions(...)]`, `[HandlerFunctions(...)]`, handler attributes, `asserterror`, `ExpectedError`, `ExpectedErrorCode`, fixture initialization, and test-library calls. -- Tokens extracted from the diff that relate to testing (`Subtype = Test`, `Subtype = TestRunner`, `TestIsolation`, `TestPermissions`, `Restrictive`, `NonRestrictive`, `Disabled`, `Permissions Mock`, `Library - Lower Permissions`, `TransactionModel`, `AutoRollback`, `AutoCommit`, `Commit`, `asserterror`, `ExpectedError`, `ExpectedErrorCode`, `HandlerFunctions`, `ConfirmHandler`, `MessageHandler`, `StrMenuHandler`, `ModalPageHandler`, `SendNotificationHandler`, `RecallNotificationHandler`, `Enqueue`, `Dequeue`, `AssertEmpty`, `Library Assert`, `LibraryVariableStorage`, `LibrarySales`, `LibraryPurchase`, `LibraryERM`, `LibraryInventory`, `LibraryRandom`, `Init`, `Insert`). +- Tokens extracted from the diff that relate to testing (`Subtype = Test`, `Subtype = TestRunner`, `TestIsolation`, `TestPermissions`, `Restrictive`, `NonRestrictive`, `Disabled`, `Permissions Mock`, `Library - Lower Permissions`, `TransactionModel`, `AutoRollback`, `AutoCommit`, `Commit`, `asserterror`, `ExpectedError`, `ExpectedErrorCode`, `HandlerFunctions`, `ConfirmHandler`, `MessageHandler`, `StrMenuHandler`, `ModalPageHandler`, `SendNotificationHandler`, `RecallNotificationHandler`, `Enqueue`, `Dequeue`, `AssertEmpty`, `Library Assert`, `LibraryVariableStorage`, `LibrarySales`, `LibraryPurchase`, `LibraryERM`, `LibraryInventory`, `LibraryRandom`, `Library - Utility`, `LibraryUtility`, `GenerateGUID`, `GenerateRandomCode`, `TestPage`, `.Visible(`, `.Enabled(`, `.Editable(`, `OpenNew`, `OpenView`, `OpenEdit`, `Init`, `Insert`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. When the diff contains no testing-related changes by any of the above signals, return `outcome: "not-applicable"` without evaluating files. @@ -50,6 +50,8 @@ The following targeted checks cover every current `testing` article. Treat each - A permission-sensitive test uses `TestPermissions = Disabled`, claims to test a restricted user without `"Permissions Mock"`/`"Library - Lower Permissions"`, or declares `[TestPermissions(...)]` without applying that context — `permission-tests-must-lower-the-execution-context`. - Test fixture code manually calls `Init`/`Insert`, invents keys or prerequisite records, or bypasses available `LibrarySales`, `LibraryPurchase`, `LibraryERM`, `LibraryInventory`, `LibraryRandom`, or equivalent library codeunits — `use-library-codeunits-for-test-fixtures`. - `asserterror` is added or changed without a following `Assert.ExpectedError`, `Assert.ExpectedErrorCode`, or a purpose-built assertion such as `ExpectedTestFieldError` — `asserterror-needs-expectederror-and-code`. +- Test fixture code assigns a hardcoded literal to a primary-key field or a field the test relies on as a unique lookup identifier, hand-builds a "unique" value for such a field (string concatenation, a counter, `Format(CurrentDateTime)`), or truncates `LibraryUtility.GenerateGUID()`'s result with `CopyStr` for such a field shorter than 10 characters — `use-generateguid-for-unique-test-fixture-values`. Calling `GenerateGUID()` untruncated into a full-length field, `GenerateRandomCodeWithLength` for a shorter field needing real verified uniqueness, or `GenerateRandomCode20` specifically for a `Code[20]` field, is the compliant shape, not the signal to flag. `GenerateRandomCode20` is not a substitute for `GenerateRandomCodeWithLength` on a shorter field — it truncates `GenerateGUID()`'s sequential value down to the field's length by keeping the *leftmost* characters, which change the slowest, so retries against a short field can churn through the same truncated prefix far longer than `GenerateRandomCodeWithLength`'s equivalent. A hardcoded or deterministic value in an ordinary descriptive field is not this anti-pattern — that field carries no uniqueness constraint. Do not claim `GenerateRandomCode` (without `WithLength`/`20`) or `GenerateRandomXMLText` verify uniqueness against the real table, or that `GenerateRandomCode` is collision-free even within one test run for a short field — none of that is true. +- A test asserts against a `TestPage` field's `.Visible()` or `.Enabled()` — `use-testpage-visible-enabled-to-verify-field-ui-state`. When the assertion is against `.Editable()`, or the page is opened with `OpenEdit()` specifically to check editability — `use-testpage-editable-to-verify-field-editability`. - A test path raises UI and `[HandlerFunctions(...)]` does not match the invoked handlers, or the test has no meaningful evidence of the UI result (for example, it treats a Boolean set before the action as proof of success) — `ui-handlers-in-tests`. A capture/reset/assert-after-`RunModal` pattern is valid. Enqueue/dequeue and `AssertEmpty` are required only when order, count, text, replies, or a scripted sequence is part of the contract. Only nonoptional handlers have to execute: a listed handler declared `[SendNotificationHandler(true)]` or `[RecallNotificationHandler(true)]` is optional by design, so do not treat it as unmatched when the run never raises the notification. - A test's `[GIVEN]`/setup looks up a hardcoded code/number/name assumed to already exist instead of creating it, leaves a mandatory field on a created record empty, uses a value that doesn't satisfy the scenario's own explicit length/format requirement (for example a truncation test whose value never exceeds the field), or a scenario-defining value (amount, quantity, percentage, date, threshold, rounding precision) is generated/randomized instead of an explicit chosen value — `test-data-must-be-random-and-complete`. Generating incidental fixture values (identifiers, names, descriptions) via the standard library codeunits is the compliant shape, not the signal to flag, and neither is a short-but-valid value in an otherwise-unremarkable field. From 130d5de6c4bd72d2158240fe431862b6434c735a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nikolaj=20Jakobi=20N=C3=B8ttrup?= Date: Tue, 29 Sep 2026 12:49:55 +0200 Subject: [PATCH 28/35] Fix indirect permission letters in indirect-permissions-for-elevated-access (#199) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each letter of a permission value is one permission, so `ri` is indirect read plus indirect insert. The good sample granted a read-only "Report Runner" role indirect insert on G/L Entry. Use `r` in the sample, name the lowercase letters in Best Practice, replace the ri/ii/mi/di keywords and cite the Microsoft Learn pages that define the letters. Co-authored-by: Nikolaj Jakobi Nøttrup <242577394+Nikolaj1407@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 --- .../indirect-permissions-for-elevated-access.good.al | 2 +- .../security/indirect-permissions-for-elevated-access.md | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/microsoft/knowledge/security/indirect-permissions-for-elevated-access.good.al b/microsoft/knowledge/security/indirect-permissions-for-elevated-access.good.al index 9fef5e4..f69dbc3 100644 --- a/microsoft/knowledge/security/indirect-permissions-for-elevated-access.good.al +++ b/microsoft/knowledge/security/indirect-permissions-for-elevated-access.good.al @@ -1,4 +1,4 @@ permissionset 50203 "Sec Sample Report Runner" { - Permissions = tabledata "G/L Entry" = ri; + Permissions = tabledata "G/L Entry" = r; } diff --git a/microsoft/knowledge/security/indirect-permissions-for-elevated-access.md b/microsoft/knowledge/security/indirect-permissions-for-elevated-access.md index 2a39b9c..8e3d620 100644 --- a/microsoft/knowledge/security/indirect-permissions-for-elevated-access.md +++ b/microsoft/knowledge/security/indirect-permissions-for-elevated-access.md @@ -1,7 +1,7 @@ --- bc-version: [all] domain: security -keywords: [permissionset, indirect-permissions, ri, ii, mi, di, code-mediated] +keywords: [permissionset, indirect-permissions, lowercase, code-mediated] technologies: [al] countries: [w1] application-area: [all] @@ -15,8 +15,12 @@ In a `permissionset`, uppercase letters (`R`, `I`, `M`, `D`) grant **direct** pe ## Best Practice -Use indirect permissions (`ri`, `ii`, `mi`, `di`) when a role needs access to a sensitive table only through a specific codeunit or report — for example, a "Report Runner" role that reads `G/L Entry` only via published reports. Pair the indirect grant with the codeunit or report that mediates access; that object's own permissions (or InherentPermissions) supply the direct rights. Document why indirect permissions are required in the permission set or in the consuming object's comments. See sample: [`indirect-permissions-for-elevated-access.good.al`](indirect-permissions-for-elevated-access.good.al). +Use indirect permissions (the lowercase letters `r`, `i`, `m`, `d`) when a role needs access to a sensitive table only through a specific codeunit or report — for example, a "Report Runner" role that reads `G/L Entry` only via published reports, granted `tabledata "G/L Entry" = r`. Each letter is one permission: `ri` grants indirect read **and** indirect insert, so grant only the letters the role needs. Pair the indirect grant with the codeunit or report that mediates access; that object's own permissions (or InherentPermissions) supply the direct rights. Document why indirect permissions are required in the permission set or in the consuming object's comments. See sample: [`indirect-permissions-for-elevated-access.good.al`](indirect-permissions-for-elevated-access.good.al). ## Anti Pattern Granting `RIMD` on a sensitive table when the role only needs to view it through a report — for example `tabledata "G/L Entry" = RIMD` on a "Report Runner" role. Users assigned that role can now query and modify ledger entries directly through any client that respects the permission, bypassing the report entirely. Reviewers should look for uppercase grants on system-of-record tables (G/L Entry, ledger entries, posted documents) where the consuming code path is clearly read-through-report or read-through-API. See sample: [`indirect-permissions-for-elevated-access.bad.al`](indirect-permissions-for-elevated-access.bad.al). + +## References + +[Permissions property](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/properties/devenv-permissions-property) and [Permissions on database objects](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-permissions-on-database-objects) define one letter per permission: `R`/`r` read, `I`/`i` insert, `M`/`m` modify, `D`/`d` delete, uppercase for direct and lowercase for indirect. From 4287233f80678fd4fb02aca6455d9cf046ca9262 Mon Sep 17 00:00:00 2001 From: Stefano Demiliani <33155438+demiliani@users.noreply.github.com> Date: Tue, 29 Sep 2026 13:03:39 +0200 Subject: [PATCH 29/35] Strengthen review contracts and add AL reliability guidance (#196) * Strengthen review contracts and HTTP guidance - add outbound HttpClient transport and HTTP status review rules with paired fixtures`n- resolve layered action-skill overrides deterministically across enabled layers`n- validate findings reports and enforce measurable changed-fixture coverage * Add data handling and test isolation guidance - add SCM guidance for deriving base quantities through line unit-of-measure validation`n- add security guidance for parameterizing SetFilter with external text`n- add test isolation guidance for resetting per-test state before initialization guards`n- add web-service guidance for JSON null handling and invariant standard format 9`n- route and cover all five rules with paired evaluation fixtures * Fix findings report rollup validation * Validate findings report rollups * Enforce merged finding identity * Fix locationless finding deduplication * Reject conflicting merged corrections * Detect conflicting leaf corrections * Route HTTP error checks to canonical web-services knowledge Let the Error Handling leaf conditionally retrieve the existing HTTP owner articles, preserving applicability and exact-path provenance. Add deterministic source-contract and retrieval regressions without duplicating knowledge rules. Copilot-Session-Id: a92a7788-103e-4651-9b84-19e34caffb94 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: wenjiefan Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Jesper Schulz-Wedde --- .github/scripts/Test-SkillIndex.ps1 | 79 ++- .github/scripts/validate_frontmatter.py | 8 +- .github/workflows/review-fixtures.yml | 21 +- docs/customizing-bcquality.md | 9 + docs/standalone-runner.md | 16 +- evaluation/README.md | 16 + evaluation/review-fixtures.json | 23 +- ...es-through-the-line-unit-of-measure.bad.al | 26 + ...s-through-the-line-unit-of-measure.good.al | 25 + ...tities-through-the-line-unit-of-measure.md | 37 ++ ...tenate-external-text-into-setfilter.bad.al | 11 + ...enate-external-text-into-setfilter.good.al | 25 + ...oncatenate-external-text-into-setfilter.md | 36 ++ ...tate-before-the-isinitialized-guard.bad.al | 57 ++ ...ate-before-the-isinitialized-guard.good.al | 62 ++ ...st-state-before-the-isinitialized-guard.md | 41 ++ ...atus-before-consuming-response-body.bad.al | 21 + ...tus-before-consuming-response-body.good.al | 23 + ...p-status-before-consuming-response-body.md | 31 + ...-json-null-before-converting-values.bad.al | 11 + ...json-null-before-converting-values.good.al | 28 + ...heck-json-null-before-converting-values.md | 35 ++ ...anged-values-with-standard-format-9.bad.al | 27 + ...nged-values-with-standard-format-9.good.al | 27 + ...exchanged-values-with-standard-format-9.md | 39 ++ ...form-failure-before-response-access.bad.al | 18 + ...orm-failure-before-response-access.good.al | 18 + ...platform-failure-before-response-access.md | 31 + microsoft/skills/review/al-code-review.md | 8 +- .../skills/review/al-error-handling-review.md | 8 + microsoft/skills/review/al-scm-review.md | 1 + microsoft/skills/review/al-security-review.md | 2 +- microsoft/skills/review/al-testing-review.md | 3 +- .../skills/review/al-web-services-review.md | 21 +- skills/do.md | 25 +- tools/Build-SkillIndex.ps1 | 16 +- tools/Resolve-SkillWorklist.ps1 | 92 +++ tools/Test-KnowledgeRetrieval.ps1 | 54 ++ tools/Test-ReviewContract.ps1 | 359 +++++++++++- tools/Test-ReviewFixtures.ps1 | 82 ++- tools/Validate-FindingsReport.ps1 | 540 ++++++++++++++++++ 41 files changed, 1974 insertions(+), 38 deletions(-) create mode 100644 microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.bad.al create mode 100644 microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.good.al create mode 100644 microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.md create mode 100644 microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.bad.al create mode 100644 microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.good.al create mode 100644 microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.md create mode 100644 microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.bad.al create mode 100644 microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.good.al create mode 100644 microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.md create mode 100644 microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.bad.al create mode 100644 microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.good.al create mode 100644 microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.md create mode 100644 microsoft/knowledge/web-services/check-json-null-before-converting-values.bad.al create mode 100644 microsoft/knowledge/web-services/check-json-null-before-converting-values.good.al create mode 100644 microsoft/knowledge/web-services/check-json-null-before-converting-values.md create mode 100644 microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.bad.al create mode 100644 microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.good.al create mode 100644 microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.md create mode 100644 microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.bad.al create mode 100644 microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.good.al create mode 100644 microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.md create mode 100644 tools/Resolve-SkillWorklist.ps1 create mode 100644 tools/Validate-FindingsReport.ps1 diff --git a/.github/scripts/Test-SkillIndex.ps1 b/.github/scripts/Test-SkillIndex.ps1 index b694a5b..bc635f2 100644 --- a/.github/scripts/Test-SkillIndex.ps1 +++ b/.github/scripts/Test-SkillIndex.ps1 @@ -30,9 +30,10 @@ function Assert-ThrowsLike { } $generator = Join-Path $Root 'tools/Build-SkillIndex.ps1' +$resolver = Join-Path $Root 'tools/Resolve-SkillWorklist.ps1' $indexSchema = Join-Path $Root 'schemas/skill-index.schema.json' $reportSchema = Join-Path $Root 'schemas/findings-report.schema.json' -foreach ($path in $generator, $indexSchema, $reportSchema) { +foreach ($path in $generator, $resolver, $indexSchema, $reportSchema) { if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { throw "Required contract file not found: $path" } @@ -235,9 +236,83 @@ Output. Assert-ThrowsLike -Pattern '*Nested super-skills are not supported*' -Action { & $generator -BCQualityRoot $fixtureRoot -IndexPath (Join-Path $tmp 'nested.json') } + + Remove-Item -LiteralPath (Join-Path $fixtureSkills 'al-nested-review.md') -Force + $validSuper = @' +--- +kind: action-skill +id: al-code-review +version: 1 +title: Review +description: Test super-skill. +inputs: [file-path] +outputs: [findings-report] +sub-skills: + - microsoft/skills/review/al-leaf-review.md +--- + +# Review + +## Source +Source. +## Relevance +Relevance. +## Worklist +Worklist. +## Action +Action. +## Output +Output. +'@ + Set-Content -LiteralPath $superPath -Value $validSuper -Encoding utf8NoBOM + + $customSkills = Join-Path -Path $fixtureRoot -ChildPath 'custom/skills/review' + New-Item -ItemType Directory -Path $customSkills -Force | Out-Null + $customLeaf = $leaf.Replace('title: Leaf', 'title: Custom Leaf') + Set-Content -LiteralPath (Join-Path $customSkills 'custom-leaf-review.md') -Value $customLeaf -Encoding utf8NoBOM + + $layeredPath = Join-Path $tmp 'layered.json' + & $generator -BCQualityRoot $fixtureRoot -IndexPath $layeredPath | Out-Null + $layeredIndex = Get-Content -LiteralPath $layeredPath -Raw | ConvertFrom-Json + $layeredLeaves = @($layeredIndex.skills | Where-Object id -eq 'al-leaf-review') + if ($layeredLeaves.Count -ne 2) { + throw "Expected both layered al-leaf-review implementations, found $($layeredLeaves.Count)." + } + if ((@($layeredLeaves.layer | Sort-Object) -join ',') -cne 'custom,microsoft') { + throw 'Layered al-leaf-review implementations did not preserve custom and microsoft records.' + } + + $resolved = & $resolver -BCQualityRoot $fixtureRoot -IndexPath $layeredPath -SuperSkillPath ( + 'microsoft/skills/review/al-code-review.md' + ) + if ($resolved.subSkills.Count -ne 1 -or + $resolved.subSkills[0].path -cne 'custom/skills/review/custom-leaf-review.md') { + throw 'The custom implementation did not win the layered leaf slot.' + } + + $microsoftOnly = & $resolver -BCQualityRoot $fixtureRoot -IndexPath $layeredPath -SuperSkillPath ( + 'microsoft/skills/review/al-code-review.md' + ) -EnabledLayers microsoft + if ($microsoftOnly.subSkills.Count -ne 1 -or + $microsoftOnly.subSkills[0].path -cne 'microsoft/skills/review/al-leaf-review.md') { + throw 'Disabling the custom layer did not fall back to the Microsoft implementation.' + } + + $customDisabled = & $resolver -BCQualityRoot $fixtureRoot -IndexPath $layeredPath -SuperSkillPath ( + 'microsoft/skills/review/al-code-review.md' + ) -DisabledSkills 'custom/skills/review/custom-leaf-review.md' + if ($customDisabled.subSkills.Count -ne 1 -or + $customDisabled.subSkills[0].path -cne 'microsoft/skills/review/al-leaf-review.md') { + throw 'Disabling the custom implementation did not fall back to Microsoft.' + } + + Set-Content -LiteralPath (Join-Path $customSkills 'duplicate-leaf-review.md') -Value $customLeaf -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*Duplicate action-skill IDs within a layer: custom:al-leaf-review*' -Action { + & $generator -BCQualityRoot $fixtureRoot -IndexPath (Join-Path $tmp 'duplicate-layer.json') + } } finally { Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue } -Write-Output "Skill-index check PASSED: deterministic, schema-valid, and all $($expectedLeaves.Count) review leaves preserved in order." +Write-Output "Skill-index check PASSED: deterministic, schema-valid, layered overrides resolved, and all $($expectedLeaves.Count) review leaves preserved in order." diff --git a/.github/scripts/validate_frontmatter.py b/.github/scripts/validate_frontmatter.py index 20f33d6..51ff546 100644 --- a/.github/scripts/validate_frontmatter.py +++ b/.github/scripts/validate_frontmatter.py @@ -688,12 +688,16 @@ def run(root: Path) -> Report: if domain_dir.is_dir(): validate_samples_in_domain(domain_dir, root, report) - # Third pass: R24 unique ids within kind + # Third pass: R24 unique ids within kind. Layered action-skill overrides + # may share an id, but two definitions in one layer are ambiguous. by_kind: dict[str, dict[str, list[Path]]] = {} for rec in skill_records: if rec.skill_id is None: continue - by_kind.setdefault(rec.kind, {}).setdefault(rec.skill_id, []).append(rec.path) + scope = rec.kind + if rec.kind == "action-skill": + scope = f"{rec.kind}:{rec.path.relative_to(root).parts[0]}" + by_kind.setdefault(scope, {}).setdefault(rec.skill_id, []).append(rec.path) for kind, by_id in by_kind.items(): for sid, paths in by_id.items(): if len(paths) > 1: diff --git a/.github/workflows/review-fixtures.yml b/.github/workflows/review-fixtures.yml index 0f39d9a..0de9a02 100644 --- a/.github/workflows/review-fixtures.yml +++ b/.github/workflows/review-fixtures.yml @@ -12,7 +12,26 @@ jobs: steps: - name: Check out repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + + - name: Collect changed paths + shell: pwsh + env: + BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }} + run: | + $paths = if (-not $env:BASE_SHA -or $env:BASE_SHA -match '^0+$') { + @(git diff-tree --no-commit-id --name-only -r $env:GITHUB_SHA) + } else { + @(git diff --name-only $env:BASE_SHA $env:GITHUB_SHA) + } + $paths | Set-Content -LiteralPath "$env:RUNNER_TEMP/changed-paths.txt" -Encoding utf8NoBOM - name: Validate review evaluation corpus shell: pwsh - run: ./tools/Test-ReviewFixtures.ps1 -Root . -PrepareDirectory "$env:RUNNER_TEMP/bcquality-review-fixtures" + run: | + ./tools/Test-ReviewFixtures.ps1 -Root . ` + -PrepareDirectory "$env:RUNNER_TEMP/bcquality-review-fixtures" ` + -ChangedPathsFile "$env:RUNNER_TEMP/changed-paths.txt" ` + -CoverageReportPath "$env:RUNNER_TEMP/review-coverage.json" + Get-Content -LiteralPath "$env:RUNNER_TEMP/review-coverage.json" diff --git a/docs/customizing-bcquality.md b/docs/customizing-bcquality.md index d3d9148..4809fcd 100644 --- a/docs/customizing-bcquality.md +++ b/docs/customizing-bcquality.md @@ -44,6 +44,15 @@ Otherwise the layers are additive. A matching filename alone does not suppress an article; the [READ contract](../skills/read.md#layer-precedence) governs knowledge conflicts. Review reports record displaced knowledge in `suppressed`. +Action skills use the same layer order but override by frontmatter `id`. A +custom leaf with the same `id` as a Community or Microsoft leaf replaces that +leaf in every super-skill slot while its layer is enabled. The files may have +different names. IDs must remain unique within each layer. Disabling the custom +layer or the custom skill path makes composition fall back to the next enabled +implementation. Hosts should build the skill index and use +`tools/Resolve-SkillWorklist.ps1`; they must not implement this selection from +filenames. + Layer selection is **not an access-control boundary**. A plugin installation still contains excluded layers on disk. An integration requiring genuine exclusion must remove denied files from its own content copy before the agent diff --git a/docs/standalone-runner.md b/docs/standalone-runner.md index 5829e4e..e5e2a0c 100644 --- a/docs/standalone-runner.md +++ b/docs/standalone-runner.md @@ -49,16 +49,20 @@ only result. action skills to run. Do not reproduce its routing logic. 3. Execute every dispatched action skill with the exact input subset in its dispatch record. Read `skills/read.md` and `skills/do.md` on demand. -4. When an action skill declares `sub-skills`, execute every relevant leaf as a - discrete invocation. Leaves are independent and may be scheduled serially - or concurrently. +4. When an action skill declares `sub-skills`, resolve its ordered leaf slots + with `tools/Resolve-SkillWorklist.ps1`, passing the enabled layers and + disabled skill paths from the task context. Execute every resolved leaf as + a discrete invocation. Leaves are independent and may be scheduled serially + or concurrently. 5. Capture the exact Task return as the immutable raw audit payload and primary transport. Preserve it unchanged in private artifacts or host logs. Before the full DO acceptance gate, create a normalized candidate only for DO's bounded optional-range case, record that normalization separately in private telemetry, and accept the candidate only if the entire copy passes the - unchanged strict gate. The accepted report contains no undeclared telemetry - fields. + unchanged strict gate. Use `tools/Validate-FindingsReport.ps1`, passing the + exact source paths and fully retrieved article paths; pass `-SkillKind super` + for the final rolled-up report. The accepted report contains no undeclared + telemetry fields. 6. Collect each accepted findings-report into `sub-results` in the declared `sub-skills` order, not completion order. Run the super-skill self-review only after all leaves have finished. @@ -92,6 +96,8 @@ A compatible runner: - invokes every worklisted leaf exactly once unless a documented retry replaces a failed attempt; +- resolves same-ID leaf implementations by `custom > community > microsoft`, + preserves declared slot order, and falls back when a higher layer is disabled; - keeps leaf contexts isolated and passes only the inputs they declare; - preserves each raw Task return unchanged for audit and distinguishes it from any normalized accepted copy; diff --git a/evaluation/README.md b/evaluation/README.md index bce3208..5863fcc 100644 --- a/evaluation/README.md +++ b/evaluation/README.md @@ -4,6 +4,15 @@ The evaluation is convention-driven. The harness discovers every `/skills `review-fixtures.json` contains only global thresholds and optional exceptional overrides. An override may select a different `article`, add context when the generic convention cannot express a scenario, or use an `articles` array when one domain needs explicit regression coverage for several paired articles. Specify either `article` or `articles`, not both. The first selected article retains the stable `-bad` and `-good` manifest IDs; additional articles use slug-qualified IDs. Overrides should remain empty in the normal case. +CI also measures selected paired articles against every effective article that +has both AL companions. A changed paired article must be selected by the +domain convention or an override. When adding it would not provide a useful +deterministic regression, add a narrow `coverageWaivers` entry with its exact +article path and a non-empty reason. Waivers are reviewable exceptions, not a +substitute for domain coverage. The generated coverage report includes totals +and per-domain ratios; the ratio is informational, while changed-file coverage +is mandatory. + Model-facing preparation hashes case IDs, neutralizes `Good`/`Bad` object-name tokens, and removes full-line sample comments so neither the article slug, domain, nor expected outcome reveals the answer. The SCM `articles` override deliberately selects every rule in the initial @@ -36,6 +45,13 @@ pwsh ./tools/Test-ReviewFixtures.ps1 -Root . This credential-free check proves every selected leaf maps to a same-named knowledge domain with at least one complete AL sample pair and that all configured overrides are valid. +To reproduce the changed-file gate and emit the same measurable report as CI: + +```powershell +git diff --name-only origin/main...HEAD | Set-Content .changed-paths.txt +pwsh ./tools/Test-ReviewFixtures.ps1 -Root . -ChangedPathsFile .changed-paths.txt -CoverageReportPath .coverage.json +``` + ## Run a fast-model evaluation 1. Prepare neutral inputs: diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index 3f131a5..90fc7d1 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -3,6 +3,7 @@ "selection": "first-paired-al-article", "minimumExpectedRecall": 1.0, "minimumCleanRate": 1.0, + "coverageWaivers": [], "overrides": { "agents": { "article": "wire-all-three-agent-interfaces" @@ -75,7 +76,14 @@ "reconcile-warehouse-adjustments-with-the-item-ledger", "post-transfers-through-shipment-and-receipt-codeunits", "use-date-aware-availability-for-promising", - "carry-out-requisition-actions-through-the-standard-workflow" + "carry-out-requisition-actions-through-the-standard-workflow", + "derive-base-quantities-through-the-line-unit-of-measure" + ] + }, + "security": { + "articles": [ + "al-has-no-built-in-htmlencode", + "do-not-concatenate-external-text-into-setfilter" ] }, "style": { @@ -88,14 +96,23 @@ "article": "telemetry-event-id-stable-unique" }, "testing": { - "article": "ui-handlers-in-tests" + "articles": [ + "ui-handlers-in-tests", + "reset-per-test-state-before-the-isinitialized-guard" + ] }, "upgrade": { "article": "initvalue-does-not-update-existing-rows", "context": "The extended table existed in the previous app version and already contains rows." }, "web-services": { - "article": "expose-systemid-as-the-api-key" + "articles": [ + "expose-systemid-as-the-api-key", + "handle-httpclient-platform-failure-before-response-access", + "check-http-status-before-consuming-response-body", + "check-json-null-before-converting-values", + "format-exchanged-values-with-standard-format-9" + ] } } } diff --git a/microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.bad.al b/microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.bad.al new file mode 100644 index 0000000..744ad53 --- /dev/null +++ b/microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.bad.al @@ -0,0 +1,26 @@ +codeunit 50181 "Scanner Receipt Import Bad" +{ + procedure PostScannedReceipt(ItemNo: Code[20]; LocationCode: Code[10]; UnitOfMeasureCode: Code[10]; ScannedQuantity: Decimal; DocumentNo: Code[20]) + var + ItemJournalLine: Record "Item Journal Line"; + ItemJnlPostLine: Codeunit "Item Jnl.-Post Line"; + begin + if ScannedQuantity <= 0 then + Error(PositiveQuantityErr); + + ItemJournalLine.Init(); + ItemJournalLine.Validate("Posting Date", WorkDate()); + ItemJournalLine.Validate("Entry Type", ItemJournalLine."Entry Type"::"Positive Adjmt."); + ItemJournalLine.Validate("Document No.", DocumentNo); + ItemJournalLine.Validate("Item No.", ItemNo); + ItemJournalLine.Validate("Location Code", LocationCode); + ItemJournalLine."Unit of Measure Code" := UnitOfMeasureCode; + ItemJournalLine.Quantity := ScannedQuantity; + ItemJournalLine."Quantity (Base)" := ScannedQuantity; + + ItemJnlPostLine.RunWithCheck(ItemJournalLine); + end; + + var + PositiveQuantityErr: Label 'The scanned quantity must be greater than zero.'; +} diff --git a/microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.good.al b/microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.good.al new file mode 100644 index 0000000..6280b59 --- /dev/null +++ b/microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.good.al @@ -0,0 +1,25 @@ +codeunit 50180 "Scanner Receipt Import Good" +{ + procedure PostScannedReceipt(ItemNo: Code[20]; LocationCode: Code[10]; UnitOfMeasureCode: Code[10]; ScannedQuantity: Decimal; DocumentNo: Code[20]) + var + ItemJournalLine: Record "Item Journal Line"; + ItemJnlPostLine: Codeunit "Item Jnl.-Post Line"; + begin + if ScannedQuantity <= 0 then + Error(PositiveQuantityErr); + + ItemJournalLine.Init(); + ItemJournalLine.Validate("Posting Date", WorkDate()); + ItemJournalLine.Validate("Entry Type", ItemJournalLine."Entry Type"::"Positive Adjmt."); + ItemJournalLine.Validate("Document No.", DocumentNo); + ItemJournalLine.Validate("Item No.", ItemNo); + ItemJournalLine.Validate("Location Code", LocationCode); + ItemJournalLine.Validate("Unit of Measure Code", UnitOfMeasureCode); + ItemJournalLine.Validate(Quantity, ScannedQuantity); + + ItemJnlPostLine.RunWithCheck(ItemJournalLine); + end; + + var + PositiveQuantityErr: Label 'The scanned quantity must be greater than zero.'; +} diff --git a/microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.md b/microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.md new file mode 100644 index 0000000..3f3d3a0 --- /dev/null +++ b/microsoft/knowledge/scm/derive-base-quantities-through-the-line-unit-of-measure.md @@ -0,0 +1,37 @@ +--- +bc-version: [all] +domain: scm +keywords: [quantity-base, qty-per-unit-of-measure, unit-of-measure-code, unit-of-measure-management, calcbaseqty, getqtyperunitofmeasure, qty-rounding-precision, item-journal-line] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Derive base quantities through the line's unit of measure + +## Description + +Inventory, item ledger entries, reservations, item tracking, and warehouse quantities are measured in the item's base unit of measure. Document and journal lines hold `Quantity` in the line's `"Unit of Measure Code"`, together with `"Qty. per Unit of Measure"` and base-unit fields such as `"Quantity (Base)"`. Ten boxes of twelve pieces are 120 base units, not 10. When a line's `Quantity` is validated, the table derives the base quantity through its `CalcBaseQty` procedure. That procedure calls `"Unit of Measure Management".CalcBaseQty` with the line's quantity rounding precision and raises an error when rounding would turn a non-zero quantity into a zero base quantity. Code that bypasses this conversion creates a line whose quantity and base quantity disagree, or makes a stock decision in the wrong unit. + +## Best Practice + +On a document or journal line, validate `"Unit of Measure Code"` before `Quantity`, and validate both. Validating the unit of measure sets `"Qty. per Unit of Measure"` from the item unit of measure; validating the quantity then fills the base fields with the correct rounding. Compare line quantities with inventory or availability in base units, for example `"Quantity (Base)"` or `"Outstanding Qty. (Base)"`. + +Outside a line, get the factor with `"Unit of Measure Management".GetQtyPerUnitOfMeasure(Item, UnitOfMeasureCode)` and convert with its `CalcBaseQty` or `CalcQtyFromBase` procedures instead of multiplying by hand. Pass the item unit's quantity rounding precision where the available overload accepts it. + +Reading these fields for display, reporting, or a temporary buffer that is never posted is not a conversion defect. Code that proves the line uses the base unit of measure (`"Qty. per Unit of Measure"` equal to 1) is also correct, but don't assume this from the item alone, because a line can use another unit. + +See sample: [`derive-base-quantities-through-the-line-unit-of-measure.good.al`](derive-base-quantities-through-the-line-unit-of-measure.good.al). + +## Anti Pattern + +Assigning `Quantity` directly on an item journal, sales, purchase, or transfer line and then inserting, modifying, or posting it. Also assigning a base field such as `"Quantity (Base)" := Quantity`, multiplying by a hard-coded or separately looked-up factor without the line's rounding, or comparing a line's `Quantity` with `Item.Inventory` or another base-unit value. Detection signal: a direct `:=` to `Quantity`, `"Qty. per Unit of Measure"`, or a `(Base)` quantity field on a persisted or posted line, or a comparison between a non-base line quantity and an inventory quantity. + +See sample: [`derive-base-quantities-through-the-line-unit-of-measure.bad.al`](derive-base-quantities-through-the-line-unit-of-measure.bad.al). + +## References + +- [Set up units of measure, including quantity rounding precision](https://learn.microsoft.com/en-us/dynamics365/business-central/inventory-how-setup-units-of-measure) +- [BCApps: Unit of Measure Management conversions](https://github.com/microsoft/BCApps/blob/4abbb8ff848cdcb4e1187fc7a3e2da0612dd0d2b/src/Layers/W1/BaseApp/Foundation/UOM/UnitofMeasureManagement.Codeunit.al) +- [BCApps: Item Journal Line quantity validation and CalcBaseQty](https://github.com/microsoft/BCApps/blob/4abbb8ff848cdcb4e1187fc7a3e2da0612dd0d2b/src/Layers/W1/BaseApp/Inventory/Journal/ItemJournalLine.Table.al) +- [BCApps: Sales Line quantity validation and CalcBaseQty](https://github.com/microsoft/BCApps/blob/4abbb8ff848cdcb4e1187fc7a3e2da0612dd0d2b/src/Layers/W1/BaseApp/Sales/Document/SalesLine.Table.al) diff --git a/microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.bad.al b/microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.bad.al new file mode 100644 index 0000000..ef67908 --- /dev/null +++ b/microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.bad.al @@ -0,0 +1,11 @@ +codeunit 50161 "Cancel External Quotes Bad" +{ + procedure CancelQuote(ExternalDocumentNo: Text) + var + SalesHeader: Record "Sales Header"; + begin + SalesHeader.SetRange("Document Type", SalesHeader."Document Type"::Quote); + SalesHeader.SetFilter("External Document No.", ExternalDocumentNo); + SalesHeader.DeleteAll(true); + end; +} diff --git a/microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.good.al b/microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.good.al new file mode 100644 index 0000000..329bc09 --- /dev/null +++ b/microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.good.al @@ -0,0 +1,25 @@ +codeunit 50160 "Cancel External Quotes Good" +{ + procedure CancelQuote(ExternalDocumentNo: Code[35]) + var + SalesHeader: Record "Sales Header"; + begin + if ExternalDocumentNo = '' then + Error(MissingExternalDocumentNoErr); + + SalesHeader.SetRange("Document Type", SalesHeader."Document Type"::Quote); + SalesHeader.SetRange("External Document No.", ExternalDocumentNo); + SalesHeader.DeleteAll(true); + end; + + procedure CancelQuotes(ExternalDocumentNos: List of [Code[35]]) + var + ExternalDocumentNo: Code[35]; + begin + foreach ExternalDocumentNo in ExternalDocumentNos do + CancelQuote(ExternalDocumentNo); + end; + + var + MissingExternalDocumentNoErr: Label 'The external document number is missing.'; +} diff --git a/microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.md b/microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.md new file mode 100644 index 0000000..df6a87f --- /dev/null +++ b/microsoft/knowledge/security/do-not-concatenate-external-text-into-setfilter.md @@ -0,0 +1,36 @@ +--- +bc-version: [all] +domain: security +keywords: [setfilter, setrange, filter-expression, filter-injection, external-input, wildcard, deleteall, modifyall] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Do not concatenate external text into a SetFilter expression + +## Description + +The `String` argument of `SetFilter` is a filter expression, not a value. Characters such as `..`, `|`, `&`, `<`, `>`, `=`, `*`, `?`, `@`, parentheses, and single quotes are operators. Text from a user, request page, API payload, file, or another system that is concatenated into that expression can therefore change which records match: `*` matches every value, `A|B` widens an exact lookup to two values, `10000..` becomes a range, and `J & V` becomes a conjunction or an invalid filter. `SetFilter` with an empty expression applies no filter at all. When the filtered record is then modified, deleted, exported, or used for a permission-relevant decision, the procedure acts on records the caller never identified. + +## Best Practice + +Treat an externally supplied identifier as a value. Use `SetRange(Field, Value)` for equality and `SetRange(Field, FromValue, ToValue)` for a typed range; neither parses operators. Reject an empty identifier explicitly when "no value" must not mean "every record". For several external values, apply `SetRange` once per value instead of joining them with `|`. + +Use `SetFilter` when an operator is part of the procedure's own contract. Keep the operator in a constant expression and pass operands through replacement fields (`%1`, `%2`) of the field's data type, such as a `Date` or `Decimal` operand for `'>=%1'`. Do not rely on wrapping text in single quotes to neutralize it: according to the filter syntax, quotes protect `&`, `(`, `)`, `=`, and `|`, but `*` still acts as a wildcard inside `'J & V*'`. + +Text that the user deliberately entered as a filter is supposed to be parsed. Do not report a request-page or `FilterPageBuilder` filter, a `GetFilters`/`GetView` round trip, a FlowFilter, or a field whose documented purpose is to hold a filter expression. Constant filter strings and operands produced by the extension's own code are also not external input. + +See sample: [`do-not-concatenate-external-text-into-setfilter.good.al`](do-not-concatenate-external-text-into-setfilter.good.al). + +## Anti Pattern + +`Rec.SetFilter(Field, ExternalText)` or `Rec.SetFilter(Field, Prefix + ExternalText + Suffix)` where the text is meant to identify one record or a known list of records, with no validation that restricts it to a literal value. The finding is strongest when the resulting set is written by `Modify`, `ModifyAll`, `Delete`, or `DeleteAll`, or is returned to an external caller. Detection signal: a non-constant expression, concatenation, or `StrSubstNo` result passed as the `String` argument of `SetFilter`, where the operand comes from a parameter, page field, JSON/XML value, file line, or HTTP request. + +See sample: [`do-not-concatenate-external-text-into-setfilter.bad.al`](do-not-concatenate-external-text-into-setfilter.bad.al). + +## References + +- [Record.SetFilter method, including the empty-filter remark](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/record/record-setfilter-method) +- [Filtering with SetRange and SetFilter](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-setcurrentkey-setrange-setfilter-getrangemin-and-getrangemax-methods) +- [Filter criteria, operators, and values that contain symbols](https://learn.microsoft.com/en-us/dynamics365/business-central/ui-enter-criteria-filters#filter-criteria-and-operators) diff --git a/microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.bad.al b/microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.bad.al new file mode 100644 index 0000000..afebd56 --- /dev/null +++ b/microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.bad.al @@ -0,0 +1,57 @@ +codeunit 50411 "Test Sales Setup Initialize Bad" +{ + Subtype = Test; + + [Test] + [HandlerFunctions('CustomerCardHandler')] + procedure CustomerCardOpensForSelectedCustomer() + var + Customer: Record Customer; + begin + Initialize(); + LibrarySales.CreateCustomer(Customer); + LibraryVariableStorage.Enqueue(Customer."No."); + + Page.RunModal(Page::"Customer Card", Customer); + + LibraryVariableStorage.AssertEmpty(); + end; + + [Test] + procedure StockoutWarningCanBeDisabled() + var + SalesSetup: Record "Sales & Receivables Setup"; + begin + Initialize(); + + LibrarySales.SetStockoutWarning(false); + + SalesSetup.Get(); + Assert.IsFalse(SalesSetup."Stockout Warning", 'The stockout warning was not disabled.'); + end; + + local procedure Initialize() + begin + if IsInitialized then + exit; + + LibraryVariableStorage.Clear(); + LibrarySetupStorage.Restore(); + LibrarySales.SetStockoutWarning(true); + IsInitialized := true; + LibrarySetupStorage.SaveSalesSetup(); + end; + + [ModalPageHandler] + procedure CustomerCardHandler(var CustomerCard: TestPage "Customer Card") + begin + Assert.AreEqual(LibraryVariableStorage.DequeueText(), CustomerCard."No.".Value(), 'The customer card opened for the wrong customer.'); + end; + + var + Assert: Codeunit Assert; + LibrarySales: Codeunit "Library - Sales"; + LibrarySetupStorage: Codeunit "Library - Setup Storage"; + LibraryVariableStorage: Codeunit "Library - Variable Storage"; + IsInitialized: Boolean; +} diff --git a/microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.good.al b/microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.good.al new file mode 100644 index 0000000..0d1d7c7 --- /dev/null +++ b/microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.good.al @@ -0,0 +1,62 @@ +codeunit 50410 "Test Sales Setup Initialize Good" +{ + Subtype = Test; + + [Test] + [HandlerFunctions('CustomerCardHandler')] + procedure CustomerCardOpensForSelectedCustomer() + var + Customer: Record Customer; + begin + Initialize(); + LibrarySales.CreateCustomer(Customer); + LibraryVariableStorage.Enqueue(Customer."No."); + + Page.RunModal(Page::"Customer Card", Customer); + + LibraryVariableStorage.AssertEmpty(); + end; + + [Test] + procedure StockoutWarningCanBeDisabled() + var + SalesSetup: Record "Sales & Receivables Setup"; + begin + Initialize(); + + LibrarySales.SetStockoutWarning(false); + + SalesSetup.Get(); + Assert.IsFalse(SalesSetup."Stockout Warning", 'The stockout warning was not disabled.'); + end; + + local procedure Initialize() + begin + LibraryTestInitialize.OnTestInitialize(Codeunit::"Test Sales Setup Initialize Good"); + LibraryVariableStorage.Clear(); + LibrarySetupStorage.Restore(); + + if IsInitialized then + exit; + LibraryTestInitialize.OnBeforeTestSuiteInitialize(Codeunit::"Test Sales Setup Initialize Good"); + + LibrarySales.SetStockoutWarning(true); + IsInitialized := true; + LibrarySetupStorage.SaveSalesSetup(); + LibraryTestInitialize.OnAfterTestSuiteInitialize(Codeunit::"Test Sales Setup Initialize Good"); + end; + + [ModalPageHandler] + procedure CustomerCardHandler(var CustomerCard: TestPage "Customer Card") + begin + Assert.AreEqual(LibraryVariableStorage.DequeueText(), CustomerCard."No.".Value(), 'The customer card opened for the wrong customer.'); + end; + + var + Assert: Codeunit Assert; + LibrarySales: Codeunit "Library - Sales"; + LibrarySetupStorage: Codeunit "Library - Setup Storage"; + LibraryTestInitialize: Codeunit "Library - Test Initialize"; + LibraryVariableStorage: Codeunit "Library - Variable Storage"; + IsInitialized: Boolean; +} diff --git a/microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.md b/microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.md new file mode 100644 index 0000000..2d2c417 --- /dev/null +++ b/microsoft/knowledge/testing/reset-per-test-state-before-the-isinitialized-guard.md @@ -0,0 +1,41 @@ +--- +bc-version: [all] +domain: testing +keywords: [initialize, isinitialized, library-test-initialize, ontestinitialize, library-variable-storage, library-setup-storage, test-fixture, test-codeunit] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Reset per-test state before the IsInitialized guard + +## Description + +Standard Business Central test codeunits call a local `Initialize` procedure at the start of every test method. Global variables in a test codeunit keep their values between the codeunit's test methods, so a Boolean such as `IsInitialized` lets `Initialize` run expensive shared setup only once. The procedure therefore has two parts with different lifetimes: work that must run before **every** test, and one-time setup behind the guard. If per-test reset is placed after the guard, it runs only for the first test. Values left in `Library - Variable Storage` by a failed test, or setup records a test changed, then leak into later tests, which pass or fail depending on execution order. + +## Best Practice + +Call `Initialize()` as the first statement of every test method. Inside it, keep this order, which the Base Application tests follow: + +1. Per-test work, before the guard: raise `"Library - Test Initialize".OnTestInitialize`, call `LibraryVariableStorage.Clear()`, and call `LibrarySetupStorage.Restore()` when setup tables were saved. +2. `if IsInitialized then exit;` +3. One-time work: raise `OnBeforeTestSuiteInitialize`, create the shared fixture and setup values, set `IsInitialized := true`, save the setup tables that tests may change (for example `LibrarySetupStorage.SaveSalesSetup()`), and raise `OnAfterTestSuiteInitialize`. + +Create data that a single test changes inside that test, not in the shared fixture. Base Application suites also commit after the one-time setup so the shared fixture survives each test's transaction; whether that commit is valid depends on the test transaction model and runner isolation, see [`transactionmodel-attribute-governs-test-transactions.md`](transactionmodel-attribute-governs-test-transactions.md) and [`testisolation-belongs-on-the-test-runner.md`](testisolation-belongs-on-the-test-runner.md). + +A test codeunit with no shared setup and no queued values doesn't need an `Initialize` procedure. Don't report its absence on its own. + +See sample: [`reset-per-test-state-before-the-isinitialized-guard.good.al`](reset-per-test-state-before-the-isinitialized-guard.good.al). + +## Anti Pattern + +`if IsInitialized then exit;` as the first statement of `Initialize`, followed by `LibraryVariableStorage.Clear()`, `LibrarySetupStorage.Restore()`, or other reset calls that are then skipped for every test after the first. A related defect is a test method in a codeunit that uses the pattern but doesn't call `Initialize()`, so it runs with whatever state the previous test left. Detection signal: in a `Subtype = Test` codeunit, a reset call placed after the `IsInitialized` exit, or a `[Test]` procedure that uses shared globals or queued values without first calling `Initialize()`. + +See sample: [`reset-per-test-state-before-the-isinitialized-guard.bad.al`](reset-per-test-state-before-the-isinitialized-guard.bad.al). + +## References + +- [BCApps: `Initialize` in the ERM Sales Document tests](https://github.com/microsoft/BCApps/blob/4abbb8ff848cdcb4e1187fc7a3e2da0612dd0d2b/src/Layers/W1/Tests/ERM-Sales/ERMSalesDocument.Codeunit.al) +- [BCApps: Library - Test Initialize events](https://github.com/microsoft/BCApps/blob/4abbb8ff848cdcb4e1187fc7a3e2da0612dd0d2b/src/Layers/W1/Tests/ApplicationTestLibrary/LibraryTestInitialize.Codeunit.al) +- [BCApps: Library - Setup Storage](https://github.com/microsoft/BCApps/blob/4abbb8ff848cdcb4e1187fc7a3e2da0612dd0d2b/src/Layers/W1/Tests/ApplicationTestLibrary/LibrarySetupStorage.Codeunit.al) +- [Testing the application](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-testing-application) diff --git a/microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.bad.al b/microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.bad.al new file mode 100644 index 0000000..847045b --- /dev/null +++ b/microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.bad.al @@ -0,0 +1,21 @@ +codeunit 50100 "HTTP Status Handling Bad" +{ + procedure GetCustomer(CustomerId: Guid): JsonObject + var + Client: HttpClient; + Response: HttpResponseMessage; + CustomerJson: JsonObject; + ResponseText: Text; + begin + if not Client.Get( + StrSubstNo('https://api.example.com/customers/%1', CustomerId), + Response) + then + Error('The customer service could not be reached.'); + + // A completed request can still contain a 4xx or 5xx error document. + Response.Content().ReadAs(ResponseText); + CustomerJson.ReadFrom(ResponseText); + exit(CustomerJson); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.good.al b/microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.good.al new file mode 100644 index 0000000..e15682b --- /dev/null +++ b/microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.good.al @@ -0,0 +1,23 @@ +codeunit 50100 "HTTP Status Handling Good" +{ + procedure GetCustomer(CustomerId: Guid): JsonObject + var + Client: HttpClient; + Response: HttpResponseMessage; + CustomerJson: JsonObject; + ResponseText: Text; + begin + if not Client.Get( + StrSubstNo('https://api.example.com/customers/%1', CustomerId), + Response) + then + Error('The customer service could not be reached.'); + + if not Response.IsSuccessStatusCode() then + Error('The customer service returned HTTP status %1.', Response.HttpStatusCode()); + + Response.Content().ReadAs(ResponseText); + CustomerJson.ReadFrom(ResponseText); + exit(CustomerJson); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.md b/microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.md new file mode 100644 index 0000000..f924870 --- /dev/null +++ b/microsoft/knowledge/web-services/check-http-status-before-consuming-response-body.md @@ -0,0 +1,31 @@ +--- +bc-version: [all] +domain: web-services +keywords: [httpclient, httpresponsemessage, issuccessstatuscode, httpstatuscode, response-body, json] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Check HTTP status before consuming the response body + +## Description + +A successful AL `HttpClient` call only confirms that the platform completed the HTTP exchange. The server can still return `4xx` or `5xx`, often with an error document whose shape differs from the expected success payload. Parsing that body as business data can produce misleading parse errors, incomplete records, or decisions based on an error response. + +## Best Practice + +After handling any platform or transport failure, check `HttpResponseMessage.IsSuccessStatusCode()` or the expected `HttpStatusCode()` before interpreting the response body as a success payload. Handle non-success status explicitly and include safe diagnostic context when appropriate. A bounded error body may be read for diagnostics, but it must not enter the success parsing path. + +See sample: [`check-http-status-before-consuming-response-body.good.al`](check-http-status-before-consuming-response-body.good.al). + +## Anti Pattern + +Checking only the Boolean result of `Get`, `Post`, `Put`, `Delete`, or `Send` and then parsing `Response.Content()` as the expected payload. The Boolean can be `true` for any HTTP status, including authentication failures, throttling, validation errors, and server failures. + +See sample: [`check-http-status-before-consuming-response-body.bad.al`](check-http-status-before-consuming-response-body.bad.al). + +## References + +- [HttpResponseMessage.IsSuccessStatusCode method](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/httpresponsemessage/httpresponsemessage-issuccessstatuscode-method) +- [HttpClient data type](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/httpclient/httpclient-data-type) \ No newline at end of file diff --git a/microsoft/knowledge/web-services/check-json-null-before-converting-values.bad.al b/microsoft/knowledge/web-services/check-json-null-before-converting-values.bad.al new file mode 100644 index 0000000..d52ebf9 --- /dev/null +++ b/microsoft/knowledge/web-services/check-json-null-before-converting-values.bad.al @@ -0,0 +1,11 @@ +codeunit 50173 "Contact Payload Reader Bad" +{ + procedure ApplyPayload(var Contact: Record Contact; Payload: JsonObject) + var + Token: JsonToken; + begin + if Payload.Get('email', Token) then + Contact.Validate("E-Mail", CopyStr(Token.AsValue().AsText(), 1, MaxStrLen(Contact."E-Mail"))); + Contact.Modify(true); + end; +} diff --git a/microsoft/knowledge/web-services/check-json-null-before-converting-values.good.al b/microsoft/knowledge/web-services/check-json-null-before-converting-values.good.al new file mode 100644 index 0000000..91f83d5 --- /dev/null +++ b/microsoft/knowledge/web-services/check-json-null-before-converting-values.good.al @@ -0,0 +1,28 @@ +codeunit 50172 "Contact Payload Reader Good" +{ + procedure ApplyPayload(var Contact: Record Contact; Payload: JsonObject) + var + EmailAddress: Text; + begin + if TryGetText(Payload, 'email', EmailAddress) then + Contact.Validate("E-Mail", CopyStr(EmailAddress, 1, MaxStrLen(Contact."E-Mail"))); + Contact.Modify(true); + end; + + local procedure TryGetText(Payload: JsonObject; PropertyName: Text; var Value: Text): Boolean + var + Token: JsonToken; + begin + if not Payload.Get(PropertyName, Token) then + exit(false); + if not Token.IsValue() then + Error(NotAValueErr, PropertyName); + if Token.AsValue().IsNull() then + exit(false); + Value := Token.AsValue().AsText(); + exit(true); + end; + + var + NotAValueErr: Label 'The property %1 must contain a single value.', Comment = '%1 = JSON property name'; +} diff --git a/microsoft/knowledge/web-services/check-json-null-before-converting-values.md b/microsoft/knowledge/web-services/check-json-null-before-converting-values.md new file mode 100644 index 0000000..b5a560e --- /dev/null +++ b/microsoft/knowledge/web-services/check-json-null-before-converting-values.md @@ -0,0 +1,35 @@ +--- +bc-version: [all] +domain: web-services +keywords: [jsonobject, jsontoken, jsonvalue, isnull, asvalue, astext, asdecimal, optional-property, json-null, payload-parsing] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Check for JSON null before converting a value + +## Description + +An optional property in a JSON payload can be missing or present with the value `null`, and the two cases behave differently in AL. When the Boolean result is captured, `JsonObject.Get` returns `false` for a missing key but `true` for `"email": null`, because the key exists. The conversion methods on `JsonValue` (`AsText`, `AsCode`, `AsDecimal`, `AsInteger`, `AsDate`, `AsBoolean`, and the others) fail with a runtime error when the value is `NULL` or `UNDEFINED`. Code that guards only with `Get` therefore passes its tests with the property omitted and fails in production when the sender serializes an empty field as `null`, which many services do by default. + +## Best Practice + +For every property that the contract allows to be optional or nullable, check three things before converting: that `Get` (or `SelectToken`) returned `true`, that the token `IsValue()` rather than an object or array, and that `AsValue().IsNull()` is `false`. Put this in one small helper per target type and decide explicitly what a missing or null property means: a default, leaving the field unchanged, or a validation error that names the property. + +Required properties can still fail fast, but with an error that states the missing or null property instead of a generic conversion error. Keep a numeric or date conversion strict when the contract says the value must be a number or a date; `IsNull` covers only `null`, not a value of the wrong type. + +See sample: [`check-json-null-before-converting-values.good.al`](check-json-null-before-converting-values.good.al). + +## Anti Pattern + +`if Json.Get('email', Token) then Email := Token.AsValue().AsText();` or an unguarded `Token.AsValue().AsDecimal()` on a property that the external contract allows to be `null`. The `Get` check makes the code look defensive, but it doesn't handle a present `null`. Detection signal: an `As()` call on a `JsonValue` obtained from an external payload with no preceding `IsNull()` check on the same token, where the property isn't documented as always non-null. + +See sample: [`check-json-null-before-converting-values.bad.al`](check-json-null-before-converting-values.bad.al). + +## References + +- [JsonObject.Get method](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/jsonobject/jsonobject-get-method) +- [JsonValue.AsText method: fails on NULL or UNDEFINED](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/jsonvalue/jsonvalue-astext-method) +- [JsonValue.IsNull method](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/jsonvalue/jsonvalue-isnull-method) +- [JsonToken data type](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/jsontoken/jsontoken-data-type) diff --git a/microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.bad.al b/microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.bad.al new file mode 100644 index 0000000..3e36c87 --- /dev/null +++ b/microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.bad.al @@ -0,0 +1,27 @@ +codeunit 50171 "Exchange Rate Export Bad" +{ + procedure SendRate(CurrencyCode: Code[10]; StartingDate: Date; ExchangeRate: Decimal) + var + Client: HttpClient; + Response: HttpResponseMessage; + RequestUrl: Text; + begin + RequestUrl := StrSubstNo(RateUrlTok, CurrencyCode, Format(StartingDate), Format(ExchangeRate)); + if not Client.Get(RequestUrl, Response) then + Error(RequestFailedErr); + if not Response.IsSuccessStatusCode() then + Error(RateRejectedErr, Response.HttpStatusCode()); + end; + + procedure ReadRate(RateText: Text) ExchangeRate: Decimal + begin + if not Evaluate(ExchangeRate, RateText) then + Error(InvalidRateErr, RateText); + end; + + var + RateUrlTok: Label 'https://rates.example.com/rates?currency=%1&date=%2&rate=%3', Locked = true; + RequestFailedErr: Label 'The exchange rate service could not be reached.'; + RateRejectedErr: Label 'The exchange rate service rejected the rate. Status code: %1.', Comment = '%1 = HTTP status code'; + InvalidRateErr: Label 'The exchange rate %1 is not a valid decimal number.', Comment = '%1 = received value'; +} diff --git a/microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.good.al b/microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.good.al new file mode 100644 index 0000000..21d6a22 --- /dev/null +++ b/microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.good.al @@ -0,0 +1,27 @@ +codeunit 50170 "Exchange Rate Export Good" +{ + procedure SendRate(CurrencyCode: Code[10]; StartingDate: Date; ExchangeRate: Decimal) + var + Client: HttpClient; + Response: HttpResponseMessage; + RequestUrl: Text; + begin + RequestUrl := StrSubstNo(RateUrlTok, CurrencyCode, Format(StartingDate, 0, 9), Format(ExchangeRate, 0, 9)); + if not Client.Get(RequestUrl, Response) then + Error(RequestFailedErr); + if not Response.IsSuccessStatusCode() then + Error(RateRejectedErr, Response.HttpStatusCode()); + end; + + procedure ReadRate(RateText: Text) ExchangeRate: Decimal + begin + if not Evaluate(ExchangeRate, RateText, 9) then + Error(InvalidRateErr, RateText); + end; + + var + RateUrlTok: Label 'https://rates.example.com/rates?currency=%1&date=%2&rate=%3', Locked = true; + RequestFailedErr: Label 'The exchange rate service could not be reached.'; + RateRejectedErr: Label 'The exchange rate service rejected the rate. Status code: %1.', Comment = '%1 = HTTP status code'; + InvalidRateErr: Label 'The exchange rate %1 is not a valid decimal number.', Comment = '%1 = received value'; +} diff --git a/microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.md b/microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.md new file mode 100644 index 0000000..adc1dae --- /dev/null +++ b/microsoft/knowledge/web-services/format-exchanged-values-with-standard-format-9.md @@ -0,0 +1,39 @@ +--- +bc-version: [all] +domain: web-services +keywords: [format, evaluate, standard-format-9, xml-format, locale, regional-settings, decimal-separator, data-exchange, integration] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Format exchanged values with standard format 9 + +## Description + +`Format(Value)` uses standard format 0, the display format, and follows the current user's regional settings. The same decimal renders as `-76.543,21` for a European region and `-76,543.21` for English (US); the same date renders as `05-04-21` or `04/05/21`. Text built this way and sent outside Business Central (an HTTP query string or body, an XML or CSV file, a signature or hash input, or an external key) changes with the user or job queue session that produces it. The receiver can reject it or, worse, misread it. `Evaluate` without a format number has the same dependency when it parses machine-generated text. + +## Best Practice + +Use `Format(Value, 0, 9)` for machine-readable text. Standard format 9 is the XML format and doesn't depend on the region: `-76543.21` for a decimal, `2021-04-05` for a date, `04:35:55.553` for a time, `true`/`false` for a Boolean, and a UTC `DateTime` such as `2021-04-05T03:35:55.553Z`. Parse such text with `Evaluate(Variable, Text, 9)`. + +Prefer typed APIs when they exist. `JsonObject.Add` and `JsonValue.SetValue` with a `Decimal`, `Date`, or `Boolean` argument write a JSON value without going through display text. An XMLport handles this with `FormatEvaluate = Xml`. + +For `Enum` and `Option` values, format 9 produces the ordinal number, not the name. When the external contract exchanges names, map them explicitly; see [`api-enum-values-are-a-contract-by-name-not-ordinal.md`](api-enum-values-are-a-contract-by-name-not-ordinal.md). + +Text shown to a person (messages, captions, report columns, notifications) should keep the regional display format. `Code`, `Text`, and `Guid` values don't need format 9 because their standard formats don't vary by region. + +See sample: [`format-exchanged-values-with-standard-format-9.good.al`](format-exchanged-values-with-standard-format-9.good.al). + +## Anti Pattern + +`Format(Amount)`, `Format(PostingDate)`, or `Format(SomeDateTime)` concatenated into a URL, request body, XML or CSV line, file name, or hash input. Passing the `Decimal` or `Date` itself to `StrSubstNo` for such text has the same effect, because `StrSubstNo` formats it with the display format. Also `Evaluate(DecimalOrDateVariable, ExternalText)` without format number 9 on text received from another system. The code usually works for the developer's own region and fails for users or job queue sessions in another one. Detection signal: `Format` with one argument, or with a format number other than 9, applied to a `Decimal`, `Date`, `Time`, `DateTime`, or `Boolean` on a path that writes to an `HttpContent`, `HttpRequestMessage`, `OutStream`, `XmlDocument`, or file. + +See sample: [`format-exchanged-values-with-standard-format-9.bad.al`](format-exchanged-values-with-standard-format-9.bad.al). + +## References + +- [Formatting values, dates, and time: standard formats by region and format 9](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-format-property) +- [System.Format method](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/system/system-format-joker-integer-integer-method) +- [System.Evaluate method and format number 9](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/system/system-evaluate-method) +- [FormatEvaluate property for XMLports](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/properties/devenv-formatevaluate-property) diff --git a/microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.bad.al b/microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.bad.al new file mode 100644 index 0000000..8ac6d6a --- /dev/null +++ b/microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.bad.al @@ -0,0 +1,18 @@ +codeunit 50100 "Http Platform Failure Bad" +{ + procedure GetCustomer(CustomerId: Guid): Text + var + Client: HttpClient; + Response: HttpResponseMessage; + ResponseText: Text; + RequestSucceeded: Boolean; + begin + RequestSucceeded := Client.Get( + StrSubstNo('https://api.example.com/customers/%1', CustomerId), + Response); + + // Response content is unavailable when the platform call failed. + Response.Content().ReadAs(ResponseText); + exit(ResponseText); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.good.al b/microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.good.al new file mode 100644 index 0000000..019f0be --- /dev/null +++ b/microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.good.al @@ -0,0 +1,18 @@ +codeunit 50100 "Http Platform Failure Good" +{ + procedure GetCustomer(CustomerId: Guid): Text + var + Client: HttpClient; + Response: HttpResponseMessage; + ResponseText: Text; + begin + if not Client.Get( + StrSubstNo('https://api.example.com/customers/%1', CustomerId), + Response) + then + Error('The customer service could not be reached.'); + + Response.Content().ReadAs(ResponseText); + exit(ResponseText); + end; +} \ No newline at end of file diff --git a/microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.md b/microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.md new file mode 100644 index 0000000..e3dd227 --- /dev/null +++ b/microsoft/knowledge/web-services/handle-httpclient-platform-failure-before-response-access.md @@ -0,0 +1,31 @@ +--- +bc-version: [all] +domain: web-services +keywords: [httpclient, transport-failure, boolean-return, httpresponsemessage, content, runtime-error] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Handle HttpClient platform failure before accessing the response + +## Description + +AL `HttpClient` methods can fail before a usable HTTP response exists because of an invalid request, DNS or network failure, certificate validation, timeout, a disabled extension setting, or the response-size limit. When code captures the optional Boolean return value, `false` reports this platform or transport failure. The accompanying `HttpResponseMessage` is not safe to consume; accessing its content after the failed call can raise another error and obscure the original failure. + +## Best Practice + +When capturing the Boolean return value from `Get`, `Post`, `Put`, `Delete`, or `Send`, stop the current response-processing path immediately when it is `false`. Report or propagate the transport failure without reading status, headers, or content. Omitting the optional Boolean is also valid when fail-fast behavior is intended: the runtime then raises an error if the operation cannot execute. + +See sample: [`handle-httpclient-platform-failure-before-response-access.good.al`](handle-httpclient-platform-failure-before-response-access.good.al). + +## Anti Pattern + +Capturing a failed call in a Boolean and then reading `Response.Content()`, parsing the body, or otherwise treating `Response` as usable. Do not report omission of the Boolean by itself; that form deliberately delegates failure propagation to the runtime. + +See sample: [`handle-httpclient-platform-failure-before-response-access.bad.al`](handle-httpclient-platform-failure-before-response-access.bad.al). + +## References + +- [HttpClient.Send method](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/httpclient/httpclient-send-method) +- [Call external services with HttpClient](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-httpclient) \ No newline at end of file diff --git a/microsoft/skills/review/al-code-review.md b/microsoft/skills/review/al-code-review.md index df476f3..7a3d0c6 100644 --- a/microsoft/skills/review/al-code-review.md +++ b/microsoft/skills/review/al-code-review.md @@ -46,8 +46,12 @@ The sub-skills invoked by this skill are those listed in frontmatter `sub-skills Hosts that orchestrate leaves mechanically SHOULD run `tools/Build-SkillIndex.ps1` and resolve this skill by `id: al-code-review`. -The generated `subSkills` array preserves the frontmatter order and avoids -host-specific Markdown parsing. +The generated `subSkills` array preserves the frontmatter slot order and +avoids host-specific Markdown parsing. Before invoking leaves, run +`tools/Resolve-SkillWorklist.ps1` with this skill's path and the task's enabled +layers and disabled skill paths. Each declared path supplies a leaf `id`; the +resolver selects the highest-precedence enabled implementation with that `id` +without changing slot order. ## Relevance diff --git a/microsoft/skills/review/al-error-handling-review.md b/microsoft/skills/review/al-error-handling-review.md index 56bc0fe..a340807 100644 --- a/microsoft/skills/review/al-error-handling-review.md +++ b/microsoft/skills/review/al-error-handling-review.md @@ -22,6 +22,13 @@ An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-pat Use READ's **Bounded retrieval for review skills** workflow with `-Domain error-handling`. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback. +When the review scope contains outbound `HttpClient.Get` or `HttpClient.Post` calls, including resolved call paths, also retrieve every catalog page with `-Domain web-services`, using the same known task dimensions and enabled layers. Restrict supplementary candidates to these article slugs across enabled layers; the links identify their canonical owners: + +- [`handle-httpclient-platform-failure-before-response-access`](../../knowledge/web-services/handle-httpclient-platform-failure-before-response-access.md) +- [`check-http-status-before-consuming-response-body`](../../knowledge/web-services/check-http-status-before-consuming-response-body.md) + +Retain each selected catalog row's exact `path`; do not invent paths for missing, pruned, or disabled entries. Apply this leaf's Relevance, Worklist, and READ layer precedence to the supplementary candidates before retrieving complete bodies with `Get-KnowledgeArticles.ps1`. Apply each selected article's own scope and exceptions when evaluating code and agent-finding candidates. Use READ's bounded path-discovery fallback over these same sources when needed. This supplements error-handling knowledge, not the scope of the review with unrelated web-services concerns. + ## Relevance Apply the frontmatter matching rules defined in READ (*Frontmatter matching semantics*) against the task context: @@ -40,6 +47,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially codeunits that post or validate, tables and table extensions with `OnValidate` triggers, and any procedure that raises errors or orchestrates a batch over records. - The changed procedures and triggers, weighted toward `OnValidate`/`OnInsert`/`OnModify` triggers, posting and validation routines, and procedures attributed with `[ErrorBehavior(...)]` or `[TryFunction]`. - Tokens extracted from the diff that relate to error surfacing and diagnostics (`Error`, `ErrorInfo`, `FieldError`, `TestField`, `Title`, `Message`, `DetailedMessage`, `AddAction`, `AddNavigationAction`, `RecordId`, `PageNo`, `ErrorBehavior`, `Collect`, `HasCollectedErrors`, `GetCollectedErrors`, `ClearCollectedErrors`, `ErrorType`, `Internal`, `Client`, `TryFunction`, `GetLastErrorText`, Boolean assignment). +- For the outbound HTTP call paths identified in Source, include `HttpClient`, `Get`, `Post`, `HttpResponseMessage`, response use, and caller failure handling (including `[TryFunction]` call sites) in keyword and topic matching. - Resolve changed standalone call targets; when the target declaration has `[TryFunction]`, worklist the ignored-return rule even if the declaration itself is unchanged. Only assignment and conditional use activate try semantics. A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. diff --git a/microsoft/skills/review/al-scm-review.md b/microsoft/skills/review/al-scm-review.md index a434529..8e22e2c 100644 --- a/microsoft/skills/review/al-scm-review.md +++ b/microsoft/skills/review/al-scm-review.md @@ -77,6 +77,7 @@ paths; they select articles, not findings. Facts and exceptions stay in articles | Registered warehouse quantity/physical-adjustment synchronization, `"Directed Put-away and Pick"`, `"Adjustment Bin Code"`, `"Warehouse Adjustment"`, or `"Calculate Whse. Adjustment"` and the resulting item-journal posting | `reconcile-warehouse-adjustments-with-the-item-ledger` | | `"Transfer Header"`/`"Transfer Line"` shipment/receipt completion, transfer posting publishers, in-transit/document-link changes, or item-journal posting presented as transfer-order completion | `post-transfers-through-shipment-and-receipt-codeunits` | | `Inventory`, `CalcQtyAvailableToPromise`, or stock sums used in a dated supply/demand promise, including changed location/variant/date filters and source-demand context | `use-date-aware-availability-for-promising` | +| Direct assignment to `Quantity`, `"Unit of Measure Code"`, `"Qty. per Unit of Measure"`, or a `(Base)` quantity field on a persisted or posted item journal, sales, purchase, or transfer line, or a line quantity compared with a base-unit inventory value | `derive-base-quantities-through-the-line-unit-of-measure` | | `"Requisition Line"` action-message execution, accepted planning suggestions, `"Req. Wksh.-Make Order"`, `CarryOutBatchAction`, or linked supply creation/change plus requisition-line deletion | `carry-out-requisition-actions-through-the-standard-workflow` | Route clean supported calls through the same cues, not just suspicious writes. diff --git a/microsoft/skills/review/al-security-review.md b/microsoft/skills/review/al-security-review.md index 00e8d10..e18d3fc 100644 --- a/microsoft/skills/review/al-security-review.md +++ b/microsoft/skills/review/al-security-review.md @@ -39,7 +39,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially permission sets, codeunits handling authentication or authorization, objects touching `Isolated Storage`, `OAuth2` flows, web service endpoints, API pages, event publishers, and RecordRef helpers. - The changed procedures and triggers, weighted toward those that call `HttpClient`, validate or compose URLs, write to telemetry, read or write secrets, unwrap SecretText, manipulate record-level security, expose var Boolean guard parameters, or bypass the permission model (for example, `RecordRef.Open`, `Record.WritePermission`, direct table access from a non-owning app). -- Tokens extracted from the diff that relate to security concerns (`IsolatedStorage`, `SetEncrypted`, `OAuth2`, `SecretText`, `Unwrap`, `NonDebuggable`, `Password`, `Token`, `HttpClient`, `Uri`, `AreURIsHaveSameHost`, `IsValidURIPattern`, `RecordRef`, `RecordId`, `TransferFields`, `Codeunit.Run`, `Access = Internal`, `internalsVisibleTo`, `Open`, `IntegrationEvent`, `SkipValidation`, `HasAccess`, `Permission`, `UserSecurityId`, `Commit`). +- Tokens extracted from the diff that relate to security concerns (`IsolatedStorage`, `SetEncrypted`, `OAuth2`, `SecretText`, `Unwrap`, `NonDebuggable`, `Password`, `Token`, `HttpClient`, `Uri`, `AreURIsHaveSameHost`, `IsValidURIPattern`, `RecordRef`, `RecordId`, `TransferFields`, `Codeunit.Run`, `Access = Internal`, `internalsVisibleTo`, `Open`, `IntegrationEvent`, `SkipValidation`, `HasAccess`, `Permission`, `UserSecurityId`, `Commit`, `SetFilter`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. diff --git a/microsoft/skills/review/al-testing-review.md b/microsoft/skills/review/al-testing-review.md index 6986977..2adbc13 100644 --- a/microsoft/skills/review/al-testing-review.md +++ b/microsoft/skills/review/al-testing-review.md @@ -39,7 +39,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially codeunits with `Subtype = Test`, test runner codeunits with `TestIsolation`, test libraries, and codeunits that define UI handlers. - The changed methods and attributes, weighted toward `[Test]`, `[TransactionModel(...)]`, `[TestPermissions(...)]`, `[HandlerFunctions(...)]`, handler attributes, `asserterror`, `ExpectedError`, `ExpectedErrorCode`, fixture initialization, and test-library calls. -- Tokens extracted from the diff that relate to testing (`Subtype = Test`, `Subtype = TestRunner`, `TestIsolation`, `TestPermissions`, `Restrictive`, `NonRestrictive`, `Disabled`, `Permissions Mock`, `Library - Lower Permissions`, `TransactionModel`, `AutoRollback`, `AutoCommit`, `Commit`, `asserterror`, `ExpectedError`, `ExpectedErrorCode`, `HandlerFunctions`, `ConfirmHandler`, `MessageHandler`, `StrMenuHandler`, `ModalPageHandler`, `SendNotificationHandler`, `RecallNotificationHandler`, `Enqueue`, `Dequeue`, `AssertEmpty`, `Library Assert`, `LibraryVariableStorage`, `LibrarySales`, `LibraryPurchase`, `LibraryERM`, `LibraryInventory`, `LibraryRandom`, `Library - Utility`, `LibraryUtility`, `GenerateGUID`, `GenerateRandomCode`, `TestPage`, `.Visible(`, `.Enabled(`, `.Editable(`, `OpenNew`, `OpenView`, `OpenEdit`, `Init`, `Insert`). +- Tokens extracted from the diff that relate to testing (`Subtype = Test`, `Subtype = TestRunner`, `TestIsolation`, `TestPermissions`, `Restrictive`, `NonRestrictive`, `Disabled`, `Permissions Mock`, `Library - Lower Permissions`, `TransactionModel`, `AutoRollback`, `AutoCommit`, `Commit`, `asserterror`, `ExpectedError`, `ExpectedErrorCode`, `HandlerFunctions`, `ConfirmHandler`, `MessageHandler`, `StrMenuHandler`, `ModalPageHandler`, `SendNotificationHandler`, `RecallNotificationHandler`, `Enqueue`, `Dequeue`, `AssertEmpty`, `Initialize`, `IsInitialized`, `OnTestInitialize`, `LibrarySetupStorage`, `Library Assert`, `LibraryVariableStorage`, `LibrarySales`, `LibraryPurchase`, `LibraryERM`, `LibraryInventory`, `LibraryRandom`, `Library - Utility`, `LibraryUtility`, `GenerateGUID`, `GenerateRandomCode`, `TestPage`, `.Visible(`, `.Enabled(`, `.Editable(`, `OpenNew`, `OpenView`, `OpenEdit`, `Init`, `Insert`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. When the diff contains no testing-related changes by any of the above signals, return `outcome: "not-applicable"` without evaluating files. @@ -49,6 +49,7 @@ The following targeted checks cover every current `testing` article. Treat each - An `AutoCommit` test runs under a `Subtype = TestRunner` codeunit that omits `TestIsolation` or sets it to `Disabled`, leaving committed data between tests — `testisolation-belongs-on-the-test-runner`. Require runner/repository context; a standalone test file cannot prove which runner executes it. - A permission-sensitive test uses `TestPermissions = Disabled`, claims to test a restricted user without `"Permissions Mock"`/`"Library - Lower Permissions"`, or declares `[TestPermissions(...)]` without applying that context — `permission-tests-must-lower-the-execution-context`. - Test fixture code manually calls `Init`/`Insert`, invents keys or prerequisite records, or bypasses available `LibrarySales`, `LibraryPurchase`, `LibraryERM`, `LibraryInventory`, `LibraryRandom`, or equivalent library codeunits — `use-library-codeunits-for-test-fixtures`. +- A test codeunit's `Initialize` procedure exits on `IsInitialized` before per-test reset such as `LibraryVariableStorage.Clear`, `LibrarySetupStorage.Restore`, or `LibraryTestInitialize.OnTestInitialize`, or a `[Test]` method in a codeunit using that pattern does not call `Initialize()` first — `reset-per-test-state-before-the-isinitialized-guard`. - `asserterror` is added or changed without a following `Assert.ExpectedError`, `Assert.ExpectedErrorCode`, or a purpose-built assertion such as `ExpectedTestFieldError` — `asserterror-needs-expectederror-and-code`. - Test fixture code assigns a hardcoded literal to a primary-key field or a field the test relies on as a unique lookup identifier, hand-builds a "unique" value for such a field (string concatenation, a counter, `Format(CurrentDateTime)`), or truncates `LibraryUtility.GenerateGUID()`'s result with `CopyStr` for such a field shorter than 10 characters — `use-generateguid-for-unique-test-fixture-values`. Calling `GenerateGUID()` untruncated into a full-length field, `GenerateRandomCodeWithLength` for a shorter field needing real verified uniqueness, or `GenerateRandomCode20` specifically for a `Code[20]` field, is the compliant shape, not the signal to flag. `GenerateRandomCode20` is not a substitute for `GenerateRandomCodeWithLength` on a shorter field — it truncates `GenerateGUID()`'s sequential value down to the field's length by keeping the *leftmost* characters, which change the slowest, so retries against a short field can churn through the same truncated prefix far longer than `GenerateRandomCodeWithLength`'s equivalent. A hardcoded or deterministic value in an ordinary descriptive field is not this anti-pattern — that field carries no uniqueness constraint. Do not claim `GenerateRandomCode` (without `WithLength`/`20`) or `GenerateRandomXMLText` verify uniqueness against the real table, or that `GenerateRandomCode` is collision-free even within one test run for a short field — none of that is true. - A test asserts against a `TestPage` field's `.Visible()` or `.Enabled()` — `use-testpage-visible-enabled-to-verify-field-ui-state`. When the assertion is against `.Editable()`, or the page is opened with `OpenEdit()` specifically to check editability — `use-testpage-editable-to-verify-field-editability`. diff --git a/microsoft/skills/review/al-web-services-review.md b/microsoft/skills/review/al-web-services-review.md index c486c88..b86c79b 100644 --- a/microsoft/skills/review/al-web-services-review.md +++ b/microsoft/skills/review/al-web-services-review.md @@ -3,7 +3,7 @@ kind: action-skill id: al-web-services-review version: 1 title: AL web services review -description: Reviews AL API surfaces and webhook integration handlers against web-services guidance from BCQuality. +description: Reviews AL API surfaces, outbound HTTP integrations, and webhook handlers against web-services guidance from BCQuality. inputs: [pr-diff, file-path, folder-path] outputs: [findings-report] bc-version: [all] @@ -14,7 +14,7 @@ application-area: [all] # AL web services review -Reviews AL source changes against the `web-services` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`. +Reviews AL source changes against the `web-services` knowledge domain in BCQuality and emits a findings report. This includes inbound API surfaces, outbound HTTP integrations, and webhook lifecycle code. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`. An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract. @@ -39,10 +39,12 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially pages declared with `PageType = API`, API page `part` controls, queries declared with `QueryType = API`, and procedures that expose bound actions. - The changed properties and triggers, weighted toward API page metadata (`APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `ODataKeyFields`, `SourceTable`, `SourceTableTemporary`), navigation metadata (`SubPageLink`, `Multiplicity`, and visible singleton or collection semantics), CRUD guards (`InsertAllowed`, `ModifyAllowed`, `DeleteAllowed`, `Editable`), the `OnOpenPage` trigger, and `OnValidate` triggers on exposed fields. +- Outbound HTTP integration code that constructs or sends requests, captures a client method's optional Boolean result, checks an `HttpResponseMessage`, or reads and parses response content. +- Integration code that converts values to or from exchanged text: `Format` or `Evaluate` on a request URL, body, or file line, and `JsonToken`/`JsonValue` conversions of payload properties. - Webhook subscriber handlers and subscription lifecycle code, especially code that creates or renews subscriptions, handles `validationToken`, schedules from `expirationDateTime`, or targets resources whose eligibility is visible in the diff. - An API page (`PageType = API`) with `InsertAllowed = true` lists a field in `ODataKeyFields` and that same field control sets `Editable = false` — `api-page-key-fields-must-be-editable-on-insert.md`. A system-generated key such as `SystemId` marked read-only is not this anti-pattern. - An API page exposes a field via `Rec` directly, and that field is a stored value computed from other fields inside an `OnValidate` trigger rather than a FlowField recalculated in `OnAfterGetRecord` — `stored-derived-fields-must-not-be-exposed-directly.md`. Exposing a genuine FlowField, or a value already recalculated in `OnAfterGetRecord`, is not this anti-pattern. -- Tokens extracted from the diff that relate to API surface and behaviour (`PageType`, `QueryType`, `API`, `api-page`, `page-part`, `APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `ODataKeyFields`, `SystemId`, `SubPageLink`, `subpagelink`, `Multiplicity`, `multiplicity`, `Many`, `ZeroOrOne`, `SourceTableTemporary`, `Job Queue Entry`, `webhook`, `webhookSupportedResources`, `webhook-supported-resources`, `subscriptions`, `notificationUrl`, `validationToken`, `validationtoken`, `expirationDateTime`, `expirationdatetime`, `ServiceEnabled`, `WebServiceActionContext`, `SetActionResponse`, `ReadIsolation`, `IsolationLevel`, `ReadCommitted`, `InsertAllowed`, `ModifyAllowed`, `DeleteAllowed`, `Editable`, `SourceTable`). +- Tokens extracted from the diff that relate to API surface and behaviour (`PageType`, `QueryType`, `API`, `api-page`, `page-part`, `APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `ODataKeyFields`, `SystemId`, `SubPageLink`, `subpagelink`, `Multiplicity`, `multiplicity`, `Many`, `ZeroOrOne`, `SourceTableTemporary`, `Job Queue Entry`, `webhook`, `webhookSupportedResources`, `webhook-supported-resources`, `subscriptions`, `notificationUrl`, `validationToken`, `validationtoken`, `expirationDateTime`, `expirationdatetime`, `ServiceEnabled`, `WebServiceActionContext`, `SetActionResponse`, `ReadIsolation`, `IsolationLevel`, `ReadCommitted`, `InsertAllowed`, `ModifyAllowed`, `DeleteAllowed`, `Editable`, `SourceTable`, `HttpClient`, `HttpRequestMessage`, `HttpResponseMessage`, `Get`, `Post`, `Put`, `Delete`, `Send`, `IsSuccessStatusCode`, `HttpStatusCode`, `Content`, `ReadAs`, `JsonObject`, `JsonToken`, `JsonValue`, `AsValue`, `IsNull`, `SelectToken`, `Format`, `Evaluate`, `XmlDocument`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. @@ -58,7 +60,14 @@ For each worklist entry, evaluate the diff against the file's `## Best Practice` - When the diff contains code that contradicts a Best Practice without being a full anti-pattern, emit `minor` with the same reference shape. - Applicability alone is not a finding. Emit `info` only for a concrete, non-actionable observation the article explicitly defines; otherwise emit nothing when no violation is present. -For API parts whose parent declares `ODataKeyFields = SystemId`, detect a child foreign key linked to a parent business field instead of `Field(SystemId)`. Do not apply the SystemId-link rule to APIs intentionally keyed by another field. Omitted `Multiplicity` is valid and means the documented default 1:N collection; never report omission alone. Report an explicit `ZeroOrOne` only when the visible contract clearly intends a collection or deep insert, and report an explicit `Many` only when it clearly intends a singleton. Singleton metadata requires an explicit `ZeroOrOne`; do not infer singleton intent from naming alone. For webhook eligibility, detect `QueryType = API`, `SourceTableTemporary = true`, composite `ODataKeyFields` (including an omitted property when a visible source primary key is composite), Job Queue Entry, and visible system-table sources; do not infer an unknown table number. For lifecycle code, require both create and renew paths to use a handler that returns the query-string `validationToken` verbatim with `200 OK`, and flag renewal scheduling that assumes subscriptions are permanent instead of using `expirationDateTime`. Do not emit generic HTTP or REST advice. +For API parts whose parent declares `ODataKeyFields = SystemId`, detect a child foreign key linked to a parent business field instead of `Field(SystemId)`. Do not apply the SystemId-link rule to APIs intentionally keyed by another field. Omitted `Multiplicity` is valid and means the documented default 1:N collection; never report omission alone. Report an explicit `ZeroOrOne` only when the visible contract clearly intends a collection or deep insert, and report an explicit `Many` only when it clearly intends a singleton. Singleton metadata requires an explicit `ZeroOrOne`; do not infer singleton intent from naming alone. For webhook eligibility, detect `QueryType = API`, `SourceTableTemporary = true`, composite `ODataKeyFields` (including an omitted property when a visible source primary key is composite), Job Queue Entry, and visible system-table sources; do not infer an unknown table number. For lifecycle code, require both create and renew paths to use a handler that returns the query-string `validationToken` verbatim with `200 OK`, and flag renewal scheduling that assumes subscriptions are permanent instead of using `expirationDateTime`. + +For outbound HTTP calls, apply these targeted checks: + +- When code captures the optional Boolean result of `HttpClient.Get`, `Post`, `Put`, `Delete`, or `Send`, require the failed branch to stop before status, headers, or content are accessed. Do not report a call that omits the Boolean result: that form intentionally lets the runtime raise an error when the request cannot execute. +- After platform success, require `IsSuccessStatusCode()` or an explicit acceptable `HttpStatusCode()` check before response content is interpreted as a success payload. Do not report code that reads a bounded non-success body solely for diagnostics and keeps it out of the success parsing path. + +Do not emit generic HTTP or REST advice beyond applicable knowledge articles. Set `confidence` to: @@ -66,7 +75,7 @@ Set `confidence` to: - `medium` when detection relies on heuristics or when any frontmatter dimension was `unknown`. - `low` when the finding is an advisory derived only from applicability. -After evaluating each worklist entry, also consider whether the diff exhibits a web-services defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with `references: []`, an `id` slug prefixed with `agent:`, `confidence` capped at `medium`, `severity` capped at `minor` (agent findings are advisory and non-gating), and a `message` that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). Hold every candidate to the precision bar in `skills/do.md` (*Agent findings*): emit only a concrete, material web-services defect a knowledgeable BC reviewer would agree is wrong — steelman it first and drop anything stylistic, speculative, dependent on code outside the diff, or merely a valid alternative; when in doubt, omit. The scope is strictly API pages and web-service surfaces; defects outside this domain belong to other leaves and MUST NOT be emitted here. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See `skills/do.md` for the full contract. +After evaluating each worklist entry, also consider whether the diff exhibits a web-services defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with `references: []`, an `id` slug prefixed with `agent:`, `confidence` capped at `medium`, `severity` capped at `minor` (agent findings are advisory and non-gating), and a `message` that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). Hold every candidate to the precision bar in `skills/do.md` (*Agent findings*): emit only a concrete, material web-services defect a knowledgeable BC reviewer would agree is wrong — steelman it first and drop anything stylistic, speculative, dependent on code outside the diff, or merely a valid alternative; when in doubt, omit. The scope is strictly API pages, outbound HTTP integrations, and other web-service surfaces; defects outside this domain belong to other leaves and MUST NOT be emitted here. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See `skills/do.md` for the full contract. For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: set `ODataKeyFields = SystemId`; add the three `*Allowed = false` guards to a read-only page; add the missing `OnOpenPage` isolation assignment). For mechanical findings, emit `findings[].suggested-code` with the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, adapt the `.good.al` replacement into `suggested-code`. @@ -76,7 +85,7 @@ Outcome selection: - `completed` — the skill evaluated every worklist item; default when the skill finishes normally, including when the resulting `findings` array is empty. - `no-knowledge` — no applicable web-services knowledge survived Source, Relevance, configuration filtering, and conflict resolution. `findings` is empty. -- `not-applicable` — the task context contains no AL API surface, JavaScript webhook subscription lifecycle code, or JavaScript notification handler, or the `technologies` filter rejected the task. +- `not-applicable` — the task context contains no AL API surface, outbound AL HTTP integration, JavaScript webhook subscription lifecycle code, or JavaScript notification handler, or the `technologies` filter rejected the task. - `partial` — a time or token budget was hit before the worklist was exhausted. `summary.coverage` reflects the evaluated subset; `outcome-reason` explains the cause. - `failed` — an unrecoverable error occurred. `outcome-reason` is required. diff --git a/skills/do.md b/skills/do.md index e67faf6..db0d634 100644 --- a/skills/do.md +++ b/skills/do.md @@ -222,6 +222,12 @@ as a findings-report, a coordinator or host MUST validate it deterministically: inclusive range identify existing lines with `start-line == line` and `end-line >= start-line`. +Hosts SHOULD execute `tools/Validate-FindingsReport.ps1` with the exact source +scope and the leaf's recorded set of fully retrieved article paths. Pass +`-SkillKind super` when validating a super-skill's rolled-up report. Pass +`-AllowBoundedNormalization` only when the host preserves the immutable raw +payload and records `removedRanges` in private telemetry as required above. + Validation failure invalidates the complete return; consumers MUST NOT salvage individual findings, infer missing fields, reconstruct JSON, clamp ranges, rewrite paths, or otherwise silently repair model output. Preserve the invalid @@ -356,16 +362,27 @@ performing any super-skill self-review or final rollup. Scheduling MUST NOT change relevance, coverage, failure, reference-integrity, or output semantics. Orchestrators SHOULD generate `skill-index.json` with -`tools/Build-SkillIndex.ps1` and consume the super-skill's ordered `subSkills` -from that index instead of parsing Markdown. Action-skill frontmatter remains -the source of truth; the generated index conforms to +`tools/Build-SkillIndex.ps1` instead of parsing Markdown. Each declared +`subSkills` path defines an ordered leaf slot: its indexed `id` identifies the +slot, while its path fixes the declaration order. Before scheduling leaves, +the orchestrator MUST resolve each slot to the highest-precedence enabled, +non-disabled leaf with that `id` (`custom` over `community` over `microsoft`). +If no implementation remains, the slot is skipped with `reason: +"configuration"`. The orchestrator SHOULD use +`tools/Resolve-SkillWorklist.ps1` for this resolution. Action-skill +frontmatter remains the source of truth; the generated index conforms to `schemas/skill-index.schema.json`. +Layer resolution MUST NOT reorder slots. Multiple implementations with the +same `id` are valid only when they belong to different layers; duplicate IDs +within one layer are invalid. Disabling a winning implementation falls back +to the next enabled implementation for that slot when one exists. + ### Section interpretation for super-skills The five required sections still apply. Their meaning shifts from knowledge files to sub-skills: -- `## Source` — names the sub-skills invoked (mirrors `sub-skills` in frontmatter). +- `## Source` — names the declared sub-skill slots (mirrors `sub-skills` in frontmatter) and resolves their effective leaf implementations by the layered rule above. - `## Relevance` — rules for deciding which sub-skills apply to the current task. A sub-skill is relevant when its declared `inputs` are satisfied by the orchestrator's provided inputs and the orchestrator has not disabled it via configuration. The super-skill MUST NOT filter sub-skills by task content (for example, by inspecting the diff or the file). Task-level applicability is the sub-skill's own responsibility; sub-skills signal non-applicability by returning `outcome: "not-applicable"` or `outcome: "no-knowledge"`. - `## Worklist` — the final list of sub-skills to invoke; the rest go to `skipped-sub-skills`. - `## Action` — invoke each worklisted sub-skill with the appropriate subset of inputs, collect its findings-report verbatim into `sub-results`, and copy its `findings[]` into the super-skill's top-level `findings[]` with `from-sub-skill` set. All finding fields, including the optional `domain`, are preserved verbatim unless this contract explicitly requires a transformation. Findings from a sub-skill with `outcome: "failed"` MUST NOT be copied into the super-skill's top-level `findings[]` and MUST NOT contribute to the super-skill's `summary.counts` (their report is still preserved in `sub-results` for traceability, consistent with DO's rule that consumers ignore a failed skill's findings). diff --git a/tools/Build-SkillIndex.ps1 b/tools/Build-SkillIndex.ps1 index 022898e..d4028c2 100644 --- a/tools/Build-SkillIndex.ps1 +++ b/tools/Build-SkillIndex.ps1 @@ -203,9 +203,19 @@ foreach ($layer in 'microsoft', 'community', 'custom') { } } -$ids = @($records | Group-Object id | Where-Object Count -gt 1) -if ($ids.Count) { - throw "Duplicate action-skill IDs: $($ids.Name -join ', ')" +$idsWithinLayer = @( + $records | + Group-Object { "$($_.layer)`0$($_.id)" } | + Where-Object Count -gt 1 +) +if ($idsWithinLayer.Count) { + $duplicates = @( + $idsWithinLayer | ForEach-Object { + $parts = $_.Name -split "`0", 2 + "$($parts[0]):$($parts[1])" + } + ) + throw "Duplicate action-skill IDs within a layer: $($duplicates -join ', ')" } foreach ($record in $records) { diff --git a/tools/Resolve-SkillWorklist.ps1 b/tools/Resolve-SkillWorklist.ps1 new file mode 100644 index 0000000..1e5e9f3 --- /dev/null +++ b/tools/Resolve-SkillWorklist.ps1 @@ -0,0 +1,92 @@ +<# +.SYNOPSIS + Resolves a super-skill's ordered leaf worklist across enabled layers. +#> +[CmdletBinding()] +param( + [string] $BCQualityRoot, + [string] $IndexPath, + [Parameter(Mandatory)] + [string] $SuperSkillPath, + [string[]] $EnabledLayers = @('microsoft', 'community', 'custom'), + [string[]] $DisabledSkills = @() +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +if (-not $BCQualityRoot) { + $BCQualityRoot = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path +} +$BCQualityRoot = (Resolve-Path -LiteralPath $BCQualityRoot).Path +if (-not $IndexPath) { + $IndexPath = Join-Path $BCQualityRoot 'skill-index.json' +} +if (-not (Test-Path -LiteralPath $IndexPath -PathType Leaf)) { + & (Join-Path $PSScriptRoot 'Build-SkillIndex.ps1') -BCQualityRoot $BCQualityRoot -IndexPath $IndexPath | Out-Null +} + +$knownLayers = @('microsoft', 'community', 'custom') +$unknownLayers = @($EnabledLayers | Where-Object { $_ -cnotin $knownLayers }) +if ($unknownLayers.Count) { + throw "Unknown enabled layers: $($unknownLayers -join ', ')" +} + +$index = Get-Content -LiteralPath $IndexPath -Raw | ConvertFrom-Json +$skills = @($index.skills) +$superSkills = @($skills | Where-Object path -CEQ $SuperSkillPath) +if ($superSkills.Count -ne 1) { + throw "Expected one indexed super-skill at '$SuperSkillPath', found $($superSkills.Count)." +} +$superSkill = $superSkills[0] +if (-not @($superSkill.subSkills).Count) { + throw "Action skill '$SuperSkillPath' is not a super-skill." +} + +$precedence = @{ microsoft = 0; community = 1; custom = 2 } +$resolved = [Collections.Generic.List[object]]::new() +$skipped = [Collections.Generic.List[object]]::new() +foreach ($declaredPath in @($superSkill.subSkills)) { + $declared = @($skills | Where-Object path -CEQ $declaredPath) + if ($declared.Count -ne 1) { + throw "Declared sub-skill '$declaredPath' is not uniquely indexed." + } + + $candidates = @( + $skills | + Where-Object { + $_.id -CEQ $declared[0].id -and + $_.layer -cin $EnabledLayers -and + $_.path -cnotin $DisabledSkills -and + -not @($_.subSkills).Count + } | + Sort-Object @{ Expression = { $precedence[$_.layer] }; Descending = $true }, path + ) + if (-not $candidates.Count) { + $skipped.Add([pscustomobject][ordered]@{ + id = $declared[0].id + declaredPath = $declaredPath + reason = 'configuration' + }) | Out-Null + continue + } + + $winner = $candidates[0] + $resolved.Add([pscustomobject][ordered]@{ + id = $winner.id + path = $winner.path + version = $winner.version + layer = $winner.layer + declaredPath = $declaredPath + }) | Out-Null +} + +return [pscustomobject][ordered]@{ + superSkill = [pscustomobject][ordered]@{ + id = $superSkill.id + path = $superSkill.path + version = $superSkill.version + } + subSkills = @($resolved) + skipped = @($skipped) +} \ No newline at end of file diff --git a/tools/Test-KnowledgeRetrieval.ps1 b/tools/Test-KnowledgeRetrieval.ps1 index ef65812..568a4bd 100644 --- a/tools/Test-KnowledgeRetrieval.ps1 +++ b/tools/Test-KnowledgeRetrieval.ps1 @@ -348,6 +348,60 @@ try { $indexPath = Join-Path $tmp 'knowledge-index.json' & $generator -BCQualityRoot $Root -IndexPath $indexPath | Out-Null $index = Get-Content -LiteralPath $indexPath -Raw -Encoding utf8 | ConvertFrom-Json + + # Check the declared finder route and real tool reachability, not model compliance. + $errorSkill = Get-Content -LiteralPath (Join-Path $Root 'microsoft/skills/review/al-error-handling-review.md') -Raw + $errorSource = [regex]::Match($errorSkill, '(?ms)^## Source\r?\n(.*?)(?=^## )').Groups[1].Value + $sourceDomains = @([regex]::Matches($errorSource, '-Domain ([a-z-]+)') | ForEach-Object { $_.Groups[1].Value }) + Assert-Sequence $sourceDomains @('error-handling', 'web-services') 'error-handling declares its own and supplementary HTTP catalogs' + foreach ($cue in @('HttpClient.Get', 'HttpClient.Post', 'resolved call paths', 'same known task dimensions and enabled layers')) { + Assert-True ($errorSource.Contains($cue)) "supplementary source retains '$cue'" + } + $httpArticleNames = @( + [regex]::Matches($errorSource, '\]\(\.\./\.\./knowledge/web-services/([a-z-]+\.md)\)') | + ForEach-Object { $_.Groups[1].Value } + ) + Assert-Sequence $httpArticleNames @( + 'handle-httpclient-platform-failure-before-response-access.md' + 'check-http-status-before-consuming-response-body.md' + ) 'supplementary source names only the two canonical HTTP articles' + $httpArguments = @{ + BCQualityRoot = $Root + IndexPath = $indexPath + EnabledLayers = @('microsoft', 'community', 'custom') + Technologies = @('al') + BCVersion = 28 + Countries = @('w1') + } + $ownCatalog = Invoke-CatalogPages -Arguments ($httpArguments + @{ Domain = $sourceDomains[0] }) + Assert-True (-not @($ownCatalog.candidates | Where-Object { $_.path -like '*/knowledge/web-services/*' }).Count) 'the primary catalog does not silently expand domains' + $httpCatalog = Invoke-CatalogPages -Arguments ($httpArguments + @{ Domain = $sourceDomains[1] }) + $httpRows = @($httpCatalog.candidates | Where-Object { $httpArticleNames -ccontains ($_.path -split '/')[-1] }) + $expectedHttpPaths = @( + $index.articles | + Where-Object { $_.domain -ceq 'web-services' -and $httpArticleNames -ccontains ($_.path -split '/')[-1] } | + ForEach-Object path | + Sort-Object + ) + foreach ($name in $httpArticleNames) { + Assert-True ($expectedHttpPaths -ccontains "microsoft/knowledge/web-services/$name") "canonical owner exists for $name" + } + Assert-Sequence @($httpRows.path | Sort-Object) $expectedHttpPaths 'supplementary selection preserves exact paths across layers' + Test-BodyRoundTrip -Paths $httpRows.path -IndexPath $indexPath + foreach ($excludedContext in @( + @{ EnabledLayers = @() } + @{ Technologies = @('javascript') } + )) { + $arguments = $httpArguments + @{ Domain = $sourceDomains[1] } + foreach ($key in $excludedContext.Keys) { + $arguments[$key] = $excludedContext[$key] + } + $catalog = Invoke-CatalogPages -Arguments $arguments + $selected = @($catalog.candidates | Where-Object { $httpArticleNames -ccontains ($_.path -split '/')[-1] }) + Assert-Equal $selected.Count 0 'supplementary selection respects disabled layers and nonmatching technology' + } + Write-Host 'HTTP source contract and exact-body reachability passed; model routing was not evaluated.' + $diskArticlePaths = @( foreach ($layer in 'microsoft', 'community', 'custom') { $knowledge = Join-Path $Root "$layer\knowledge" diff --git a/tools/Test-ReviewContract.ps1 b/tools/Test-ReviewContract.ps1 index 1d40058..adacb36 100644 --- a/tools/Test-ReviewContract.ps1 +++ b/tools/Test-ReviewContract.ps1 @@ -1,12 +1,11 @@ <# .SYNOPSIS - Validates the bounded leaf-range normalization contract. + Validates executable findings-report acceptance and bounded normalization. .DESCRIPTION - BCQuality has no executable findings-report consumer. These assertions keep - the normative DO contract, AL coordinator, and standalone runner aligned - while exercising the exact normalization predicate against representative - safe and ambiguous inputs. + These assertions keep the normative DO contract, executable validator, AL + coordinator, and standalone runner aligned while exercising semantic report + validation and the exact normalization predicate. #> [CmdletBinding()] param( @@ -39,6 +38,24 @@ function Assert-Contains { Assert-True $Text.Contains($Expected) $Message } +function Assert-ThrowsLike { + param( + [scriptblock] $Action, + [string] $Pattern + ) + + try { + & $Action + } + catch { + if ($_.Exception.Message -like $Pattern) { + return + } + throw "Expected error like '$Pattern', received: $($_.Exception.Message)" + } + throw "Expected error like '$Pattern', but no error was thrown." +} + function Test-PositiveInteger { param([object] $Value) @@ -168,4 +185,334 @@ Assert-True (-not ($candidateFinding.location.PSObject.Properties.Name -contains Assert-True ($candidateFinding.location.line -eq $rawFinding.location.line) 'candidate preserves the primary line' Assert-True ($candidateFinding.message -ceq $rawFinding.message) 'candidate preserves all other finding content' -Write-Output "Review contract validation passed ($($cases.Count) normalization cases)." +$validator = Join-Path $Root 'tools/Validate-FindingsReport.ps1' +Assert-True (Test-Path -LiteralPath $validator -PathType Leaf) 'executable report validator exists' +$tmp = Join-Path ([IO.Path]::GetTempPath()) ("reviewcontract_" + [guid]::NewGuid().ToString('N')) +New-Item -ItemType Directory -Path $tmp -Force | Out-Null +try { + $sourcePath = 'src/codeunit.al' + $sourceFile = Join-Path $tmp 'src/codeunit.al' + New-Item -ItemType Directory -Path (Split-Path -Parent $sourceFile) -Force | Out-Null + Set-Content -LiteralPath $sourceFile -Value @('line one', 'line two', 'line three') -Encoding utf8NoBOM + $articlePath = 'microsoft/knowledge/style/caption-required-on-page-fields.md' + $supportingArticlePath = 'microsoft/knowledge/style/tooltip-required-on-page-fields.md' + $reportPath = Join-Path $tmp 'report.json' + + $validReport = [ordered]@{ + skill = [ordered]@{ id = 'al-style-review'; version = 1 } + outcome = 'completed' + summary = [ordered]@{ + counts = [ordered]@{ blocker = 0; major = 0; minor = 1; info = 0 } + coverage = [ordered]@{ 'worklist-size' = 1; 'items-evaluated' = 1 } + } + findings = @( + [ordered]@{ + id = $articlePath + severity = 'minor' + message = 'A concrete style defect.' + location = [ordered]@{ + file = $sourcePath + line = 2 + range = [ordered]@{ 'start-line' = 2; 'end-line' = 3 } + } + references = @([ordered]@{ path = $articlePath }) + confidence = 'high' + domain = 'Style' + } + ) + suppressed = @() + } + Set-Content -LiteralPath $reportPath -Value ($validReport | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + $accepted = & $validator -ReportPath $reportPath -BCQualityRoot $Root -SourceRoot $tmp ` + -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + Assert-True (-not $accepted.normalized) 'valid report is accepted without normalization' + + $invalidCounts = $validReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $invalidCounts.summary.counts.minor = 0 + Set-Content -LiteralPath $reportPath -Value ($invalidCounts | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*COUNT_MISMATCH*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SourceRoot $tmp ` + -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + } + + $completedUndercoverage = $validReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $completedUndercoverage.summary.coverage.'items-evaluated' = 0 + Set-Content -LiteralPath $reportPath -Value ($completedUndercoverage | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*COMPLETED_COVERAGE_INCOMPLETE*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SourceRoot $tmp ` + -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + } + + $partialFullCoverage = $validReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $partialFullCoverage.outcome = 'partial' + $partialFullCoverage | Add-Member -NotePropertyName 'outcome-reason' -NotePropertyValue 'Stopped early.' + Set-Content -LiteralPath $reportPath -Value ($partialFullCoverage | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*PARTIAL_COVERAGE_INVALID*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SourceRoot $tmp ` + -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + } + + $completedLeaf = [ordered]@{ + skill = [ordered]@{ id = 'al-style-review'; version = 1 } + outcome = 'completed' + summary = [ordered]@{ + counts = [ordered]@{ blocker = 0; major = 0; minor = 0; info = 0 } + coverage = [ordered]@{ 'worklist-size' = 1; 'items-evaluated' = 1 } + } + findings = @() + suppressed = @() + } + $leafWithSubResults = $completedLeaf | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $leafWithSubResults | Add-Member -NotePropertyName 'sub-results' -NotePropertyValue @($completedLeaf) + Set-Content -LiteralPath $reportPath -Value ($leafWithSubResults | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*LEAF_COMPOSITION_INVALID*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root + } + + $validSuperReport = [ordered]@{ + skill = [ordered]@{ id = 'al-code-review'; version = 1 } + outcome = 'completed' + summary = [ordered]@{ + counts = [ordered]@{ blocker = 0; major = 0; minor = 0; info = 0 } + coverage = [ordered]@{ 'worklist-size' = 2; 'items-evaluated' = 2 } + } + findings = @() + suppressed = @() + 'sub-results' = @($completedLeaf, $completedLeaf) + } + Set-Content -LiteralPath $reportPath -Value ($validSuperReport | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + $acceptedSuper = & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super + Assert-True (-not $acceptedSuper.normalized) 'valid super-skill report is accepted' + + $styleFindingLeaf = $validReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $securityFindingLeaf = $validReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $securityFindingLeaf.skill.id = 'al-security-review' + $rolledFinding = $validReport.findings[0] | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $rolledFinding | Add-Member -NotePropertyName 'from-sub-skill' -NotePropertyValue 'al-style-review' + $deduplicatedSuperReport = $validSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $deduplicatedSuperReport.summary.counts.minor = 1 + $deduplicatedSuperReport.findings = @($rolledFinding) + $deduplicatedSuperReport.'sub-results' = @($styleFindingLeaf, $securityFindingLeaf) + Set-Content -LiteralPath $reportPath -Value ($deduplicatedSuperReport | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + $acceptedDeduplicatedSuper = & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + Assert-True (-not $acceptedDeduplicatedSuper.normalized) 'one top-level finding may deduplicate the same citation from two leaves' + + $twoOccurrenceLeaf = $styleFindingLeaf | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $secondOccurrence = $twoOccurrenceLeaf.findings[0] | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $secondOccurrence.location.line = 1 + $secondOccurrence.location.range.'start-line' = 1 + $secondOccurrence.location.range.'end-line' = 1 + $twoOccurrenceLeaf.findings = @($twoOccurrenceLeaf.findings[0], $secondOccurrence) + $twoOccurrenceLeaf.summary.counts.minor = 2 + $emptySecurityLeaf = $completedLeaf | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $emptySecurityLeaf.skill.id = 'al-security-review' + $sameIdOccurrenceOmitted = $deduplicatedSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $sameIdOccurrenceOmitted.'sub-results' = @($twoOccurrenceLeaf, $emptySecurityLeaf) + Set-Content -LiteralPath $reportPath -Value ($sameIdOccurrenceOmitted | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_FINDING_MISSING*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + } + + $mergeOwnerLeaf = $styleFindingLeaf | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $mergeOwnerLeaf.findings[0] | Add-Member -NotePropertyName 'suggested-code' -NotePropertyValue 'Caption = ''Customer name'';' + $supportingFindingLeaf = $securityFindingLeaf | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $supportingFindingLeaf.findings[0].id = $supportingArticlePath + $supportingFindingLeaf.findings[0].references[0].path = $supportingArticlePath + $supportingFindingLeaf.findings[0].confidence = 'medium' + $supportingFindingLeaf.findings[0].message = 'The field needs the same mechanical correction for a supporting rule.' + $supportingFindingLeaf.findings[0] | Add-Member -NotePropertyName 'suggested-code' -NotePropertyValue 'Caption = ''Customer name'';' + $mergedFinding = $rolledFinding | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $mergedFinding | Add-Member -NotePropertyName 'suggested-code' -NotePropertyValue 'Caption = ''Customer name'';' + $mergedFinding.references = @( + [pscustomobject]@{ path = $articlePath } + [pscustomobject]@{ path = $supportingArticlePath } + ) + $mergedSuperReport = $deduplicatedSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $mergedSuperReport.findings = @($mergedFinding) + $mergedSuperReport.'sub-results' = @($mergeOwnerLeaf, $supportingFindingLeaf) + Set-Content -LiteralPath $reportPath -Value ($mergedSuperReport | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + $acceptedMergedSuper = & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath, $supportingArticlePath + Assert-True (-not $acceptedMergedSuper.normalized) 'overlapping A and B findings may merge into A with B as a supporting reference' + + $textOnlyOwnerLeaf = $mergeOwnerLeaf | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $textOnlyOwnerLeaf.findings[0].PSObject.Properties.Remove('suggested-code') + $textOnlySupportingLeaf = $supportingFindingLeaf | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $textOnlySupportingLeaf.findings[0].PSObject.Properties.Remove('suggested-code') + $textOnlyMergedFinding = $mergedFinding | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $textOnlyMergedFinding.PSObject.Properties.Remove('suggested-code') + $textOnlyMergedSuper = $mergedSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $textOnlyMergedSuper.findings = @($textOnlyMergedFinding) + $textOnlyMergedSuper.'sub-results' = @($textOnlyOwnerLeaf, $textOnlySupportingLeaf) + Set-Content -LiteralPath $reportPath -Value ($textOnlyMergedSuper | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + $acceptedTextOnlyMerge = & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath, $supportingArticlePath + Assert-True (-not $acceptedTextOnlyMerge.normalized) 'supporting references permit an overlapping A and B merge with different messages and no suggested code' + + $conflictingSupportingLeaf = $supportingFindingLeaf | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $conflictingSupportingLeaf.findings[0].'suggested-code' = 'ToolTip = ''Customer name'';' + $conflictingCorrectionMerge = $mergedSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $conflictingCorrectionMerge.'sub-results' = @($mergeOwnerLeaf, $conflictingSupportingLeaf) + Set-Content -LiteralPath $reportPath -Value ($conflictingCorrectionMerge | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_FINDING_MISSING*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath, $supportingArticlePath + } + + $omittedConflictingCorrectionMerge = $conflictingCorrectionMerge | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $omittedConflictingCorrectionMerge.findings[0].PSObject.Properties.Remove('suggested-code') + Set-Content -LiteralPath $reportPath -Value ($omittedConflictingCorrectionMerge | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_FINDING_MISMATCH*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath, $supportingArticlePath + } + + $unmergedSupportingFinding = $supportingFindingLeaf.findings[0] | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $unmergedSupportingFinding | Add-Member -NotePropertyName 'from-sub-skill' -NotePropertyValue 'al-security-review' + $unmergedDuplicates = $mergedSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $unmergedDuplicates.summary.counts.minor = 2 + $unmergedDuplicates.findings = @($mergedFinding, $unmergedSupportingFinding) + Set-Content -LiteralPath $reportPath -Value ($unmergedDuplicates | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_DUPLICATE_FINDINGS*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath, $supportingArticlePath + } + + $omittedLeafFinding = $deduplicatedSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $omittedLeafFinding.summary.counts.minor = 0 + $omittedLeafFinding.findings = @() + Set-Content -LiteralPath $reportPath -Value ($omittedLeafFinding | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_FINDING_MISSING*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + } + + $locationlessLeaf = $styleFindingLeaf | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $locationlessLeaf.findings[0].PSObject.Properties.Remove('location') + $secondLocationlessFinding = $locationlessLeaf.findings[0] | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $locationlessLeaf.findings = @($locationlessLeaf.findings[0], $secondLocationlessFinding) + $locationlessLeaf.summary.counts.minor = 2 + $locationlessRolledFinding = $rolledFinding | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $locationlessRolledFinding.PSObject.Properties.Remove('location') + $locationlessOmission = $deduplicatedSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $locationlessOmission.findings = @($locationlessRolledFinding) + $locationlessOmission.'sub-results' = @($locationlessLeaf, $emptySecurityLeaf) + Set-Content -LiteralPath $reportPath -Value ($locationlessOmission | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_FINDING_MISSING*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + } + + $completeLocationlessRollup = $locationlessOmission | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $completeLocationlessRollup.summary.counts.minor = 2 + $completeLocationlessRollup.findings = @( + $locationlessRolledFinding + ($locationlessRolledFinding | ConvertTo-Json -Depth 20 | ConvertFrom-Json) + ) + Set-Content -LiteralPath $reportPath -Value ($completeLocationlessRollup | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + $acceptedLocationlessRollup = & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + Assert-True (-not $acceptedLocationlessRollup.normalized) 'two locationless leaf occurrences require and accept two distinct rolled findings' + + $nonexistentProducer = $deduplicatedSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $nonexistentProducer.findings[0].'from-sub-skill' = 'al-missing-review' + Set-Content -LiteralPath $reportPath -Value ($nonexistentProducer | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_PRODUCER_INVALID*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + } + + $rewrittenLeafFinding = $deduplicatedSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $rewrittenLeafFinding.findings[0].message = 'A rewritten rollup message.' + Set-Content -LiteralPath $reportPath -Value ($rewrittenLeafFinding | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_FINDING_MISMATCH*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + } + + $failedLeaf = $completedLeaf | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $failedLeaf.skill.id = 'al-security-review' + $failedLeaf.outcome = 'failed' + $failedLeaf | Add-Member -NotePropertyName 'outcome-reason' -NotePropertyValue 'Validation failed.' + $failedLeaf.summary.coverage.'items-evaluated' = 0 + $partialSuperReport = $validSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $partialSuperReport.outcome = 'partial' + $partialSuperReport | Add-Member -NotePropertyName 'outcome-reason' -NotePropertyValue 'One sub-skill failed.' + $partialSuperReport.summary.coverage.'worklist-size' = 1 + $partialSuperReport.summary.coverage.'items-evaluated' = 1 + $partialSuperReport.'sub-results' = @($completedLeaf, $failedLeaf) + Set-Content -LiteralPath $reportPath -Value ($partialSuperReport | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + $acceptedPartialSuper = & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super + Assert-True (-not $acceptedPartialSuper.normalized) 'partial super-skill excludes failed coverage from its rollup' + + $failedLeafLeakage = $partialSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $failedLeafLeakage.summary.counts.minor = 1 + $failedLeafLeakage.findings = @($rolledFinding | ConvertTo-Json -Depth 20 | ConvertFrom-Json) + $failedLeafLeakage.findings[0].'from-sub-skill' = 'al-security-review' + Set-Content -LiteralPath $reportPath -Value ($failedLeafLeakage | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_FAILED_FINDING_LEAKAGE*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + } + + $failedLeafRelabeledAsAgent = $partialSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $failedLeafRelabeledAsAgent.summary.counts.minor = 1 + $failedLeafRelabeledAsAgent.findings = @($rolledFinding | ConvertTo-Json -Depth 20 | ConvertFrom-Json) + $failedLeafRelabeledAsAgent.findings[0].'from-sub-skill' = 'agent' + $failedLeafRelabeledAsAgent.findings[0].domain = 'Agent' + Set-Content -LiteralPath $reportPath -Value ($failedLeafRelabeledAsAgent | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_AGENT_FINDING_INVALID*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super ` + -SourceRoot $tmp -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + } + + $incorrectOutcome = $validSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $incorrectOutcome.outcome = 'not-applicable' + Set-Content -LiteralPath $reportPath -Value ($incorrectOutcome | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_OUTCOME_MISMATCH*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super + } + + $incorrectRollup = $validSuperReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $incorrectRollup.summary.coverage.'worklist-size' = 1 + $incorrectRollup.summary.coverage.'items-evaluated' = 1 + Set-Content -LiteralPath $reportPath -Value ($incorrectRollup | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*SUPER_COVERAGE_MISMATCH*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SkillKind super + } + + Set-Content -LiteralPath $reportPath -Value ($validReport | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*REFERENCE_NOT_RETRIEVED*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SourceRoot $tmp -SourcePaths $sourcePath + } + + $invalidAgent = $validReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $invalidAgent.findings[0].id = 'agent:uncited-defect' + $invalidAgent.findings[0].references = @() + $invalidAgent.findings[0].confidence = 'high' + Set-Content -LiteralPath $reportPath -Value ($invalidAgent | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*AGENT_CONFIDENCE_INVALID*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SourceRoot $tmp -SourcePaths $sourcePath + } + + $normalizable = $validReport | ConvertTo-Json -Depth 20 | ConvertFrom-Json + $normalizable.findings[0].location.range.'start-line' = 1 + Set-Content -LiteralPath $reportPath -Value ($normalizable | ConvertTo-Json -Depth 20) -Encoding utf8NoBOM + Assert-ThrowsLike -Pattern '*RANGE_START_MISMATCH*' -Action { + & $validator -ReportPath $reportPath -BCQualityRoot $Root -SourceRoot $tmp ` + -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath + } + $normalized = & $validator -ReportPath $reportPath -BCQualityRoot $Root -SourceRoot $tmp ` + -SourcePaths $sourcePath -RetrievedArticlePaths $articlePath -AllowBoundedNormalization + Assert-True $normalized.normalized 'eligible range mismatch is normalized' + Assert-True ($normalized.removedRanges.Count -eq 1) 'normalization records one removed range' + Assert-True (-not ($normalized.report.findings[0].location.PSObject.Properties.Name -contains 'range')) ` + 'accepted normalized report removes only the optional range' +} +finally { + Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue +} + +Write-Output "Review contract validation passed ($($cases.Count) predicate cases plus executable acceptance cases)." diff --git a/tools/Test-ReviewFixtures.ps1 b/tools/Test-ReviewFixtures.ps1 index 8cf019f..2941c02 100644 --- a/tools/Test-ReviewFixtures.ps1 +++ b/tools/Test-ReviewFixtures.ps1 @@ -18,7 +18,9 @@ param( [string] $ManifestPath, [string] $PrepareDirectory, [string] $ResultsPath, - [string] $ResultsDirectory + [string] $ResultsDirectory, + [string] $ChangedPathsFile, + [string] $CoverageReportPath ) Set-StrictMode -Version Latest @@ -160,7 +162,23 @@ foreach ($overrideDomain in $overrides.Keys) { } } +$coverageWaivers = @{} +if ($manifest.PSObject.Properties.Name -contains 'coverageWaivers') { + foreach ($waiver in @($manifest.coverageWaivers)) { + if (-not $waiver.path -or -not $waiver.reason) { + $problems.Add('Each coverage waiver requires non-empty path and reason values.') | Out-Null + continue + } + if ($coverageWaivers.ContainsKey([string]$waiver.path)) { + $problems.Add("Duplicate coverage waiver: $($waiver.path)") | Out-Null + continue + } + $coverageWaivers[[string]$waiver.path] = [string]$waiver.reason + } +} + $caseList = [System.Collections.Generic.List[object]]::new() +$pairedArticlesByDomain = @{} foreach ($domain in $leafDomains) { $articleCandidates = @( foreach ($layer in $layers) { @@ -189,6 +207,7 @@ foreach ($domain in $leafDomains) { ForEach-Object { $_.Group | Sort-Object Rank -Descending | Select-Object -First 1 } | Sort-Object BaseName ) + $pairedArticlesByDomain[$domain] = @($articles) if (-not $articles.Count) { $problems.Add("${domain}: no enabled knowledge layer has an article with both .good.al and .bad.al companion samples.") | Out-Null continue @@ -339,6 +358,65 @@ foreach ($domain in $leafDomains) { } } +$selectedArticlePaths = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal) +foreach ($case in $cases) { + foreach ($reference in @($case.expected)) { + $selectedArticlePaths.Add([string]$reference) | Out-Null + } +} +$effectivePairedPaths = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal) +$coverageDomains = @( + foreach ($domain in $leafDomains) { + $paired = @($pairedArticlesByDomain[$domain]) + foreach ($article in $paired) { + $effectivePairedPaths.Add([string]$article.ArticlePath) | Out-Null + } + $selected = @($paired | Where-Object { $selectedArticlePaths.Contains([string]$_.ArticlePath) }).Count + [pscustomobject][ordered]@{ + domain = $domain + pairedArticles = $paired.Count + selectedArticles = $selected + coverage = if ($paired.Count) { $selected / $paired.Count } else { 0 } + } + } +) +$pairedTotal = ($coverageDomains | Measure-Object pairedArticles -Sum).Sum +$selectedTotal = ($coverageDomains | Measure-Object selectedArticles -Sum).Sum +$coverageReport = [pscustomobject][ordered]@{ + pairedArticles = $pairedTotal + selectedArticles = $selectedTotal + coverage = if ($pairedTotal) { $selectedTotal / $pairedTotal } else { 0 } + domains = $coverageDomains +} +if ($CoverageReportPath) { + $coverageParent = Split-Path -Parent $CoverageReportPath + if ($coverageParent -and -not (Test-Path -LiteralPath $coverageParent)) { + New-Item -ItemType Directory -Path $coverageParent -Force | Out-Null + } + $coverageReport | ConvertTo-Json -Depth 6 | Set-Content -LiteralPath $CoverageReportPath -Encoding utf8NoBOM +} + +if ($ChangedPathsFile) { + if (-not (Test-Path -LiteralPath $ChangedPathsFile -PathType Leaf)) { + $problems.Add("Changed paths file not found: $ChangedPathsFile") | Out-Null + } + else { + foreach ($changedPathValue in Get-Content -LiteralPath $ChangedPathsFile) { + $changedPath = ([string]$changedPathValue).Trim().Replace('\', '/') + if ($changedPath -notmatch '^(microsoft|community|custom)/knowledge/[^/]+/(.+?)(?:\.(?:good|bad)\.al|\.md)$') { + continue + } + $articlePath = "$($Matches[1])/knowledge/$($changedPath.Split('/')[2])/$($Matches[2]).md" + if (-not $effectivePairedPaths.Contains($articlePath) -or $selectedArticlePaths.Contains($articlePath)) { + continue + } + if (-not $coverageWaivers.ContainsKey($articlePath)) { + $problems.Add("Changed paired article is not selected for evaluation and has no coverage waiver: $articlePath") | Out-Null + } + } + } +} + if ($problems.Count) { Write-Host "Review fixture validation FAILED ($($problems.Count) problem(s)):" -ForegroundColor Red $problems | ForEach-Object { Write-Host " - $_" -ForegroundColor Red } @@ -474,7 +552,7 @@ if ($PrepareDirectory) { if (-not $ResultsPath -and -not $ResultsDirectory) { & (Join-Path $PSScriptRoot 'Test-ReviewContract.ps1') -Root $Root - Write-Host "Review fixture validation PASSED: $($cases.Count) cases cover $($leafDomains.Count) leaf domains." -ForegroundColor Green + Write-Host "Review fixture validation PASSED: $($cases.Count) cases cover $selectedTotal/$pairedTotal paired articles across $($leafDomains.Count) leaf domains." -ForegroundColor Green exit 0 } diff --git a/tools/Validate-FindingsReport.ps1 b/tools/Validate-FindingsReport.ps1 new file mode 100644 index 0000000..d3442d3 --- /dev/null +++ b/tools/Validate-FindingsReport.ps1 @@ -0,0 +1,540 @@ +<# +.SYNOPSIS + Validates a BCQuality findings-report against its structural and semantic contract. +#> +[CmdletBinding()] +param( + [Parameter(Mandatory)] + [string] $ReportPath, + [string] $BCQualityRoot, + [string] $SourceRoot, + [string[]] $SourcePaths = @(), + [string[]] $RetrievedArticlePaths = @(), + [ValidateSet('leaf', 'super')] + [string] $SkillKind = 'leaf', + [switch] $AllowBoundedNormalization +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +if (-not $BCQualityRoot) { + $BCQualityRoot = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path +} +$BCQualityRoot = (Resolve-Path -LiteralPath $BCQualityRoot).Path +$schemaPath = Join-Path $BCQualityRoot 'schemas/findings-report.schema.json' +$raw = Get-Content -LiteralPath $ReportPath -Raw +try { + if (-not ($raw | Test-Json -SchemaFile $schemaPath -ErrorAction Stop)) { + throw 'Report does not satisfy schemas/findings-report.schema.json.' + } + $report = $raw | ConvertFrom-Json -Depth 100 +} +catch { + throw "Invalid findings-report JSON or schema: $($_.Exception.Message)" +} + +$retrieved = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal) +foreach ($path in $RetrievedArticlePaths) { + $retrieved.Add($path) | Out-Null +} +$sources = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal) +foreach ($path in $SourcePaths) { + $sources.Add($path) | Out-Null +} +$lineCounts = @{} + +function Test-HasProperty { + param([object] $Object, [string] $Name) + return $null -ne $Object -and $Object.PSObject.Properties.Name -ccontains $Name +} + +function Get-SourceLineCount { + param([string] $Path) + + if ($lineCounts.ContainsKey($Path)) { + return $lineCounts[$Path] + } + if (-not $SourceRoot) { + return -1 + } + $fullPath = Join-Path $SourceRoot ($Path -replace '/', [IO.Path]::DirectorySeparatorChar) + if (-not (Test-Path -LiteralPath $fullPath -PathType Leaf)) { + return -1 + } + $lineCounts[$Path] = [IO.File]::ReadAllLines($fullPath).Count + return $lineCounts[$Path] +} + +function Get-SemanticErrors { + param( + [object] $Candidate, + [switch] $PermitRangeStartMismatch + ) + + $errors = [Collections.Generic.List[object]]::new() + function Add-Error { + param([string] $Code, [string] $Path, [string] $Message) + $errors.Add([pscustomobject]@{ Code = $Code; Path = $Path; Message = $Message }) | Out-Null + } + + function Get-DerivedSuperOutcome { + param([object[]] $SubResults) + + if (-not $SubResults.Count) { + return 'not-applicable' + } + + $outcomes = @($SubResults | ForEach-Object { $_.outcome }) + if (-not @($outcomes | Where-Object { $_ -cne 'failed' }).Count) { + return 'failed' + } + if (($outcomes -ccontains 'partial') -or + (($outcomes -ccontains 'failed') -and @($outcomes | Where-Object { $_ -cne 'failed' }).Count)) { + return 'partial' + } + if (-not @($outcomes | Where-Object { $_ -cne 'not-applicable' }).Count) { + return 'not-applicable' + } + if (($outcomes -ccontains 'no-knowledge') -and + -not @($outcomes | Where-Object { $_ -cnotin @('no-knowledge', 'not-applicable') }).Count) { + return 'no-knowledge' + } + return 'completed' + } + + function Get-SeverityRank { + param([string] $Severity) + return @{'info' = 0; 'minor' = 1; 'major' = 2; 'blocker' = 3}[$Severity] + } + + function Get-ConfidenceRank { + param([string] $Confidence) + return @{'low' = 0; 'medium' = 1; 'high' = 2}[$Confidence] + } + + function Test-LocationsOverlap { + param([object] $First, [object] $Second) + + $firstHasLocation = Test-HasProperty $First 'location' + $secondHasLocation = Test-HasProperty $Second 'location' + if ($firstHasLocation -ne $secondHasLocation) { + return $false + } + if (-not $firstHasLocation) { + return $false + } + if ($First.location.file -cne $Second.location.file) { + return $false + } + $firstEnd = if (Test-HasProperty $First.location 'range') { $First.location.range.'end-line' } else { $First.location.line } + $secondEnd = if (Test-HasProperty $Second.location 'range') { $Second.location.range.'end-line' } else { $Second.location.line } + return $First.location.line -le $secondEnd -and $Second.location.line -le $firstEnd + } + + function Test-SameCorrection { + param([object] $First, [object] $Second) + + $firstHasCode = Test-HasProperty $First 'suggested-code' + $secondHasCode = Test-HasProperty $Second 'suggested-code' + if ($firstHasCode -or $secondHasCode) { + return $firstHasCode -and $secondHasCode -and $First.'suggested-code' -ceq $Second.'suggested-code' + } + return $First.message -ceq $Second.message + } + + function Test-ReferencesInclude { + param([object[]] $RolledReferences, [object[]] $LeafReferences) + + foreach ($leafReference in $LeafReferences) { + $matched = @($RolledReferences | Where-Object { + if ($_.path -cne $leafReference.path) { + return $false + } + $rolledHasSha = Test-HasProperty $_ 'sha' + $leafHasSha = Test-HasProperty $leafReference 'sha' + return $rolledHasSha -eq $leafHasSha -and + (-not $rolledHasSha -or $_.sha -ceq $leafReference.sha) + }).Count + if (-not $matched) { + return $false + } + } + return $true + } + + function Test-RolledFindingRepresents { + param( + [object] $RolledFinding, + [object] $LeafFinding, + [string] $LeafProducerId, + [switch] $RequirePrimaryOwner + ) + + $rolledHasLocation = Test-HasProperty $RolledFinding 'location' + $leafHasLocation = Test-HasProperty $LeafFinding 'location' + $leafReferences = @($LeafFinding.references) + $rolledReferences = @($RolledFinding.references) + if (-not $rolledHasLocation -and -not $leafHasLocation) { + $expectedId = if ($leafReferences.Count) { $LeafFinding.id } else { "${LeafProducerId}:$($LeafFinding.id)" } + if ($RolledFinding.'from-sub-skill' -cne $LeafProducerId -or + $RolledFinding.id -cne $expectedId -or + $RolledFinding.severity -cne $LeafFinding.severity -or + $RolledFinding.confidence -cne $LeafFinding.confidence -or + $RolledFinding.message -cne $LeafFinding.message -or + $rolledReferences.Count -ne $leafReferences.Count -or + -not (Test-ReferencesInclude $rolledReferences $leafReferences)) { + return $false + } + foreach ($name in 'domain', 'suggested-code', 'suggested-code-omission-reason') { + $rolledHasProperty = Test-HasProperty $RolledFinding $name + $leafHasProperty = Test-HasProperty $LeafFinding $name + if ($rolledHasProperty -ne $leafHasProperty -or + ($rolledHasProperty -and $RolledFinding.$name -cne $LeafFinding.$name)) { + return $false + } + } + return $true + } + + if (-not (Test-LocationsOverlap $RolledFinding $LeafFinding) -or + (Get-SeverityRank $RolledFinding.severity) -lt (Get-SeverityRank $LeafFinding.severity) -or + (Get-ConfidenceRank $RolledFinding.confidence) -lt (Get-ConfidenceRank $LeafFinding.confidence)) { + return $false + } + + $sameCorrection = Test-SameCorrection $RolledFinding $LeafFinding + $correctionsConflict = (Test-HasProperty $RolledFinding 'suggested-code') -and + (Test-HasProperty $LeafFinding 'suggested-code') -and + $RolledFinding.'suggested-code' -cne $LeafFinding.'suggested-code' + $explicitCrossRuleMerge = $leafReferences.Count -and + $rolledReferences.Count -gt $leafReferences.Count -and + -not $correctionsConflict -and + (Test-ReferencesInclude $rolledReferences $leafReferences) + if (-not $sameCorrection -and -not $explicitCrossRuleMerge) { + return $false + } + + if (-not $leafReferences.Count) { + return $RolledFinding.'from-sub-skill' -ceq $LeafProducerId -and + $RolledFinding.id -ceq "${LeafProducerId}:$($LeafFinding.id)" -and + -not $rolledReferences.Count + } + if (-not (Test-ReferencesInclude $rolledReferences $leafReferences)) { + return $false + } + if ($RequirePrimaryOwner) { + $rolledHasDomain = Test-HasProperty $RolledFinding 'domain' + $leafHasDomain = Test-HasProperty $LeafFinding 'domain' + return $RolledFinding.'from-sub-skill' -ceq $LeafProducerId -and + $RolledFinding.id -ceq $LeafFinding.id -and + @($RolledFinding.references)[0].path -ceq $leafReferences[0].path -and + $rolledHasDomain -eq $leafHasDomain -and + (-not $rolledHasDomain -or $RolledFinding.domain -ceq $LeafFinding.domain) + } + return $true + } + + function Test-Report { + param( + [object] $Current, + [string] $ReportPathPrefix, + [ValidateSet('leaf', 'super')] + [string] $CurrentSkillKind + ) + + $findings = @($Current.findings) + foreach ($severity in 'blocker', 'major', 'minor', 'info') { + $actual = @($findings | Where-Object severity -CEQ $severity).Count + if ($Current.summary.counts.$severity -ne $actual) { + Add-Error 'COUNT_MISMATCH' "$ReportPathPrefix.summary.counts.$severity" "Expected $actual." + } + } + $worklistSize = $Current.summary.coverage.'worklist-size' + $itemsEvaluated = $Current.summary.coverage.'items-evaluated' + if ($itemsEvaluated -gt $worklistSize) { + Add-Error 'COVERAGE_INVALID' "$ReportPathPrefix.summary.coverage" 'items-evaluated exceeds worklist-size.' + } + elseif ($Current.outcome -ceq 'completed' -and $itemsEvaluated -ne $worklistSize) { + Add-Error 'COMPLETED_COVERAGE_INCOMPLETE' "$ReportPathPrefix.summary.coverage" 'A completed report must evaluate its full worklist.' + } + elseif ($CurrentSkillKind -ceq 'leaf' -and $Current.outcome -ceq 'partial' -and + ($itemsEvaluated -le 0 -or $itemsEvaluated -ge $worklistSize)) { + Add-Error 'PARTIAL_COVERAGE_INVALID' "$ReportPathPrefix.summary.coverage" 'A partial report must evaluate a non-zero proper subset of its worklist.' + } + + $hasSubResults = Test-HasProperty $Current 'sub-results' + $hasSkippedSubSkills = Test-HasProperty $Current 'skipped-sub-skills' + if ($CurrentSkillKind -ceq 'leaf') { + if ($hasSubResults -or $hasSkippedSubSkills) { + Add-Error 'LEAF_COMPOSITION_INVALID' $ReportPathPrefix 'A leaf report must not contain sub-results or skipped-sub-skills.' + } + } + elseif (-not $hasSubResults) { + Add-Error 'SUPER_SUB_RESULTS_REQUIRED' $ReportPathPrefix 'A super-skill report must contain sub-results.' + } + + for ($index = 0; $index -lt $findings.Count; $index++) { + $finding = $findings[$index] + $findingPath = "$ReportPathPrefix.findings[$index]" + $references = @($finding.references) + $hasProducer = Test-HasProperty $finding 'from-sub-skill' + if ($CurrentSkillKind -ceq 'leaf' -and $hasProducer) { + Add-Error 'LEAF_PRODUCER_INVALID' "$findingPath.from-sub-skill" 'A leaf finding must not contain from-sub-skill.' + } + elseif ($CurrentSkillKind -ceq 'super' -and -not $hasProducer) { + Add-Error 'SUPER_PRODUCER_REQUIRED' $findingPath 'A super-skill finding must identify its producer in from-sub-skill.' + } + if (-not $references.Count) { + if ($finding.id -cnotmatch '(^|:)agent:[a-z0-9]+(?:-[a-z0-9]+)*$') { + Add-Error 'AGENT_ID_INVALID' "$findingPath.id" 'An agent finding id must contain an agent: slug marker.' + } + if ($finding.confidence -ceq 'high') { + Add-Error 'AGENT_CONFIDENCE_INVALID' "$findingPath.confidence" 'Agent confidence cannot be high.' + } + if ($finding.severity -cin @('blocker', 'major')) { + Add-Error 'AGENT_SEVERITY_INVALID' "$findingPath.severity" 'Agent severity cannot exceed minor.' + } + } + else { + if ($finding.id -cne $references[0].path) { + Add-Error 'PRIMARY_REFERENCE_MISMATCH' "$findingPath.id" 'Finding id must equal the primary reference path.' + } + foreach ($reference in $references) { + if ($reference.path -cnotmatch '^(microsoft|community|custom)/knowledge/.+\.md$') { + Add-Error 'REFERENCE_PATH_INVALID' "$findingPath.references" "Invalid knowledge path '$($reference.path)'." + continue + } + if (-not (Test-Path -LiteralPath (Join-Path $BCQualityRoot $reference.path) -PathType Leaf)) { + Add-Error 'REFERENCE_MISSING' "$findingPath.references" "Knowledge path '$($reference.path)' does not exist." + } + if (-not $retrieved.Contains($reference.path)) { + Add-Error 'REFERENCE_NOT_RETRIEVED' "$findingPath.references" "Knowledge path '$($reference.path)' was not retrieved in full." + } + } + } + + if (Test-HasProperty $finding 'location') { + $location = $finding.location + if (-not $sources.Contains($location.file)) { + Add-Error 'SOURCE_OUT_OF_SCOPE' "$findingPath.location.file" "Source path '$($location.file)' is outside the supplied scope." + } + $lineCount = Get-SourceLineCount $location.file + if ($lineCount -lt 0) { + Add-Error 'SOURCE_MISSING' "$findingPath.location.file" "Source path '$($location.file)' does not exist." + } + elseif ($location.line -gt $lineCount) { + Add-Error 'SOURCE_LINE_INVALID' "$findingPath.location.line" "Line exceeds the file's $lineCount lines." + } + + if (Test-HasProperty $location 'range') { + $range = $location.range + if ($range.'start-line' -ne $location.line) { + Add-Error 'RANGE_START_MISMATCH' "$findingPath.location.range.start-line" 'start-line must equal line.' + } + if ($range.'end-line' -lt $range.'start-line' -or + ($lineCount -ge 0 -and $range.'end-line' -gt $lineCount)) { + Add-Error 'SOURCE_RANGE_INVALID' "$findingPath.location.range" 'Range is reversed or exceeds the source file.' + } + } + } + } + + if ($CurrentSkillKind -ceq 'super' -and $hasSubResults) { + $subResults = @($Current.'sub-results') + for ($index = 0; $index -lt $subResults.Count; $index++) { + Test-Report $subResults[$index] "$ReportPathPrefix.sub-results[$index]" 'leaf' + } + + $expectedOutcome = Get-DerivedSuperOutcome $subResults + if ($Current.outcome -cne $expectedOutcome) { + Add-Error 'SUPER_OUTCOME_MISMATCH' "$ReportPathPrefix.outcome" "Expected '$expectedOutcome' from sub-results." + } + + $includedSubResults = @($subResults | Where-Object outcome -CNE 'failed') + $expectedWorklistSize = ($includedSubResults | Measure-Object -Property { $_.summary.coverage.'worklist-size' } -Sum).Sum + $expectedItemsEvaluated = ($includedSubResults | Measure-Object -Property { $_.summary.coverage.'items-evaluated' } -Sum).Sum + if ($null -eq $expectedWorklistSize) { $expectedWorklistSize = 0 } + if ($null -eq $expectedItemsEvaluated) { $expectedItemsEvaluated = 0 } + if ($worklistSize -ne $expectedWorklistSize -or $itemsEvaluated -ne $expectedItemsEvaluated) { + Add-Error 'SUPER_COVERAGE_MISMATCH' "$ReportPathPrefix.summary.coverage" ` + "Expected worklist-size $expectedWorklistSize and items-evaluated $expectedItemsEvaluated from non-failed sub-results." + } + + $failedProducerIds = @($subResults | Where-Object outcome -CEQ 'failed' | ForEach-Object { $_.skill.id }) + $includedProducerIds = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal) + $eligibleFindings = [Collections.Generic.List[object]]::new() + foreach ($subResult in $includedSubResults) { + $includedProducerIds.Add([string]$subResult.skill.id) | Out-Null + foreach ($finding in @($subResult.findings)) { + $eligibleFindings.Add([pscustomobject]@{ + ProducerId = [string]$subResult.skill.id + Finding = $finding + }) | Out-Null + } + } + + for ($index = 0; $index -lt $findings.Count; $index++) { + $finding = $findings[$index] + $producerId = [string]$finding.'from-sub-skill' + if ($producerId -ceq 'agent') { + if (@($finding.references).Count -or + $finding.id -cnotmatch '^agent:[a-z0-9]+(?:-[a-z0-9]+)*$' -or + -not (Test-HasProperty $finding 'domain') -or + $finding.domain -cne 'Agent') { + Add-Error 'SUPER_AGENT_FINDING_INVALID' "$ReportPathPrefix.findings[$index]" ` + 'A super-skill agent finding must use an agent: id, Agent domain, and no references.' + } + continue + } + if ($producerId -cin $failedProducerIds) { + Add-Error 'SUPER_FAILED_FINDING_LEAKAGE' "$ReportPathPrefix.findings[$index].from-sub-skill" ` + "Finding is attributed to failed sub-skill '$producerId'." + continue + } + if (-not $includedProducerIds.Contains($producerId)) { + Add-Error 'SUPER_PRODUCER_INVALID' "$ReportPathPrefix.findings[$index].from-sub-skill" ` + "Sub-skill '$producerId' has no non-failed result." + continue + } + $ownedLeafFindings = @($eligibleFindings | Where-Object { + $_.ProducerId -ceq $producerId -and + (Test-RolledFindingRepresents $finding $_.Finding $_.ProducerId -RequirePrimaryOwner) + }) + if (-not $ownedLeafFindings.Count) { + Add-Error 'SUPER_FINDING_MISMATCH' "$ReportPathPrefix.findings[$index]" ` + "Rolled-up finding '$($finding.id)' is not owned by a matching finding from '$producerId'." + continue + } + $representedLeafFindings = @($eligibleFindings | Where-Object { + Test-RolledFindingRepresents $finding $_.Finding $_.ProducerId + }) + $representedCorrections = @( + $representedLeafFindings | + Where-Object { Test-HasProperty $_.Finding 'suggested-code' } | + ForEach-Object { $_.Finding.'suggested-code' } | + Sort-Object -CaseSensitive -Unique + ) + if ($representedCorrections.Count -gt 1) { + Add-Error 'SUPER_FINDING_MISMATCH' "$ReportPathPrefix.findings[$index]" ` + "Rolled-up finding '$($finding.id)' represents leaf findings with conflicting suggested-code replacements." + continue + } + $expectedSeverityRank = ($representedLeafFindings | ForEach-Object { Get-SeverityRank $_.Finding.severity } | Measure-Object -Maximum).Maximum + $expectedConfidenceRank = ($representedLeafFindings | ForEach-Object { Get-ConfidenceRank $_.Finding.confidence } | Measure-Object -Maximum).Maximum + if ((Get-SeverityRank $finding.severity) -ne $expectedSeverityRank -or + (Get-ConfidenceRank $finding.confidence) -ne $expectedConfidenceRank) { + Add-Error 'SUPER_FINDING_MISMATCH' "$ReportPathPrefix.findings[$index]" ` + "Rolled-up finding '$($finding.id)' must retain the highest severity and confidence justified by its represented leaf findings." + } + } + + for ($firstIndex = 0; $firstIndex -lt $findings.Count; $firstIndex++) { + for ($secondIndex = $firstIndex + 1; $secondIndex -lt $findings.Count; $secondIndex++) { + if ((Test-HasProperty $findings[$firstIndex] 'location') -and + (Test-HasProperty $findings[$secondIndex] 'location') -and + (Test-LocationsOverlap $findings[$firstIndex] $findings[$secondIndex]) -and + (Test-SameCorrection $findings[$firstIndex] $findings[$secondIndex])) { + Add-Error 'SUPER_DUPLICATE_FINDINGS' "$ReportPathPrefix.findings[$secondIndex]" ` + "Top-level findings $firstIndex and $secondIndex overlap and prescribe the same correction; they must be merged." + } + } + } + + $usedLocationlessFindings = [Collections.Generic.HashSet[int]]::new() + foreach ($eligibleFinding in @($eligibleFindings | Where-Object { -not (Test-HasProperty $_.Finding 'location') })) { + $matchingIndex = -1 + for ($index = 0; $index -lt $findings.Count; $index++) { + if (-not $usedLocationlessFindings.Contains($index) -and + -not (Test-HasProperty $findings[$index] 'location') -and + (Test-RolledFindingRepresents $findings[$index] $eligibleFinding.Finding $eligibleFinding.ProducerId)) { + $matchingIndex = $index + break + } + } + if ($matchingIndex -lt 0) { + Add-Error 'SUPER_FINDING_MISSING' "$ReportPathPrefix.findings" ` + "No distinct rolled-up finding represents a locationless finding from '$($eligibleFinding.ProducerId)'." + } + else { + $usedLocationlessFindings.Add($matchingIndex) | Out-Null + } + } + for ($index = 0; $index -lt $findings.Count; $index++) { + if ($findings[$index].'from-sub-skill' -cne 'agent' -and + -not (Test-HasProperty $findings[$index] 'location') -and + -not $usedLocationlessFindings.Contains($index)) { + Add-Error 'SUPER_FINDING_MISMATCH' "$ReportPathPrefix.findings[$index]" ` + 'No distinct locationless leaf finding corresponds to this rolled-up finding.' + } + } + + foreach ($eligibleFinding in @($eligibleFindings | Where-Object { Test-HasProperty $_.Finding 'location' })) { + $represented = @($findings | Where-Object { + $_.'from-sub-skill' -cne 'agent' -and + (Test-RolledFindingRepresents $_ $eligibleFinding.Finding $eligibleFinding.ProducerId) + }).Count + if (-not $represented) { + Add-Error 'SUPER_FINDING_MISSING' "$ReportPathPrefix.findings" ` + "No valid rolled-up finding represents a finding from '$($eligibleFinding.ProducerId)' at its source location." + } + } + } + } + + Test-Report $Candidate '$' $SkillKind + if ($PermitRangeStartMismatch) { + return @($errors | Where-Object Code -CNE 'RANGE_START_MISMATCH') + } + return @($errors) +} + +$errors = @(Get-SemanticErrors $report) +$normalized = $false +$removedRanges = [Collections.Generic.List[object]]::new() +if ($errors.Count -and $AllowBoundedNormalization) { + $otherErrors = @($errors | Where-Object Code -CNE 'RANGE_START_MISMATCH') + $rangeErrors = @($errors | Where-Object Code -CEQ 'RANGE_START_MISMATCH') + if (-not $otherErrors.Count -and $rangeErrors.Count) { + $candidate = $report | ConvertTo-Json -Depth 100 | ConvertFrom-Json -Depth 100 + $eligible = $true + foreach ($finding in @($candidate.findings)) { + if (-not (Test-HasProperty $finding 'location') -or + -not (Test-HasProperty $finding.location 'range') -or + $finding.location.range.'start-line' -eq $finding.location.line) { + continue + } + $range = $finding.location.range + if ($range.'start-line' -gt $finding.location.line -or + $finding.location.line -gt $range.'end-line' -or + (Test-HasProperty $finding 'suggested-code')) { + $eligible = $false + break + } + $removedRanges.Add([pscustomobject]@{ + findingId = $finding.id + file = $finding.location.file + line = $finding.location.line + startLine = $range.'start-line' + endLine = $range.'end-line' + }) | Out-Null + $finding.location.PSObject.Properties.Remove('range') + } + if ($eligible -and -not @(Get-SemanticErrors $candidate).Count) { + $report = $candidate + $normalized = $true + $errors = @() + } + } +} + +if ($errors.Count) { + $details = @($errors | ForEach-Object { "$($_.Code) at $($_.Path): $($_.Message)" }) -join '; ' + throw "Findings-report acceptance failed: $details" +} + +return [pscustomobject][ordered]@{ + normalized = $normalized + report = $report + removedRanges = @($removedRanges) +} \ No newline at end of file From f63943dcfdfd1bb776441b2f9f08966f97295a01 Mon Sep 17 00:00:00 2001 From: Michael Dieringer <65093775+MichaelDieringer@users.noreply.github.com> Date: Tue, 29 Sep 2026 17:12:51 +0200 Subject: [PATCH 30/35] 18 more AL/BC patterns: data-modeling, testing, style, security, error-handling, ui, upgrade, web-services, appsource (#157) * Add 18 more community AL/BC patterns across appsource, data-modeling, error-handling, security, style, testing, ui, upgrade, and web-services Second contribution from CURABIS ApS, generalized from patterns observed across real AppSource/PTE development. Cross-checked against the current microsoft/knowledge corpus before opening; several originally-drafted candidates were dropped as duplicates of existing files. * Address Jesper Schulz-Wedde's review on PR #157 - release-must-update-app-version.md: reframe around AppSource's actual strict full-version-ordering requirement; scope branching-policy claims as team convention, not platform rule. - pictures-must-use-media-not-blob.md: MediaSet is a collection of independent media objects, not automatic image variants/thumbnails. - log-writes-must-survive-rollback.{md,good.al}: StartSession's only data channel into the new session is its Record parameter to a TableNo-scoped codeunit; a setter called on a local instance before starting the session populates nothing in the new session. - exposed-objects-must-be-in-a-permission-set.md: correct the three exposure mechanisms (Web Services config, PageType/QueryType=API, ServiceEnabled as a method-only attribute). - pages-must-not-contain-business-logic.md: scope to persisted mutations and cross-entry-point rules; presentation-only calculations and table-owned invariants are not violations. - given-blocks-must-cover-full-precondition-chain.good.al: replace invented LibrarySales calls with the real API (CreateCustomer/CreateSalesOrderForCustomerNo/PostSalesDocument). - test-feature-scenario-tags.{md,good.al}: move [SCENARIO] inside the test procedure body to match the current BCApps corpus; keep [FEATURE] at codeunit level per Microsoft's own documented option. - ui-test-codeunit-naming.md: scope the _UT suffix and adjacent-ID pairing as an explicit team convention, not a BCApps-wide standard. - page-design-must-match-bc-page-type-conventions.md / table-design-must-match-bc-table-type-conventions.md: Card's single-key primary-key claim is a contextual heuristic, not a mandatory constraint (Ship-to Address, Customer/Vendor Bank Account are real composite-key Card pages); a Subsidiary table with its own identity commonly gets List+Card, not Worksheet/Tabular. - api-page-least-privilege-write-access.{md,good.al}: only page-placed fields are ever exposed; set InsertAllowed/DeleteAllowed=false in the good sample so a narrow field set can't still create/delete records. - source-organized-by-feature-not-object-type.md, test-one-when-per-test.md: scope as team/testing-design conventions, not Microsoft platform requirements. - upgrade-tag-logic-must-not-nest-deeply.md: add the Microsoft Learn citation that already backs the two-level nesting limit. - Wire the new articles into the testing/data-modeling/error-handling/ security/ui review skills' candidate-selection signals. Co-Authored-By: Claude Sonnet 5 * Address second round of Jesper Schulz-Wedde's review on PR #157 - log-writes-must-survive-rollback.good.al: fixed invalid trigger OnRun(var Rec: ...) declaration; Rec is implicit when TableNo is set. - exposed-objects-must-be-in-a-permission-set.md: distinguished the three exposure mechanisms (page/query web service or API, codeunit published as a web service, [ServiceEnabled] bound action on a page) and their actual permission targets (page/query "..." = X vs codeunit "..." = X). - code-must-not-change-workdate.md: scoped from an absolute "never" to "not as a side effect of unrelated logic" - verified real WorkDate(x) setter usage in BCApps demo-data generators and test codeunits. - bcpt-scenarios-must-be-app-specific.md: SingleInstance and StartScenario/EndScenario reframed as context-dependent patterns, not mandatory requirements - BCPT Create Customer uses neither. - test-feature-scenario-tags.good.al/.bad.al: replaced the invented LibrarySales.CreateCustomerWithPrice/"Item Price Mgt." calls with a real, verified price-list-line test using Library - Sales/Library - Inventory/ Library - Price Calculation. - page-design-must-match-bc-page-type-conventions.md: scoped the missing UsageCategory anti-pattern to pages intended as searchable entry points. - defensive-vs-offensive-code-must-match-blast-radius.md/.good.al/.bad.al: replaced the VAT registration number "low blast radius" example with a genuinely cosmetic field (customer home page URL). - source-organized-by-feature-not-object-type.md: anti-pattern reframed as inconsistency with a repo's own convention, not the object-type scheme itself. - pictures-must-use-media-not-blob.md: removed leftover "image variants" wording contradicting the already-corrected MediaSet description. Proactively fixed while sweeping all fixtures for invented APIs: - given-blocks-must-cover-full-precondition-chain.bad.al: PostSalesOrder called with wrong arity and referenced an undeclared variable. - ui-test-codeunit-naming.good.al/.bad.al: replaced the same fake "Item Price Mgt."/TestPage "Item Price" with real Library - Sales calls and the real Customer Card TestPage. Worklist completeness: added review-skill cues for the 12 of 18 new rules that had none (al-appsource-review.md, al-data-modeling-review.md, al-error-handling-review.md, al-security-review.md, al-style-review.md x3, al-testing-review.md x2, al-ui-review.md, al-upgrade-review.md, al-web-services-review.md), and fixed test-feature-scenario-tags' cue, which only matched the compliant (tagged) shape instead of the anti-pattern (untagged/generic-named test). Co-Authored-By: Claude Sonnet 5 * Fix ten focused correctness items plus sample links from Jesper's 2026-09-15 re-review Six carried-over threads: - api-page-least-privilege-write-access fixtures: added the mandatory EntityName/EntitySetName properties (AL0485). - pages-must-not-contain-business-logic fixtures: Sales Line has no "Total Amount" field; replaced with the real "Line Amount" (field 103). - test-feature-scenario-tags.good.al and test-one-when-per-test.good.al: CreatePriceHeader leaves a price list in Draft status, which price calculation ignores. Added Validate(Status, Active) + Modify before the sales line that depends on it. Verified Status field/enum against PriceListHeader.Table.al and PriceStatus.Enum.al in the BCApps clone. - exposed-objects-must-be-in-a-permission-set.md: a published codeunit is a SOAP endpoint (SOAP is deprecated), not OData - Page/Query are the OData object types. Corrected and pointed new integrations at API pages/queries instead. - al-error-handling-review.md: the log-writes-must-survive-rollback cue selected on Session.StartSession, which only appears in the compliant fix, never in the anti-pattern - the bad fixture could never be worklisted. Recued on the actual risk shape (log insert around a failed TryFunction/GetLastError* path, then raise/propagate), with StartSession as an explicit compliant discriminator instead. - page-design-must-match-bc-page-type-conventions.md: the enum value is NavigatePage, not Navigate; noted the type list is a selected subset, not an exhaustive PageType catalogue (PromptDialog, ConfigurationDialog, UserControlHost, XmlPort also exist, out of this article's scope). Four new correctness gaps: - release-must-update-app-version.md: "the version is the only identity" was backwards - id is the app's stable identity, version identifies a release/code-state of it. - defensive-vs-offensive-code-must-match-blast-radius.good.al: the "low blast radius" example had no else branch, so a failed Customer.Get() left the field at its prior/default value instead of the explicit chosen fallback the article claims to demonstrate. Added the else. - bcpt-scenarios-must-be-app-specific.good.al: InitTest and both measured StartScenario/EndScenario sections were empty/comment-only, so the "app-specific" fixture measured no actual work. Filled in a real, self-contained header+line creation path. - upgrade-tag-logic-must-not-nest-deeply.good.al: the flattened version dropped both safety conditions the bad fixture had (Discount % = 0, nonblank posting group), silently changing behavior instead of just removing nesting. Extracted the guarded update into a helper with both conditions preserved as early exits. Also converted this PR's remaining plain-backtick "See sample:" sample references (16 articles) to the READ-convention markdown-link form, matching the fix already made on #156/#158. Rebased onto upstream/main (conflicts in al-ui-review.md, al-style-review.md, al-upgrade-review.md against merged upstream PRs - all additive, both sides' worklist cues retained). * Fix four merge-critical issues from Jesper's 2026-09-22 review - pages-must-not-contain-business-logic.good.al/.bad.al: the "good" codeunit still directly assigned real Sales Line."Line Amount" and called Modify(), bypassing the field's normal Validate cascade (discount, VAT, related-amount maintenance) - persisting inconsistent document lines regardless of which object the code lived in. Replaced the real Sales Line example with a self-contained "Sample Order Line" table and switched the codeunit to Validate()/Modify(true), so the fixture demonstrates the page-vs-codeunit separation without teaching unsafe direct field writes to a real BC document table. - bcpt-scenarios-must-be-app-specific.good.al: Customer.FindFirst() assumed a pre-existing customer (fails against an empty environment), and a session-local NextNo counter for the header key collides across concurrent BCPT sessions and repeated runs. Creates its own customer when none exists, and generates keys from CreateGuid() instead of an in-memory counter. - upgrade-tag-logic-must-not-nest-deeply: the rule conflated two different things - nesting one tag's existence check inside another (the real anti-pattern Microsoft's guidance warns against) with having business-data safety conditions inside a single tagged migration's own loop body (which Microsoft's own worked example does, and its own design guidance explicitly requires: "Implement extra safety checks to avoid data corruption, even though you're using upgrade tags"). Rewrote the Description/Best Practice/Anti Pattern to scope the rule to actual tag nesting and migrations blended under one tag, and rewrote both fixtures: good.al now shows two safety conditions correctly nested inside one migration's own loop plus a second, genuinely separate migration as its own flat tagged procedure; bad.al now shows the real anti-pattern, one tag's check nested inside another's guarded body. - table-design-must-match-bc-table-type-conventions: the rule and its worklist cue fired on any new table with a keys block, forcing buffers, queues, logs, mapping tables, and staging tables into the nearest-looking one of nine business-record archetypes. Added an explicit scope note that these nine types aren't an exhaustive table catalogue, and narrowed the al-data-modeling-review.md cue to require positive evidence (a type-specific naming suffix, key shape, or usage) before worklisting, instead of a bare keys/primary-key declaration. * Narrow upgrade-tag nesting cue to match revised article Cue now flags only nested upgrade-tag checks or functionally unrelated migrations under one tag, and explicitly excludes record loops and business-data safety guards belonging to a single migration. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Sonnet 5 Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../release-must-update-app-version.md | 37 +++++++ .../code-must-not-change-workdate.bad.al | 9 ++ .../code-must-not-change-workdate.good.al | 11 +++ .../code-must-not-change-workdate.md | 58 +++++++++++ .../pictures-must-use-media-not-blob.bad.al | 11 +++ .../pictures-must-use-media-not-blob.good.al | 11 +++ .../pictures-must-use-media-not-blob.md | 49 +++++++++ ...ust-match-bc-table-type-conventions.bad.al | 17 ++++ ...st-match-bc-table-type-conventions.good.al | 16 +++ ...gn-must-match-bc-table-type-conventions.md | 99 +++++++++++++++++++ ...ensive-code-must-match-blast-radius.bad.al | 11 +++ ...nsive-code-must-match-blast-radius.good.al | 14 +++ ...-offensive-code-must-match-blast-radius.md | 26 +++++ .../log-writes-must-survive-rollback.bad.al | 24 +++++ .../log-writes-must-survive-rollback.good.al | 45 +++++++++ .../log-writes-must-survive-rollback.md | 26 +++++ ...objects-must-be-in-a-permission-set.bad.al | 12 +++ ...bjects-must-be-in-a-permission-set.good.al | 10 ++ ...sed-objects-must-be-in-a-permission-set.md | 32 ++++++ ...not-restate-what-code-already-shows.bad.al | 18 ++++ ...ot-restate-what-code-already-shows.good.al | 20 ++++ ...ust-not-restate-what-code-already-shows.md | 30 ++++++ ...ges-must-not-contain-business-logic.bad.al | 49 +++++++++ ...es-must-not-contain-business-logic.good.al | 60 +++++++++++ .../pages-must-not-contain-business-logic.md | 31 ++++++ ...ce-organized-by-feature-not-object-type.md | 48 +++++++++ ...bcpt-scenarios-must-be-app-specific.bad.al | 29 ++++++ ...cpt-scenarios-must-be-app-specific.good.al | 73 ++++++++++++++ .../bcpt-scenarios-must-be-app-specific.md | 26 +++++ ...-must-cover-full-precondition-chain.bad.al | 15 +++ ...must-cover-full-precondition-chain.good.al | 20 ++++ ...ocks-must-cover-full-precondition-chain.md | 26 +++++ .../testing/test-feature-scenario-tags.bad.al | 33 +++++++ .../test-feature-scenario-tags.good.al | 40 ++++++++ .../testing/test-feature-scenario-tags.md | 26 +++++ .../testing/test-one-when-per-test.bad.al | 32 ++++++ .../testing/test-one-when-per-test.good.al | 56 +++++++++++ .../testing/test-one-when-per-test.md | 34 +++++++ .../testing/ui-test-codeunit-naming.bad.al | 27 +++++ .../testing/ui-test-codeunit-naming.good.al | 42 ++++++++ .../testing/ui-test-codeunit-naming.md | 26 +++++ ...must-match-bc-page-type-conventions.bad.al | 21 ++++ ...ust-match-bc-page-type-conventions.good.al | 20 ++++ ...ign-must-match-bc-page-type-conventions.md | 90 +++++++++++++++++ ...rade-tag-logic-must-not-nest-deeply.bad.al | 32 ++++++ ...ade-tag-logic-must-not-nest-deeply.good.al | 40 ++++++++ .../upgrade-tag-logic-must-not-nest-deeply.md | 34 +++++++ ...i-page-least-privilege-write-access.bad.al | 25 +++++ ...-page-least-privilege-write-access.good.al | 25 +++++ .../api-page-least-privilege-write-access.md | 26 +++++ .../skills/review/al-appsource-review.md | 1 + .../skills/review/al-data-modeling-review.md | 3 + .../skills/review/al-error-handling-review.md | 2 + microsoft/skills/review/al-security-review.md | 3 +- microsoft/skills/review/al-style-review.md | 3 + microsoft/skills/review/al-testing-review.md | 5 + microsoft/skills/review/al-ui-review.md | 3 +- microsoft/skills/review/al-upgrade-review.md | 1 + .../skills/review/al-web-services-review.md | 1 + 59 files changed, 1612 insertions(+), 2 deletions(-) create mode 100644 microsoft/knowledge/appsource/release-must-update-app-version.md create mode 100644 microsoft/knowledge/data-modeling/code-must-not-change-workdate.bad.al create mode 100644 microsoft/knowledge/data-modeling/code-must-not-change-workdate.good.al create mode 100644 microsoft/knowledge/data-modeling/code-must-not-change-workdate.md create mode 100644 microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.bad.al create mode 100644 microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.good.al create mode 100644 microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.md create mode 100644 microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.bad.al create mode 100644 microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.good.al create mode 100644 microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.md create mode 100644 microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.bad.al create mode 100644 microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.good.al create mode 100644 microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.md create mode 100644 microsoft/knowledge/error-handling/log-writes-must-survive-rollback.bad.al create mode 100644 microsoft/knowledge/error-handling/log-writes-must-survive-rollback.good.al create mode 100644 microsoft/knowledge/error-handling/log-writes-must-survive-rollback.md create mode 100644 microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.bad.al create mode 100644 microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.good.al create mode 100644 microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.md create mode 100644 microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.bad.al create mode 100644 microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.good.al create mode 100644 microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.md create mode 100644 microsoft/knowledge/style/pages-must-not-contain-business-logic.bad.al create mode 100644 microsoft/knowledge/style/pages-must-not-contain-business-logic.good.al create mode 100644 microsoft/knowledge/style/pages-must-not-contain-business-logic.md create mode 100644 microsoft/knowledge/style/source-organized-by-feature-not-object-type.md create mode 100644 microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.bad.al create mode 100644 microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.good.al create mode 100644 microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.md create mode 100644 microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.bad.al create mode 100644 microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.good.al create mode 100644 microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.md create mode 100644 microsoft/knowledge/testing/test-feature-scenario-tags.bad.al create mode 100644 microsoft/knowledge/testing/test-feature-scenario-tags.good.al create mode 100644 microsoft/knowledge/testing/test-feature-scenario-tags.md create mode 100644 microsoft/knowledge/testing/test-one-when-per-test.bad.al create mode 100644 microsoft/knowledge/testing/test-one-when-per-test.good.al create mode 100644 microsoft/knowledge/testing/test-one-when-per-test.md create mode 100644 microsoft/knowledge/testing/ui-test-codeunit-naming.bad.al create mode 100644 microsoft/knowledge/testing/ui-test-codeunit-naming.good.al create mode 100644 microsoft/knowledge/testing/ui-test-codeunit-naming.md create mode 100644 microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.bad.al create mode 100644 microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.good.al create mode 100644 microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.md create mode 100644 microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.bad.al create mode 100644 microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.good.al create mode 100644 microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.md create mode 100644 microsoft/knowledge/web-services/api-page-least-privilege-write-access.bad.al create mode 100644 microsoft/knowledge/web-services/api-page-least-privilege-write-access.good.al create mode 100644 microsoft/knowledge/web-services/api-page-least-privilege-write-access.md diff --git a/microsoft/knowledge/appsource/release-must-update-app-version.md b/microsoft/knowledge/appsource/release-must-update-app-version.md new file mode 100644 index 0000000..fb8f483 --- /dev/null +++ b/microsoft/knowledge/appsource/release-must-update-app-version.md @@ -0,0 +1,37 @@ +--- +bc-version: [all] +domain: appsource +keywords: [version, release, app-json, semver, al-go, appsource] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Update the app version at every release + +## Description + +At every release — a branch merged to `main`, a tagged release build, or an AppSource submission — the app's version is consciously updated, not left to the pipeline alone. + +| Version part | Owner | When | +|---|---|---| +| Major | Developer decision | Breaking change (schema, API, removed objects) | +| Minor | Developer decision | Every release with new functionality | +| Build / Revision | AL-Go pipeline | Automatic — never hand-edited | + +The app's stable identity is its `id` in `app.json`; the version identifies which release — which code state — of that app is deployed. Two customer environments running "the same" version with different code is an undiagnosable support case. AppSource's actual requirement is strict full-version ordering — the complete version must be greater than the previously submitted version — which an AL-Go-generated build/revision increment can satisfy on its own; AppSource does not require major.minor itself to change. Treating major.minor as a deliberate, human-decided compatibility signal is still valuable practice — it is a statement about what changed that no pipeline can make on its own — just not a platform-enforced requirement. + +## Best Practice + + Before the release merge: + app.json: "version": "1.3.0.0" (new functionality -> minor bump, by team convention) + AL-Go settings: "repoVersion": "1.3" (where used) + Then: feature branch -> main via PR, tag, release. + +"Feature branches never touch the version" and "every merge to main is a release" are workflow choices your team can adopt for compatibility clarity — not something AppSource itself requires. + +## Anti Pattern + + Branch merged to main and released. + app.json still says "version": "1.2.0.0" -- same as the previous release. + Two different code states now share one version identity. diff --git a/microsoft/knowledge/data-modeling/code-must-not-change-workdate.bad.al b/microsoft/knowledge/data-modeling/code-must-not-change-workdate.bad.al new file mode 100644 index 0000000..0c265e9 --- /dev/null +++ b/microsoft/knowledge/data-modeling/code-must-not-change-workdate.bad.al @@ -0,0 +1,9 @@ +codeunit 50101 "Batch Job Runner" +{ + procedure AdvanceToNextBusinessDay() + begin + // Anti-pattern: repurposes the user's session WorkDate as a + // scratch variable for unrelated business logic. + WorkDate(CalcDate('<1D>', WorkDate())); + end; +} diff --git a/microsoft/knowledge/data-modeling/code-must-not-change-workdate.good.al b/microsoft/knowledge/data-modeling/code-must-not-change-workdate.good.al new file mode 100644 index 0000000..f1dcf5e --- /dev/null +++ b/microsoft/knowledge/data-modeling/code-must-not-change-workdate.good.al @@ -0,0 +1,11 @@ +codeunit 50100 "Posting Date Helper" +{ + procedure GetDefaultPostingDate(): Date + var + PostingDate: Date; + begin + // Read the work date to default a value; never write to it. + PostingDate := WorkDate(); + exit(PostingDate); + end; +} diff --git a/microsoft/knowledge/data-modeling/code-must-not-change-workdate.md b/microsoft/knowledge/data-modeling/code-must-not-change-workdate.md new file mode 100644 index 0000000..3e2ea0e --- /dev/null +++ b/microsoft/knowledge/data-modeling/code-must-not-change-workdate.md @@ -0,0 +1,58 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [workdate, session-setting, user-control, side-effect] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Application code must not change the WorkDate + +## Description + +The work date is a per-user session setting the user controls from the +client (the date shown in the top-right corner, used to default posting +dates and date filters). Business logic unrelated to that setting must not +call `WorkDate(NewDate)` as a side effect of doing something else — that +silently changes what the user sees and defaults to for the rest of their +session, a surprising, hard-to-trace behavior change the user never asked +for and has no visibility into. This is not a blanket ban on the setter +itself: BCApps' own demo-data generators legitimately save the current +work date, set a specific one to backdate the data they create, and +restore it afterward (see `CreateDemoEDocsBE.Codeunit.al`'s +`WorkDate(SampleInvoiceDate)` / `WorkDate(SavedWorkDate)` pair), and test +codeunits routinely set `WorkDate` deliberately to control the date context +a test runs under (hundreds of calls across BCApps' test suite, for +example `SustainabilityPostingTest.Codeunit.al`). Both are the code's +*actual purpose*, not a side effect of something unrelated. + +This is a call-direction distinction for the read side: reading the +current work date via `WorkDate` (or `WorkDate()` with no argument) is +always fine. + +## Best Practice + +Read the work date to default a value. Only write to it when changing it +*is* the operation being performed — implementing the user's own +work-date/settings action, or a test or demo-data routine that deliberately +establishes a date context (saving and restoring the prior value if the +routine must leave the session as it found it). Business logic that exists +to do something else must never write `WorkDate` as an incidental side +effect; if a calculation needs a specific date, pass or compute that date +as a local variable instead. + +See sample: [`code-must-not-change-workdate.good.al`](code-must-not-change-workdate.good.al). + +## Anti Pattern + +Setting the work date from within a codeunit, report, or page action whose +purpose is unrelated to the user's date preference — for example, a +posting or calculation routine that calls `WorkDate(SomeDate)` to make its +own logic simpler. This changes session state the user owns for the +duration of a call that was never about the work date, and never restores +it. This is a different case from a test or demo-data routine explicitly +declaring a date context: the anti-pattern is unrelated logic silently +mutating state it does not own, not the setter form itself. + +See sample: [`code-must-not-change-workdate.bad.al`](code-must-not-change-workdate.bad.al). diff --git a/microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.bad.al b/microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.bad.al new file mode 100644 index 0000000..e20775a --- /dev/null +++ b/microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.bad.al @@ -0,0 +1,11 @@ +table 50111 "Sample Item Card" +{ + fields + { + field(1; "No."; Code[20]) { } + field(50; Picture; BLOB) + { + Caption = 'Picture'; + } + } +} diff --git a/microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.good.al b/microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.good.al new file mode 100644 index 0000000..4fec633 --- /dev/null +++ b/microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.good.al @@ -0,0 +1,11 @@ +table 50110 "Sample Item Card" +{ + fields + { + field(1; "No."; Code[20]) { } + field(50; Picture; Media) + { + Caption = 'Picture'; + } + } +} diff --git a/microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.md b/microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.md new file mode 100644 index 0000000..1767a0d --- /dev/null +++ b/microsoft/knowledge/data-modeling/pictures-must-use-media-not-blob.md @@ -0,0 +1,49 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [blob, media, mediaset, picture-field, image-field, table-design] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Pictures must be stored in a Media/MediaSet field, not BLOB + +## Description + +`BLOB` is still a valid AL field type for arbitrary binary data, but it is +not the right choice for storing pictures or images. The current +recommendation is the `Media` field type for a single image, or +`MediaSet` when a record needs several independent images (e.g. multiple +product photos) — `MediaSet` is a collection of separately-imported media +objects, each with its own identity; it does not generate resized variants +or thumbnails on its own, and displaying more than one item still requires +custom page handling. Media/MediaSet integrate with the platform's +picture control and media repository, which a plain `BLOB` field does not +— but any derived preview or thumbnail image still has to be generated +explicitly and stored in its own field, regardless of which type holds the +source image. + +`BLOB` remains the correct choice for genuinely arbitrary binary payloads +that are not images and don't benefit from the media pipeline (e.g. a raw +file attachment blob unrelated to picture rendering). + +## Best Practice + +Use `Media` for a single image, or `MediaSet` for multiple independent +images, for any field that holds a picture. + +See sample: [`pictures-must-use-media-not-blob.good.al`](pictures-must-use-media-not-blob.good.al). + +## Anti Pattern + +A `BLOB` field named "Picture" compiles and stores the image bytes, but +it misses the picture control integration and media repository that a +`Media`/`MediaSet` field provides for free — the anti pattern is choosing +`BLOB` for image storage out of habit rather than recognizing that the +field is holding a picture, not generic binary data. A related anti +pattern: assuming `MediaSet` gives automatic image variants or thumbnails +because it sounds like a collection with derived versions — it is only a +collection of independently-imported media objects. + +See sample: [`pictures-must-use-media-not-blob.bad.al`](pictures-must-use-media-not-blob.bad.al). diff --git a/microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.bad.al b/microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.bad.al new file mode 100644 index 0000000..c241640 --- /dev/null +++ b/microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.bad.al @@ -0,0 +1,17 @@ +table 50121 "Sample Ledger Entry" +{ + fields + { + // Anti-pattern: a Ledger table's key must never be user-editable. + field(1; "Entry No."; Integer) { } + field(2; "Posting Date"; Date) { } + field(3; Amount; Decimal) { } + } + keys + { + key(PK; "Entry No.") { Clustered = true; } + } + // No AutoIncrement, no guard against manual insert/delete — a user or + // integration can renumber or remove entries, breaking the Ledger + // type's audit-trail guarantee. +} diff --git a/microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.good.al b/microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.good.al new file mode 100644 index 0000000..825ca45 --- /dev/null +++ b/microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.good.al @@ -0,0 +1,16 @@ +table 50120 "Sample Ledger Entry" +{ + fields + { + // Ledger primary key: Integer "Entry No.", set only by posting. + field(1; "Entry No."; Integer) { AutoIncrement = true; } + field(2; "Posting Date"; Date) { } + field(3; Amount; Decimal) { } + } + keys + { + key(PK; "Entry No.") { Clustered = true; } + } + // No user-facing Insert/Delete/Modify path is exposed; rows are + // created exclusively by the posting routine. +} diff --git a/microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.md b/microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.md new file mode 100644 index 0000000..ce82f9b --- /dev/null +++ b/microsoft/knowledge/data-modeling/table-design-must-match-bc-table-type-conventions.md @@ -0,0 +1,99 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [tables, table-design, naming-conventions, primary-key, master-table, ledger-table, journal-table, register-table, document-table, setup-table, subsidiary-table, supplemental-table] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Tables must match one of Business Central's nine table-type conventions + +## Description + +Business Central's Base Application follows nine recurring table types — +Master, Supplemental, Subsidiary, Ledger, Register, Journal, Document, +Document History, and Setup. Each type fixes a naming pattern, a +primary-key shape, and a set of associated pages. A new or extended table +whose design doesn't match the conventions of its own type is either +misclassified or built inconsistently with the rest of the application, +and should be flagged in review even if it compiles. Before assigning a +primary key or naming a new table, first identify which of the nine types +it is — that answer fixes almost every other design decision. + +## Best Practice + +Match the table's design to its type: + +1. **Master** (Customer, Item) — one record is the subject; primary key + `Code[20]` named `No.`; description field in `DataCaptionFields`; Card + + List (+ Statistics) pages. +2. **Supplemental** (Currency, Language) — used across functional areas; + primary key `Code[10]` named `Code`; one List page, plural name, set as + `LookupPageID`. +3. **Subsidiary** (Item Vendor) — subsidiary to a Master/Supplemental + table; primary key is the parent key field(s), optionally + `Line No.`; + page shape depends on whether the table carries its own identity: a + pure parent-join table (Item Vendor) typically gets a plain List page + filtered by the calling page, while a subsidiary table that supplements + a master record with its own identity — parent key + own code, e.g. + Ship-to Address, Customer/Vendor Bank Account — commonly gets a + List+Card pair instead, for direct editing of that record. +4. **Ledger** (Cust. Ledger Entry) — transactional record of a functional + area; primary key `Integer` `Entry No.`, always auto-generated by + posting, never user-editable, no free add/delete; List page as + `LookupPageID`/`DrillDownPageID`. +5. **Register** (G/L Register) — table of contents for its Ledger, one row + per posting run; primary key `Integer` `No.`, auto-generated; carries + `From Entry No.`/`To Entry No.`; List page with a link to the Ledger. +6. **Journal** (Resource Journal Line) — where users enter data before + posting to a Ledger; primary key Template + Batch + `Integer` `Line No.`; + Worksheet page with `AutoSplitKey`, a Posting action, and a link to the + Ledger. +7. **Document** (Sales Header/Line) — posts to Ledgers via Journals, not + directly; Header primary key `Code[20]` `No.` (or + `Option Document + Type`); Line primary key = Header key renamed ` No.` + + `Integer Line No.`; Document/Card page with a Posting action and a lines + subpage. +8. **Document History** (Posted Sales Invoice Header/Line) — posted copy of + a Document table, created during posting; mirrors the source table's + fields; never user-editable; same page shape but the Line-equivalent is + a List page, not a Worksheet. +9. **Setup** (General Ledger Setup) — exactly one record for a functional + area; primary key `Code[10]` named `Primary Key`, always blank; one page + with the key field hidden, whose `OnOpenPage` creates the singleton the + first time it's opened (`Reset()` → `Get()` → if not found, `Init()` → + `Insert()`) rather than assuming the record pre-exists. + +A table named "Setup" that holds more than one record follows Subsidiary +rules instead — the name alone is not proof of type. When a table's +identity can't be resolved from its definition alone (e.g. a "Setup"-named +table with a real business-field key and no page), say so explicitly +rather than forcing a classification; settling it requires checking actual +row cardinality or call sites, not just the object definition. + +These nine types cover Business Central's *business-record* tables — they +are not an exhaustive catalogue of every legitimate table shape. A +temporary/buffer table, a work queue, a log or telemetry table, a +cross-reference/mapping table with no business meaning of its own, or a +staging/working table used only inside one process is not required to fit +any of the nine, and forcing one into the nearest-looking type (usually +Ledger, because it has an `Integer` key, or Subsidiary, because it has a +composite key) produces a harmful redesign recommendation for a table that +was never meant to carry that type's guarantees. Apply this rule only when +the table's name, fields, or usage genuinely establish it as one of the +nine business-record types; when nothing points that way, this rule simply +does not apply — that is not the same as an unresolved classification. + +See sample: [`table-design-must-match-bc-table-type-conventions.good.al`](table-design-must-match-bc-table-type-conventions.good.al). + +## Anti Pattern + +A table that mixes conventions from two types — for example, a "Ledger" +table with a user-editable primary key that lets users freely insert or +delete rows — is not "flexible", it is either misclassified or has skipped +a design step. A Ledger table's `Entry No.` must come only from the +posting routine; exposing it as an editable field breaks the type's core +guarantee that entries are an immutable, sequential audit trail. + +See sample: [`table-design-must-match-bc-table-type-conventions.bad.al`](table-design-must-match-bc-table-type-conventions.bad.al). diff --git a/microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.bad.al b/microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.bad.al new file mode 100644 index 0000000..6f2835f --- /dev/null +++ b/microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.bad.al @@ -0,0 +1,11 @@ +// Both fields guarded the same way, out of habit rather than analysis. +if Customer.Get(SalesHeader."Sell-to Customer No.") then + CustomerHomePage := Customer."Home Page"; // low blast radius - fine + +// but the same pattern, unexamined, was also applied here: +if SalesHeader.Get(SalesHeader."Document Type"::Order, DocumentNo) then + VATBusPostingGroup := SalesHeader."VAT Bus. Posting Group" +else + VATBusPostingGroup := ''; + // High blast radius: silently wrong VAT posting group reaches posting + // with no error, no TestField, and no reviewer in the loop. diff --git a/microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.good.al b/microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.good.al new file mode 100644 index 0000000..35f88ee --- /dev/null +++ b/microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.good.al @@ -0,0 +1,14 @@ +// Low blast radius: guard, with an explicit chosen fallback. +if Customer.Get(SalesHeader."Sell-to Customer No.") then + CustomerHomePage := Customer."Home Page" +else + CustomerHomePage := ''; +// Blank is an acceptable, deliberately-considered default here - the field +// is purely a display convenience and a reviewer sees it before the document ships. +// It is assigned explicitly, though, not left to whatever the variable +// happened to hold before this lookup ran. + +// High blast radius: let it fail loud, because this feeds posted VAT. +SalesHeader.Get(SalesHeader."Document Type"::Order, DocumentNo); +SalesHeader.TestField("VAT Bus. Posting Group"); +VATBusPostingGroup := SalesHeader."VAT Bus. Posting Group"; diff --git a/microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.md b/microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.md new file mode 100644 index 0000000..91a8aff --- /dev/null +++ b/microsoft/knowledge/error-handling/defensive-vs-offensive-code-must-match-blast-radius.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: error-handling +keywords: [defensive-programming, offensive-programming, fail-fast, blast-radius, guarded-lookup] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Match defensive vs. offensive error handling to the blast radius of being wrong + +## Description + +Whether code should guard gracefully (defensive) or fail loudly (offensive/fail-fast) is not a matter of habit or a blanket house style — it depends on what happens downstream if the guarded condition is silently defaulted or skipped. Treating every missing value the same way, defensively or offensively, is itself the anti-pattern: uniform defensiveness hides the failures that matter most, while uniform fail-fast turns ordinary, expected absence into unnecessary crashes. Two fields can look structurally identical — both read from a related record, both potentially missing — and still deserve opposite treatment depending on what they feed. + +## Best Practice + +Trace what a silently-defaulted or skipped value actually reaches before deciding how to guard it. If it reaches a posted ledger amount, a tax/VAT calculation, a quantity or price actually used in a transaction, or a legally/compliance-facing output, code offensively: let the lookup fail loud (`TestField`, an unguarded `Get()` expected to always succeed, or an explicit `Error`) so a human sees the problem before anything posts. If it is cosmetic, informational, or easily corrected after the fact (a display field, an optional UI enhancement, a report not yet run), code defensively — but the fallback must be an explicit, deliberately-chosen, named business value, never a blank or zero that is merely the datatype default. When genuinely unsure which category a field falls into, that is a question to resolve explicitly with whoever owns the requirement, not a coin flip. + +See sample: [`defensive-vs-offensive-code-must-match-blast-radius.good.al`](defensive-vs-offensive-code-must-match-blast-radius.good.al). + +## Anti Pattern + +Guarding two fields the same way purely out of habit, without analyzing what each one feeds. A low-blast-radius field, such as a customer's home page URL shown only for convenience on a printed document, and a high-blast-radius field, such as the VAT posting group that determines VAT actually applied to a posted transaction, are both wrapped in the same `if Header.Get(...) then ... else` pattern with a blank/zero fallback — leaving the posting-critical field free to post with a silently wrong value. A VAT registration number is not a safe stand-in for the low-risk side of this example: it is legally relevant, often validated, and can feed external VAT services or mandated document output, so it belongs on the offensive/fail-fast side alongside the posting group, not next to it as the "safe" contrast. + +See sample: [`defensive-vs-offensive-code-must-match-blast-radius.bad.al`](defensive-vs-offensive-code-must-match-blast-radius.bad.al). diff --git a/microsoft/knowledge/error-handling/log-writes-must-survive-rollback.bad.al b/microsoft/knowledge/error-handling/log-writes-must-survive-rollback.bad.al new file mode 100644 index 0000000..6cc2876 --- /dev/null +++ b/microsoft/knowledge/error-handling/log-writes-must-survive-rollback.bad.al @@ -0,0 +1,24 @@ +codeunit 50101 "Sample Web Service Caller" +{ + procedure CallExternalService() + var + ErrorLogEntry: Record "Sample Error Log"; + begin + // BUG: the log write happens inside the same transaction as the + // risky call, using the same Record instance as the caller. + if not TryCallService() then begin + ErrorLogEntry.Init(); + ErrorLogEntry."Error Message" := CopyStr(GetLastErrorText(), 1, 250); + ErrorLogEntry.Insert(); + Error(GetLastErrorText()); + // Error() above rolls back this transaction - including the + // Insert() just made. The failure is never actually logged. + end; + end; + + [TryFunction] + local procedure TryCallService() + begin + // ... external call that may fail ... + end; +} diff --git a/microsoft/knowledge/error-handling/log-writes-must-survive-rollback.good.al b/microsoft/knowledge/error-handling/log-writes-must-survive-rollback.good.al new file mode 100644 index 0000000..c0f7d65 --- /dev/null +++ b/microsoft/knowledge/error-handling/log-writes-must-survive-rollback.good.al @@ -0,0 +1,45 @@ +table 50100 "Sample Error Log Buffer" +{ + TableType = Temporary; + fields + { + field(1; "Call Duration (ms)"; Integer) { } + field(2; "Error Message"; Text[250]) { } + } +} + +codeunit 50100 "Sample Error Log Writer" +{ + // TableNo makes OnRun receive the Record that Session.StartSession + // passes to the new session. This is the only data channel into that + // session — there is no shared memory with the caller's instance. + TableNo = "Sample Error Log Buffer"; + + trigger OnRun() + var + ErrorLogEntry: Record "Sample Error Log"; + begin + ErrorLogEntry.Init(); + ErrorLogEntry."Call Duration (ms)" := Rec."Call Duration (ms)"; + ErrorLogEntry."Error Message" := + CopyStr(Rec."Error Message", 1, MaxStrLen(ErrorLogEntry."Error Message")); + ErrorLogEntry.Insert(true); + Commit(); + end; +} + +// Caller side: populate the buffer record, then hand it to StartSession. +// The insert-and-commit above happens inside the started session, so it +// survives even if the caller's own transaction rolls back afterward. +codeunit 50101 "Sample Error Log Caller Excerpt" +{ + procedure LogFailure(Duration: Integer; ErrorText: Text) + var + LogBuffer: Record "Sample Error Log Buffer" temporary; + SessionId: Integer; + begin + LogBuffer."Call Duration (ms)" := Duration; + LogBuffer."Error Message" := CopyStr(ErrorText, 1, MaxStrLen(LogBuffer."Error Message")); + Session.StartSession(SessionId, Codeunit::"Sample Error Log Writer", CompanyName, LogBuffer); + end; +} diff --git a/microsoft/knowledge/error-handling/log-writes-must-survive-rollback.md b/microsoft/knowledge/error-handling/log-writes-must-survive-rollback.md new file mode 100644 index 0000000..eae1700 --- /dev/null +++ b/microsoft/knowledge/error-handling/log-writes-must-survive-rollback.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: error-handling +keywords: [logging, rollback, session, transaction, isolated-session, telemetry] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Log writes that must capture failures must survive transaction rollback + +## Description + +Inserting a log record inside the same transaction as the operation it logs looks correct until the operation errors: the transaction rolls back and takes the log entry with it. The result is a log that faithfully records every success and silently loses exactly the failures it exists to capture. This is a common blind spot in error/duration logging around web-service calls, background jobs, and other operations expected to fail sometimes. + +## Best Practice + +Write any log whose purpose includes capturing failures from a transaction that is independent of the operation being logged: start an isolated session (`Session.StartSession` on a `TableNo`-scoped codeunit that only inserts the log record and commits) so the entry persists regardless of what happens to the caller's transaction. `StartSession`'s only channel for getting data into that new session is its optional `Record` parameter, delivered to the target codeunit's `OnRun` trigger — a separate session gets a fresh instantiation of the codeunit, so calling a setter procedure on a local object variable before starting the session does not populate anything in the new session's instance. Capture duration and other telemetry values in the caller, place them into the `Record` passed to `StartSession`, and do the insert-and-commit entirely inside that session's own `OnRun`. Logs that only record successful, committed work can safely stay in the main transaction; this pattern targets error and diagnostic logs specifically. + +See sample: [`log-writes-must-survive-rollback.good.al`](log-writes-must-survive-rollback.good.al). + +## Anti Pattern + +Inserting the error-log record in the same transaction as the risky operation, so a rollback deletes the very entry meant to explain the failure. Adding a stray `Commit` before the risky call is not a fix either — it breaks the caller's atomicity and can violate posting-routine rules. Swallowing the error to keep the log alive (running a codeunit without checking or re-raising its result) is equally wrong: the log must observe the failure, not suppress it. + +See sample: [`log-writes-must-survive-rollback.bad.al`](log-writes-must-survive-rollback.bad.al). diff --git a/microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.bad.al b/microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.bad.al new file mode 100644 index 0000000..1a93861 --- /dev/null +++ b/microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.bad.al @@ -0,0 +1,12 @@ +permissionset 50100 "Sample - Integration" +{ + Access = Public; + Assignable = false; + Caption = 'Sample Integration'; + Permissions = + tabledata "Sample Order" = RIMD; + // BUG: "Sample Order API" (PageType = API) and "Sample Order Query" + // (a published API query) have no "= X" entry anywhere in this app. + // Both endpoints are unreachable even though the table looks fully + // granted - nobody decided who may call them. +} diff --git a/microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.good.al b/microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.good.al new file mode 100644 index 0000000..de8d2ab --- /dev/null +++ b/microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.good.al @@ -0,0 +1,10 @@ +permissionset 50100 "Sample - Integration" +{ + Access = Public; + Assignable = false; + Caption = 'Sample Integration'; + Permissions = + tabledata "Sample Order" = RIMD, + page "Sample Order API" = X, // exposed API page: execute granted + query "Sample Order Query" = X; // exposed API query: execute granted +} diff --git a/microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.md b/microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.md new file mode 100644 index 0000000..fd933d7 --- /dev/null +++ b/microsoft/knowledge/security/exposed-objects-must-be-in-a-permission-set.md @@ -0,0 +1,32 @@ +--- +bc-version: [all] +domain: security +keywords: [permission-set, api-page, web-service, exposure, access-control] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Every exposed object must belong to a permission set + +## Description + +An object that is reachable from outside the app's own UI is only usable if it is also granted execute access through a permission set. Three distinct mechanisms make an object reachable this way, each with its own permission target: + +- A page or query published through the **Web Services** configuration page, or a custom REST endpoint declared with `PageType = API` / `QueryType = API` — both need a `page "..." = X` / `query "..." = X` entry for that object. +- A codeunit published through **Web Services** exposes *every* public procedure on it as a SOAP operation automatically — there is no per-method attribute to add. SOAP web service support is deprecated and scheduled for removal; prefer publishing an API page/query for a new integration rather than a new codeunit web service. The permission target for an existing published codeunit is the codeunit itself: `codeunit "..." = X`. +- `[ServiceEnabled]` is a method-level attribute used on a *page* procedure to expose it as an OData v4 bound action (for example a `Post` action on an invoice page) — it does not apply to pages, queries, or codeunits as an object-level property, and it does not create its own permission target. The action is still a call into that page object, so the page's own `page "..." = X` entry is what governs it. + +When such an object is left out of every permission set, it becomes both unusable (no caller, human or service, can reach it) and invisible in review: nobody deliberately decided who may call it. Exposure without a matching grant is not a safe default; it is an endpoint nobody is governing. + +## Best Practice + +Give every exposed object an explicit execute entry in a permission set shipped by the app: `page "..." = X` / `query "..." = X` for a published or API page/query (including one that exposes a `[ServiceEnabled]` bound action), and `codeunit "..." = X` for a codeunit published as a web service. Route sensitive endpoints into a dedicated, non-default admin permission set so reaching them requires a deliberate grant rather than being included by default. If an object should never be reachable from outside the app, remove the exposure itself (drop `PageType = API` / the Web Services registration) rather than leaving an orphaned endpoint with no permission-set membership. + +See sample: [`exposed-objects-must-be-in-a-permission-set.good.al`](exposed-objects-must-be-in-a-permission-set.good.al). + +## Anti Pattern + +Granting access to the underlying table data while forgetting to grant execute access to the exposed page or query itself. The table looks fully covered by a permission set, but the API/service layer in front of it has no `= X` entry anywhere, so the endpoint silently fails for every caller even though the data permissions look complete. + +See sample: [`exposed-objects-must-be-in-a-permission-set.bad.al`](exposed-objects-must-be-in-a-permission-set.bad.al). diff --git a/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.bad.al b/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.bad.al new file mode 100644 index 0000000..869e398 --- /dev/null +++ b/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.bad.al @@ -0,0 +1,18 @@ +codeunit 50101 "Credit Memo Routing" +{ + procedure PostSalesLine(var SalesHeader: Record "Sales Header"; var SalesLine: Record "Sales Line"; CustomerNo: Code[20]; Amount: Decimal) + begin + // Set the customer number + SalesHeader.Validate("Sell-to Customer No.", CustomerNo); + // Insert the line + SalesLine.Insert(true); + // Check if the amount is positive + if Amount > 0 then + // Post the entry + PostEntry(Amount); + end; + + local procedure PostEntry(Amount: Decimal) + begin + end; +} diff --git a/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.good.al b/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.good.al new file mode 100644 index 0000000..6bd39b1 --- /dev/null +++ b/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.good.al @@ -0,0 +1,20 @@ +codeunit 50101 "Credit Memo Routing" +{ + procedure PostSalesLine(var SalesHeader: Record "Sales Header"; var SalesLine: Record "Sales Line"; CustomerNo: Code[20]; Amount: Decimal) + begin + SalesHeader.Validate("Sell-to Customer No.", CustomerNo); + SalesLine.Insert(true); + + // Negative amounts arrive from credit memos routed through this + // codeunit; PostEntry() rejects them, so they're filtered here. + if Amount < 0 then + exit; + + if Amount > 0 then + PostEntry(Amount); + end; + + local procedure PostEntry(Amount: Decimal) + begin + end; +} diff --git a/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.md b/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.md new file mode 100644 index 0000000..09a2ea4 --- /dev/null +++ b/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.md @@ -0,0 +1,30 @@ +--- +bc-version: [all] +domain: style +keywords: [comments, verbosity, self-documenting, restate, tutorial-style] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Comments must not restate what the code already shows + +## Description + +A comment above nearly every statement that just narrates what the statement already says (`// Validate the customer number` above `SalesHeader.Validate("Sell-to Customer No.", CustomerNo)`) adds noise without adding information. Production AL — the Base Application, mature partner codebases — is comment-sparse by comparison: identifiers do the explaining, and a comment appears only when the code alone can't carry the reason. + +A comment earns its place only when it captures something the code cannot: a non-obvious business rule, a workaround for a specific platform limitation, or a constraint that would surprise the next reader. If removing the comment would leave the reader no worse off, the comment should not have been written. + +This does not override required structural documentation — feature/scenario test tags and XML-doc summaries on public library procedures remain required where they apply; those are structural markers, not narrative comments. + +## Best Practice + +Let the code speak for itself; reserve comments for the reason a reader could not otherwise infer. + +See sample: [`al-comments-must-not-restate-what-code-already-shows.good.al`](al-comments-must-not-restate-what-code-already-shows.good.al). + +## Anti Pattern + +A comment line before every statement, repeating in English what the statement's own identifiers already say. + +See sample: [`al-comments-must-not-restate-what-code-already-shows.bad.al`](al-comments-must-not-restate-what-code-already-shows.bad.al). diff --git a/microsoft/knowledge/style/pages-must-not-contain-business-logic.bad.al b/microsoft/knowledge/style/pages-must-not-contain-business-logic.bad.al new file mode 100644 index 0000000..352c515 --- /dev/null +++ b/microsoft/knowledge/style/pages-must-not-contain-business-logic.bad.al @@ -0,0 +1,49 @@ +table 50101 "Sample Order Line" +{ + fields + { + field(1; "Document No."; Code[20]) { } + field(2; "Line No."; Integer) { } + field(10; Quantity; Decimal) { } + field(11; "Unit Price"; Decimal) { } + field(12; "Line Amount"; Decimal) { } + } + keys + { + key(PK; "Document No.", "Line No.") { Clustered = true; } + } +} + +page 50100 "Sample Order Line Card" +{ + PageType = Card; + SourceTable = "Sample Order Line"; + + layout + { + area(content) + { + repeater(General) + { + field(quantity; Rec.Quantity) { } + field(unitPrice; Rec."Unit Price") { } + field(lineAmount; Rec."Line Amount") { } + } + } + } + + actions + { + area(Processing) + { + action(Recalculate) + { + trigger OnAction() + begin + Rec."Line Amount" := Rec.Quantity * Rec."Unit Price"; + Rec.Modify(); + end; + } + } + } +} diff --git a/microsoft/knowledge/style/pages-must-not-contain-business-logic.good.al b/microsoft/knowledge/style/pages-must-not-contain-business-logic.good.al new file mode 100644 index 0000000..a22f307 --- /dev/null +++ b/microsoft/knowledge/style/pages-must-not-contain-business-logic.good.al @@ -0,0 +1,60 @@ +table 50101 "Sample Order Line" +{ + fields + { + field(1; "Document No."; Code[20]) { } + field(2; "Line No."; Integer) { } + field(10; Quantity; Decimal) { } + field(11; "Unit Price"; Decimal) { } + field(12; "Line Amount"; Decimal) { } + } + keys + { + key(PK; "Document No.", "Line No.") { Clustered = true; } + } +} + +codeunit 50100 "Sample Order Line Management" +{ + procedure RecalculateLine(var OrderLine: Record "Sample Order Line") + begin + OrderLine.Validate("Line Amount", OrderLine.Quantity * OrderLine."Unit Price"); + OrderLine.Modify(true); + end; +} + +page 50100 "Sample Order Line Card" +{ + PageType = Card; + SourceTable = "Sample Order Line"; + + layout + { + area(content) + { + repeater(General) + { + field(quantity; Rec.Quantity) { } + field(unitPrice; Rec."Unit Price") { } + field(lineAmount; Rec."Line Amount") { } + } + } + } + + actions + { + area(Processing) + { + action(Recalculate) + { + trigger OnAction() + begin + OrderLineMgt.RecalculateLine(Rec); + end; + } + } + } + + var + OrderLineMgt: Codeunit "Sample Order Line Management"; +} diff --git a/microsoft/knowledge/style/pages-must-not-contain-business-logic.md b/microsoft/knowledge/style/pages-must-not-contain-business-logic.md new file mode 100644 index 0000000..3326a25 --- /dev/null +++ b/microsoft/knowledge/style/pages-must-not-contain-business-logic.md @@ -0,0 +1,31 @@ +--- +bc-version: [all] +domain: style +keywords: [pages, business-logic, codeunit, separation-of-concerns, presentation-layer] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Keep business logic out of page objects + +## Description + +A page procedure that persists a business mutation directly (`Rec.Modify()` outside the standard record-bound save, or a cross-entry-point business rule implemented only in a page trigger) is an architecture violation even when it compiles: the rule only applies when a user opens that specific page, and silently doesn't run through any other entry point (API, batch job, another page). This is narrower than "no calculation may live on a page" — a presentation-specific calculation (formatting, a derived display value) is fine on the page that shows it, and a reusable data invariant commonly belongs on the table itself (a field's own validation/trigger), not forced into a codeunit merely to keep it off the page. The actual line is entry-point independence: a business operation or invariant that must hold regardless of which entry point touches the record belongs in a codeunit or the table, not solely in one page's trigger. + +A narrow set of patterns are conventional rather than violations: +- A setup page reading and writing its own singleton setup record. +- A dedicated "Run Conversion" page invoking a conversion codeunit directly. +- The standard singleton-initialization idiom on `OnOpenPage` (`if not Rec.Get() then begin Rec.Init(); Rec.Insert(); end`) used by cue/activities pages to bootstrap their own presentation-state record — this is not business logic, it is the same pattern used throughout base-app cue pages. + +## Best Practice + +Delegate all business operations to a codeunit: the page owns presentation, the codeunit owns logic. A calculation or validation triggered from a page action should call a codeunit procedure rather than compute the result inline. + +See sample: [`pages-must-not-contain-business-logic.good.al`](pages-must-not-contain-business-logic.good.al). + +## Anti Pattern + +A cross-entry-point business rule or persisted mutation implemented only in a page trigger — calling `Rec.Modify()` to save a computed business value from `OnValidate`/`OnAction`, or a validation that must hold regardless of caller, instead of routed through a codeunit or the table's own field validation. A presentation-only calculation or a table-owned field invariant is not an instance of this anti-pattern. + +See sample: [`pages-must-not-contain-business-logic.bad.al`](pages-must-not-contain-business-logic.bad.al). diff --git a/microsoft/knowledge/style/source-organized-by-feature-not-object-type.md b/microsoft/knowledge/style/source-organized-by-feature-not-object-type.md new file mode 100644 index 0000000..c698093 --- /dev/null +++ b/microsoft/knowledge/style/source-organized-by-feature-not-object-type.md @@ -0,0 +1,48 @@ +--- +bc-version: [all] +domain: style +keywords: [folder-structure, feature-organization, source-layout, maintainability] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Organize AL source by business feature, not object type + +## Description + +Folder structure inside an AL app has no effect on compilation or runtime behavior — this is a repository-organization convention, not a platform requirement, and different projects reasonably choose differently. Grouping files by business feature or module (`src/Sales/Invoice/`, `src/NoSeries/`) rather than by AL object type (`src/Tables/`, `src/Pages/`, `src/Codeunits/`) keeps everything belonging to one feature physically together, which many teams find easier to navigate than jumping between object-type folders that share nothing but their AL object kind. Adopt this consistently on a project rather than mixing both schemes, but treat it as a team convention to apply deliberately, not a Microsoft-mandated structure. + +Code genuinely shared across multiple features (utility codeunits, common interfaces, shared enums) belongs in a `Common` or `Shared` folder, not duplicated per feature and not left in a catch-all root. + +## Best Practice + + src/ + ├── NoSeries/ + ├── Sales/ + │ ├── Invoice/ + │ └── Order/ + └── Common/ + +Each feature folder holds every object type it needs; shared code has one dedicated home. + +## Anti Pattern + +A repository that documents or has established feature-based organization +as its convention, but then mixes in object-type folders for new work +anyway: + + src/ + ├── Sales/ + │ └── Invoice/ + ├── Tables/ <- new objects land here instead of a feature folder + └── Codeunits/ + +The anti-pattern is inconsistency with the project's own chosen convention, +not the object-type scheme itself — a repository that deliberately and +consistently organizes by object type throughout is exercising the other +reasonable choice described above, not violating this rule. What actually +costs a reader time is a codebase where some features live under their own +folder and others are scattered across type folders, so finding everything +related to one feature means checking both schemes and reassembling it from +wherever each object happened to land. diff --git a/microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.bad.al b/microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.bad.al new file mode 100644 index 0000000..d6a29d6 --- /dev/null +++ b/microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.bad.al @@ -0,0 +1,29 @@ +// Only wraps Microsoft's own generic scenario — measures BC, not this extension +codeunit 50101 "BCPT Create Sales Order" implements "BCPT Test Param. Provider" +{ + SingleInstance = true; + + trigger OnRun() + begin + CreateStandardSalesOrder(GlobalBCPTTestContext); + end; + + var + GlobalBCPTTestContext: Codeunit "BCPT Test Context"; + + local procedure CreateStandardSalesOrder(var BCPTTestContext: Codeunit "BCPT Test Context") + begin + BCPTTestContext.StartScenario('Create Sales Order With N Lines'); + // ... standard sales order creation, no reference to the extension's own logic + BCPTTestContext.EndScenario('Create Sales Order With N Lines'); + end; + + procedure GetDefaultParameters(): Text[1000] + begin + exit(''); + end; + + procedure ValidateParameters(Parameters: Text[1000]) + begin + end; +} diff --git a/microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.good.al b/microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.good.al new file mode 100644 index 0000000..68239d7 --- /dev/null +++ b/microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.good.al @@ -0,0 +1,73 @@ +codeunit 50100 "BCPT Create Service Request" implements "BCPT Test Param. Provider" +{ + SingleInstance = true; + + trigger OnRun() + begin + if not IsInitialized then begin + InitTest(); + IsInitialized := true; + end; + CreateServiceRequest(GlobalBCPTTestContext); + end; + + var + GlobalBCPTTestContext: Codeunit "BCPT Test Context"; + CustomerNo: Code[20]; + IsInitialized: Boolean; + + local procedure InitTest() + var + Customer: Record Customer; + begin + // Do not assume a customer already exists: a BCPT run may target an + // otherwise-empty environment. Create one if none is found instead + // of failing on FindFirst(). + if not Customer.FindFirst() then begin + Customer.Init(); + Customer."No." := GenerateUniqueCode(MaxStrLen(Customer."No.")); + Customer.Insert(true); + end; + CustomerNo := Customer."No."; + end; + + local procedure GenerateUniqueCode(Length: Integer): Code[20] + begin + // A GUID-derived code, not a session-local counter: it stays unique + // across concurrent BCPT sessions and repeated runs against the + // same environment, which an in-memory counter reset per session + // cannot guarantee. + exit(CopyStr(DelChr(Format(CreateGuid()), '=', '{}-'), 1, Length)); + end; + + local procedure CreateServiceRequest(var BCPTTestContext: Codeunit "BCPT Test Context") + var + ServiceRequestHeader: Record "Service Request Header"; + ServiceRequestLine: Record "Service Request Line"; + begin + BCPTTestContext.StartScenario('Create Service Request Header'); + ServiceRequestHeader.Init(); + ServiceRequestHeader."No." := GenerateUniqueCode(MaxStrLen(ServiceRequestHeader."No.")); + ServiceRequestHeader.Validate("Customer No.", CustomerNo); + ServiceRequestHeader.Insert(true); + BCPTTestContext.EndScenario('Create Service Request Header'); + BCPTTestContext.UserWait(); + + BCPTTestContext.StartScenario('Add Service Request Line'); + ServiceRequestLine.Init(); + ServiceRequestLine."Document No." := ServiceRequestHeader."No."; + ServiceRequestLine."Line No." := 10000; + ServiceRequestLine.Description := 'Performance test line'; + ServiceRequestLine.Insert(true); + BCPTTestContext.EndScenario('Add Service Request Line'); + end; + + procedure GetDefaultParameters(): Text[1000] + begin + exit(''); + end; + + procedure ValidateParameters(Parameters: Text[1000]) + begin + end; +} diff --git a/microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.md b/microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.md new file mode 100644 index 0000000..51ebddd --- /dev/null +++ b/microsoft/knowledge/testing/bcpt-scenarios-must-be-app-specific.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: testing +keywords: [bcpt, performance-test, scenarios, app-specific, regression] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Include app-specific scenarios in a PerformanceTest app's BCPT suite + +## Description + +A PerformanceTest app that ships with only the generic Microsoft BCPT samples (creating sales orders, purchase orders, posting item journals) measures Business Central's own baseline performance, not the extension it was built to test. Those samples are starting points, not coverage. Without a scenario that exercises the extension's own business flow — its own codeunits, its own FlowFields, its own page rendering — a performance regression introduced by the extension has no test that would ever detect it. + +## Best Practice + +For every major business flow the extension adds, create a matching `BCPT*` scenario codeunit implementing `"BCPT Test Param. Provider"`, building its own test data in a local `InitTest()` procedure rather than depending on hardcoded records. Beyond that shared shape, the interface details are context-dependent, not fixed requirements: most of Microsoft's own shipped BCPT samples declare `SingleInstance = true`, but `codeunit "BCPT Create Customer"` does not, relying instead on `OnRun` calling `InitTest()` unconditionally every run. Likewise, wrapping the operation under test in `BCPTTestContext.StartScenario()` / `EndScenario()` is a real, available pattern for splitting one codeunit's run into several separately measured steps — useful when a regression in one step should not hide inside a coarser, whole-`OnRun` measurement — but it is not what every sample does; `"BCPT Create Customer"` measures its entire `OnRun` as a single implicit scenario and never calls `StartScenario`/`EndScenario` at all. Choose per-step scenarios when step-level granularity matters to the flow being tested; otherwise a single measured `OnRun` is a legitimate, simpler choice. + +See sample: [`bcpt-scenarios-must-be-app-specific.good.al`](bcpt-scenarios-must-be-app-specific.good.al). + +## Anti Pattern + +A PerformanceTest app whose only scenario codeunits are copies of Microsoft's shipped samples (creating a standard sales order, opening the standard customer list) tests the platform, not the extension. Any regression in the extension's own posting logic, calculations, or pages goes unmeasured and unnoticed. + +See sample: [`bcpt-scenarios-must-be-app-specific.bad.al`](bcpt-scenarios-must-be-app-specific.bad.al). diff --git a/microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.bad.al b/microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.bad.al new file mode 100644 index 0000000..0181fdb --- /dev/null +++ b/microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.bad.al @@ -0,0 +1,15 @@ +[Test] +procedure PostSalesOrder_CreatesInvoice() +var + SalesHeader: Record "Sales Header"; + SalesInvoiceHeader: Record "Sales Invoice Header"; + InvoiceNo: Code[20]; +begin + // [GIVEN] a sales order — posting groups left to whatever exists in the test company + LibrarySales.CreateSalesOrder(SalesHeader); + // [WHEN] + InvoiceNo := LibrarySales.PostSalesDocument(SalesHeader, false, true); + // [THEN] + SalesInvoiceHeader.Get(InvoiceNo); + Assert.RecordIsNotEmpty(SalesInvoiceHeader); +end; diff --git a/microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.good.al b/microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.good.al new file mode 100644 index 0000000..224f0dc --- /dev/null +++ b/microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.good.al @@ -0,0 +1,20 @@ +[Test] +procedure PostSalesOrder_CreatesInvoice() +var + Customer: Record Customer; + SalesHeader: Record "Sales Header"; + SalesInvoiceHeader: Record "Sales Invoice Header"; + InvoiceNo: Code[20]; +begin + // [GIVEN] a customer + LibrarySales.CreateCustomer(Customer); + // [GIVEN] a sales order for that customer + LibrarySales.CreateSalesOrderForCustomerNo(SalesHeader, Customer."No."); + SalesHeader.Validate("Posting Date", WorkDate()); + SalesHeader.Modify(true); + // [WHEN] + InvoiceNo := LibrarySales.PostSalesDocument(SalesHeader, false, true); + // [THEN] + SalesInvoiceHeader.Get(InvoiceNo); + Assert.RecordIsNotEmpty(SalesInvoiceHeader); +end; diff --git a/microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.md b/microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.md new file mode 100644 index 0000000..b34adfe --- /dev/null +++ b/microsoft/knowledge/testing/given-blocks-must-cover-full-precondition-chain.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: testing +keywords: [given, test-setup, posting, report, request-page, precondition, completeness] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Cover the full precondition chain in GIVEN, not just the primary record + +## Description + +A `[GIVEN]` block is only correct if it sets up every precondition the code under test actually reads, not just the record the scenario is "about." For most master-data tests, creating the primary record is enough. For posting routines and reports it usually is not: an incomplete `[GIVEN]` produces a test that either fails with a setup error unrelated to the scenario, or worse, passes without ever reaching the logic it claims to verify. + +## Best Practice + +For a posting test, set up the full posting-group chain the document requires (e.g. customer/vendor posting group, gen. business/product posting group, VAT posting setup), the setup records the specific posting path reads, and an explicit date when the path is date-sensitive — a missing link surfaces as an unrelated G/L error, not a meaningful test failure. For a report test that claims to verify filtering or dataset logic, include both a record that should be included and one that should be excluded, plus any request-page parameter or FlowField the report's logic branches on. A report test that only claims to run without error is exempt from the include/exclude pairing, but it must say so in its scenario name or comment — an unlabelled single-record `[GIVEN]` is ambiguous about which claim it is making, and that ambiguity is itself the defect. + +See sample: [`given-blocks-must-cover-full-precondition-chain.good.al`](given-blocks-must-cover-full-precondition-chain.good.al). + +## Anti Pattern + +A posting test whose `[GIVEN]` creates only the sales header, relying on whatever posting groups happen to exist in the test company. A report test whose `[GIVEN]` creates only matching records, so the report "passes" whether or not its filter logic does anything at all. + +See sample: [`given-blocks-must-cover-full-precondition-chain.bad.al`](given-blocks-must-cover-full-precondition-chain.bad.al). diff --git a/microsoft/knowledge/testing/test-feature-scenario-tags.bad.al b/microsoft/knowledge/testing/test-feature-scenario-tags.bad.al new file mode 100644 index 0000000..06e5d54 --- /dev/null +++ b/microsoft/knowledge/testing/test-feature-scenario-tags.bad.al @@ -0,0 +1,33 @@ +codeunit 50102 "Item Price Testing" +{ + Subtype = Test; + + var + LibrarySales: Codeunit "Library - Sales"; + LibraryInventory: Codeunit "Library - Inventory"; + LibraryPriceCalculation: Codeunit "Library - Price Calculation"; + Assert: Codeunit "Library Assert"; + + [Test] + procedure Test1() + var + Customer: Record Customer; + Item: Record Item; + PriceListHeader: Record "Price List Header"; + PriceListLine: Record "Price List Line"; + SalesHeader: Record "Sales Header"; + SalesLine: Record "Sales Line"; + begin + // setup mixed with assertions, no clear layers, no FEATURE/SCENARIO/GIVEN/WHEN/THEN tags + LibrarySales.CreateCustomer(Customer); + LibraryInventory.CreateItem(Item); + LibraryPriceCalculation.CreatePriceHeader( + PriceListHeader, PriceListHeader."Price Type"::Sale, "Price Source Type"::Customer, Customer."No."); + LibraryPriceCalculation.CreateSalesPriceLine( + PriceListLine, PriceListHeader.Code, "Price Source Type"::Customer, Customer."No.", + "Price Asset Type"::Item, Item."No."); + LibrarySales.CreateSalesDocumentWithItem( + SalesHeader, SalesLine, SalesHeader."Document Type"::Order, Customer."No.", Item."No.", 1, '', 0D); + Assert.AreEqual(PriceListLine."Unit Price", SalesLine."Unit Price", ''); + end; +} diff --git a/microsoft/knowledge/testing/test-feature-scenario-tags.good.al b/microsoft/knowledge/testing/test-feature-scenario-tags.good.al new file mode 100644 index 0000000..b2cbf06 --- /dev/null +++ b/microsoft/knowledge/testing/test-feature-scenario-tags.good.al @@ -0,0 +1,40 @@ +// [FEATURE] Item Price — price cascade (Customer -> Price Group -> All Customers) +codeunit 50103 "Item Price Testing" +{ + Subtype = Test; + + var + LibrarySales: Codeunit "Library - Sales"; + LibraryInventory: Codeunit "Library - Inventory"; + LibraryPriceCalculation: Codeunit "Library - Price Calculation"; + Assert: Codeunit "Library Assert"; + + [Test] + procedure GetPrice_CustomerPrice_ReturnsUnitPrice() + var + Customer: Record Customer; + Item: Record Item; + PriceListHeader: Record "Price List Header"; + PriceListLine: Record "Price List Line"; + SalesHeader: Record "Sales Header"; + SalesLine: Record "Sales Line"; + begin + // [SCENARIO] Customer with a specific price list line gets that unit price + // [GIVEN] a customer and an item with a customer-specific sales price list line + LibrarySales.CreateCustomer(Customer); + LibraryInventory.CreateItem(Item); + LibraryPriceCalculation.CreatePriceHeader( + PriceListHeader, PriceListHeader."Price Type"::Sale, "Price Source Type"::Customer, Customer."No."); + LibraryPriceCalculation.CreateSalesPriceLine( + PriceListLine, PriceListHeader.Code, "Price Source Type"::Customer, Customer."No.", + "Price Asset Type"::Item, Item."No."); + // CreatePriceHeader leaves the list in Draft status, which price calculation ignores. + PriceListHeader.Validate(Status, PriceListHeader.Status::Active); + PriceListHeader.Modify(true); + // [WHEN] a sales line is created for that customer and item + LibrarySales.CreateSalesDocumentWithItem( + SalesHeader, SalesLine, SalesHeader."Document Type"::Order, Customer."No.", Item."No.", 1, '', 0D); + // [THEN] the sales line picks up the customer's price list line + Assert.AreEqual(PriceListLine."Unit Price", SalesLine."Unit Price", 'Unit price must match customer price list'); + end; +} diff --git a/microsoft/knowledge/testing/test-feature-scenario-tags.md b/microsoft/knowledge/testing/test-feature-scenario-tags.md new file mode 100644 index 0000000..2247c7e --- /dev/null +++ b/microsoft/knowledge/testing/test-feature-scenario-tags.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: testing +keywords: [feature, scenario, given, when, then, tags, bdd, atdd, comments] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Tag test codeunits with FEATURE, SCENARIO, GIVEN, WHEN, and THEN comments + +## Description + +Test codeunits are easier to trust and to review when they carry a four-level comment structure taken from Behaviour-/Acceptance-Test-Driven Development: `[FEATURE]` once at the top of the codeunit naming the functional area under test, `[SCENARIO]` above each test procedure stating one falsifiable business claim in plain language, and `[GIVEN]`/`[WHEN]`/`[THEN]` marking the precondition, action, and assertion inside the test body. Without these tags a test procedure is an opaque block of AL that only reveals its intent by being read line by line; a reviewer or product owner cannot scan a codeunit and know what business behaviour it covers. + +## Best Practice + +Put `[FEATURE]` as a comment before the codeunit's opening brace, naming the domain rather than the object — Microsoft's own guidance allows setting it once for the whole codeunit, inherited by every test in it. Put `[SCENARIO]`, matching the current BCApps corpus, as the first comment inside each test procedure's body (after `begin`), describing the scenario in business language that complements — not duplicates — the procedure name, followed by `[GIVEN]` marking the precondition setup, `[WHEN]` marking the single action under test, and `[THEN]` marking the assertions. The procedure name stays the machine-readable identity shown in test-runner output; the `[SCENARIO]` comment stays the human-readable one. Neither replaces the other. + +See sample: [`test-feature-scenario-tags.good.al`](test-feature-scenario-tags.good.al). + +## Anti Pattern + +A test procedure with no `[FEATURE]`/`[SCENARIO]`/`[GIVEN]`/`[WHEN]`/`[THEN]` structure, setup mixed freely with assertions, and a procedure name like `Test1` that says nothing about what is being verified. Nothing in the codeunit tells a reader what business rule it exists to protect. + +See sample: [`test-feature-scenario-tags.bad.al`](test-feature-scenario-tags.bad.al). diff --git a/microsoft/knowledge/testing/test-one-when-per-test.bad.al b/microsoft/knowledge/testing/test-one-when-per-test.bad.al new file mode 100644 index 0000000..c49696c --- /dev/null +++ b/microsoft/knowledge/testing/test-one-when-per-test.bad.al @@ -0,0 +1,32 @@ +[Test] +procedure GetPrice_ThenGetPriceLines_ReturnsCorrectValues() +var + Customer: Record Customer; + Item: Record Item; + PriceListHeader: Record "Price List Header"; + PriceListLine: Record "Price List Line"; + SalesHeader: Record "Sales Header"; + SalesLine: Record "Sales Line"; +begin + // [GIVEN] ... + LibrarySales.CreateCustomer(Customer); + LibraryInventory.CreateItem(Item); + LibraryPriceCalculation.CreatePriceHeader( + PriceListHeader, PriceListHeader."Price Type"::Sale, "Price Source Type"::Customer, Customer."No."); + LibraryPriceCalculation.CreateSalesPriceLine( + PriceListLine, PriceListHeader.Code, "Price Source Type"::Customer, Customer."No.", + "Price Asset Type"::Item, Item."No."); + // [WHEN] first action + LibrarySales.CreateSalesDocumentWithItem( + SalesHeader, SalesLine, SalesHeader."Document Type"::Order, Customer."No.", Item."No.", 1, '', 0D); + // [WHEN] second action — this is a second test in disguise + PriceListLine.Validate("Minimum Quantity", 10); + PriceListLine.Modify(true); + LibraryPriceCalculation.CreateSalesPriceLine( + PriceListLine, PriceListHeader.Code, "Price Source Type"::Customer, Customer."No.", + "Price Asset Type"::Item, Item."No."); + // [THEN] asserting two unrelated things + Assert.AreEqual(PriceListLine."Unit Price", SalesLine."Unit Price", ''); + PriceListLine.SetRange("Price List Code", PriceListHeader.Code); + Assert.AreEqual(2, PriceListLine.Count(), ''); +end; diff --git a/microsoft/knowledge/testing/test-one-when-per-test.good.al b/microsoft/knowledge/testing/test-one-when-per-test.good.al new file mode 100644 index 0000000..6b58c51 --- /dev/null +++ b/microsoft/knowledge/testing/test-one-when-per-test.good.al @@ -0,0 +1,56 @@ +[Test] +procedure GetPrice_CustomerPrice_ReturnsCorrectUnitPrice() +var + Customer: Record Customer; + Item: Record Item; + PriceListHeader: Record "Price List Header"; + PriceListLine: Record "Price List Line"; + SalesHeader: Record "Sales Header"; + SalesLine: Record "Sales Line"; +begin + // [GIVEN] a customer with a price list line for the item + LibrarySales.CreateCustomer(Customer); + LibraryInventory.CreateItem(Item); + LibraryPriceCalculation.CreatePriceHeader( + PriceListHeader, PriceListHeader."Price Type"::Sale, "Price Source Type"::Customer, Customer."No."); + LibraryPriceCalculation.CreateSalesPriceLine( + PriceListLine, PriceListHeader.Code, "Price Source Type"::Customer, Customer."No.", + "Price Asset Type"::Item, Item."No."); + // CreatePriceHeader leaves the list in Draft status, which price calculation ignores. + PriceListHeader.Validate(Status, PriceListHeader.Status::Active); + PriceListHeader.Modify(true); + // [WHEN] + LibrarySales.CreateSalesDocumentWithItem( + SalesHeader, SalesLine, SalesHeader."Document Type"::Order, Customer."No.", Item."No.", 1, '', 0D); + // [THEN] + Assert.AreEqual(PriceListLine."Unit Price", SalesLine."Unit Price", 'Unit price must match price list'); +end; + +[Test] +procedure GetPriceLines_TwoMinimumQuantityLines_ReturnsBoth() +var + Customer: Record Customer; + Item: Record Item; + PriceListHeader: Record "Price List Header"; + PriceListLine: Record "Price List Line"; +begin + // [GIVEN] a customer price list with two minimum-quantity price lines for the same item + LibrarySales.CreateCustomer(Customer); + LibraryInventory.CreateItem(Item); + LibraryPriceCalculation.CreatePriceHeader( + PriceListHeader, PriceListHeader."Price Type"::Sale, "Price Source Type"::Customer, Customer."No."); + LibraryPriceCalculation.CreateSalesPriceLine( + PriceListLine, PriceListHeader.Code, "Price Source Type"::Customer, Customer."No.", + "Price Asset Type"::Item, Item."No."); + PriceListLine.Validate("Minimum Quantity", 10); + PriceListLine.Modify(true); + LibraryPriceCalculation.CreateSalesPriceLine( + PriceListLine, PriceListHeader.Code, "Price Source Type"::Customer, Customer."No.", + "Price Asset Type"::Item, Item."No."); + PriceListLine.Validate("Minimum Quantity", 50); + PriceListLine.Modify(true); + // [WHEN] + PriceListLine.SetRange("Price List Code", PriceListHeader.Code); + // [THEN] + Assert.AreEqual(2, PriceListLine.Count(), 'Exactly two price lines expected'); +end; diff --git a/microsoft/knowledge/testing/test-one-when-per-test.md b/microsoft/knowledge/testing/test-one-when-per-test.md new file mode 100644 index 0000000..69c3b37 --- /dev/null +++ b/microsoft/knowledge/testing/test-one-when-per-test.md @@ -0,0 +1,34 @@ +--- +bc-version: [all] +domain: testing +keywords: [when, single-action, bdd, atdd, given-when-then, flow-test, regression-test] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Keep exactly one WHEN per test, with narrow exceptions for flow and defect-then-fix tests + +## Description + +This is a testing-design practice, not a BC platform requirement — no AL API enforces it, and it should not gate a change the way a platform-contradicted claim would. Each test procedure should contain exactly one `[WHEN]` block: one action that triggers the behaviour under test. A test with multiple WHENs — "do A, then do B, then check C" — is two or more tests in disguise. Splitting them gives failure isolation (a failing test points at one action, not an ambiguous sequence) and keeps each test readable as a single, falsifiable claim. A precondition action, such as posting a document so a ledger entry exists to assert against, belongs in `[GIVEN]`; only the action actually being asserted belongs in `[WHEN]`. + +## Best Practice + +Give each test one `[WHEN]` and one focused claim. A procedure name containing "And" or "Then" in the middle (`GetPrice_AndDiscount_ReturnsValues`) is a strong signal the test should be split. + +See sample: [`test-one-when-per-test.good.al`](test-one-when-per-test.good.al). + +## Anti Pattern + +A test that performs a first action, then a second unrelated action, then asserts on both — mixing two falsifiable claims into one procedure so a failure can't tell you which action broke. + +See sample: [`test-one-when-per-test.bad.al`](test-one-when-per-test.bad.al). + +## Flow tests — a deliberate exception + +A flow test verifies the accumulated outcome of a genuinely multi-round business process (partial receipt then invoicing, several posting rounds against one document), where the sequence itself is the scenario — splitting it would lose the interaction under test. Multiple `[WHEN]` blocks are allowed only when the procedure name declares the flow, each `[WHEN]` is labelled as one round of a single scenario rather than an unrelated action, and the `[THEN]` asserts the accumulated end-state rather than assertions that decompose cleanly per action (if they do decompose cleanly, it is still two tests in disguise). Outside this shape, unit-level tests keep the strict one-WHEN rule. + +## Defect-then-fix tests — a second, narrower exception + +A test that reproduces a specific broken state and then verifies a subsequent action corrects it is not the same shape as an unrelated-action test, even though its `[THEN]` assertions decompose cleanly per step — clean decomposition is expected here, not a sign of two unrelated tests. This shape is permitted only when the second `[WHEN]` cannot be meaningfully tested without the first (the fix only affects the exact stale state the first action produced, so splitting would just re-run the first action inside a second test's `[GIVEN]`), and the procedure name communicates the before/after relationship. diff --git a/microsoft/knowledge/testing/ui-test-codeunit-naming.bad.al b/microsoft/knowledge/testing/ui-test-codeunit-naming.bad.al new file mode 100644 index 0000000..2acba18 --- /dev/null +++ b/microsoft/knowledge/testing/ui-test-codeunit-naming.bad.al @@ -0,0 +1,27 @@ +codeunit 50104 "Item Price Testing" +{ + Subtype = Test; + + [Test] + procedure ApplyDiscount_LogicTest() + var + Assert: Codeunit "Library Assert"; + begin + // logic test — fine on its own, but not paired with a UI test below + Assert.AreEqual(90, ApplyDiscount(100, 10), 'A 10% discount on 100 must yield 90'); + end; + + local procedure ApplyDiscount(UnitPrice: Decimal; DiscountPct: Decimal): Decimal + begin + exit(UnitPrice - (UnitPrice * DiscountPct / 100)); + end; + + [Test] + procedure CustomerCard_Opens_UT() + var + CustomerCard: TestPage "Customer Card"; + begin + // UI test mixed into a logic-test codeunit, and the codeunit lacks the _UT suffix + CustomerCard.OpenNew(); + end; +} diff --git a/microsoft/knowledge/testing/ui-test-codeunit-naming.good.al b/microsoft/knowledge/testing/ui-test-codeunit-naming.good.al new file mode 100644 index 0000000..6c343d8 --- /dev/null +++ b/microsoft/knowledge/testing/ui-test-codeunit-naming.good.al @@ -0,0 +1,42 @@ +codeunit 50105 "Item Price Testing" +{ + Subtype = Test; + + [Test] + procedure ApplyDiscount_ReducesUnitPrice() + var + Assert: Codeunit "Library Assert"; + DiscountedPrice: Decimal; + begin + DiscountedPrice := ApplyDiscount(100, 10); + Assert.AreEqual(90, DiscountedPrice, 'A 10% discount on 100 must yield 90'); + end; + + local procedure ApplyDiscount(UnitPrice: Decimal; DiscountPct: Decimal): Decimal + begin + exit(UnitPrice - (UnitPrice * DiscountPct / 100)); + end; +} + +codeunit 50106 "Item Price Testing_UT" +{ + Subtype = Test; + + [Test] + procedure CustomerCard_SetName_UpdatesField() + var + Customer: Record Customer; + CustomerCard: TestPage "Customer Card"; + Assert: Codeunit "Library Assert"; + LibrarySales: Codeunit "Library - Sales"; + begin + LibrarySales.CreateCustomer(Customer); + CustomerCard.OpenEdit(); + CustomerCard.GoToRecord(Customer); + CustomerCard.Name.SetValue('Updated Name'); + CustomerCard.Close(); + + Customer.Get(Customer."No."); + Assert.AreEqual('Updated Name', Customer.Name, 'Name must be updated through the page'); + end; +} diff --git a/microsoft/knowledge/testing/ui-test-codeunit-naming.md b/microsoft/knowledge/testing/ui-test-codeunit-naming.md new file mode 100644 index 0000000..0790f37 --- /dev/null +++ b/microsoft/knowledge/testing/ui-test-codeunit-naming.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: testing +keywords: [ui-test, testpage, naming, suffix, codeunit, page-testing, team-convention] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Separate UI-layer and logic-layer tests into different codeunits + +## Description + +A test codeunit that drives pages through `TestPage` — opening pages, reading FactBox parts, triggering field `OnValidate` through the page — is testing a different layer than a codeunit that calls business-logic procedures directly. Readers need to know which layer a given test exercises without opening it, and a single codeunit that mixes both kinds of test hides that distinction: a failure could mean the logic broke, the page broke, or both. The `_UT` suffix and adjacent-object-ID pairing below are one team's naming convention for making that split visible, not a BCApps-wide naming standard — BCApps itself uses `UT` for unit tests generally, not specifically to mean "UI layer," and does not treat adjacent object IDs as a semantic pairing mechanism. Apply the suffix only on a project that has explicitly adopted this convention. + +## Best Practice + +Keep UI-layer (`TestPage`-driven) and logic-layer tests in separate codeunits regardless of naming. Projects that adopt a `_UT`-style suffix convention should apply it consistently to every UI-layer test codeunit, keep the corresponding logic-only codeunit unsuffixed, and document the convention where the team's other naming rules live. + +See sample: [`ui-test-codeunit-naming.good.al`](ui-test-codeunit-naming.good.al). + +## Anti Pattern + +One codeunit that mixes a direct logic-call test and a `TestPage`-driven test side by side — a failing test no longer tells a reader which layer actually broke. On a project that has adopted the `_UT` convention, a UI-layer codeunit missing the suffix is also an instance of this anti-pattern; on a project that has not adopted it, the suffix itself is not required. + +See sample: [`ui-test-codeunit-naming.bad.al`](ui-test-codeunit-naming.bad.al). diff --git a/microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.bad.al b/microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.bad.al new file mode 100644 index 0000000..fd371f5 --- /dev/null +++ b/microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.bad.al @@ -0,0 +1,21 @@ +page 50131 "Sample Item List" +{ + PageType = List; + SourceTable = "Sample Item"; + // Anti-pattern: no CardPageID even though a Card page exists for + // this table, and no UsageCategory, so the page is invisible to + // Tell Me search. + ApplicationArea = All; + + layout + { + area(content) + { + repeater(Group) + { + field(Description; Rec.Description) { } + field("No."; Rec."No.") { } // primary key buried, not left-most + } + } + } +} diff --git a/microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.good.al b/microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.good.al new file mode 100644 index 0000000..7b53ac0 --- /dev/null +++ b/microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.good.al @@ -0,0 +1,20 @@ +page 50130 "Sample Item List" +{ + PageType = List; + SourceTable = "Sample Item"; + CardPageID = "Sample Item Card"; // links back to its Card page + UsageCategory = Lists; + ApplicationArea = All; + + layout + { + area(content) + { + repeater(Group) + { + field("No."; Rec."No.") { } // primary key, left-most + field(Description; Rec.Description) { } + } + } + } +} diff --git a/microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.md b/microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.md new file mode 100644 index 0000000..18f7178 --- /dev/null +++ b/microsoft/knowledge/ui/page-design-must-match-bc-page-type-conventions.md @@ -0,0 +1,90 @@ +--- +bc-version: [all] +domain: ui +keywords: [pages, page-design, naming-conventions, page-type, card-page, list-page, factbox, worksheet-page, document-page, rolecenter, cardpageid, autosplitkey] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Pages must match one of Business Central's page-type conventions + +## Description + +Business Central's page types — RoleCenter, Card, List, CardPart, +ListPart, Worksheet, Document, ListPlus, plus system dialog/special +types such as `NavigatePage`, `ConfirmationDialog`, `StandardDialog`, +`HeadlinePart`, and `API` (a selected list of conventional types this +article covers design conventions for — not an exhaustive catalogue of +every current `PageType` value; `PromptDialog`, `ConfigurationDialog`, +`UserControlHost`, and `XmlPort` also exist but follow their own +design rules, out of scope here) — each +fix a naming pattern and a structural constraint, not just a visual +layout. A page whose name, primary-key handling, or linkage +(`CardPageID`, `SubPageLink`, `AutoSplitKey`) doesn't match its own type's +conventions is either the wrong page type for the job or built +inconsistently with the rest of the application, and should be flagged in +review even if it compiles and renders. Before naming a new page or +wiring its links, first ask which page type it is, and whether the source +table actually fits that type's structural requirement — the type fixes +the naming suffix, which fields are visible, and which other page it must +link back to. + +## Best Practice + +Match the page's design to its type: + +- **RoleCenter** — tailored home page for a role; named role + `Role + Center`; links to List pages, shows Cues/Activities. +- **Card** — view/edit one record; named table + `Card`; FastTabs only, + first FastTab named `General`. A single-field primary key is typical, + but not a hard requirement: a subsidiary table that supplements a + master record with its own identity (parent key + own code — Ship-to + Address, Customer/Vendor Bank Account) commonly gets its own Card page + over a composite key too. Treat the key shape as a contextual signal, + not a mandatory constraint — a composite-key table with no such + supplementing relationship to a master record is the actual signal a + List/Worksheet/Tabular page fits better. +- **List** — view multiple records, also the lookup/drilldown surface; + named table + `List` if read-only, or the plural table name if + editable; primary-key fields shown left-most; `CardPageID` must point + at the associated Card page when one exists. +- **CardPart** — single-column FactBox; named for its content + + `FactBox`. +- **ListPart** — multi-column FactBox or subpage (e.g. document lines); + named for its content + `FactBox`/`SubPage`; `SubPageLink` must + actually filter to the host record. +- **Worksheet** — multi-record entry for a Journal-like table, insertion + order preserved; primary-key fields never shown; uses `AutoSplitKey` + with a trailing `Integer` key field. +- **Document** — FastTabs plus a lines subpage, lines filtered to the + header; named for the document (`Sales Invoice`). +- **ListPlus** — like Document but with multiple lists instead of one; + named like the record/report it summarizes. +- System dialog types (`NavigatePage`, `ConfirmationDialog`, + `StandardDialog`, `HeadlinePart`) are fixed shapes with no page-name + suffix convention. `API` pages follow their own property rules and are + extended by adding a new API page, never a page extension. + +Before wiring controls, the design step should fix: which users and +tasks the page serves, the concrete fields/commands/links those tasks +need, the page type that matches the content (chosen before the source +table), and the source table that actually holds the page's primary data. + +See sample: [`page-design-must-match-bc-page-type-conventions.good.al`](page-design-must-match-bc-page-type-conventions.good.al). + +## Anti Pattern + +A page that mixes conventions from two types — for example, a "List" +page with no `CardPageID` even though a Card page exists for the same +table — signals a design step was skipped, not a stylistic choice. A +Card page over a composite-key table is not automatically this anti +pattern; check whether the table supplements a master record first. Also watch +for a Worksheet or List page showing primary-key fields it shouldn't (or +hiding them when it should show them). A page with no `UsageCategory` set +is not automatically a defect either: supporting pages, subpages, dialogs, +and pages intended only to be reached through another workflow correctly +have no `UsageCategory` — flag its absence only on a page intended as a +searchable entry point in its own right. + +See sample: [`page-design-must-match-bc-page-type-conventions.bad.al`](page-design-must-match-bc-page-type-conventions.bad.al). diff --git a/microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.bad.al b/microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.bad.al new file mode 100644 index 0000000..82065f0 --- /dev/null +++ b/microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.bad.al @@ -0,0 +1,32 @@ +local procedure UpgradeCustomerFields() +begin + if not UpgradeTag.HasUpgradeTag(GetCustomerDiscountFieldTag()) then begin + Customer.SetLoadFields("Discount %", "Customer Posting Group"); + if Customer.FindSet() then + repeat + if (Customer."Discount %" = 0) and (Customer."Customer Posting Group" <> '') then begin + Customer."Discount %" := 5; + Customer.Modify(); + end; + until Customer.Next() = 0; + UpgradeTag.SetUpgradeTag(GetCustomerDiscountFieldTag()); + + // BUG: a second, unrelated migration's tag check nested inside the + // first migration's guarded body. Neither tag can be checked, + // skipped, or fixed independently of the other - a failure or a + // deliberate skip of the discount migration silently takes the + // shipping-agent migration down with it, and nothing in the + // Upgrade Tags table records that the second step ran on its own. + if not UpgradeTag.HasUpgradeTag(GetCustomerShippingAgentFieldTag()) then begin + Customer.SetLoadFields("Shipping Agent Code"); + if Customer.FindSet() then + repeat + if Customer."Shipping Agent Code" = '' then begin + Customer."Shipping Agent Code" := DefaultShippingAgentCode(); + Customer.Modify(); + end; + until Customer.Next() = 0; + UpgradeTag.SetUpgradeTag(GetCustomerShippingAgentFieldTag()); + end; + end; +end; diff --git a/microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.good.al b/microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.good.al new file mode 100644 index 0000000..e121570 --- /dev/null +++ b/microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.good.al @@ -0,0 +1,40 @@ +local procedure UpgradeCustomerDiscountField() +begin + if UpgradeTag.HasUpgradeTag(GetCustomerDiscountFieldTag()) then + exit; + + Customer.SetLoadFields("Discount %", "Customer Posting Group"); + if Customer.FindSet() then + repeat + // A business-data safety condition inside this one migration's + // loop is not a second migration hiding inside the first - + // Microsoft's own upgrade-tag example nests exactly this shape + // (a corruption guard, then a redundant-write guard) inside a + // single tagged procedure. + if (Customer."Discount %" = 0) and (Customer."Customer Posting Group" <> '') then begin + Customer."Discount %" := 5; + Customer.Modify(); + end; + until Customer.Next() = 0; + + UpgradeTag.SetUpgradeTag(GetCustomerDiscountFieldTag()); +end; + +// A second, genuinely unrelated migration gets its own tag and its own +// top-level procedure - not nested inside the first one's guarded body. +local procedure UpgradeCustomerShippingAgentField() +begin + if UpgradeTag.HasUpgradeTag(GetCustomerShippingAgentFieldTag()) then + exit; + + Customer.SetLoadFields("Shipping Agent Code"); + if Customer.FindSet() then + repeat + if Customer."Shipping Agent Code" = '' then begin + Customer."Shipping Agent Code" := DefaultShippingAgentCode(); + Customer.Modify(); + end; + until Customer.Next() = 0; + + UpgradeTag.SetUpgradeTag(GetCustomerShippingAgentFieldTag()); +end; diff --git a/microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.md b/microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.md new file mode 100644 index 0000000..d2384f8 --- /dev/null +++ b/microsoft/knowledge/upgrade/upgrade-tag-logic-must-not-nest-deeply.md @@ -0,0 +1,34 @@ +--- +bc-version: [all] +domain: upgrade +keywords: [upgrade-tag, nesting, complexity, upgrade-per-company, upgrade-per-database] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Never nest upgrade tag checks or blend two migrations under one tag + +## Description + +Upgrade tag *checks* should stay flat: never nest one tag's existence check inside another tag's guarded body, and never let one tagged procedure quietly perform a second, functionally distinct migration — that turns two upgrade steps into one that can't be tracked, skipped, or fixed independently, which is exactly what separate tags exist to prevent. That is the specific nesting Microsoft's own guidance warns against ("Keep tags simple by limiting nesting tags to two levels"). + +That is not a limit on how much conditional logic a single migration's own loop body may contain. Microsoft's own worked example for upgrade tags nests a record loop with two business-data safety conditions — a corruption guard, then a redundant-write guard — inside one `if UpgradeTagMgt.HasUpgradeTag(...) then exit;`-guarded procedure, and its own design guidance separately *requires* this: "Implement extra safety checks to avoid data corruption, even though you're using upgrade tags." A business-data guard that protects the single migration a tag represents is not a second migration hiding inside the first, however many `if` levels it takes. + +Upgrade code runs unattended, once, against production data with no chance to interactively debug a wrong branch — which is why mixing two migrations under one tag, or losing track of which tag guards which step, is a genuinely higher-cost mistake here than the equivalent would be in ordinary application code. + +## Best Practice + +One tag, one migration: exit early if the tag is already set, then run the one upgrade step that tag represents — including as many business-data safety conditions as that single step's own correctness requires, nested however deep the logic actually needs. Reach for a second, separately tagged migration only when the nested logic is doing genuinely unrelated work (a different table, a different field, a different concern) that could legitimately be skipped, retried, or fixed on its own. + +See sample: [`upgrade-tag-logic-must-not-nest-deeply.good.al`](upgrade-tag-logic-must-not-nest-deeply.good.al). + +## Anti Pattern + +Checking one upgrade tag inside the guarded body of another, or writing two functionally unrelated migrations — different tables, different concerns — under a single tag so neither can be tracked, skipped, or fixed independently of the other. A record loop with business-data safety conditions inside one tagged migration's own body is not this anti-pattern, even several `if` levels deep, as long as every condition serves that one migration. + +See sample: [`upgrade-tag-logic-must-not-nest-deeply.bad.al`](upgrade-tag-logic-must-not-nest-deeply.bad.al). + +## Source + +Microsoft's own "Upgrading Extensions" guidance, Design considerations: "Keep tags simple by limiting nesting tags to two levels. Complicated if statements can lead to problems." — https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-upgrading-extensions#using-upgrade-tags-to-control-upgrade-code diff --git a/microsoft/knowledge/web-services/api-page-least-privilege-write-access.bad.al b/microsoft/knowledge/web-services/api-page-least-privilege-write-access.bad.al new file mode 100644 index 0000000..13c33b4 --- /dev/null +++ b/microsoft/knowledge/web-services/api-page-least-privilege-write-access.bad.al @@ -0,0 +1,25 @@ +page 50100 "Vendor Document API" +{ + PageType = API; + APIPublisher = 'contoso'; + APIGroup = 'documents'; + APIVersion = 'v1.0'; + EntityName = 'vendorDocument'; + EntitySetName = 'vendorDocuments'; + SourceTable = Vendor; + // no InsertAllowed/ModifyAllowed override, no Editable = false anywhere + + layout + { + area(content) + { + repeater(GroupName) + { + field(no; Rec."No.") { } + field(vatRegNo; Rec."VAT Registration No.") { } + field(contactEmail; Rec."E-Mail") { } + // ...dozens more fields, none marked Editable = false + } + } + } +} diff --git a/microsoft/knowledge/web-services/api-page-least-privilege-write-access.good.al b/microsoft/knowledge/web-services/api-page-least-privilege-write-access.good.al new file mode 100644 index 0000000..b524b4f --- /dev/null +++ b/microsoft/knowledge/web-services/api-page-least-privilege-write-access.good.al @@ -0,0 +1,25 @@ +page 50102 "Vendor Contact Info API" +{ + PageType = API; + APIPublisher = 'contoso'; + APIGroup = 'integration'; + APIVersion = 'v1.0'; + EntityName = 'vendorContact'; + EntitySetName = 'vendorContacts'; + SourceTable = Vendor; + DelayedInsert = true; + InsertAllowed = false; + DeleteAllowed = false; + + layout + { + area(content) + { + repeater(GroupName) + { + field(no; Rec."No.") { Editable = false; } + field(contactEmail; Rec."E-Mail") { } + } + } + } +} diff --git a/microsoft/knowledge/web-services/api-page-least-privilege-write-access.md b/microsoft/knowledge/web-services/api-page-least-privilege-write-access.md new file mode 100644 index 0000000..6f40c87 --- /dev/null +++ b/microsoft/knowledge/web-services/api-page-least-privilege-write-access.md @@ -0,0 +1,26 @@ +--- +bc-version: [all] +domain: web-services +keywords: [api-page, least-privilege, write-access, odata, security, external-api, identity-fields] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Give API pages least-privilege write access + +## Description + +A general-purpose API page that exposes many fields should not be widened to allow writes on one additional field. A `PageType = API` page consumed by an external integration, an automation agent, or a partner system carries the same risk regardless of caller: a write-enabled page with no per-field restriction is a wide-open surface. Least privilege has to cover both dimensions of exposure: which fields are on the page, and which operations the page allows. Only a field actually placed on the page is reachable at all — but a page that includes many fields, with `InsertAllowed`/`ModifyAllowed`/`DeleteAllowed` left at their defaults and no `Editable = false` on most of them, leaves every one of those included fields — identity fields and financially significant ones among them — fully writable, with nothing marking that as deliberate. Restricting fields alone is not enough either: a page with only two fields on it can still let a caller insert brand-new records or delete existing ones if `InsertAllowed`/`DeleteAllowed` are left at their true defaults (both `true`). + +## Best Practice + +Create a separate, minimal API page that exposes only the key and the specific field the consumer needs to write, with everything else `Editable = false` or simply absent from the page — and set `InsertAllowed`/`DeleteAllowed` to `false` unless the consumer's use case genuinely needs to create or delete records through that page. + +See sample: [`api-page-least-privilege-write-access.good.al`](api-page-least-privilege-write-access.good.al). + +## Anti Pattern + +Widening an existing general-purpose API page with write access to one field, leaving every other field on the page (including identity and posting fields) writable by default because no one added `Editable = false`. + +See sample: [`api-page-least-privilege-write-access.bad.al`](api-page-least-privilege-write-access.bad.al). diff --git a/microsoft/skills/review/al-appsource-review.md b/microsoft/skills/review/al-appsource-review.md index 2efc049..c12815f 100644 --- a/microsoft/skills/review/al-appsource-review.md +++ b/microsoft/skills/review/al-appsource-review.md @@ -52,6 +52,7 @@ The following targeted checks cover every current `appsource` article across the - A page or report that repository context identifies as a direct user entry point omits `UsageCategory` or sets it to `None` — `set-usagecategory-on-searchable-entry-points`. Do not select this article based only on object type; exclude supporting parts, dialogs, API pages, and objects intentionally reached through another page. - A `DateTime` assignment adds or subtracts a fixed duration to represent an assumed regional offset — `do-not-hard-code-time-zone-offsets`. Require contextual evidence such as an hour-sized constant, offset-oriented name, or time-zone comment; do not flag deadlines, schedules, or elapsed-time calculations. - For BC v27 or later, `app.json` adds or changes the `help` URL to a path deeper than two levels, or a changed Copilot/context-sensitive help arrangement would ground the app under an overly broad truncated parent — `keep-copilot-help-url-to-two-path-levels`. +- A release/submission pipeline change (`AL-Go-Settings.json`, a publish/release workflow) or an `app.json` version bump is present without the new complete version being strictly greater than the previously submitted one, or the change asserts a hand-edited build/revision or every-merge-is-a-release policy as a universal AppSource rule rather than a project-specific workflow choice — `release-must-update-app-version`. Require repository/pipeline context to know the previously submitted version; a single `app.json` diff cannot prove ordering on its own. - Changed code declares or calls `File.Open`/`File.Create`/`File.Read`/`File.Write` in an app targeting Business Central Online — `file-datatype-saas`. Once the candidate worklist is known, resolve layer-precedence conflicts per READ. Drop lower-precedence files whose normative guidance (`## Best Practice` or `## Anti Pattern`) directly contradicts a higher-precedence candidate, and record each dropped file in `suppressed` with `reason: "layer-precedence"`. Files that would have been candidates but are hidden because their layer is disabled in consumer configuration are recorded with `reason: "configuration"`. Files that never became candidates are NOT recorded in `suppressed`. diff --git a/microsoft/skills/review/al-data-modeling-review.md b/microsoft/skills/review/al-data-modeling-review.md index e58b6b0..a73f929 100644 --- a/microsoft/skills/review/al-data-modeling-review.md +++ b/microsoft/skills/review/al-data-modeling-review.md @@ -46,6 +46,9 @@ A file enters the candidate worklist when its `keywords` intersect the extracted The following targeted checks cover every current `data-modeling` article. Treat each as a candidate-selection cue: when the signal appears in changed code, add the named article to the worklist and evaluate it in Action. - A `* Setup` table or its page changes singleton structure, uses a nonblank or generated key, permits insert/delete, uses a List page, or does not ensure the blank-keyed row exists — `setup-table-is-a-singleton`. +- A new field is typed `Media`, `MediaSet`, or `BLOB` and the field's caption/name suggests a picture or image — `pictures-must-use-media-not-blob`. +- Code outside a test codeunit or a demo-data generator calls `WorkDate(NewDate)` (the assignment form, not a bare `WorkDate()` read) as part of logic whose purpose is unrelated to the work date itself — `code-must-not-change-workdate`. A test deliberately setting a date context, or a demo-data routine that saves, sets, and restores the work date to backdate the data it creates, is not this anti-pattern. +- A new or extended table's name, fields, or usage positively establish it as one of Business Central's nine business-record types — a name ending `Ledger Entry`/`Register`/`Journal Line`/`Header`/`Line`/`Setup`, an auto-generated `Entry No.`/`No.` key posted from elsewhere, a `Template Name`+`Batch Name`+`Line No.` key, or a singleton `Primary Key` field — `table-design-must-match-bc-table-type-conventions`. Do not worklist it from a bare `keys` block or primary-key declaration alone: a temporary/buffer table, a work queue, a log, a cross-reference/mapping table, or a process-local staging table is not one of the nine types and is out of this rule's scope entirely, not an unresolved case. - Code reads `Item Ledger Entry."Document No."` (or `"Last Shipping No."`/`"Last Posting No."`) after a combined Ship+Invoice **sales** post — `item-ledger-entry-document-no-follows-last-shipping-no`. This is a sales-specific rule: purchase combined posting is Receive+Invoice and uses receiving fields such as `"Last Receiving No."`, not the shipment/document-number behavior this article describes. Do not worklist it from purchase posting code. - A custom master table changes its primary key, `No.`/`No. Series` fields, or `OnInsert` without assigning a blank `No.` from setup through a number series — `master-table-no-from-number-series-in-oninsert`. - BC v22 or later code introduces or retains `NoSeriesManagement`, `InitSeries`, `SelectSeries`, or `SetSeries`, or number assignment/manual-entry checks do not use codeunit `"No. Series"` methods such as `GetNextNo`, `IsManual`, or `TestManual` — `use-no-series-codeunit-not-noseriesmanagement`. diff --git a/microsoft/skills/review/al-error-handling-review.md b/microsoft/skills/review/al-error-handling-review.md index a340807..3962363 100644 --- a/microsoft/skills/review/al-error-handling-review.md +++ b/microsoft/skills/review/al-error-handling-review.md @@ -55,6 +55,8 @@ A file enters the candidate worklist when its `keywords` intersect the extracted The following targeted checks cover every current `error-handling` article: - `[ErrorBehavior(ErrorBehavior::Collect)]`, `ErrorInfo.Collectible`, `HasCollectedErrors`, `GetCollectedErrors`, or `ClearCollectedErrors` is added or changed, especially when errors are collected without later surfacing/clearing them — `collect-validation-errors-with-errorbehavior`. +- New or changed code inserts an error/duration log record around a failed `TryFunction`/`GetLastErrorText`/`GetLastErrorCode` path and then raises, propagates, or rethrows the error — `log-writes-must-survive-rollback`. Do not worklist it when the log insert already happens inside a `Session.StartSession`-targeted codeunit's `OnRun`; that is the compliant shape, not the signal to flag. +- A guarded lookup (`if Record.Get(...) then ... else` or similar) sets a value used later, and the same guard shape (with the same blank/zero fallback style) is applied to a field that feeds a posted amount, a tax/VAT calculation, a quantity or price actually used in a transaction, or a legally/compliance-facing output — `defensive-vs-offensive-code-must-match-blast-radius`. The signal is a posting-critical or compliance-facing field guarded defensively with a silent fallback, not the mere presence of a guarded lookup. - Developer-only invariant text is raised with default client visibility, or a user-actionable validation is hidden as `ErrorType::Internal` — `errortype-internal-vs-client-for-diagnostics`. - `FieldError` receives a complete capitalized sentence, repeats the field caption/value, or ends the predicate with punctuation — `fielderror-default-message-logic`. - An unguarded `FieldError` is used as though it performed a comparison, or `TestField` is forced onto a complex rule needing a tailored predicate — `fielderror-vs-testfield`. diff --git a/microsoft/skills/review/al-security-review.md b/microsoft/skills/review/al-security-review.md index e18d3fc..3d70173 100644 --- a/microsoft/skills/review/al-security-review.md +++ b/microsoft/skills/review/al-security-review.md @@ -39,7 +39,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially permission sets, codeunits handling authentication or authorization, objects touching `Isolated Storage`, `OAuth2` flows, web service endpoints, API pages, event publishers, and RecordRef helpers. - The changed procedures and triggers, weighted toward those that call `HttpClient`, validate or compose URLs, write to telemetry, read or write secrets, unwrap SecretText, manipulate record-level security, expose var Boolean guard parameters, or bypass the permission model (for example, `RecordRef.Open`, `Record.WritePermission`, direct table access from a non-owning app). -- Tokens extracted from the diff that relate to security concerns (`IsolatedStorage`, `SetEncrypted`, `OAuth2`, `SecretText`, `Unwrap`, `NonDebuggable`, `Password`, `Token`, `HttpClient`, `Uri`, `AreURIsHaveSameHost`, `IsValidURIPattern`, `RecordRef`, `RecordId`, `TransferFields`, `Codeunit.Run`, `Access = Internal`, `internalsVisibleTo`, `Open`, `IntegrationEvent`, `SkipValidation`, `HasAccess`, `Permission`, `UserSecurityId`, `Commit`, `SetFilter`). +- Tokens extracted from the diff that relate to security concerns (`IsolatedStorage`, `SetEncrypted`, `OAuth2`, `SecretText`, `Unwrap`, `NonDebuggable`, `Password`, `Token`, `HttpClient`, `Uri`, `AreURIsHaveSameHost`, `IsValidURIPattern`, `RecordRef`, `RecordId`, `TransferFields`, `Codeunit.Run`, `Access = Internal`, `internalsVisibleTo`, `Open`, `IntegrationEvent`, `SkipValidation`, `HasAccess`, `Permission`, `UserSecurityId`, `Commit`, `SetFilter`, `ServiceEnabled`, `PageType = API`, `QueryType = API`, `permissionset`, `Web Services`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. @@ -49,6 +49,7 @@ For secret values, select the most specific sink owner: - When a `Text`/`Code` credential is declared, passed, returned, or unwrapped without a visible HTTP URI/header/body sink, use `secrettext-for-credentials.md`. - When that value is interpolated into a URI, authorization header, or HTTP body and sent through `HttpClient`, use `secrettext-with-httpclient.md` as the primary finding. It supersedes the generic credential-type article at that location; keep the latter only as a supporting reference when useful. +- When a page/query is registered in Web Services, declares `PageType = API`/`QueryType = API`, a codeunit is registered in Web Services, or `[ServiceEnabled]` is added to a page procedure, and no permission set in the app grants a matching `page "..." = X` / `query "..." = X` / `codeunit "..." = X` entry for that specific object — use `exposed-objects-must-be-in-a-permission-set.md`. The anti-pattern is the exposed object missing its own execute entry, even when the underlying table's `tabledata` permissions look complete; require repository-level permission-set context, since one file cannot prove an entry is absent elsewhere in the app. Once the candidate worklist is known, resolve layer-precedence conflicts per READ. Drop lower-precedence files whose normative guidance (`## Best Practice` or `## Anti Pattern`) directly contradicts a higher-precedence candidate, and record each dropped file in `suppressed` with `reason: "layer-precedence"`. Files that would have been candidates but are hidden because their layer is disabled in consumer configuration are recorded with `reason: "configuration"`. Files that never became candidates are NOT recorded in `suppressed`. diff --git a/microsoft/skills/review/al-style-review.md b/microsoft/skills/review/al-style-review.md index 0cc747e..2aaf902 100644 --- a/microsoft/skills/review/al-style-review.md +++ b/microsoft/skills/review/al-style-review.md @@ -52,6 +52,9 @@ Apply these high-signal mappings before fuzzy topic ranking: - A `Label` or `TextConst` contains multiple or ambiguous placeholders but has no `Comment`, or its Comment does not explain every placeholder — `label-comment-explains-placeholders.md`. A single placeholder whose meaning is explicit in the text, such as `Customer %1`, is allowed without a Comment and must not be flagged. - A normal two-argument `Evaluate` has a resolved `DateFormula` destination and a hard-coded non-angle-bracket date-formula literal, directly or through a visible constant — `dateformula-evaluate-needs-language-independent-literals.md`. Do not use this cue for dynamic/localized external input, already invariant `<...>` input, or direct `CalcDate(Text, ...)` calls. - `function-call-parentheses-required.md` applies only to a zero-argument invocation written without `()`. Never worklist it from an invocation that already has parentheses or supplies arguments, including `Error(Label, Arg1, Arg2)`. +- A new or changed comment restates what the adjacent code already makes obvious from its own names and structure (a comment that just repeats a variable/field/method name in prose) rather than explaining a non-obvious constraint, invariant, or workaround — `al-comments-must-not-restate-what-code-already-shows.md`. A comment absent entirely is not this anti-pattern; only a present-but-redundant comment is. +- A `page`/`pageextension` adds or changes a procedure body that performs a calculation, validation, or record mutation belonging to a business operation reused across entry points, rather than presentation-specific state or a call into a codeunit — `pages-must-not-contain-business-logic.md`. A page calling a codeunit procedure, or a page's own presentation-only state and formatting, is not this anti-pattern; nor is a data invariant that belongs on the table itself. +- Changed source files are added under an object-type folder (`Tables/`, `Pages/`, `Codeunits/`, etc.) in a repository whose existing structure is predominantly feature-based, or vice versa — `source-organized-by-feature-not-object-type.md`. The anti-pattern is inconsistency with the repository's own established convention, not the choice of either scheme; a repository consistently organized by object type throughout is not a violation. Require repository-level folder context; a single new file's path cannot prove the project's convention alone. - A new `.app` build artifact appears at the project root or another unversioned/arbitrary location, or is added to source control alongside the AL source that produced it — `al-build-output-must-not-pollute-project-root.md`. A deliberate `--outfolder`/`outputPath` destination added to `.gitignore` is the compliant shape, not the signal to flag. - A new or renamed AL identifier (variable, procedure, parameter, field, object, enum value, or label identifier) contains non-English words — `al-identifiers-english.md`. A caption, tooltip, or other user-facing text value in a non-English language is not this anti-pattern; only the identifier itself is in scope. - A field or variable is typed `Boolean` and its two possible values are genuinely named domain alternatives (a status pair like Inbound/Outbound, Debit/Credit, Buy/Sell) rather than a true/false predicate, or an `Option`/`Enum`/`Integer` models a domain concept that is intrinsically a yes/no flag — `binary-choice-must-be-boolean.md`. The signal is a semantic mismatch between the type and the domain concept, not the current number of states. diff --git a/microsoft/skills/review/al-testing-review.md b/microsoft/skills/review/al-testing-review.md index 2adbc13..5bc30c8 100644 --- a/microsoft/skills/review/al-testing-review.md +++ b/microsoft/skills/review/al-testing-review.md @@ -46,6 +46,11 @@ A file enters the candidate worklist when its `keywords` intersect the extracted The following targeted checks cover every current `testing` article. Treat each as a candidate-selection cue: when the signal appears in changed code, add the named article to the worklist and evaluate it in Action. - A method in a `Subtype = Test` codeunit adds or changes `[TransactionModel(...)]`, exercises code that calls `Commit` under `AutoRollback`, defaults broadly to `AutoCommit`, or chooses `None` for a writing test — `transactionmodel-attribute-governs-test-transactions`. +- A new or changed `[Test]` procedure is added, whether or not it already carries `[FEATURE]`/`[SCENARIO]`/`[GIVEN]`/`[WHEN]`/`[THEN]` tags — `test-feature-scenario-tags`. A procedure with no tags at all, or a generic name like `Test1`, is the anti-pattern signal; presence of the tags is the compliant shape, not the thing to search for. +- A test codeunit calls `TestPage` methods (`OpenNew`, `OpenView`, `OpenEdit`) alongside `[Test]` procedures in the same codeunit that call business-logic procedures directly with no `TestPage` involved — `ui-test-codeunit-naming`. The anti-pattern signal is both kinds of test mixed into one codeunit (or, on a project using the `_UT` convention, a UI-layer codeunit missing the suffix); a codeunit containing only `TestPage`-driven tests is not itself a violation. +- A `[GIVEN]`-tagged setup precedes a posting call or report execution and does not visibly set up posting-group/VAT setup records, an explicit date, or (for a report test) both an included and an excluded record — `given-blocks-must-cover-full-precondition-chain`. +- A test procedure contains more than one `[WHEN]` block, or more than one distinct action not labelled `[GIVEN]`, without the procedure name declaring a flow/defect-then-fix shape — `test-one-when-per-test`. +- A `BCPT*` scenario codeunit is added and the PerformanceTest app's only other scenario codeunits are copies of Microsoft's shipped BCPT samples (`BCPT Create Customer`, `BCPT Create Item Journal`, `BCPT Post GL Entries`, etc.) with no scenario exercising the extension's own codeunits, FlowFields, or pages — `bcpt-scenarios-must-be-app-specific`. - An `AutoCommit` test runs under a `Subtype = TestRunner` codeunit that omits `TestIsolation` or sets it to `Disabled`, leaving committed data between tests — `testisolation-belongs-on-the-test-runner`. Require runner/repository context; a standalone test file cannot prove which runner executes it. - A permission-sensitive test uses `TestPermissions = Disabled`, claims to test a restricted user without `"Permissions Mock"`/`"Library - Lower Permissions"`, or declares `[TestPermissions(...)]` without applying that context — `permission-tests-must-lower-the-execution-context`. - Test fixture code manually calls `Init`/`Insert`, invents keys or prerequisite records, or bypasses available `LibrarySales`, `LibraryPurchase`, `LibraryERM`, `LibraryInventory`, `LibraryRandom`, or equivalent library codeunits — `use-library-codeunits-for-test-fixtures`. diff --git a/microsoft/skills/review/al-ui-review.md b/microsoft/skills/review/al-ui-review.md index 8c35f49..f54c0c9 100644 --- a/microsoft/skills/review/al-ui-review.md +++ b/microsoft/skills/review/al-ui-review.md @@ -40,8 +40,9 @@ Discard files that are not applicable. Retain conditionally applicable files onl Narrow the relevant files to the subset that applies to the changes under review. - **UI-file filter.** UI review applies to files declaring `page`, `pageextension`, or `pagecustomization`, and to JavaScript/CSS/HTML that implements a control add-in's rendering or Business Central communication. When the diff contains no such files, return `outcome: "not-applicable"` without evaluating knowledge files. +- A new or changed page's name/suffix, primary-key handling, `CardPageID`, `SubPageLink`, `AutoSplitKey`, or `UsageCategory` doesn't match the conventions of its own declared `PageType` — `page-design-must-match-bc-page-type-conventions.md`. A Card page over a composite-key table that supplements a master record, or a supporting/subpage/dialog page intended only to be reached through another workflow and correctly omitting `UsageCategory`, is not this anti-pattern on its own; check whether the page is actually mixing conventions or is meant as a searchable entry point before flagging. - For each relevant knowledge file, compute overlap against changed page declarations and control add-in files, weighted toward `Caption`, `ToolTip`, `AboutTitle`, `AboutText`, `OptionCaption`, `ShowCaption`, `InstructionalText`, `GridLayout`, `Style`, `StyleExpr`, promoted action definitions, field importance, page background tasks, DOM creation, ARIA attributes, keyboard/focus handlers, packaged-resource AJAX, and calls from JavaScript into AL. -- Tokens extracted from the diff (`Caption`, `ToolTip`, `AboutTitle`, `AboutText`, `PageType`, `ShowCaption`, `InstructionalText`, `grid`, `fixed`, `GridLayout`, `Style`, `StyleExpr`, `Importance`, `Promoted`, `Additional`, `area(Promoted)`, `actionref`, `PromotedCategory`, `PromotedOnly`, `PromotedIsBig`, `ShowAs`, `SplitButton`, `fieldgroups`, `DropDown`, `UpdatePropagation`, `EnqueueBackgroundTask`, `OnAfterGetCurrRecord`, `OnAfterGetRecord`, `OnPageBackgroundTaskCompleted`, `OnPageBackgroundTaskError`, `RunPageBackgroundTask`, `Favorable`, `Unfavorable`, `Ambiguous`, `cuegroup`, `controladdin`, `control-add-in`, `usercontrol`, `aria-`, `tabindex`, `keydown`, `focus`, `innerHTML`, `createElement`, `packaged-resource`, `ajax`, `$.get`, `$.ajax`, `XMLHttpRequest`, `xhrFields`, `withCredentials`, `withcredentials`, `InvokeExtensibilityMethod`, `invokeextensibilitymethod`, `skipIfBusy`, `successCallback`, `success-callback`, `errorCallback`, `setInterval`, `JSON.stringify`, `payload`, `throttling`, `reduced-functionality`, `ClientServicesMaxUploadSize`, `&`, `Specifies`, `Message(`, `Confirm(`, `Error(` in a page context, `Disabled`, `Invalid`, `Whitelist`, `Blacklist`, trailing punctuation patterns on captions). +- Tokens extracted from the diff (`Caption`, `ToolTip`, `AboutTitle`, `AboutText`, `PageType`, `ShowCaption`, `InstructionalText`, `grid`, `fixed`, `GridLayout`, `Style`, `StyleExpr`, `Importance`, `Promoted`, `Additional`, `area(Promoted)`, `actionref`, `PromotedCategory`, `PromotedOnly`, `PromotedIsBig`, `ShowAs`, `SplitButton`, `fieldgroups`, `DropDown`, `UpdatePropagation`, `EnqueueBackgroundTask`, `OnAfterGetCurrRecord`, `OnAfterGetRecord`, `OnPageBackgroundTaskCompleted`, `OnPageBackgroundTaskError`, `RunPageBackgroundTask`, `Favorable`, `Unfavorable`, `Ambiguous`, `cuegroup`, `controladdin`, `control-add-in`, `usercontrol`, `aria-`, `tabindex`, `keydown`, `focus`, `innerHTML`, `createElement`, `packaged-resource`, `ajax`, `$.get`, `$.ajax`, `XMLHttpRequest`, `xhrFields`, `withCredentials`, `withcredentials`, `InvokeExtensibilityMethod`, `invokeextensibilitymethod`, `skipIfBusy`, `successCallback`, `success-callback`, `errorCallback`, `setInterval`, `JSON.stringify`, `payload`, `throttling`, `reduced-functionality`, `ClientServicesMaxUploadSize`, `&`, `Specifies`, `Message(`, `Confirm(`, `Error(` in a page context, `Disabled`, `Invalid`, `Whitelist`, `Blacklist`, trailing punctuation patterns on captions, `CardPageID`, `AutoSplitKey`, `PageType = Card`, `PageType = List`, `PageType = Worksheet`, `PageType = Document`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed page element. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. diff --git a/microsoft/skills/review/al-upgrade-review.md b/microsoft/skills/review/al-upgrade-review.md index 9ae61f8..dce1053 100644 --- a/microsoft/skills/review/al-upgrade-review.md +++ b/microsoft/skills/review/al-upgrade-review.md @@ -45,6 +45,7 @@ Narrow the relevant files to the subset that applies to the changes under review - Worklist the install-versus-upgrade rule when migration helpers are reachable only from an install codeunit. - Worklist `install-and-upgrade-codeunits-have-no-order.md` when a change adds multiple install or upgrade codeunits whose same-phase triggers share state or depend on one another. - Worklist `appversion-meaning-depends-on-execution-context.md` when install or upgrade code branches on `ModuleInfo.AppVersion()` or confuses it with `DataVersion()`. +- An upgrade tag's existence check (`HasUpgradeTag`) is nested inside another tag's guarded body, or one tagged procedure performs two or more functionally unrelated migrations (different tables, fields, or concerns) under a single tag, or one procedure mixes the gated logic for more than one distinct upgrade tag — `upgrade-tag-logic-must-not-nest-deeply.md`. Do not flag record loops or business-data safety guards (corruption checks, redundant-write checks, or other conditions) that serve the single migration the tag represents, however many `if` levels they take — that is the compliant shape the article explicitly permits. A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. When the diff contains no upgrade-related changes by any of the above signals, return `outcome: "not-applicable"` without evaluating files. diff --git a/microsoft/skills/review/al-web-services-review.md b/microsoft/skills/review/al-web-services-review.md index b86c79b..6d7d71a 100644 --- a/microsoft/skills/review/al-web-services-review.md +++ b/microsoft/skills/review/al-web-services-review.md @@ -42,6 +42,7 @@ Narrow the relevant files to the subset that applies to the changes under review - Outbound HTTP integration code that constructs or sends requests, captures a client method's optional Boolean result, checks an `HttpResponseMessage`, or reads and parses response content. - Integration code that converts values to or from exchanged text: `Format` or `Evaluate` on a request URL, body, or file line, and `JsonToken`/`JsonValue` conversions of payload properties. - Webhook subscriber handlers and subscription lifecycle code, especially code that creates or renews subscriptions, handles `validationToken`, schedules from `expirationDateTime`, or targets resources whose eligibility is visible in the diff. +- An API page (`PageType = API`) is added or changed and its `InsertAllowed`/`ModifyAllowed`/`DeleteAllowed` properties are left at their default `true` (or explicitly set `true`) for an operation the endpoint's stated purpose does not need — `api-page-least-privilege-write-access.md`. The signal is an operation left enabled beyond what the endpoint's own described purpose requires, not the mere presence of these properties; a page that genuinely needs full CRUD and grants it deliberately is not a violation. - An API page (`PageType = API`) with `InsertAllowed = true` lists a field in `ODataKeyFields` and that same field control sets `Editable = false` — `api-page-key-fields-must-be-editable-on-insert.md`. A system-generated key such as `SystemId` marked read-only is not this anti-pattern. - An API page exposes a field via `Rec` directly, and that field is a stored value computed from other fields inside an `OnValidate` trigger rather than a FlowField recalculated in `OnAfterGetRecord` — `stored-derived-fields-must-not-be-exposed-directly.md`. Exposing a genuine FlowField, or a value already recalculated in `OnAfterGetRecord`, is not this anti-pattern. - Tokens extracted from the diff that relate to API surface and behaviour (`PageType`, `QueryType`, `API`, `api-page`, `page-part`, `APIPublisher`, `APIGroup`, `APIVersion`, `EntityName`, `EntitySetName`, `ODataKeyFields`, `SystemId`, `SubPageLink`, `subpagelink`, `Multiplicity`, `multiplicity`, `Many`, `ZeroOrOne`, `SourceTableTemporary`, `Job Queue Entry`, `webhook`, `webhookSupportedResources`, `webhook-supported-resources`, `subscriptions`, `notificationUrl`, `validationToken`, `validationtoken`, `expirationDateTime`, `expirationdatetime`, `ServiceEnabled`, `WebServiceActionContext`, `SetActionResponse`, `ReadIsolation`, `IsolationLevel`, `ReadCommitted`, `InsertAllowed`, `ModifyAllowed`, `DeleteAllowed`, `Editable`, `SourceTable`, `HttpClient`, `HttpRequestMessage`, `HttpResponseMessage`, `Get`, `Post`, `Put`, `Delete`, `Send`, `IsSuccessStatusCode`, `HttpStatusCode`, `Content`, `ReadAs`, `JsonObject`, `JsonToken`, `JsonValue`, `AsValue`, `IsNull`, `SelectToken`, `Format`, `Evaluate`, `XmlDocument`). From 830eaff68f92128dc764275d2b93b4b4e315ea77 Mon Sep 17 00:00:00 2001 From: Michael Dieringer <65093775+MichaelDieringer@users.noreply.github.com> Date: Tue, 29 Sep 2026 17:13:06 +0200 Subject: [PATCH 31/35] 3 AL/BC testing patterns from an external BC testing expert's blog (Luc van Vugt, fluxxus.nl) (#159) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add 4 more AL/BC testing patterns from Luc van Vugt's fluxxus.nl blog Fourth batch from CURABIS ApS, mined from an external BC/NAV testing expert's blog archive (fluxxus.nl). Confirm+StrSubstNo interaction with ConfirmHandler, Table Relation Test's OnAfterRemoveTableRelation exclusion hook (verified against BCApps source, codeunit 134926), committing shared lazy-Initialize fixture data, and Assert.IsFalse vs asserterror for boolean checks. * Address Jesper Schulz-Wedde's review on PR #159 - transactionmodel-attribute-governs-test-transactions.md: the "Commit causes an error" behavior is specific to an explicitly declared AutoRollback attribute. A test method with no TransactionModel attribute at all is a distinct, valid shape — BCApps' own codeunit 134915 "ERM Online Mapping Setup" commits inside a lazy Initialize() with no attribute declared, cleaning up via a manual asserterror at the end. Evidence for commit-shared-test-fixture- inside-lazy-initialize.md (this PR), which is correct as submitted. - confirm-needs-strsubstno-before-confirmhandler-sees-substituted-text.md: reframe as a known, unconfirmed-fix platform defect (microsoft/ALAppExtensions#23935) rather than designed behavior; add the Message/MessageHandler asymmetry as supporting evidence. - table-relation-test-exclude-known-invalid-relations-via-event.md: note the test-app-only consumer dependency; correct "walks every TableRelation field property in the app" to the actual tenant-wide Table Relations Metadata scope across installed apps. - Wire confirm-needs-strsubstno, commit-shared-test-fixture-inside- lazy-initialize, and table-relation-test-exclude-known-invalid- relations-via-event into al-testing-review.md's candidate-selection cues. Co-Authored-By: Claude Sonnet 5 * Address second round of Jesper Schulz-Wedde's review on PR #159 - commit-shared-test-fixture-inside-lazy-initialize.md: fundamentally rewritten. AutoCommit is the documented default TransactionModel, not AutoRollback. Explains the real mechanism (Commit() protects a fixture from the test method's own later deliberate rollback, per Codeunit.Run/ TransactionModel-property semantics) and the TestIsolation dependency (Disabled/Codeunit survive across methods, Function does not). Fixtures rewritten to demonstrate the actual failure/success shape. - transactionmodel-attribute-governs-test-transactions.md: now states the AutoCommit default explicitly and agrees with the article above, closing the contradiction Jesper flagged between the two testing articles. - Deleted confirm-needs-strsubstno-before-confirmhandler-sees-substituted-text (.md/.good.al/.bad.al): the underlying platform bug (microsoft/ ALAppExtensions#23935) was closed as completed in Feb 2024; cannot be reproduced or bc-version-pinned on any currently supported version. - table-relation-test-exclude-known-invalid-relations-via-event.md: added the [Scope('OnPrem')] boundary verified against BCApps' Table Relation Test codeunit. - use-assert-isfalse-not-asserterror-for-boolean-checks.md: added a Scope section resolving the overlap with asserterror-needs-expectederror-and-code. - al-testing-review.md: fixed the shared-fixture cue to catch the actual anti-pattern instead of the compliant shape, added the missing cue for use-assert-isfalse-not-asserterror-for-boolean-checks, wired precedence between it and the generic asserterror rule, and removed the cue for the deleted article. - Added in-file Source provenance (specific fluxxus.nl post per article, with what was independently verified vs. taken from the post) to the three surviving externally-inspired articles, per Jesper's request that provenance live in the knowledge file itself, not only the PR description. Co-Authored-By: Claude Sonnet 5 * Fix remaining correctness issues from Jesper's 2026-09-15 re-review - commit-shared-test-fixture-inside-lazy-initialize: three sub-issues. Recommended TestIsolation = Codeunit instead of listing Disabled as an equal option - Disabled never rolls back at all ("tests are not isolated from each other" per the property's own docs), so a fixture this pattern commits under Disabled is permanent database contamination unless something else tears it down; Disabled is now only mentioned alongside that explicit teardown requirement. Added precedence in al-testing-review.md so the deliberate end-of-test asserterror Error(...) rollback sentinel isn't also flagged by the generic asserterror-needs-expectederror-and-code rule. Rewrote both fixtures to actually demonstrate the pattern: persisted fixture data (an Item record) instead of an empty comment, a second [Test] method that depends on the fixture surviving into it, and an explicit Subtype = TestRunner / TestIsolation = Codeunit runner codeunit. - table-relation-test-exclude-known-invalid-relations-via-event: the length/type rule was stated as one global requirement. Verified ValidateFieldRelation in codeunit 134926 directly (BCApps reference clone) and split it into the two branches the source actually has: a field with any unconditional relation needs exact length and exact resolved type; a field whose relations are all conditional only fails on being shorter (longer is fine) than the largest related field, and when the required type is specifically Code, a Text source passes too - a tolerance that does not apply on the unconditional side and does not extend to a required Text. Rebased onto upstream/main (one conflict in transactionmodel-attribute-governs-test-transactions.md - upstream had already linked its sample references via the READ convention, ours added a Source section; merged both). Also converted the 3 remaining plain-backtick sample references in this PR to the READ-convention markdown-link form, same fix as #156/#157/#158. * Fix four merge-critical issues from Jesper's 2026-09-22 review - al-testing-review.md: the generic ExpectedError cue's asserterror Assert.IsTrue/IsFalse exclusion was unconditional, but the specialized rule it deferred to only claims the pure-inversion shape. A test expecting the guarded Boolean-returning call itself to raise fell through both routes. Narrowed the exclusion to the same inversion-only condition the specialized cue already uses. - asserterror-needs-expectederror-and-code.md: the rollback-sentinel exception (a trailing asserterror Error(...) used purely to force a fixture rollback, not to verify a specific failure) previously lived only in skill routing prose. Encoded it directly in the article's Anti Pattern section so every consumer of the knowledge base sees it, not just this one skill. - commit-shared-test-fixture-inside-lazy-initialize.good.al/.bad.al: replaced hand-rolled Item.Init()/Insert(true) with LibraryInventory.CreateItem, so the canonical fixture doesn't itself trigger use-library-codeunits-for-test-fixtures. - table-relation-test-exclude-known-invalid-relations-via-event.good.al/ .bad.al: declared minimal "Sample Setup"/"Sample Header" tables inline instead of referencing undefined symbols, matching this repo's own convention that every fixture is self-contained. * Give the table-relation-test fixtures a real relation to exclude and one to protect The "Category Code" field had no TableRelation at all, so the good subscriber's RemoveTableRelation call targeted metadata that never existed - a no-op. Added a real TableRelation to "Sample Setup" on that field (the one known exception to exclude) and a second, ordinary self-referencing relation ("Parent No." -> "Sample Header"."No.") with no exception. The good fixture now removes only the first; the bad fixture's table-wide removal (field/related table/field all 0) now demonstrably also strips the second, showing the actual anti-pattern instead of removing nothing meaningful. --------- Co-authored-by: Claude Sonnet 5 Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- ...sserterror-needs-expectederror-and-code.md | 2 + ...test-fixture-inside-lazy-initialize.bad.al | 73 +++++++++++++++++++ ...est-fixture-inside-lazy-initialize.good.al | 71 ++++++++++++++++++ ...red-test-fixture-inside-lazy-initialize.md | 34 +++++++++ ...e-known-invalid-relations-via-event.bad.al | 47 ++++++++++++ ...-known-invalid-relations-via-event.good.al | 51 +++++++++++++ ...clude-known-invalid-relations-via-event.md | 35 +++++++++ ...del-attribute-governs-test-transactions.md | 10 ++- ...-not-asserterror-for-boolean-checks.bad.al | 18 +++++ ...not-asserterror-for-boolean-checks.good.al | 18 +++++ ...alse-not-asserterror-for-boolean-checks.md | 34 +++++++++ microsoft/skills/review/al-testing-review.md | 5 +- 12 files changed, 394 insertions(+), 4 deletions(-) create mode 100644 microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.bad.al create mode 100644 microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.good.al create mode 100644 microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.md create mode 100644 microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.bad.al create mode 100644 microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.good.al create mode 100644 microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.md create mode 100644 microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.bad.al create mode 100644 microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.good.al create mode 100644 microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.md diff --git a/microsoft/knowledge/testing/asserterror-needs-expectederror-and-code.md b/microsoft/knowledge/testing/asserterror-needs-expectederror-and-code.md index 4560a18..9ebf3f8 100644 --- a/microsoft/knowledge/testing/asserterror-needs-expectederror-and-code.md +++ b/microsoft/knowledge/testing/asserterror-needs-expectederror-and-code.md @@ -23,4 +23,6 @@ See sample: [`asserterror-needs-expectederror-and-code.good.al`](asserterror-nee `asserterror DoInvalid();` with nothing after it. The test asserts only that the call failed somehow; swap the validation for a different bug and the test still passes, certifying a guard that may no longer fire. A negative test that cannot tell one error from another verifies almost nothing. +Not an instance of this anti-pattern: a trailing `asserterror Error(SomeLabel)` used purely as an end-of-test rollback sentinel to undo a lazily-initialized shared fixture's scratch changes (see `commit-shared-test-fixture-inside-lazy-initialize.md`). That `Error` call exists to force a rollback, not to verify that a specific failure occurred — the sentinel's own text is not meant to be asserted against, and adding an `ExpectedError` there would just duplicate the label without checking anything the test doesn't already control. + See sample: [`asserterror-needs-expectederror-and-code.bad.al`](asserterror-needs-expectederror-and-code.bad.al). diff --git a/microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.bad.al b/microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.bad.al new file mode 100644 index 0000000..f2af637 --- /dev/null +++ b/microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.bad.al @@ -0,0 +1,73 @@ +codeunit 50142 "Sample Test Library" +{ + Subtype = Test; + + var + LibraryInventory: Codeunit "Library - Inventory"; + Initialized: Boolean; + SharedItemNo: Code[20]; + RollBackMsg: Label 'Revert back the tables to their original state.'; + + local procedure Initialize() + begin + if Initialized then + exit; + + CreateSharedFixtureData(); + // BUG: no Commit() here. The fixture below is still inside this + // test method's own transaction. + Initialized := true; + end; + + local procedure CreateSharedFixtureData() + var + Item: Record Item; + begin + LibraryInventory.CreateItem(Item); + SharedItemNo := Item."No."; + end; + + [Test] + procedure FirstTestUsesSharedFixture() + var + Item: Record Item; + begin + Initialize(); + + Item.Get(SharedItemNo); + Item.Description := 'Scratch change this test makes and does not need to keep.'; + Item.Modify(); + + asserterror Error(RollBackMsg); + // The deliberate rollback above also erases the never-committed + // fixture from CreateSharedFixtureData(). Initialized still reads + // true on the next test, but the row it points at is gone. + end; + + [Test] + procedure SecondTestStillFindsSharedFixture() + var + Item: Record Item; + begin + Initialize(); + + // Fails here: Initialize() saw Initialized = true and returned + // immediately, so it never recreated the fixture - and the first + // test's rollback took the original row with it. + Item.Get(SharedItemNo); + end; +} + +codeunit 50143 "Sample Test Runner" +{ + // Codeunit isolation alone does not save this fixture: TestIsolation + // only controls whether committed changes survive between methods, and + // this fixture was never committed in the first place. + Subtype = TestRunner; + TestIsolation = Codeunit; + + trigger OnRun() + begin + Codeunit.Run(Codeunit::"Sample Test Library"); + end; +} diff --git a/microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.good.al b/microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.good.al new file mode 100644 index 0000000..c550697 --- /dev/null +++ b/microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.good.al @@ -0,0 +1,71 @@ +codeunit 50142 "Sample Test Library" +{ + Subtype = Test; + + var + LibraryInventory: Codeunit "Library - Inventory"; + Initialized: Boolean; + SharedItemNo: Code[20]; + RollBackMsg: Label 'Revert back the tables to their original state.'; + + local procedure Initialize() + begin + if Initialized then + exit; + + CreateSharedFixtureData(); + Commit(); + Initialized := true; + end; + + local procedure CreateSharedFixtureData() + var + Item: Record Item; + begin + LibraryInventory.CreateItem(Item); + SharedItemNo := Item."No."; + end; + + [Test] + procedure FirstTestUsesSharedFixture() + var + Item: Record Item; + begin + Initialize(); + + Item.Get(SharedItemNo); + Item.Description := 'Scratch change this test makes and does not need to keep.'; + Item.Modify(); + + asserterror Error(RollBackMsg); + // Rolls back the Modify() above, but not the fixture: that was + // already committed inside Initialize(). + end; + + [Test] + procedure SecondTestStillFindsSharedFixture() + var + Item: Record Item; + begin + // Runs after FirstTestUsesSharedFixture's deliberate rollback. + // Initialize() sees Initialized = true and does nothing, but the + // committed fixture it created earlier is still there to Get(). + Initialize(); + + Item.Get(SharedItemNo); + end; +} + +codeunit 50143 "Sample Test Runner" +{ + // Codeunit isolation: everything this codeunit's tests commit, + // including the shared fixture, survives from one test method to the + // next, and rolls back only once every method in the codeunit has run. + Subtype = TestRunner; + TestIsolation = Codeunit; + + trigger OnRun() + begin + Codeunit.Run(Codeunit::"Sample Test Library"); + end; +} diff --git a/microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.md b/microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.md new file mode 100644 index 0000000..7ec16df --- /dev/null +++ b/microsoft/knowledge/testing/commit-shared-test-fixture-inside-lazy-initialize.md @@ -0,0 +1,34 @@ +--- +bc-version: [all] +domain: testing +keywords: [initialize, isinitialized, shared-fixture, commit, autocommit, asserterror, testisolation, lazy-initialization] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Commit shared fixture data created inside a lazy Initialize(), or later tests lose it + +## Description + +A test method with no `[TransactionModel(...)]` attribute defaults to `AutoCommit` (see `transactionmodel-attribute-governs-test-transactions.md`): a method that completes without error commits automatically at its own boundary, with no explicit `Commit()` needed. So a lazy/shared `Initialize()` — guarded by an `IsInitialized` flag, creating master/setup data once to avoid repeating expensive setup across many `[Test]` methods — does not need `Commit()` just to survive into the next test method; under the default model it already will. (Declaring `[TransactionModel(AutoRollback)]` instead is not compatible with this pattern at all: `AutoRollback` assumes the code under test never commits, and a `Commit()` call under it raises a runtime error.) + +What an early `Commit()` inside `Initialize()` actually guards against is the test method's *own later, deliberate* rollback — the BCApps cleanup idiom of ending a test with `asserterror Error(SomeLabel)` to undo demo-data mutations that method made, so the run doesn't permanently dirty the database. Per the documented `Codeunit.Run` transaction semantics, changes are committed at the end of an execution "unless an error occurs" — an unhandled error rolls back whatever wasn't already committed. `Commit()` closes out the fixture's own transaction immediately, so it is unaffected by whatever the rest of that method does afterward, including that end-of-test error. Without the early `Commit()`, the same deliberate rollback wipes out the fixture too, even though `IsInitialized` still reads `true` on the next test, since it's a plain variable, not persisted data. BCApps' `codeunit 134915 "ERM Online Mapping Setup"` shows exactly this shape: no `TransactionModel` attribute, `Commit()` inside a lazy `Initialize()`, and the test itself ends with `asserterror Error(RollBackMessage)`. + +Protecting the fixture from that same-method rollback is necessary but not sufficient for the fixture to reach a *later* test method — that also depends on the executing test runner's `TestIsolation`. Under `Disabled` (the property's own documented default) or `Codeunit` (used by BCApps' own `TestRunner`, `CLITestRunner`, and `SnapTestRunner` codeunits), nothing rolls back until the whole test codeunit finishes, so the already-committed fixture survives across every method run before then. These two are not interchangeable, though: `Codeunit` rolls back everything once the codeunit's last method completes, so the environment is clean afterward; `Disabled` never rolls back anything at all — "tests are not isolated from each other" is the property's own description — so a fixture this pattern commits stays in the database permanently unless something else explicitly deletes it. Under `Function`, the runner rolls back all database changes — explicitly including ones already committed via `Commit()` — after every single test method; no amount of committing inside `Initialize()` makes a fixture shared across methods survive that regime, because the whole premise of a lazy, once-per-codeunit fixture doesn't hold when every method is isolated from every other. + +## Best Practice + +When a test method's own cleanup relies on ending in a deliberate error to roll back its scratch changes, call `Commit()` once, inside the lazy `Initialize()` guard, right after the shared fixture is created — before that cleanup-triggering error can run. This pattern only delivers a fixture shared across test methods when the executing runner's `TestIsolation` is `Disabled` or `Codeunit`; do not recommend it, or pair it with, a `Function`-isolated runner — that configuration undoes the committed fixture after every method regardless. Recommend `TestIsolation = Codeunit`: it gives every method in the codeunit the same shared, committed fixture and still leaves the database clean once the codeunit finishes. Recommend `Disabled` only alongside an explicit, verified teardown step that removes the fixture data at the end of the run — without one, the committed fixture is permanent contamination, not a controlled trade-off. + +See sample: [`commit-shared-test-fixture-inside-lazy-initialize.good.al`](commit-shared-test-fixture-inside-lazy-initialize.good.al). + +## Anti Pattern + +A shared `Initialize()` guarded by `IsInitialized` that creates fixture records without committing, in a test method that ends with a deliberate `asserterror Error(...)` to undo its own scratch changes, run under a `Disabled`- or `Codeunit`-isolated test runner. That rollback also erases the never-committed fixture; the next test still finds `IsInitialized = true` but the rows it depends on are gone. (Under a `Function`-isolated runner the fixture is lost regardless of `Commit()`, for the unrelated reason above — that is a runner-configuration problem, not this anti-pattern.) + +See sample: [`commit-shared-test-fixture-inside-lazy-initialize.bad.al`](commit-shared-test-fixture-inside-lazy-initialize.bad.al). + +## Source + +The shared/lazy `Initialize()` pattern and its `Commit()` call are drawn from Luc van Vugt's "Let's talk about Shared Fixture and how to profit from this with the Dynamics NAV Test Toolkit": https://www.fluxxus.nl/index.php/bc/let39s-talk-about-shared-fixture-and-how-to-profit-from-this-with-the-dynamics-nav-test-toolkit/. That post shows the `Commit()` call in its `Initialize()` example but does not explain the transaction mechanics behind it; the `AutoCommit`-default, `Codeunit.Run`-error, and `TestIsolation`-level analysis above is this article's own, verified independently against Microsoft's TransactionModel/TestIsolation documentation and BCApps' `codeunit 134915 "ERM Online Mapping Setup"` source, not taken from the post. diff --git a/microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.bad.al b/microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.bad.al new file mode 100644 index 0000000..d95d9f2 --- /dev/null +++ b/microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.bad.al @@ -0,0 +1,47 @@ +table 50144 "Sample Setup" +{ + fields + { + field(1; "Primary Key"; Code[10]) { } + field(2; "Default Category Code"; Code[20]) { } + } + keys + { + key(PK; "Primary Key") { Clustered = true; } + } +} + +table 50145 "Sample Header" +{ + fields + { + field(1; "No."; Code[20]) { } + field(10; "Category Code"; Code[10]) + { + TableRelation = "Sample Setup"."Primary Key"; + } + field(11; "Parent No."; Code[20]) + { + TableRelation = "Sample Header"."No."; + } + } + keys + { + key(PK; "No.") { Clustered = true; } + } +} + +codeunit 50141 "Sample Table Relation Test Ext" +{ + [EventSubscriber(ObjectType::Codeunit, Codeunit::"Table Relation Test", 'OnAfterRemoveTableRelation', '', false, false)] + local procedure ExcludeSampleFieldFromTableRelationTest(var TableRelationsMetadata: Record "Table Relations Metadata" temporary) + var + TableRelationTest: Codeunit "Table Relation Test"; + begin + // Removes every relation on the whole table (field/related table/ + // related field all 0), not just the one known exception - this + // also strips "Parent No." -> "Sample Header"."No.", which had no + // exception and should have stayed covered by the standard test. + TableRelationTest.RemoveTableRelation(TableRelationsMetadata, Database::"Sample Header", 0, 0, 0); + end; +} diff --git a/microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.good.al b/microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.good.al new file mode 100644 index 0000000..26db161 --- /dev/null +++ b/microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.good.al @@ -0,0 +1,51 @@ +table 50144 "Sample Setup" +{ + fields + { + field(1; "Primary Key"; Code[10]) { } + field(2; "Default Category Code"; Code[20]) { } + } + keys + { + key(PK; "Primary Key") { Clustered = true; } + } +} + +table 50145 "Sample Header" +{ + fields + { + field(1; "No."; Code[20]) { } + // A known exception: "Category Code" predates "Sample Setup" and + // can carry a value that no longer resolves to a real row there, + // so the standard Table Relation Test would otherwise reject it - + // excluded via OnAfterRemoveTableRelation below. + field(10; "Category Code"; Code[10]) + { + TableRelation = "Sample Setup"."Primary Key"; + } + // An ordinary relation with no exception - ExcludeSampleFieldFrom + // TableRelationTest below must leave this one checked. + field(11; "Parent No."; Code[20]) + { + TableRelation = "Sample Header"."No."; + } + } + keys + { + key(PK; "No.") { Clustered = true; } + } +} + +codeunit 50141 "Sample Table Relation Test Ext" +{ + [EventSubscriber(ObjectType::Codeunit, Codeunit::"Table Relation Test", 'OnAfterRemoveTableRelation', '', false, false)] + local procedure ExcludeSampleFieldFromTableRelationTest(var TableRelationsMetadata: Record "Table Relations Metadata" temporary) + var + TableRelationTest: Codeunit "Table Relation Test"; + begin + // Removes only the one known exception. "Parent No." -> "Sample + // Header"."No." is untouched and stays covered by the standard test. + TableRelationTest.RemoveTableRelation(TableRelationsMetadata, Database::"Sample Header", 10, Database::"Sample Setup", 1); + end; +} diff --git a/microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.md b/microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.md new file mode 100644 index 0000000..3f7d778 --- /dev/null +++ b/microsoft/knowledge/testing/table-relation-test-exclude-known-invalid-relations-via-event.md @@ -0,0 +1,35 @@ +--- +bc-version: [all] +domain: testing +keywords: [table-relation-test, tablerelationsmetadata, onafterremovetablerelation, field-length, field-type] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Exclude a known-valid TableRelation exception via OnAfterRemoveTableRelation + +## Description + +Codeunit 134926 "Table Relation Test" (shipped in BCApps' test app — only consumers that depend on the BC test libraries can subscribe to it) reads Table Relations Metadata tenant-wide across every installed app, not just the current one, and validates each field's type and length against what its relations require — but the exact rule depends on whether that field has an *unconditional* relation (a `Table Relations Metadata` row with `Condition Field No. = 0`) among its relations, or only *conditional* ones: + +- If any relation is unconditional, the field's length must equal *exactly* the largest related field's length, and its type must exactly match the required type — resolved to `Text` when the related fields themselves mix `Code` and `Text`. +- If every relation for that field is conditional, the requirement relaxes: the field only needs to be *at least* as long as the largest related field (longer is accepted; only shorter fails), and when the required type is specifically `Code`, both a `Code` and a `Text` source field pass. That `Code`/`Text` tolerance is conditional-only — it does not apply on the unconditional side, and it does not extend to a required type of `Text` (a `Code` source field does not satisfy a required `Text`). + +A field with a legitimate, intentional relation shape outside both of these tolerances has no per-field override in its own object definition; the check runs with no built-in escape hatch beyond them. The validation test method itself is `[Scope('OnPrem')]`: it only runs from an on-premises test surface, not from a cloud-targeted test app, so this whole exception mechanism — and the check it works around — is only reachable where that test can actually execute. + +## Best Practice + +Subscribe to `OnAfterRemoveTableRelation` and call the codeunit's own `RemoveTableRelation(TableRelationsMetadata, TableID, FieldID, RelatedTableID, RelatedFieldID)` to strike the one known-valid relation before the test evaluates it, scoped as narrowly as the exception actually is. Because the test itself is `[Scope('OnPrem')]`, do not recommend subscribing to it as a way to guard a cloud-targeted app's test suite — the subscription has no effect where the test never runs. + +See sample: [`table-relation-test-exclude-known-invalid-relations-via-event.good.al`](table-relation-test-exclude-known-invalid-relations-via-event.good.al). + +## Anti Pattern + +Excluding an entire table's relations (or disabling the whole test codeunit) to work around one known exception. This discards the check's coverage for every other relation on that table, or in the app, not just the one that needed an exception. + +See sample: [`table-relation-test-exclude-known-invalid-relations-via-event.bad.al`](table-relation-test-exclude-known-invalid-relations-via-event.bad.al). + +## Source + +The `OnAfterRemoveTableRelation` exclusion technique is drawn from Luc van Vugt's "How-to: Test your Table Relations (2)": https://www.fluxxus.nl/index.php/bc/how-to-test-your-table-relations-2/. The codeunit/event signature, the `[Scope('OnPrem')]` boundary, and the tenant-wide `Table Relations Metadata` scope described above were verified directly against BCApps' `codeunit 134926 "Table Relation Test"` source, not taken from the post. diff --git a/microsoft/knowledge/testing/transactionmodel-attribute-governs-test-transactions.md b/microsoft/knowledge/testing/transactionmodel-attribute-governs-test-transactions.md index c9c159a..0f4f3bd 100644 --- a/microsoft/knowledge/testing/transactionmodel-attribute-governs-test-transactions.md +++ b/microsoft/knowledge/testing/transactionmodel-attribute-governs-test-transactions.md @@ -11,16 +11,20 @@ application-area: [all] ## Description -`[TransactionModel(...)]` declares how a test method interacts with the database's write transaction. The attribute applies only to methods inside a codeunit with `SubType = Test` and takes one of three values: `AutoRollback`, `AutoCommit`, or `None`. The choice must match the code being exercised — in particular, whether that code calls `Commit()`. Per the platform reference, "if the code that you test includes calls to the COMMIT Method, then set the TransactionModel property on the test method to AutoCommit." Applying `AutoRollback` to a test that drives code which calls `Commit` produces a runtime error on the first Commit, not a meaningful assertion failure — the test does not complete, and the reviewer sees an infrastructure error instead of a business-logic verdict. +`[TransactionModel(...)]` declares how a test method interacts with the database's write transaction. The attribute applies only to methods inside a codeunit with `SubType = Test` and takes one of three values: `AutoRollback`, `AutoCommit`, or `None`. **`AutoCommit` is the documented default** — a test method with no `[TransactionModel(...)]` attribute at all runs under `AutoCommit`, not `AutoRollback` and not `None` (Microsoft's TransactionModel property reference states this explicitly: "AutoCommit is the default value"). The "a call to `Commit` produces a runtime error" behavior is specific to the *explicitly declared* `AutoRollback` attribute. BCApps' own canonical pattern for a lazily-initialized shared fixture (see `codeunit 134915 "ERM Online Mapping Setup"`) declares no `TransactionModel` attribute at all — so it runs under the `AutoCommit` default — calls `Commit()` inside its `Initialize()` helper, and cleans up manually with a deliberate `asserterror Error(...)` at the end rather than relying on automatic rollback; this is a legitimate, common pattern, not a bug. Per the same reference, under `AutoCommit` an error, even one caught by `asserterror`, still rolls back the transaction — but "only to the point at which `Commit` was called" if the code being tested committed first. When a test method *does* declare `AutoRollback` explicitly, the choice must match the code being exercised: per the platform reference, "if the code that you test includes calls to the COMMIT Method, then set the TransactionModel property on the test method to AutoCommit." Applying `AutoRollback` to a test that drives code which calls `Commit` produces a runtime error on the first Commit, not a meaningful assertion failure. ## Best Practice -Default to `AutoRollback`: it opens a write transaction at the start of the test, runs the test body, and rolls back at the end, leaving the database in its original state. Pick `AutoCommit` only when the code under test genuinely calls `Commit` — posting routines, job-queue handlers, integration flows — and make the test exercise that commit path. Pair the test codeunit with a `TestIsolation`-enabled test runner so committed changes are reverted at a higher scope. Pick `None` only for read-only tests or tests that drive UI code without writing from the test method itself. +Leave `[TransactionModel(...)]` undeclared to get the `AutoCommit` default when the codeunit's own tests rely on that default's behavior — for example a lazily-initialized shared fixture that commits once and cleans up its own scratch changes with a manual `asserterror`-based rollback (see `commit-shared-test-fixture-inside-lazy-initialize.md`); do not treat that absence as equivalent to declaring `AutoRollback`. When declaring `[TransactionModel(...)]` explicitly instead, pick `AutoRollback` for a test whose own logic and the code it exercises make no `Commit` call, `AutoCommit` when the code under test genuinely calls `Commit` — posting routines, job-queue handlers, integration flows — and make the test exercise that commit path, and `None` for a read-only test or one that drives UI code without writing from the test method itself. Pair an intentional, suite-wide reliance on `AutoCommit` with a `TestIsolation`-enabled test runner so committed changes are reverted at a higher scope. See sample: [`transactionmodel-attribute-governs-test-transactions.good.al`](transactionmodel-attribute-governs-test-transactions.good.al). ## Anti Pattern -Applying `AutoRollback` to every test method without checking whether the tested business logic calls `Commit`. The test throws at the first Commit, leaving no verdict on the behavior it intended to verify; in a CI run this looks like a flake or a setup bug, not a specification mismatch. The mirror-image anti-pattern is defaulting to `AutoCommit` across the suite "to avoid the error" — without a `TestIsolation` runner this permanently dirties the test database between runs and produces order-dependent test outcomes. +Declaring `[TransactionModel(AutoRollback)]` explicitly on a test method without checking whether the tested business logic calls `Commit`. The test throws at the first Commit, leaving no verdict on the behavior it intended to verify; in a CI run this looks like a flake or a setup bug, not a specification mismatch. The mirror-image anti-pattern is defaulting to `AutoCommit` across the suite "to avoid the error" — without a `TestIsolation` runner this permanently dirties the test database between runs and produces order-dependent test outcomes. Flagging a `Commit()` call in a test method that declares no `TransactionModel` attribute at all is not this anti-pattern — that shape does not error, and is BCApps' own documented pattern for shared lazy fixtures. See sample: [`transactionmodel-attribute-governs-test-transactions.bad.al`](transactionmodel-attribute-governs-test-transactions.bad.al). + +## Source + +The `AutoCommit`-is-default claim and the exact rollback-to-last-`Commit` mechanics are quoted from Microsoft's TransactionModel Property reference: https://learn.microsoft.com/en-us/previous-versions/dynamicsnav-2018-developer/TransactionModel-Property. The current AL [TransactionModel attribute](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/attributes/devenv-transactionmodel-attribute) page describes the same three values but never states a default; this older property reference is the citable source for that fact. diff --git a/microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.bad.al b/microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.bad.al new file mode 100644 index 0000000..07ad6b2 --- /dev/null +++ b/microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.bad.al @@ -0,0 +1,18 @@ +codeunit 50143 "Sample Doc Amount Test" +{ + Subtype = Test; + + [Test] + procedure DocAmountIsNotVerifiedWhenLinesAreMissing() + var + Assert: Codeunit Assert; + PurchHeader: Record "Purchase Header"; + begin + asserterror Assert.IsTrue(VerifyDocAmount(PurchHeader), 'Doc. amount should not verify with no lines.'); + end; + + local procedure VerifyDocAmount(var PurchHeader: Record "Purchase Header"): Boolean + begin + exit(false); + end; +} diff --git a/microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.good.al b/microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.good.al new file mode 100644 index 0000000..eb21d6c --- /dev/null +++ b/microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.good.al @@ -0,0 +1,18 @@ +codeunit 50143 "Sample Doc Amount Test" +{ + Subtype = Test; + + [Test] + procedure DocAmountIsNotVerifiedWhenLinesAreMissing() + var + Assert: Codeunit Assert; + PurchHeader: Record "Purchase Header"; + begin + Assert.IsFalse(VerifyDocAmount(PurchHeader), 'Doc. amount should not verify with no lines.'); + end; + + local procedure VerifyDocAmount(var PurchHeader: Record "Purchase Header"): Boolean + begin + exit(false); + end; +} diff --git a/microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.md b/microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.md new file mode 100644 index 0000000..182a62b --- /dev/null +++ b/microsoft/knowledge/testing/use-assert-isfalse-not-asserterror-for-boolean-checks.md @@ -0,0 +1,34 @@ +--- +bc-version: [all] +domain: testing +keywords: [assert, isfalse, istrue, asserterror, boolean-check, negative-test] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Use Assert.IsFalse to check a boolean result, not asserterror around Assert.IsTrue + +## Description + +`asserterror` exists to assert that a statement raises a runtime error; it is not a general-purpose way to invert a boolean check. Wrapping `asserterror Assert.IsTrue(SomeFunc(), Msg)` to verify that `SomeFunc()` returns `false` tests whether `Assert.IsTrue`'s own error-raising behavior fired, not the value `SomeFunc()` actually returned. + +## Best Practice + +When the code under test returns a `Boolean` rather than raising an error, assert the value directly with `Assert.IsFalse(SomeFunc(), Msg)` (or `Assert.IsTrue` for the positive case). Reserve `asserterror` for statements expected to actually raise an error. + +See sample: [`use-assert-isfalse-not-asserterror-for-boolean-checks.good.al`](use-assert-isfalse-not-asserterror-for-boolean-checks.good.al). + +## Anti Pattern + +`asserterror Assert.IsTrue(SomeFunc(), Msg);` to verify `SomeFunc()` is `false`. It passes today because `Assert.IsTrue` happens to raise an error on failure, but it verifies the assertion helper's error-raising behavior, not the value under test. + +See sample: [`use-assert-isfalse-not-asserterror-for-boolean-checks.bad.al`](use-assert-isfalse-not-asserterror-for-boolean-checks.bad.al). + +## Source + +Drawn from Luc van Vugt's "TDD in NAV – ASSERTERROR or IsFalse": https://www.fluxxus.nl/index.php/bc/tdd-in-nav-asserterror-or-isfalse/. The post's own example and reasoning — reserve `asserterror` for the product code actually raising an error, use `Assert.IsFalse`/`Assert.IsTrue` to check a boolean the test framework itself computes — carries over directly; the overlap with `asserterror-needs-expectederror-and-code.md` below is this repository's own addition, not from the source. + +## Scope + +This rule and `asserterror-needs-expectederror-and-code.md` can both match `asserterror Assert.IsTrue(SomeFunc(), Msg);` with nothing after it — the generic rule sees a bare `asserterror`, this one sees `asserterror` wrapping an `Assert.IsTrue`/`Assert.IsFalse` call used to invert a boolean. This rule wins for that shape: the fix is to replace the construct with a direct `Assert.IsFalse`/`Assert.IsTrue` call, not to add `Assert.ExpectedError`/`Assert.ExpectedErrorCode` after it. `asserterror-needs-expectederror-and-code.md` still applies on its own to every other bare `asserterror`, including one guarding `Assert.IsTrue`/`Assert.IsFalse` where the intent genuinely is to assert that the guarded call itself raises an error (for example, asserting that a validation helper errors before it can even return a boolean). diff --git a/microsoft/skills/review/al-testing-review.md b/microsoft/skills/review/al-testing-review.md index 5bc30c8..c42fe85 100644 --- a/microsoft/skills/review/al-testing-review.md +++ b/microsoft/skills/review/al-testing-review.md @@ -55,7 +55,10 @@ The following targeted checks cover every current `testing` article. Treat each - A permission-sensitive test uses `TestPermissions = Disabled`, claims to test a restricted user without `"Permissions Mock"`/`"Library - Lower Permissions"`, or declares `[TestPermissions(...)]` without applying that context — `permission-tests-must-lower-the-execution-context`. - Test fixture code manually calls `Init`/`Insert`, invents keys or prerequisite records, or bypasses available `LibrarySales`, `LibraryPurchase`, `LibraryERM`, `LibraryInventory`, `LibraryRandom`, or equivalent library codeunits — `use-library-codeunits-for-test-fixtures`. - A test codeunit's `Initialize` procedure exits on `IsInitialized` before per-test reset such as `LibraryVariableStorage.Clear`, `LibrarySetupStorage.Restore`, or `LibraryTestInitialize.OnTestInitialize`, or a `[Test]` method in a codeunit using that pattern does not call `Initialize()` first — `reset-per-test-state-before-the-isinitialized-guard`. -- `asserterror` is added or changed without a following `Assert.ExpectedError`, `Assert.ExpectedErrorCode`, or a purpose-built assertion such as `ExpectedTestFieldError` — `asserterror-needs-expectederror-and-code`. +- `asserterror` is added or changed without a following `Assert.ExpectedError`, `Assert.ExpectedErrorCode`, or a purpose-built assertion such as `ExpectedTestFieldError` — `asserterror-needs-expectederror-and-code`. Exclude `asserterror Assert.IsTrue(...)` / `asserterror Assert.IsFalse(...)` only when it is used solely to invert the guarded call's Boolean result (the same condition `use-assert-isfalse-not-asserterror-for-boolean-checks` cues on below, which wins for that shape) — not when the test expects the guarded Boolean-returning call itself to raise an error, which this rule still owns even though it happens to wrap an `Assert.IsTrue`/`IsFalse` call. Also exclude a trailing `asserterror Error(...)` used purely as an end-of-test rollback sentinel after a lazy `Initialize()` fixture already committed — that shape belongs to `commit-shared-test-fixture-inside-lazy-initialize`, which wins for it; the sentinel's own error text is not meant to be asserted against. +- `asserterror` wraps `Assert.IsTrue(BooleanExpression, ...)` (or the `IsFalse` mirror) solely to invert the boolean result of the guarded call, rather than to assert that call itself raises an error — `use-assert-isfalse-not-asserterror-for-boolean-checks`. +- A shared/lazy `Initialize()`-style fixture helper creates fixture data without a following `Commit()`, in a test method whose body later forces its own rollback (for example `asserterror Error(...)` used for end-of-test cleanup) — `commit-shared-test-fixture-inside-lazy-initialize`. The presence of `Commit()` after the fixture is the compliant shape, not the signal to look for; the missing-`Commit()` shape combined with a later deliberate rollback is the anti-pattern. Require runner/repository context for the `TestIsolation` value: a standalone test file cannot prove which runner executes it, and under `Function`-level isolation this whole pattern is moot regardless of `Commit()` — do not raise the finding when the executing runner's `TestIsolation` is known to be `Function`. +- Changed code subscribes to `OnAfterRemoveTableRelation`, calls `RemoveTableRelation`, or references `Codeunit "Table Relation Test"`/134926 — `table-relation-test-exclude-known-invalid-relations-via-event`. - Test fixture code assigns a hardcoded literal to a primary-key field or a field the test relies on as a unique lookup identifier, hand-builds a "unique" value for such a field (string concatenation, a counter, `Format(CurrentDateTime)`), or truncates `LibraryUtility.GenerateGUID()`'s result with `CopyStr` for such a field shorter than 10 characters — `use-generateguid-for-unique-test-fixture-values`. Calling `GenerateGUID()` untruncated into a full-length field, `GenerateRandomCodeWithLength` for a shorter field needing real verified uniqueness, or `GenerateRandomCode20` specifically for a `Code[20]` field, is the compliant shape, not the signal to flag. `GenerateRandomCode20` is not a substitute for `GenerateRandomCodeWithLength` on a shorter field — it truncates `GenerateGUID()`'s sequential value down to the field's length by keeping the *leftmost* characters, which change the slowest, so retries against a short field can churn through the same truncated prefix far longer than `GenerateRandomCodeWithLength`'s equivalent. A hardcoded or deterministic value in an ordinary descriptive field is not this anti-pattern — that field carries no uniqueness constraint. Do not claim `GenerateRandomCode` (without `WithLength`/`20`) or `GenerateRandomXMLText` verify uniqueness against the real table, or that `GenerateRandomCode` is collision-free even within one test run for a short field — none of that is true. - A test asserts against a `TestPage` field's `.Visible()` or `.Enabled()` — `use-testpage-visible-enabled-to-verify-field-ui-state`. When the assertion is against `.Editable()`, or the page is opened with `OpenEdit()` specifically to check editability — `use-testpage-editable-to-verify-field-editability`. - A test path raises UI and `[HandlerFunctions(...)]` does not match the invoked handlers, or the test has no meaningful evidence of the UI result (for example, it treats a Boolean set before the action as proof of success) — `ui-handlers-in-tests`. A capture/reset/assert-after-`RunModal` pattern is valid. Enqueue/dequeue and `AssertEmpty` are required only when order, count, text, replies, or a scripted sequence is part of the contract. Only nonoptional handlers have to execute: a listed handler declared `[SendNotificationHandler(true)]` or `[RecallNotificationHandler(true)]` is optional by design, so do not treat it as unmatched when the run never raises the notification. From 56ce52a9c7a01046d4f2b603ddb0d9d044bb9502 Mon Sep 17 00:00:00 2001 From: Michael Dieringer <65093775+MichaelDieringer@users.noreply.github.com> Date: Tue, 29 Sep 2026 17:13:35 +0200 Subject: [PATCH 32/35] AL methods limited during write transactions (RunModal, Codeunit.Run) (#161) * Add runmodal-is-not-allowed-inside-write-transactions.md; drop "modal page" from the prompts article A modal page does not behave like Confirm/StrMenu inside a write transaction: the platform refuses Page.RunModal (and Report/XmlPort .RunModal with a request page, and Codeunit.Run with its return value used) with a runtime error instead of holding the lock. The new article documents that guard - verified against Microsoft Learn (Codeunit.Run transaction semantics), microsoft/AL#5452, Microsoft's own Base Application (Commit(); Page.RunModal pattern), and a live reproduction on Business Central 26 quoted verbatim. avoid-user-prompts-inside- transactions.md keeps its scope to the prompts the platform does allow; "modal page" is removed from its list because that case is refused, not stalled. Co-Authored-By: Claude Fable 5.1 * Do not list Message among the lock-holding prompts Message runs asynchronously - it is queued and shown when the calling method ends or another method requests input - so it never pauses the transaction and holds no lock. Only Confirm and StrMenu wait for the user. Co-Authored-By: Claude Fable 5.1 * State the four write-transaction conditions as one explicit line per method Mirrors the structure of the platform's own error message so the Report.RunModal and XmlPort.RunModal request-page exceptions are visible at a glance instead of buried in prose. Co-Authored-By: Claude Fable 5.1 * Title the article after the platform error it explains "AL methods limited during write transactions: commit before RunModal and Codeunit.Run" - so a developer or agent searching for the runtime error text lands on the one article that covers all four restricted methods. Slug and sample stems renamed to match; keywords gain the error's own phrase and the legacy Form.RunModal name it still uses. Co-Authored-By: Claude Fable 5.1 * Trim keywords to 10 per validator guidance * Wire the new article into al-performance-review.md Adds Page.RunModal / Report.RunModal / XmlPort.RunModal / UseRequestPage to the extracted-token list and one deterministic worklist cue with exclusions, so the article is selected from the RunModal call itself rather than only via a co-located Commit/Modify token. Codeunit.Run in that position is routed to its existing owner article. Co-Authored-By: Claude Fable 5.1 * Correct XmlPort.RunModal to Xmlport.Run; fix READ-convention sample links XmlPort has no RunModal method (static or instance) - Microsoft Learn confirms only Xmlport.Run(Integer [, Boolean RequestWindow] [, Boolean] [, var Record]). Replaces the invented API with the real one throughout the article, worklist cue, and token list, and explains the platform error message's own "XmlPort.RunModal" wording as the same kind of legacy phrasing already noted for Form.RunModal/RequestForm. Also corrects UseRequestPage(false): that's a Report instance method only, not applicable to XMLport, which uses the UseRequestPage = false object property or Run's RequestWindow argument instead. Fixes the two sample references to use the READ-convention markdown link form (Test-KnowledgeIndex.ps1's Knowledge-Retrieval.ps1 check was failing on plain backtick text). Rebased onto upstream/main to resolve conflicts with #148's job-queue additions to al-performance-review.md - both sets of worklist tokens and cues are retained. * Add Report.Run alongside Report.RunModal to the write-transaction guard routing al-performance-review.md's tokens/cues only recognized Report.RunModal, so a failing Modify(); Report.Run(..., true, ...) path was never worklisted even though Report.Run shares the exact same RequestWindow- blocking-dialog mechanism as Report.RunModal (they differ only in whether the report instance is cleared afterward). Added Report.Run to the token list and the targeted cue, with the same request-page- suppressed exclusion, and extended the knowledge article's Description bullet to name both methods explicitly instead of only RunModal. --------- Co-authored-by: Claude Fable 5.1 Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- ...s-limited-during-write-transactions.bad.al | 18 ++++++++ ...-limited-during-write-transactions.good.al | 18 ++++++++ ...thods-limited-during-write-transactions.md | 46 +++++++++++++++++++ .../avoid-user-prompts-inside-transactions.md | 2 +- .../skills/review/al-performance-review.md | 3 +- 5 files changed, 85 insertions(+), 2 deletions(-) create mode 100644 microsoft/knowledge/performance/al-methods-limited-during-write-transactions.bad.al create mode 100644 microsoft/knowledge/performance/al-methods-limited-during-write-transactions.good.al create mode 100644 microsoft/knowledge/performance/al-methods-limited-during-write-transactions.md diff --git a/microsoft/knowledge/performance/al-methods-limited-during-write-transactions.bad.al b/microsoft/knowledge/performance/al-methods-limited-during-write-transactions.bad.al new file mode 100644 index 0000000..665520b --- /dev/null +++ b/microsoft/knowledge/performance/al-methods-limited-during-write-transactions.bad.al @@ -0,0 +1,18 @@ +codeunit 50258 "Perf Sample RunModalInTxn Bad" +{ + procedure ChangeShippingAgent(DocNo: Code[20]) + var + SalesHeader: Record "Sales Header"; + ShippingAgent: Record "Shipping Agent"; + begin + SalesHeader.Get(SalesHeader."Document Type"::Order, DocNo); + SalesHeader."Shipment Date" := WorkDate(); + SalesHeader.Modify(true); // a write transaction is now open + + // Runtime error: RunModal is not allowed in write transactions. + if Page.RunModal(Page::"Shipping Agents", ShippingAgent) = Action::LookupOK then begin + SalesHeader.Validate("Shipping Agent Code", ShippingAgent.Code); + SalesHeader.Modify(true); + end; + end; +} diff --git a/microsoft/knowledge/performance/al-methods-limited-during-write-transactions.good.al b/microsoft/knowledge/performance/al-methods-limited-during-write-transactions.good.al new file mode 100644 index 0000000..0fcfcb2 --- /dev/null +++ b/microsoft/knowledge/performance/al-methods-limited-during-write-transactions.good.al @@ -0,0 +1,18 @@ +codeunit 50259 "Perf Sample RunModalInTxn Good" +{ + procedure ChangeShippingAgent(DocNo: Code[20]) + var + SalesHeader: Record "Sales Header"; + ShippingAgent: Record "Shipping Agent"; + begin + // User interaction first, while no write transaction is open. + if Page.RunModal(Page::"Shipping Agents", ShippingAgent) <> Action::LookupOK then + exit; + + // All writes after the choice is made; the transaction ends with the trigger. + SalesHeader.Get(SalesHeader."Document Type"::Order, DocNo); + SalesHeader."Shipment Date" := WorkDate(); + SalesHeader.Validate("Shipping Agent Code", ShippingAgent.Code); + SalesHeader.Modify(true); + end; +} diff --git a/microsoft/knowledge/performance/al-methods-limited-during-write-transactions.md b/microsoft/knowledge/performance/al-methods-limited-during-write-transactions.md new file mode 100644 index 0000000..2bbedb3 --- /dev/null +++ b/microsoft/knowledge/performance/al-methods-limited-during-write-transactions.md @@ -0,0 +1,46 @@ +--- +bc-version: [all] +domain: performance +keywords: [limited-during-write-transactions, write-transaction, runmodal, report-run, page-runmodal, report-runmodal, xmlport-run, codeunit-run, commit, requestpage] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# AL methods limited during write transactions: commit before RunModal and Codeunit.Run + +## Description + +Once AL code has written to the database in the current transaction — an `Insert`, `Modify`, or `Delete` with no `Commit` since — the platform restricts four methods until that transaction is committed. The exact conditions, as enforced: + +- `Page.RunModal` — not allowed in a write transaction, under any circumstances. +- `Report.RunModal` and `Report.Run` — both allowed only if the request page is suppressed: `Report.RunModal(ReportId, false)` / `Report.Run(ReportId, false)` (the second argument is `RequestWindow` in both), or `UseRequestPage(false)` on a report instance. With a request page shown, either fails identically — `Run` and `RunModal` differ only in whether the report instance is cleared afterward, not in this guard. +- `Xmlport.Run` — same rule when it would show a request page: allowed only if the request page is suppressed, `Xmlport.Run(XmlPortId, false)` (the second argument is `RequestWindow`) or the `UseRequestPage = false;` object property. With a request page shown it fails. There is no `XmlPort.RunModal` method — see the note on the platform's error text below. +- `Codeunit.Run` — allowed only if its Boolean return value is not used. `OK := Codeunit.Run()` and `if Codeunit.Run() then` fail, because that form commits — see `codeunit-run-requires-prior-commit-inside-transaction.md`. + +This is a runtime error, not a compiler diagnostic: the code builds, and the first execution that reaches the call with an open write transaction dies. The guard keys on transaction state alone, not on any relation between what was written and what is opened: an `Item.Insert()` followed by `Page.RunModal(Page::"Customer Card")` — an unrelated table — fails on the `RunModal` line, and because the error stops the transaction, the insert rolls back with it. + +The platform's message (Business Central 26, reproduced 2026-09-07) reads: "The following AL methods are limited during write transactions because one or more tables will be locked: Form.RunModal, Codeunit.Run, Report.RunModal, XmlPort.RunModal. Form.RunModal is not allowed in write transactions. Codeunit.Run is allowed in write transactions only if the return value is not used. For example, 'OK := Codeunit.Run()' is not allowed. Report.RunModal is allowed in write transactions only if 'RequestForm = false'. For example, 'Report.RunModal(...,false)' is allowed. XmlPort.RunModal is allowed in write transactions only if 'RequestForm = false'. For example, 'XmlPort.RunModal(...,false)' is allowed. Use the commit method to save the changes before this call, or structure the code differently." The message still uses the legacy names `Form.RunModal` and `RequestForm` even though the AL method is `Page.RunModal` and the report parameter is `RequestWindow`; older versions said "C/AL functions" instead of "AL methods" (microsoft/AL#5452, 2019). The message also names `XmlPort.RunModal`, which is legacy phrasing too — there is no such AL method; the actual API the guard applies to is `Xmlport.Run`, and the message's `RequestForm = false` condition corresponds to `Xmlport.Run`'s `RequestWindow` argument or the `UseRequestPage` property. The behavior is unchanged across versions. + +The reason is the same one behind `avoid-user-prompts-inside-transactions.md`: a modal object waits for the user, and the platform will not let a write transaction — and every lock it holds — sit open for as long as that takes. The difference is enforcement. `Confirm` and `StrMenu` are *allowed* inside a write transaction and silently hold the locks; `RunModal` is *refused*. Both point at the same design fix. + +## Best Practice + +Sequence the work so the modal interaction happens before the write phase: run the lookup or dialog page first, then perform the writes the user's choice requires, and let the transaction end. When a modal object genuinely must follow a write, `Commit()` first — but only when the state written so far is complete and safe to persist on its own, because that Commit is a real transaction boundary, not a formality. Microsoft's own Base Application follows exactly this pattern where the preceding state is final (`ActivityLog.Table.al` commits the log entry before `Page.RunModal(Page::"Activity Log", Rec)`; `DocumentSendingProfile.Table.al` commits before `Page.RunModal(Page::"Select Sending Options", …)`). For a report, suppressing the request page — `Report.UseRequestPage(false)` on a report instance, or `false` as the `RequestWindow` argument to `Run`/`RunModal` — is a legitimate way to run it inside a write transaction when no user input is needed. For an XMLport, the equivalent is `false` as the `RequestWindow` argument to `Xmlport.Run`, or the `UseRequestPage = false;` object property; XMLports have no instance `UseRequestPage` method. `Database.IsInWriteTransaction()` (runtime 11.0+) lets library code that cannot control its caller detect the state, with the same caveat as the Codeunit.Run article: branching production flow on it usually signals unclear transaction ownership. + +See sample: [`al-methods-limited-during-write-transactions.good.al`](al-methods-limited-during-write-transactions.good.al). + +## Anti Pattern + +Writing to the database and then calling `Page.RunModal` (or a report/XMLport with its request page) in the same trigger — the first production run hits the runtime error. The reflexive fixes are worse than the error: dropping in `Commit()` to silence it persists a half-finished state that can no longer roll back with the rest of the operation, and swapping the page for a `Confirm` or `StrMenu` to "avoid the error" trades a loud failure for the silent lock-holding that `avoid-user-prompts-inside-transactions.md` warns about. + +See sample: [`al-methods-limited-during-write-transactions.bad.al`](al-methods-limited-during-write-transactions.bad.al). + +## Source + +- Microsoft Learn, `Codeunit.Run` transaction semantics ("If you're already in a transaction you must commit first before calling Codeunit.Run"): https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/codeunit/codeunit-run-method +- Microsoft Learn, `Xmlport.Run(Integer [, Boolean] [, Boolean] [, var Record])` (the `RequestWindow` argument; confirms the XMLport data type has no `RunModal` method, static or instance): https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/xmlport/xmlport-run-method +- Microsoft Learn, `UseRequestPage` property ("Applies to: Xml Port, Report" — an object property, not an XMLport instance method; the instance method of the same name exists only on `Report`): https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/properties/devenv-userequestpage-property +- microsoft/AL issue #5452 (verbatim English error text, reproduced on "any current version of Business Central", 2019-11-13): https://github.com/microsoft/AL/issues/5452 +- Reproduced 2026-09-07 on Business Central 26 (runtime error dialog, English and Danish clients): a page `OnAction` doing `Item.Insert()` then `Page.RunModal(Page::"Customer Card")` fails with the text quoted in the Description, the AL call stack pointing at the `RunModal` line, and the dialog stating that the transaction was stopped. +- Microsoft Base Application (BCApps, W1): the `Commit(); … Page.RunModal(…)` pattern in `Modules/System/Logging/ActivityLog.Table.al`, `Foundation/Reporting/DocumentSendingProfile.Table.al`, `Bank/Setup/PaymentServiceSetup.Table.al`, and others; BCApps test suites annotate the same guard as "COMMIT is required for Write Transaction Error" (`Tests/General Journal/ERMTestMultipleGenJnlLines.Codeunit.al`). diff --git a/microsoft/knowledge/performance/avoid-user-prompts-inside-transactions.md b/microsoft/knowledge/performance/avoid-user-prompts-inside-transactions.md index bb03f41..f871c98 100644 --- a/microsoft/knowledge/performance/avoid-user-prompts-inside-transactions.md +++ b/microsoft/knowledge/performance/avoid-user-prompts-inside-transactions.md @@ -11,7 +11,7 @@ application-area: [all] ## Description -A `Confirm`, `StrMenu`, modal page, or other user prompt issued from inside a write transaction stalls the transaction — and therefore every lock it holds — until the user responds. Per the upstream guidance, "Avoid user interactions (Confirm, StrMenu) inside transactions — they hold locks while waiting for user input." The wait is bounded only by the user; meanwhile other sessions block on whatever this transaction has acquired. +A `Confirm`, `StrMenu`, or other user prompt issued from inside a write transaction stalls the transaction — and therefore every lock it holds — until the user responds. Per the upstream guidance, "Avoid user interactions (Confirm, StrMenu) inside transactions — they hold locks while waiting for user input." The wait is bounded only by the user; meanwhile other sessions block on whatever this transaction has acquired. ## Best Practice diff --git a/microsoft/skills/review/al-performance-review.md b/microsoft/skills/review/al-performance-review.md index 6109f7b..cfaf9f7 100644 --- a/microsoft/skills/review/al-performance-review.md +++ b/microsoft/skills/review/al-performance-review.md @@ -39,7 +39,7 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially tables, pages with SourceTable bindings, reports, queries, and codeunits performing record iteration. - The changed procedures and triggers, weighted toward those that perform loops, Find/FindSet/FindFirst calls, CalcFields, SetAutoCalcFields, CalcSums, FlowField access, Commit calls, checkpoint helpers, record copying, RecordRef conversion, Modify/Delete calls, or cross-table navigation. -- Tokens extracted from the diff that relate to data access, hot-path costs, and background scheduling (`SetRange`, `SetFilter`, `SetLoadFields`, `SetCurrentKey`, `FindSet`, `ReadIsolation`, `LockTable`, `ModifyAll`, `DeleteAll`, `Modify`, `Delete`, `Commit`, `checkpoint`, `Copy`, `RecordRef`, `GetTable`, `TextBuilder`, `Dictionary`, `temporary`, `repeat`, `until`, `CalcFields`, `SetAutoCalcFields`, `CalcSums`, `FlowField`, `Visible`, `Job Queue Entry`, `Job Queue Category Code`, `Confirm`, `RunModal`, `GuiAllowed`, `TryFunction`, `Codeunit.Run`, `HttpClient`, `Status`, `On Hold`, `stop request`, `TaskScheduler.CreateTask`, `TaskScheduler.TaskExists`). +- Tokens extracted from the diff that relate to data access, hot-path costs, and background scheduling (`SetRange`, `SetFilter`, `SetLoadFields`, `SetCurrentKey`, `FindSet`, `ReadIsolation`, `LockTable`, `ModifyAll`, `DeleteAll`, `Modify`, `Delete`, `Commit`, `checkpoint`, `Copy`, `RecordRef`, `GetTable`, `TextBuilder`, `Dictionary`, `temporary`, `repeat`, `until`, `CalcFields`, `SetAutoCalcFields`, `CalcSums`, `FlowField`, `Visible`, `Job Queue Entry`, `Job Queue Category Code`, `Confirm`, `RunModal`, `GuiAllowed`, `TryFunction`, `Codeunit.Run`, `HttpClient`, `Status`, `On Hold`, `stop request`, `TaskScheduler.CreateTask`, `TaskScheduler.TaskExists`, `Page.RunModal`, `Report.RunModal`, `Report.Run`, `Xmlport.Run`, `UseRequestPage`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. @@ -58,6 +58,7 @@ Apply these targeted cues even when simple token overlap would rank the article - Worklist `job-queue-on-hold-does-not-stop-running-work.md` when a running job queue handler polls the entry's `Status` or `On Hold` value as a cancellation signal. Exclude application-owned stop requests that are checked before every bounded unit of work, including the first, when completed work and its checkpoint remain consistent and resume logic clears the request. - Worklist `job-queue-category-code-serializes-conflicting-jobs.md` when two or more job queue entries in the same company are shown by the changed context to require mutual exclusion but have empty or different Job Queue Category Codes. Do not infer a conflict merely because jobs touch the same tables, and do not recommend a category to coordinate across companies, environments, or workers outside the job queue dispatcher. - Worklist `store-scheduled-task-id-to-avoid-duplicate-tasks.md` when `TaskScheduler.CreateTask` runs from initialization, login, setup, or another repeatable path without persisting its returned GUID and checking it with `TaskScheduler.TaskExists` before creating a replacement. Exclude one-shot creation and correctly persisted check-before-create flows; concurrent callers still require serialization around that sequence. +- Worklist `al-methods-limited-during-write-transactions.md` when `Page.RunModal` follows an `Insert`, `Modify`, or `Delete` in the same trigger or procedure with no intervening `Commit`; or when `Report.RunModal`/`Report.Run` without `false` as its `RequestWindow` argument and without `UseRequestPage(false)` follows one; or when `Xmlport.Run` without `false` as its `RequestWindow` argument and without the `UseRequestPage = false` object property follows one. Do not worklist it from a call that precedes every write, from a report run with its request page suppressed via `UseRequestPage(false)`/`Run(...,false)`/`RunModal(...,false)`, or from an XMLport run with its request page suppressed via the `RequestWindow` argument or the `UseRequestPage` property. A `Codeunit.Run` whose return value is used in that position belongs to `codeunit-run-requires-prior-commit-inside-transaction.md`. - A new or changed report object whose usage/name/caption identifies it as a single-record document (invoice, statement, order confirmation) sets or retains `DefaultRenderingLayout = RDLC` — `document-report-word-layout.md`. Do not worklist this from a tabular/list report with heavy aggregation or calculated columns; RDLC/Excel remains the better fit there. These targeted inclusions and exclusions override generic token overlap. Do not retain an excluded article solely because the diff contains one of its keywords. From 87ba36e650dde6a1cd4c1bd499303cbde3a6a47f Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Tue, 29 Sep 2026 17:21:28 +0200 Subject: [PATCH 33/35] Add BC performance knowledge from OptimAL learnings (#198) * Add BC performance knowledge from OptimAL learnings Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Address review feedback on performance guidance Clarify predicate-supporting keys versus covering queries, demonstrate proven cache reuse, and evaluate the updated partial-load and bulk-update rules. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- evaluation/review-fixtures.json | 17 +++- ...ore-persisting-intermediate-results.bad.al | 73 +++++++++++++++ ...re-persisting-intermediate-results.good.al | 93 +++++++++++++++++++ ...-before-persisting-intermediate-results.md | 28 ++++++ .../avoid-get-inside-loop-on-large-table.md | 4 +- ...void-repeating-unchanged-validation.bad.al | 39 ++++++++ ...oid-repeating-unchanged-validation.good.al | 38 ++++++++ .../avoid-repeating-unchanged-validation.md | 28 ++++++ ...iltered-results-with-explicit-scope.bad.al | 24 +++++ ...ltered-results-with-explicit-scope.good.al | 48 ++++++++++ ...ed-filtered-results-with-explicit-scope.md | 27 ++++++ ...csums-instead-of-calcfields-in-loop.bad.al | 7 +- ...sums-instead-of-calcfields-in-loop.good.al | 7 +- .../calcsums-instead-of-calcfields-in-loop.md | 15 ++- ...ign-covering-keys-from-read-pattern.bad.al | 38 ++++++++ ...gn-covering-keys-from-read-pattern.good.al | 41 ++++++++ .../design-covering-keys-from-read-pattern.md | 30 ++++++ ...mpty-before-findset-is-extra-round-trip.md | 4 +- ...efer-modifyall-over-per-row-modify.good.al | 1 + .../prefer-modifyall-over-per-row-modify.md | 2 +- ...-inserts-by-separating-target-reads.bad.al | 61 ++++++++++++ ...inserts-by-separating-target-reads.good.al | 56 +++++++++++ ...ered-inserts-by-separating-target-reads.md | 27 ++++++ ...y-key-get-in-loop-is-transaction-cached.md | 6 +- .../query-results-bypass-primary-key-cache.md | 2 +- ...lapping-keys-before-adding-an-index.bad.al | 43 +++++++++ ...apping-keys-before-adding-an-index.good.al | 43 +++++++++ ...overlapping-keys-before-adding-an-index.md | 29 ++++++ ...rrentkey-sets-sort-order-not-index-hint.md | 8 +- ...porary-tables-have-no-database-cost.bad.al | 39 ++++++++ ...orary-tables-have-no-database-cost.good.al | 39 ++++++++ .../temporary-tables-have-no-database-cost.md | 6 +- ...etautocalcfields-for-per-row-flowfields.md | 4 +- ...e-setloadfields-for-partial-records.bad.al | 10 +- ...-setloadfields-for-partial-records.good.al | 11 ++- .../use-setloadfields-for-partial-records.md | 2 +- .../skills/review/al-performance-review.md | 7 +- 37 files changed, 920 insertions(+), 37 deletions(-) create mode 100644 microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.bad.al create mode 100644 microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.good.al create mode 100644 microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.md create mode 100644 microsoft/knowledge/performance/avoid-repeating-unchanged-validation.bad.al create mode 100644 microsoft/knowledge/performance/avoid-repeating-unchanged-validation.good.al create mode 100644 microsoft/knowledge/performance/avoid-repeating-unchanged-validation.md create mode 100644 microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.bad.al create mode 100644 microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.good.al create mode 100644 microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.md create mode 100644 microsoft/knowledge/performance/design-covering-keys-from-read-pattern.bad.al create mode 100644 microsoft/knowledge/performance/design-covering-keys-from-read-pattern.good.al create mode 100644 microsoft/knowledge/performance/design-covering-keys-from-read-pattern.md create mode 100644 microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.bad.al create mode 100644 microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.good.al create mode 100644 microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.md create mode 100644 microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.bad.al create mode 100644 microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.good.al create mode 100644 microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.md create mode 100644 microsoft/knowledge/performance/temporary-tables-have-no-database-cost.bad.al create mode 100644 microsoft/knowledge/performance/temporary-tables-have-no-database-cost.good.al diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index 90fc7d1..7732e7e 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -39,7 +39,22 @@ "job-queue-handlers-must-not-require-ui", "job-queue-handlers-must-propagate-failures", "job-queue-on-hold-does-not-stop-running-work", - "store-scheduled-task-id-to-avoid-duplicate-tasks" + "store-scheduled-task-id-to-avoid-duplicate-tasks", + "design-covering-keys-from-read-pattern", + "review-overlapping-keys-before-adding-an-index", + "setcurrentkey-sets-sort-order-not-index-hint", + "preserve-buffered-inserts-by-separating-target-reads", + "aggregate-before-persisting-intermediate-results", + "cache-repeated-filtered-results-with-explicit-scope", + "avoid-repeating-unchanged-validation", + "avoid-get-inside-loop-on-large-table", + "isempty-before-findset-is-extra-round-trip", + "query-results-bypass-primary-key-cache", + "calcsums-instead-of-calcfields-in-loop", + "use-setautocalcfields-for-per-row-flowfields", + "temporary-tables-have-no-database-cost", + "use-setloadfields-for-partial-records", + "prefer-modifyall-over-per-row-modify" ] }, "privacy": { diff --git a/microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.bad.al b/microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.bad.al new file mode 100644 index 0000000..9e3de05 --- /dev/null +++ b/microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.bad.al @@ -0,0 +1,73 @@ +// Input stays stable for this run; output contains one row per group with entries. +table 50367 "Perf Posted Entry" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Entry No."; Integer) { } + field(2; "Item No."; Code[20]) { } + field(3; "Location Code"; Code[10]) { } + field(4; "Posting Date"; Date) { } + field(5; Quantity; Decimal) { } + } + + keys + { + key(PK; "Entry No.") { Clustered = true; } + key(ByItemLocationDate; "Item No.", "Location Code", "Posting Date") + { + SumIndexFields = Quantity; + } + } +} + +table 50368 "Perf Quantity Summary" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Run ID"; Guid) { } + field(2; "Item No."; Code[20]) { } + field(3; "Location Code"; Code[10]) { } + field(4; Quantity; Decimal) { } + } + + keys + { + key(PK; "Run ID", "Item No.", "Location Code") { Clustered = true; } + } +} + +codeunit 50369 "Perf Summary Bad" +{ + procedure BuildSummary(CutoffDate: Date) RunId: Guid + var + Entry: Record "Perf Posted Entry"; + Scan: Record "Perf Posted Entry"; + Summary: Record "Perf Quantity Summary"; + begin + RunId := CreateGuid(); + Entry.SetFilter("Posting Date", '..%1', CutoffDate); + if Entry.FindSet() then + repeat + Scan.SetRange("Item No.", Entry."Item No."); + Scan.SetRange("Location Code", Entry."Location Code"); + Scan.SetFilter("Posting Date", '..%1', CutoffDate); + Scan.CalcSums(Quantity); + + if Summary.Get(RunId, Entry."Item No.", Entry."Location Code") then begin + Summary.Quantity := Scan.Quantity; + Summary.Modify(false); + end else begin + Summary.Init(); + Summary."Run ID" := RunId; + Summary."Item No." := Entry."Item No."; + Summary."Location Code" := Entry."Location Code"; + Summary.Quantity := Scan.Quantity; + Summary.Insert(false); + end; + until Entry.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.good.al b/microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.good.al new file mode 100644 index 0000000..c94e970 --- /dev/null +++ b/microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.good.al @@ -0,0 +1,93 @@ +// Input stays stable for this run; output contains one row per group with entries. +table 50367 "Perf Posted Entry" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Entry No."; Integer) { } + field(2; "Item No."; Code[20]) { } + field(3; "Location Code"; Code[10]) { } + field(4; "Posting Date"; Date) { } + field(5; Quantity; Decimal) { } + } + + keys + { + key(PK; "Entry No.") { Clustered = true; } + key(ByItemLocationDate; "Item No.", "Location Code", "Posting Date") + { + SumIndexFields = Quantity; + } + } +} + +table 50368 "Perf Quantity Summary" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Run ID"; Guid) { } + field(2; "Item No."; Code[20]) { } + field(3; "Location Code"; Code[10]) { } + field(4; Quantity; Decimal) { } + } + + keys + { + key(PK; "Run ID", "Item No.", "Location Code") { Clustered = true; } + } +} + +query 50370 "Perf Grouped Quantity" +{ + QueryType = Normal; + + elements + { + dataitem(Entry; "Perf Posted Entry") + { + column(ItemNo; "Item No.") { } + column(LocationCode; "Location Code") { } + column(TotalQuantity; Quantity) + { + Method = Sum; + } + filter(PostingDate; "Posting Date") { } + } + } +} + +codeunit 50369 "Perf Summary Good" +{ + procedure BuildSummary(CutoffDate: Date) RunId: Guid + var + Totals: Query "Perf Grouped Quantity"; + TempSummary: Record "Perf Quantity Summary" temporary; + Summary: Record "Perf Quantity Summary"; + begin + RunId := CreateGuid(); + Totals.SetFilter(PostingDate, '..%1', CutoffDate); + Totals.Open(); + while Totals.Read() do begin + TempSummary.Init(); + TempSummary."Run ID" := RunId; + TempSummary."Item No." := Totals.ItemNo; + TempSummary."Location Code" := Totals.LocationCode; + TempSummary.Quantity := Totals.TotalQuantity; + TempSummary.Insert(); + end; + Totals.Close(); + + if TempSummary.FindSet() then + repeat + Summary.Init(); + Summary."Run ID" := RunId; + Summary."Item No." := TempSummary."Item No."; + Summary."Location Code" := TempSummary."Location Code"; + Summary.Quantity := TempSummary.Quantity; + Summary.Insert(false); + until TempSummary.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.md b/microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.md new file mode 100644 index 0000000..bdff7ca --- /dev/null +++ b/microsoft/knowledge/performance/aggregate-before-persisting-intermediate-results.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: performance +keywords: [query, grouping, aggregate, intermediate-results, temporary-buffer, persistent-writes, calcsums, modify, method-sum] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Aggregate source rows before persisting completed results + +## Description + +A batch may repeatedly calculate the same group total while inserting and updating persistent working rows, even though only one completed result per group is needed. An AL Query with `Method = Sum` groups by its other output columns, so the required grain can often be computed from qualifying source rows before writing final output. This is a data-path change, not a blanket replacement for posting or for intermediate rows needed for recovery or business behavior. + +## Best Practice + +Specify the output grain and whether absent groups should produce zero rows. Apply source filters (including cutoff dates), aggregate at exactly that grain, and write only completed results; a small temporary buffer can separate the query from persistent output, but streaming or bounded units may be better for large grouped sets. Avoid a one-to-many join that duplicates quantities or an extra output column that silently changes the grouping. Preserve security filters, signs, units, FlowFilters, relevant master-data restrictions, transaction/trigger behavior, and acceptable read consistency; a shared date cutoff does not create a snapshot. Compare complete keyed outputs and measure source reads, repeated calculations, temporary memory, and persistent writes. See sample: [`aggregate-before-persisting-intermediate-results.good.al`](aggregate-before-persisting-intermediate-results.good.al). + +## Anti Pattern + +For an output that only needs one signed total per item/location with qualifying entries, summing the same source range and rewriting a persistent summary for *every* entry. Do not flag incremental persisted state that is required for locking, resumability, or downstream processing, or require an in-memory copy of all raw history to perform SQL grouping. See sample: [`aggregate-before-persisting-intermediate-results.bad.al`](aggregate-before-persisting-intermediate-results.bad.al). + +## References + +- [Aggregating data in query objects](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-query-totals-grouping). +- [Query performance](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/optimize-sql-query-objects-and-performance). +- [Buffered inserts](preserve-buffered-inserts-by-separating-target-reads.md). diff --git a/microsoft/knowledge/performance/avoid-get-inside-loop-on-large-table.md b/microsoft/knowledge/performance/avoid-get-inside-loop-on-large-table.md index db4f5e1..08c73a9 100644 --- a/microsoft/knowledge/performance/avoid-get-inside-loop-on-large-table.md +++ b/microsoft/knowledge/performance/avoid-get-inside-loop-on-large-table.md @@ -1,7 +1,7 @@ --- bc-version: [all] domain: performance -keywords: [n-plus-one, get, findfirst, loop, inner-lookup, large-table] +keywords: [n-plus-one, get, findfirst, loop, inner-lookup, large-table, item-get, query] technologies: [al] countries: [w1] application-area: [all] @@ -15,7 +15,7 @@ A `Get` or `FindFirst` against another persistent table inside a loop can produc ## Best Practice -Use a query object to join the outer and inner tables when the relationship and filters can be expressed as one query. If keys repeat, a dictionary cache can reduce lookups to one per distinct key. `SetLoadFields` can reduce the columns transferred by unavoidable inner reads, but it does not eliminate the N+1 shape and must not be presented as doing so. +Use a query object to join the outer and inner tables when the relationship and filters can be expressed as one query. If complete lookup keys repeat and the result remains valid, a [scoped cache](cache-repeated-filtered-results-with-explicit-scope.md) can reduce lookups to one per distinct key; do not assume primary-key `Get` calls each hit SQL (see [transaction caching](primary-key-get-in-loop-is-transaction-cached.md)). `SetLoadFields` can reduce the columns transferred by unavoidable inner reads, but it does not eliminate the N+1 shape and must not be presented as doing so. See sample: [`avoid-get-inside-loop-on-large-table.good.al`](avoid-get-inside-loop-on-large-table.good.al). diff --git a/microsoft/knowledge/performance/avoid-repeating-unchanged-validation.bad.al b/microsoft/knowledge/performance/avoid-repeating-unchanged-validation.bad.al new file mode 100644 index 0000000..d3bc03b --- /dev/null +++ b/microsoft/knowledge/performance/avoid-repeating-unchanged-validation.bad.al @@ -0,0 +1,39 @@ +// Quantity validation depends only on Quantity and Unit Price in this demo. +table 50371 "Perf Validated Line" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Line No."; Integer) { } + field(2; Quantity; Decimal) + { + trigger OnValidate() + begin + Amount := Quantity * "Unit Price"; + end; + } + field(3; "Unit Price"; Decimal) { } + field(4; Amount; Decimal) { } + field(5; Note; Text[100]) { } + } + + keys + { + key(PK; "Line No.") { Clustered = true; } + } +} + +codeunit 50372 "Perf Validation Bad" +{ + procedure UpdateLine(LineNo: Integer; NewQuantity: Decimal; NewNote: Text[100]) + var + Line: Record "Perf Validated Line"; + begin + Line.Get(LineNo); + Line.Validate(Quantity, NewQuantity); + Line.Note := NewNote; + Line.Validate(Quantity, NewQuantity); + Line.Modify(false); + end; +} diff --git a/microsoft/knowledge/performance/avoid-repeating-unchanged-validation.good.al b/microsoft/knowledge/performance/avoid-repeating-unchanged-validation.good.al new file mode 100644 index 0000000..de03f3a --- /dev/null +++ b/microsoft/knowledge/performance/avoid-repeating-unchanged-validation.good.al @@ -0,0 +1,38 @@ +// Quantity validation depends only on Quantity and Unit Price in this demo. +table 50371 "Perf Validated Line" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Line No."; Integer) { } + field(2; Quantity; Decimal) + { + trigger OnValidate() + begin + Amount := Quantity * "Unit Price"; + end; + } + field(3; "Unit Price"; Decimal) { } + field(4; Amount; Decimal) { } + field(5; Note; Text[100]) { } + } + + keys + { + key(PK; "Line No.") { Clustered = true; } + } +} + +codeunit 50372 "Perf Validation Good" +{ + procedure UpdateLine(LineNo: Integer; NewQuantity: Decimal; NewNote: Text[100]) + var + Line: Record "Perf Validated Line"; + begin + Line.Get(LineNo); + Line.Validate(Quantity, NewQuantity); + Line.Note := NewNote; + Line.Modify(false); + end; +} diff --git a/microsoft/knowledge/performance/avoid-repeating-unchanged-validation.md b/microsoft/knowledge/performance/avoid-repeating-unchanged-validation.md new file mode 100644 index 0000000..96325b3 --- /dev/null +++ b/microsoft/knowledge/performance/avoid-repeating-unchanged-validation.md @@ -0,0 +1,28 @@ +--- +bc-version: [all] +domain: performance +keywords: [validate, onvalidate, repeated-write, sales-line, subscriber, unchanged-value] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Avoid repeating validation when its inputs have not changed + +## Description + +`Validate` runs field validation logic, which can invoke subscribers and additional reads or writes even if the assigned value is unchanged. When a document-building path validates the same field twice without changing any input its validation depends on, the second cascade may do the same work again. A field-value comparison alone does not prove that the dependent context or required event behavior is unchanged. + +## Best Practice + +Trace the table's `OnValidate`, subscribers, and dependent fields before removing a duplicate invocation. Keep the required validation and write, but skip a second `Validate` only when all its inputs, its order-dependent effects, and the business contract are demonstrably unchanged. Measure validations and writes per business unit and test pricing, reservations, error behavior, and subscriber effects on real document paths. The sample's custom field validation depends only on Quantity and Unit Price; a note assigned between calls does not affect either. See sample: [`avoid-repeating-unchanged-validation.good.al`](avoid-repeating-unchanged-validation.good.al). + +## Anti Pattern + +Validating Quantity, changing only an unrelated local or record note, validating the same Quantity again, then modifying the row, without any required second event. Do not replace `Validate` with direct assignment, use `Insert(false)` indiscriminately, or reorder validations on a Sales Line solely to reduce call counts: its standard logic can depend on other fields and event subscribers. See sample: [`avoid-repeating-unchanged-validation.bad.al`](avoid-repeating-unchanged-validation.bad.al). + +## References + +- [Record.Validate and field validation behavior](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/record/record-validate-method). +- [Equivalent bulk assignments versus per-row validation](prefer-modifyall-over-per-row-modify.md). +- [Subscriber guards](guard-event-subscribers-before-db-call.md). diff --git a/microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.bad.al b/microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.bad.al new file mode 100644 index 0000000..e200297 --- /dev/null +++ b/microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.bad.al @@ -0,0 +1,24 @@ +codeunit 50363 "Perf Variant Cache Bad" +{ + procedure CountAndCollectVariantLines(var TempSalesLine: Record "Sales Line" temporary; OrderNo: Code[20]; var VariantItemNos: List of [Code[20]]) VariantLines: Integer + var + ItemVariant: Record "Item Variant"; + begin + TempSalesLine.SetRange("Document Type", TempSalesLine."Document Type"::Order); + TempSalesLine.SetRange("Document No.", OrderNo); + TempSalesLine.SetRange(Type, TempSalesLine.Type::Item); + if TempSalesLine.FindSet() then + repeat + ItemVariant.SetRange("Item No.", TempSalesLine."No."); + if not ItemVariant.IsEmpty() then + VariantLines += 1; + until TempSalesLine.Next() = 0; + + if TempSalesLine.FindSet() then + repeat + ItemVariant.SetRange("Item No.", TempSalesLine."No."); + if not ItemVariant.IsEmpty() then + VariantItemNos.Add(TempSalesLine."No."); + until TempSalesLine.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.good.al b/microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.good.al new file mode 100644 index 0000000..d5db5d6 --- /dev/null +++ b/microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.good.al @@ -0,0 +1,48 @@ +codeunit 50363 "Perf Variant Cache Good" +{ + procedure CountAndCollectVariantLines(var TempSalesLine: Record "Sales Line" temporary; OrderNo: Code[20]; var VariantItemNos: List of [Code[20]]) VariantLines: Integer + var + ItemVariant: Record "Item Variant"; + HasVariantsByItem: Dictionary of [Code[20], Boolean]; + begin + TempSalesLine.SetRange("Document Type", TempSalesLine."Document Type"::Order); + TempSalesLine.SetRange("Document No.", OrderNo); + TempSalesLine.SetRange(Type, TempSalesLine.Type::Item); + if TempSalesLine.FindSet() then + repeat + if HasVariants(TempSalesLine."No.", ItemVariant, HasVariantsByItem) then + VariantLines += 1; + until TempSalesLine.Next() = 0; + + if TempSalesLine.FindSet() then + repeat + if HasVariants(TempSalesLine."No.", ItemVariant, HasVariantsByItem) then + VariantItemNos.Add(TempSalesLine."No."); + until TempSalesLine.Next() = 0; + end; + + local procedure HasVariants(ItemNo: Code[20]; var ItemVariant: Record "Item Variant"; var HasVariantsByItem: Dictionary of [Code[20], Boolean]): Boolean + var + CachedResult: Boolean; + begin + if HasVariantsByItem.Get(ItemNo, CachedResult) then + exit(CachedResult); + + ItemVariant.SetRange("Item No.", ItemNo); + CachedResult := not ItemVariant.IsEmpty(); + HasVariantsByItem.Add(ItemNo, CachedResult); + exit(CachedResult); + end; + + procedure CountDistinctItemsWithVariants(var TempItems: Record Item temporary) VariantItems: Integer + var + ItemVariant: Record "Item Variant"; + begin + if TempItems.FindSet() then + repeat + ItemVariant.SetRange("Item No.", TempItems."No."); + if not ItemVariant.IsEmpty() then + VariantItems += 1; + until TempItems.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.md b/microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.md new file mode 100644 index 0000000..b85bff0 --- /dev/null +++ b/microsoft/knowledge/performance/cache-repeated-filtered-results-with-explicit-scope.md @@ -0,0 +1,27 @@ +--- +bc-version: [all] +domain: performance +keywords: [cache, dictionary, filtered-lookup, isempty, repeated-query, invalidation, scope] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Reuse repeated filtered results within a correct cache scope + +## Description + +A loop can ask the same filtered existence or calculation question for many rows sharing a business key, or two phases can ask it for the same rows. Unlike repeated primary-key `Get` calls, non-keyed filtered lookups are not automatically answered by the primary-key record cache. Memoization can remove repeated AL and data-access work, but a cache keyed by too few inputs or kept past a data change returns the wrong answer. A single pass over lines with unknown, possibly distinct item numbers does not establish reuse. + +## Best Practice + +First reuse an already-loaded result if valid. Require evidence that complete lookup keys actually repeat, such as repeated queries for the same item in two passes over an unchanged line set (as in the sample), or measured cache hits. For a repeated, stable filtered lookup, keep a local dictionary for one operation, keyed by every input that affects the result (including company, filters, date, unit, currency, and quantity where applicable). Cache negative results as well as positive ones; distinguish a missing dictionary entry from an entry whose value is `false`. If underlying records can change during the run, update or invalidate the entry, or do not cache it. Bound entries or process in chunks when key cardinality is large. Check distinct complete keys, hits/misses, SQL work, AL time, and memory before adding a cache to a low-reuse workload. Use a temporary table for record-shaped values or multiple keys. See sample: [`cache-repeated-filtered-results-with-explicit-scope.good.al`](cache-repeated-filtered-results-with-explicit-scope.good.al). + +## Anti Pattern + +Running the same filtered `IsEmpty` in two passes over the same unchanged lines (even when every item number is distinct within a pass), or caching a price by item alone when customer, variant, date, and quantity affect it. Do **not** infer a cache opportunity from a single pass with no established key reuse, such as visiting each distinct Item once; the [good sample](cache-repeated-filtered-results-with-explicit-scope.good.al) also shows this valid direct lookup. Do not equate each `Get` with a SQL round trip or automatically wrap a cached primary-key read in another dictionary; see [primary-key cache exceptions](primary-key-get-in-loop-is-transaction-cached.md). See sample: [`cache-repeated-filtered-results-with-explicit-scope.bad.al`](cache-repeated-filtered-results-with-explicit-scope.bad.al). + +## References + +- [Data access and caching](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/optimize-sql-data-access). +- [Dictionary type and `Get`](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/dictionary/dictionary-data-type). diff --git a/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.bad.al b/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.bad.al index 48318a9..8153e70 100644 --- a/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.bad.al +++ b/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.bad.al @@ -1,15 +1,14 @@ codeunit 50223 "Perf Sample CalcSums Bad" { - procedure TotalRemaining(CustomerNo: Code[20]) Total: Decimal + procedure TotalSales(CustomerNo: Code[20]) Total: Decimal var CustLedgerEntry: Record "Cust. Ledger Entry"; begin + CustLedgerEntry.SetCurrentKey("Customer No."); CustLedgerEntry.SetRange("Customer No.", CustomerNo); - // One SQL query per row over a 10M-row ledger. if CustLedgerEntry.FindSet() then repeat - CustLedgerEntry.CalcFields("Remaining Amount"); - Total += CustLedgerEntry."Remaining Amount"; + Total += CustLedgerEntry."Sales (LCY)"; until CustLedgerEntry.Next() = 0; end; } diff --git a/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.good.al b/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.good.al index 2e1f367..2e41049 100644 --- a/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.good.al +++ b/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.good.al @@ -1,11 +1,12 @@ codeunit 50222 "Perf Sample CalcSums Good" { - procedure TotalRemaining(CustomerNo: Code[20]) Total: Decimal + procedure TotalSales(CustomerNo: Code[20]) Total: Decimal var CustLedgerEntry: Record "Cust. Ledger Entry"; begin + CustLedgerEntry.SetCurrentKey("Customer No."); CustLedgerEntry.SetRange("Customer No.", CustomerNo); - CustLedgerEntry.CalcSums("Remaining Amount"); - Total := CustLedgerEntry."Remaining Amount"; + CustLedgerEntry.CalcSums("Sales (LCY)"); + Total := CustLedgerEntry."Sales (LCY)"; end; } diff --git a/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.md b/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.md index f4d7ad9..fff5e25 100644 --- a/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.md +++ b/microsoft/knowledge/performance/calcsums-instead-of-calcfields-in-loop.md @@ -1,26 +1,31 @@ --- bc-version: [all] domain: performance -keywords: [calcfields, calcsums, loop, flowfield, n-plus-one, aggregation] +keywords: [calcfields, calcsums, loop, flowfield, source-field, sumindexfields, aggregation] technologies: [al] countries: [w1] application-area: [all] --- -# Use CalcSums to aggregate, not CalcFields inside a loop +# Use CalcSums for stored-field totals, not as a shortcut for FlowFields ## Description -`CalcFields` materializes FlowField values for one record. Each call against a persistent table is "a separate SQL query"; running it inside a `repeat ... until Next() = 0` over a large table issues one query per row on top of the iteration itself. `CalcSums` answers the same aggregation question — "give me the sum of this FlowField over the filtered set" — as a single SQL statement. Per the upstream guidance, `CalcFields` inside loops on large persistent tables is "a performance problem"; the aggregation form is `CalcSums()`. +`CalcFields` evaluates a FlowField for one record; `CalcSums` totals stored numeric fields in a filtered source table. They do not generally answer the same question. A loop that adds a normal source field for one total can often use one `CalcSums`, possibly backed by a compatible SIFT index. A loop that adds calculated FlowFields cannot be replaced with `CalcSums` on those FlowFields: each `CalcFormula` may depend on its parent record, FlowFilters, and the selected parent set. `CalcFields` requests can also use a recent calculation cache, so source-level call counts are not SQL statement counts. ## Best Practice -When the procedure totals a FlowField (or several) across a filtered set, set the filters, then call `CalcSums("Field 1", "Field 2", ...)`. The platform issues one query; the result is read off the record's FlowField slot. Single `CalcFields` outside loops is fine, and `CalcFields` on the current row in a page's `OnAfterGetRecord` or in `OnValidate` is the standard pattern — those are per-action, not per-row over a large set. +When only one total over stored source fields is needed, set the source-table filters and call `CalcSums` on those fields; select an appropriate current key with `SumIndexFields` when relying on SIFT, and measure the read/write trade-off. If the inputs are FlowFields, derive any proposed source aggregation from their `CalcFormula`, including the selected parent set and FlowFilters, and verify equivalent results before replacing the loop. When every row needs its own FlowField value, [use `SetAutoCalcFields`](use-setautocalcfields-for-per-row-flowfields.md) where appropriate rather than replacing row values with one total. See [SIFT trade-offs](choose-maintainsiftindex-by-read-write-ratio.md). See sample: [`calcsums-instead-of-calcfields-in-loop.good.al`](calcsums-instead-of-calcfields-in-loop.good.al). ## Anti Pattern -`if CustLedgerEntry.FindSet() then repeat CustLedgerEntry.CalcFields("Remaining Amount"); Total += CustLedgerEntry."Remaining Amount"; until CustLedgerEntry.Next() = 0;` — exactly the upstream-flagged shape. The iteration is the cheap part; the per-row `CalcFields` is what scales linearly with table size. +Looping over filtered `Cust. Ledger Entry` records and adding the stored `"Sales (LCY)"` field when the only output is its total. The opposite mistake is proposing `Customer.CalcSums(Balance)` as a generic replacement for adding selected customers' FlowField balances; that changes or fails to express the required calculation. See sample: [`calcsums-instead-of-calcfields-in-loop.bad.al`](calcsums-instead-of-calcfields-in-loop.bad.al). + +## References + +- [CalcFields and CalcSums operate on different field calculations](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-calcfields-calcsums-fielderror-fieldname-init-testfield-and-validate-methods). +- [Record.CalcSums](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/record/record-calcsums-method). diff --git a/microsoft/knowledge/performance/design-covering-keys-from-read-pattern.bad.al b/microsoft/knowledge/performance/design-covering-keys-from-read-pattern.bad.al new file mode 100644 index 0000000..7358289 --- /dev/null +++ b/microsoft/knowledge/performance/design-covering-keys-from-read-pattern.bad.al @@ -0,0 +1,38 @@ +table 50360 "Perf Read Entry" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Entry No."; Integer) { } + field(2; "Customer No."; Code[20]) { } + field(3; "Posting Date"; Date) { } + field(4; "Item No."; Code[20]) { } + field(5; Quantity; Decimal) { } + field(6; Description; Text[100]) { } + } + + keys + { + key(PK; "Entry No.") { Clustered = true; } + key(ByDescription; Description, "Item No.", "Posting Date") { } + key(ByQuantity; Quantity, "Customer No.") { } + } +} + +codeunit 50361 "Perf Read Entry Bad" +{ + procedure SumNonblankItems(CustomerNo: Code[20]; FromDate: Date; ToDate: Date) Total: Decimal + var + Entry: Record "Perf Read Entry"; + begin + Entry.SetRange("Customer No.", CustomerNo); + Entry.SetRange("Posting Date", FromDate, ToDate); + Entry.SetLoadFields("Item No.", Quantity); + if Entry.FindSet() then + repeat + if Entry."Item No." <> '' then + Total += Entry.Quantity; + until Entry.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/design-covering-keys-from-read-pattern.good.al b/microsoft/knowledge/performance/design-covering-keys-from-read-pattern.good.al new file mode 100644 index 0000000..17ea82d --- /dev/null +++ b/microsoft/knowledge/performance/design-covering-keys-from-read-pattern.good.al @@ -0,0 +1,41 @@ +table 50360 "Perf Read Entry" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Entry No."; Integer) { } + field(2; "Customer No."; Code[20]) { } + field(3; "Posting Date"; Date) { } + field(4; "Item No."; Code[20]) { } + field(5; Quantity; Decimal) { } + field(6; Description; Text[100]) { } + } + + keys + { + key(PK; "Entry No.") { Clustered = true; } + key(ByCustomerDate; "Customer No.", "Posting Date") + { + // Supports the filters and explicit payload; implicit system fields may still require lookups. + IncludedFields = "Item No.", Quantity; + } + } +} + +codeunit 50361 "Perf Read Entry Good" +{ + procedure SumNonblankItems(CustomerNo: Code[20]; FromDate: Date; ToDate: Date) Total: Decimal + var + Entry: Record "Perf Read Entry"; + begin + Entry.SetRange("Customer No.", CustomerNo); + Entry.SetRange("Posting Date", FromDate, ToDate); + Entry.SetLoadFields("Item No.", Quantity); + if Entry.FindSet() then + repeat + if Entry."Item No." <> '' then + Total += Entry.Quantity; + until Entry.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/design-covering-keys-from-read-pattern.md b/microsoft/knowledge/performance/design-covering-keys-from-read-pattern.md new file mode 100644 index 0000000..0650086 --- /dev/null +++ b/microsoft/knowledge/performance/design-covering-keys-from-read-pattern.md @@ -0,0 +1,30 @@ +--- +bc-version: [19..] +domain: performance +keywords: [includedfields, covering-index, secondary-key, filter, projection, selectivity, key, setrange] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Design a read-pattern key and verify whether it covers the query + +## Description + +A secondary key should serve a particular read, not a list of fields that happen to look important. The order of key fields affects which filters and sort orders it can support; `IncludedFields` supplies non-key payload columns without making them ordered key columns. `SetCurrentKey` sets an order, not an index hint (see [sort guidance](setcurrentkey-sets-sort-order-not-index-hint.md)). A key that supports the predicates is not necessarily a covering index, and coverage alone does not make a query selective. + +## Best Practice + +For a costly, frequent read, establish its equality and range filters, joins, required ordering, actual SQL projection, cardinality, and existing physical indexes. Test a key whose leading fields support the useful predicates; for example, customer equality followed by a posting-date range. On a nonclustered secondary key, consider `IncludedFields` for small payload fields read but not filtered or ordered. The sample's key supports customer/date filters and includes the explicit payload, but is **not demonstrated to cover the read**: Business Central also projects `SystemId` and system audit fields on partial records. Check the generated SQL, including automatically selected, clustered-key, and extension fields, against the physical index before claiming coverage. Adding more included fields has storage and write-maintenance costs; measure reads, sorts, lookups, latency, and writes before expanding it. The [Database Missing Indexes page](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/database-missing-indexes) supplies candidates, not a mandate to add every suggested key. + +`IncludedFields` requires runtime 8.0 (BC 19) or later and cannot be set on a primary or clustered secondary key. An included field does not participate in `SetCurrentKey` matching or maintain a SIFT sum. If the item is also a selective predicate or required ordering column, evaluate it as a key field instead. Respect table-extension key field-ownership restrictions. See sample: [`design-covering-keys-from-read-pattern.good.al`](design-covering-keys-from-read-pattern.good.al). + +## Anti Pattern + +Adding a key on output-only fields or requesting an unrelated `SetCurrentKey` ordering to "force" the optimizer to use that key, without establishing the read's filters or validating its plan. Likewise, calling an index covering just because it contains the fields explicitly listed in `SetLoadFields` ignores automatically projected columns. Do not report every uncovered read as a defect: a small table, a low-frequency query, or a write-heavy table may be better without another maintained index. See sample: [`design-covering-keys-from-read-pattern.bad.al`](design-covering-keys-from-read-pattern.bad.al). + +## References + +- [Table keys, included columns, and extension restrictions](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-table-keys). +- [IncludedFields property](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/properties/devenv-includedfields-property). +- [Table keys and performance](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/optimize-sql-table-keys-and-performance). diff --git a/microsoft/knowledge/performance/isempty-before-findset-is-extra-round-trip.md b/microsoft/knowledge/performance/isempty-before-findset-is-extra-round-trip.md index c88cdfe..cdbd8ae 100644 --- a/microsoft/knowledge/performance/isempty-before-findset-is-extra-round-trip.md +++ b/microsoft/knowledge/performance/isempty-before-findset-is-extra-round-trip.md @@ -13,11 +13,11 @@ application-area: [all] ## Description -`IsEmpty` is the right API when the caller only needs existence — see `microsoft/knowledge/performance/use-isempty-for-existence-check.md`. It is not a cheap guard in front of a loop that will `FindSet` anyway. Both calls hit the database; `FindSet` already returns false when the filter matches nothing. Agents and reviewers often insert `if not Rec.IsEmpty() then` "for performance" and pay a second query for a result the iterator already provides. +`IsEmpty` is the right API when the caller only needs existence — see `microsoft/knowledge/performance/use-isempty-for-existence-check.md`. It is not a cheap guard in front of a loop that will `FindSet` anyway. `FindSet` already returns false when the filter matches nothing; an extra `IsEmpty` is unnecessary AL work and can issue a second database request, depending on caching. Agents and reviewers often insert `if not Rec.IsEmpty() then` "for performance" and duplicate a result the iterator already provides. ## Best Practice -When the body iterates, open with `if Rec.FindSet() then repeat ... until Next() = 0`. Do not flag a bare `FindSet` loop as missing an `IsEmpty` precondition. Reserve `IsEmpty` for branches that never materialize the row set. +When the body iterates, open with `if Rec.FindSet() then repeat ... until Next() = 0`. Do not flag a bare `FindSet` loop as missing an `IsEmpty` precondition. Reserve `IsEmpty` for branches that never materialize the row set. An early check before a *bulk write* or lock is a different, workload-dependent decision: it can help when the filtered set is usually empty, but adds work when rows exist and does not lock the set against change. See sample: [`isempty-before-findset-is-extra-round-trip.good.al`](isempty-before-findset-is-extra-round-trip.good.al). diff --git a/microsoft/knowledge/performance/prefer-modifyall-over-per-row-modify.good.al b/microsoft/knowledge/performance/prefer-modifyall-over-per-row-modify.good.al index 9a3ad4c..1c0fa22 100644 --- a/microsoft/knowledge/performance/prefer-modifyall-over-per-row-modify.good.al +++ b/microsoft/knowledge/performance/prefer-modifyall-over-per-row-modify.good.al @@ -20,6 +20,7 @@ codeunit 50242 "Perf Sample ModifyAll Good" StagingEntry: Record "Perf Import Staging Entry"; begin StagingEntry.SetRange("Batch ID", BatchId); + StagingEntry.SetRange(Processed, false); // Processed has no OnValidate logic, and the equivalent loop uses Modify(false). StagingEntry.ModifyAll(Processed, true, false); end; diff --git a/microsoft/knowledge/performance/prefer-modifyall-over-per-row-modify.md b/microsoft/knowledge/performance/prefer-modifyall-over-per-row-modify.md index ad7a6cf..34ea81c 100644 --- a/microsoft/knowledge/performance/prefer-modifyall-over-per-row-modify.md +++ b/microsoft/knowledge/performance/prefer-modifyall-over-per-row-modify.md @@ -15,7 +15,7 @@ application-area: [all] ## Best Practice -Use `ModifyAll` when the loop directly assigns the same value, does not call `Validate`, needs no per-row calculation, and does not depend on `OnModify` unless the equivalent `RunTrigger` value is supplied. Check whether table trigger code, related subscribers, security filtering, `Media`/`MediaSet`, or companion fields force row-by-row fallback (see `triggers-and-media-field-regress-modifyall.md`). A visible loop for progress UX is acceptable only when evidence shows the equivalent bulk call already executes as individual operations and the loop preserves trigger and business semantics. +Use `ModifyAll` when the loop directly assigns the same value, does not call `Validate`, needs no per-row calculation, and does not depend on `OnModify` unless the equivalent `RunTrigger` value is supplied. For a data-only update, exclude rows already holding the target value when that filter preserves the business outcome. Do not skip unchanged rows if the original call's per-row effects are required. Check whether table trigger code, related subscribers, security filtering, `Media`/`MediaSet`, or companion fields force row-by-row fallback (see `triggers-and-media-field-regress-modifyall.md`). A visible loop for progress UX is acceptable only when evidence shows the equivalent bulk call already executes as individual operations and the loop preserves trigger and business semantics. See sample: [`prefer-modifyall-over-per-row-modify.good.al`](prefer-modifyall-over-per-row-modify.good.al). diff --git a/microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.bad.al b/microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.bad.al new file mode 100644 index 0000000..d6c02c3 --- /dev/null +++ b/microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.bad.al @@ -0,0 +1,61 @@ +// Each invocation exclusively owns a new run; these tables have no write logic. +table 50364 "Perf Input" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Row No."; Integer) { } + field(2; "Item No."; Code[20]) { } + field(3; Quantity; Decimal) { } + } + + keys + { + key(PK; "Row No.") { Clustered = true; } + } +} + +table 50365 "Perf Output" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Run ID"; Guid) { } + field(2; "Line No."; Integer) { } + field(3; "Item No."; Code[20]) { } + field(4; Quantity; Decimal) { } + } + + keys + { + key(PK; "Run ID", "Line No.") { Clustered = true; } + } +} + +codeunit 50366 "Perf Buffered Insert Bad" +{ + procedure CopyRun(var TempInput: Record "Perf Input" temporary) RunId: Guid + var + Output: Record "Perf Output"; + NextLineNo: Integer; + begin + RunId := CreateGuid(); + Output.SetRange("Run ID", RunId); + if TempInput.FindSet() then + repeat + if Output.FindLast() then + NextLineNo := Output."Line No." + 1 + else + NextLineNo := 1; + Output.Init(); + Output."Run ID" := RunId; + Output."Line No." := NextLineNo; + Output."Item No." := TempInput."Item No."; + Output.Insert(false); + Output.Quantity := TempInput.Quantity; + Output.Modify(false); + until TempInput.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.good.al b/microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.good.al new file mode 100644 index 0000000..96d0faa --- /dev/null +++ b/microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.good.al @@ -0,0 +1,56 @@ +// Each invocation exclusively owns a new run; these tables have no write logic. +table 50364 "Perf Input" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Row No."; Integer) { } + field(2; "Item No."; Code[20]) { } + field(3; Quantity; Decimal) { } + } + + keys + { + key(PK; "Row No.") { Clustered = true; } + } +} + +table 50365 "Perf Output" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Run ID"; Guid) { } + field(2; "Line No."; Integer) { } + field(3; "Item No."; Code[20]) { } + field(4; Quantity; Decimal) { } + } + + keys + { + key(PK; "Run ID", "Line No.") { Clustered = true; } + } +} + +codeunit 50366 "Perf Buffered Insert Good" +{ + procedure CopyRun(var TempInput: Record "Perf Input" temporary) RunId: Guid + var + Output: Record "Perf Output"; + NextLineNo: Integer; + begin + RunId := CreateGuid(); + if TempInput.FindSet() then + repeat + NextLineNo += 1; + Output.Init(); + Output."Run ID" := RunId; + Output."Line No." := NextLineNo; + Output."Item No." := TempInput."Item No."; + Output.Quantity := TempInput.Quantity; + Output.Insert(false); + until TempInput.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.md b/microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.md new file mode 100644 index 0000000..7459ee4 --- /dev/null +++ b/microsoft/knowledge/performance/preserve-buffered-inserts-by-separating-target-reads.md @@ -0,0 +1,27 @@ +--- +bc-version: [all] +domain: performance +keywords: [buffered-inserts, bulk-inserts, findlast, insert, target-table, commit, staging] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Keep eligible inserts together instead of re-reading their target + +## Description + +Business Central can automatically buffer eligible `Insert` calls. `Find`/`Calc` on the **target** table, `Modify`/`Delete` on it, or `Commit` flushes pending inserts; consuming the `Insert` return value, or BLOB/AutoIncrement fields on the target, prevents buffering. A source-table read is not itself a target-table flush. There is no general `InsertAll` replacement for an AL loop. + +## Best Practice + +When writing completed rows to an application-owned data-only table, allocate a collision-free run or range once, prepare every field before each `Insert`, and keep the insert sequence free of intervening target-table reads and writes. Let the owning business transaction determine the commit point. Trace called procedures and events as well as the visible loop; inspect actual SQL batches and writes, then test failures, retries, and any concurrent writers. The sample assumes an exclusive new run ID and no required trigger, validation, number-series, or subscriber effects. See sample: [`preserve-buffered-inserts-by-separating-target-reads.good.al`](preserve-buffered-inserts-by-separating-target-reads.good.al). + +## Anti Pattern + +Calling `FindLast` on the target for every row to allocate its next line number, inserting an incomplete row and immediately modifying it, or committing each iteration of an otherwise eligible insert sequence. Moving a shared `FindLast` out of the loop without concurrency-safe allocation is **not** a valid fix. Do not recommend skipping required triggers or persistence steps in sales documents, journals, or posting ledgers just to obtain buffering; repeated `Modify` calls do not automatically batch like eligible inserts. See sample: [`preserve-buffered-inserts-by-separating-target-reads.bad.al`](preserve-buffered-inserts-by-separating-target-reads.bad.al). + +## References + +- [Bulk inserts and flush/non-buffering conditions](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/optimize-sql-bulk-inserts). +- [Transaction checkpoints and restart safety](avoid-commit-inside-loops.md). diff --git a/microsoft/knowledge/performance/primary-key-get-in-loop-is-transaction-cached.md b/microsoft/knowledge/performance/primary-key-get-in-loop-is-transaction-cached.md index ed41f1b..3594a05 100644 --- a/microsoft/knowledge/performance/primary-key-get-in-loop-is-transaction-cached.md +++ b/microsoft/knowledge/performance/primary-key-get-in-loop-is-transaction-cached.md @@ -13,12 +13,12 @@ application-area: [all] The Business Central server caches primary-key reads within a transaction. Repeated `Record.Get()` calls for the same key are served from that cache rather than re-queried, so a guarded `if not Rec.Get(...) then exit;` inside a per-row helper is not a genuine N+1 pattern. When each row legitimately carries a distinct key — for example one `Bin Content` row per bin, so `Bin.Get` and `BinType.Get` see a different bin each iteration — the `Get` must run per row regardless, and there is nothing to hoist. -Reviewers sometimes see two `Get` calls inside a routine that runs once per row and recommend wrapping them in a `Dictionary` cache. That is over-engineering: it duplicates the server's built-in record cache, adds state that must be invalidated, and breaks the surrounding extension's established pattern of direct guarded `Get` calls. +Reviewers sometimes see two `Get` calls inside a routine that runs once per row and recommend wrapping them in a `Dictionary` cache. Without evidence of a material additional cost, that duplicates the server's built-in record cache and adds state that must be invalidated. Filtered, non-keyed reads are a different case (see [repeated filtered results](cache-repeated-filtered-results-with-explicit-scope.md)). ## Best Practice -Treat a primary-key `Get()` — especially a guarded `if not Rec.Get(...) then exit;` — as a cheap, transaction-cached read. Do not recommend a manual `Dictionary` cache around per-row primary-key `Get` calls. Reserve N+1 concerns for genuinely repeated non-keyed queries (`FindSet`/`FindFirst` with filters, `Count`) that re-hit the database each iteration. +Treat a primary-key `Get()` — especially a guarded `if not Rec.Get(...) then exit;` — as a transaction-cached read, not as proof of N+1 SQL. Do not recommend a manual cache solely from source-level call counts. If profiling shows repeated AL work or cache misses are material and the complete result can be reused safely, assess an explicitly scoped cache on its own merits. Investigate genuinely repeated non-keyed queries (`FindSet`/`FindFirst` with filters, `Count`) separately. ## Anti Pattern -Reporting repeated primary-key `Get` calls (such as `Bin.Get` and `BinType.Get`) inside a per-row helper as a performance defect, or recommending they be cached in a `Dictionary`. The reads are already cached by the server within the transaction, and per-row keys often differ so the calls cannot be hoisted. +Reporting repeated primary-key `Get` calls (such as `Bin.Get` and `BinType.Get`) inside a per-row helper as one SQL round trip per call, or recommending a `Dictionary` without measuring reuse and cost. Per-row keys often differ, and the server can satisfy repeated keys from its transaction cache. diff --git a/microsoft/knowledge/performance/query-results-bypass-primary-key-cache.md b/microsoft/knowledge/performance/query-results-bypass-primary-key-cache.md index 5bcfbd8..52f590c 100644 --- a/microsoft/knowledge/performance/query-results-bypass-primary-key-cache.md +++ b/microsoft/knowledge/performance/query-results-bypass-primary-key-cache.md @@ -13,7 +13,7 @@ application-area: [all] ## Description -The Business Central server caches primary-key `Get` calls within a transaction. Query objects do not use that cache: every `Open`/`Read` goes to SQL. `avoid-get-inside-loop-on-large-table.md` is right when an unbounded inner `Get`/`FindFirst` joins two large sets. It is wrong as a blanket rewrite of repeated `Get` on the same keys. Replacing a cached `Get` with a Query that re-executes per call can be slower. This file exists so reviewers stop treating every `Get` inside a loop as a Query candidate. +The Business Central server caches primary-key `Get` calls within a transaction. Query objects do not use that primary-key cache: reopening a Query per lookup executes the query again; `Read` consumes rows from an open query, not a new query for each row. `avoid-get-inside-loop-on-large-table.md` is right when an unbounded inner `Get`/`FindFirst` joins two large sets. It is wrong as a blanket rewrite of repeated `Get` on the same keys. Replacing a cached `Get` with a Query reopened per call can be slower. ## Best Practice diff --git a/microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.bad.al b/microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.bad.al new file mode 100644 index 0000000..7ad16a6 --- /dev/null +++ b/microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.bad.al @@ -0,0 +1,43 @@ +// The only supported read filters customer/date and displays item, quantity, and amount. +// No consumer needs ordering on the displayed fields or a SIFT aggregate. +table 50362 "Perf Document Entry" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Entry No."; Integer) { } + field(2; "Customer No."; Code[20]) { } + field(3; "Posting Date"; Date) { } + field(4; "Item No."; Code[20]) { } + field(5; Quantity; Decimal) { } + field(6; Amount; Decimal) { } + } + + keys + { + key(PK; "Entry No.") { Clustered = true; } + key(CustomerDate; "Customer No.", "Posting Date") { } + key(CustomerDateItem; "Customer No.", "Posting Date", "Item No.") { } + key(CustomerDateQuantity; "Customer No.", "Posting Date", Quantity) { } + key(CustomerDateAmount; "Customer No.", "Posting Date", Amount) { } + } +} + +codeunit 50375 "Perf Document Reader Bad" +{ + procedure CustomerDateTotals(CustomerNo: Code[20]; FromDate: Date; ToDate: Date; var ItemNos: List of [Code[20]]; var TotalAmount: Decimal; var TotalQuantity: Decimal) + var + Entry: Record "Perf Document Entry"; + begin + Entry.SetRange("Customer No.", CustomerNo); + Entry.SetRange("Posting Date", FromDate, ToDate); + Entry.SetLoadFields("Item No.", Quantity, Amount); + if Entry.FindSet() then + repeat + ItemNos.Add(Entry."Item No."); + TotalQuantity += Entry.Quantity; + TotalAmount += Entry.Amount; + until Entry.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.good.al b/microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.good.al new file mode 100644 index 0000000..8608396 --- /dev/null +++ b/microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.good.al @@ -0,0 +1,43 @@ +// The only supported read filters customer/date and displays item, quantity, and amount. +// No consumer needs ordering on the displayed fields or a SIFT aggregate. +table 50362 "Perf Document Entry" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Entry No."; Integer) { } + field(2; "Customer No."; Code[20]) { } + field(3; "Posting Date"; Date) { } + field(4; "Item No."; Code[20]) { } + field(5; Quantity; Decimal) { } + field(6; Amount; Decimal) { } + } + + keys + { + key(PK; "Entry No.") { Clustered = true; } + key(CustomerDatePayload; "Customer No.", "Posting Date") + { + IncludedFields = "Item No.", Quantity, Amount; + } + } +} + +codeunit 50375 "Perf Document Reader Good" +{ + procedure CustomerDateTotals(CustomerNo: Code[20]; FromDate: Date; ToDate: Date; var ItemNos: List of [Code[20]]; var TotalAmount: Decimal; var TotalQuantity: Decimal) + var + Entry: Record "Perf Document Entry"; + begin + Entry.SetRange("Customer No.", CustomerNo); + Entry.SetRange("Posting Date", FromDate, ToDate); + Entry.SetLoadFields("Item No.", Quantity, Amount); + if Entry.FindSet() then + repeat + ItemNos.Add(Entry."Item No."); + TotalQuantity += Entry.Quantity; + TotalAmount += Entry.Amount; + until Entry.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.md b/microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.md new file mode 100644 index 0000000..61ed36e --- /dev/null +++ b/microsoft/knowledge/performance/review-overlapping-keys-before-adding-an-index.md @@ -0,0 +1,29 @@ +--- +bc-version: [all] +domain: performance +keywords: [overlapping-keys, redundant-index, includedfields, sift, write-amplification, index-portfolio, key, setrange] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Review overlapping keys as a portfolio + +## Description + +Adding a secondary key to a frequently written table maintains another SQL index for every affected write. Several keys with the same leading fields might be serving distinct filters, sort orders, unique constraints, or SIFT aggregates; they might instead be redundant payload variants. A shared prefix, absent `SetCurrentKey` calls, or low usage in a short window is not proof that a key is unused. + +## Best Practice + +Before adding or removing a key, inventory keys from the table and installed extensions and identify each key's consumers and purpose: seek, ordering, uniqueness, or aggregation. Check `SQLIndex`, `MaintainSQLIndex`, `SumIndexFields`, and `MaintainSIFTIndex`, not only the AL key name. For *confirmed* payload-only variants on BC 19 or later, a single nonclustered key with `IncludedFields` can be a consolidation candidate (see [read-pattern key design](design-covering-keys-from-read-pattern.md)); an included field cannot replace a key column used for ordering or a maintained SIFT sum. Including the explicit payload does not prove that the resulting index covers every automatically selected field. Measure representative read and write workloads, including periodic reports, integrations, and other companies, before and after a supported extension/schema change. Retain a rollback path for a critical reader that regresses. See sample: [`review-overlapping-keys-before-adding-an-index.good.al`](review-overlapping-keys-before-adding-an-index.good.al). + +## Anti Pattern + +Keeping another customer/date key for each displayed field without checking whether the trailing fields support distinct operations. Conversely, merging `(Customer, Date)` with `(Customer, Item, Date)` merely because they share a prefix can regress item-selective queries; removing a unique key or a SIFT aggregate changes more than write cost. Do not report a key as unused solely because AL never calls `SetCurrentKey` on it. See sample: [`review-overlapping-keys-before-adding-an-index.bad.al`](review-overlapping-keys-before-adding-an-index.bad.al). + +## References + +- [Table keys: benefits, costs, and constraints](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-table-keys). +- [IncludedFields property](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/properties/devenv-includedfields-property). +- [Manage index usage (BC 2026 release wave 1 and later)](https://learn.microsoft.com/en-us/dynamics365/business-central/manage-indexes). +- [SIFT read/write trade-off](choose-maintainsiftindex-by-read-write-ratio.md). diff --git a/microsoft/knowledge/performance/setcurrentkey-sets-sort-order-not-index-hint.md b/microsoft/knowledge/performance/setcurrentkey-sets-sort-order-not-index-hint.md index ad0bb40..ea99299 100644 --- a/microsoft/knowledge/performance/setcurrentkey-sets-sort-order-not-index-hint.md +++ b/microsoft/knowledge/performance/setcurrentkey-sets-sort-order-not-index-hint.md @@ -7,11 +7,11 @@ countries: [w1] application-area: [all] --- -# SetCurrentKey only sets sort order — it is not an index hint +# SetCurrentKey is not a SQL index hint for record reads ## Description -A common misconception is that `SetCurrentKey` tells SQL Server which index to use for a query. It does not. In Business Central, `SetCurrentKey` only changes the `ORDER BY` clause of the generated SQL statement. It does not add an index hint, and the SQL Server query optimizer is free to ignore the named key entirely. +A common misconception is that `SetCurrentKey` tells SQL Server which index to use for a filtered `FindSet`/`FindFirst` query. It does not. For record iteration, `SetCurrentKey` changes the `ORDER BY` clause of the generated SQL statement; it does not add an index hint, and the SQL Server query optimizer is free to ignore the named key entirely. A distinct use is selecting an appropriate key with `SumIndexFields` before `CalcSums` so the platform can use a compatible SIFT aggregate (see [SIFT and SQL Server](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-sift-and-sql-server)). The optimizer picks the index from the `WHERE` clause (your `SetRange`/`SetFilter`) together with table statistics and estimated cost. In practice it almost never chooses an index just because that key appears in `ORDER BY`. So calling `SetCurrentKey` to "steer" the plan toward an index is a no-op for index selection — and can make things worse: an `ORDER BY` that the query does not otherwise need can push the optimizer toward a less selective index or add a Sort operator to the plan. @@ -19,13 +19,15 @@ Selectivity comes from having the right index available (a key on the table whos ## Best Practice -Decide `SetCurrentKey` on one question only: **do I need the result set in a specific order?** +For a record-iteration read, decide `SetCurrentKey` on one question: **do I need the result set in a specific order?** - If yes — you iterate rows in a defined sequence, or rely on `FindFirst`/`FindLast`/`Next` returning a particular row — call `SetCurrentKey` for that sort. The order is a functional requirement, and the `ORDER BY` is justified. - If no — omit `SetCurrentKey`. Let the optimizer choose the cheapest plan for your filters; it may pick a better index and skip a sort. To make a filtered read fast, ensure a key (index) exists on the table whose leading fields cover the filter, and filter on those fields with `SetRange`/`SetFilter`. That is what lets the optimizer seek. Defining the key creates the index; `SetCurrentKey` is not required to make the optimizer use it. +For a stored-field `CalcSums` instead of iteration, consider a matching current key with the summed field in `SumIndexFields`, as documented for SIFT; do not classify that call as an unnecessary `ORDER BY` on a row iterator (see [stored-field totals](calcsums-instead-of-calcfields-in-loop.md)). + See sample: [`setcurrentkey-sets-sort-order-not-index-hint.good.al`](setcurrentkey-sets-sort-order-not-index-hint.good.al). ## Anti Pattern diff --git a/microsoft/knowledge/performance/temporary-tables-have-no-database-cost.bad.al b/microsoft/knowledge/performance/temporary-tables-have-no-database-cost.bad.al new file mode 100644 index 0000000..f3de8f5 --- /dev/null +++ b/microsoft/knowledge/performance/temporary-tables-have-no-database-cost.bad.al @@ -0,0 +1,39 @@ +// Caller supplies an unfiltered temporary buffer that does not change during this call. +table 50373 "Perf Cell" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Cell No."; Integer) { } + field(2; "Item No."; Code[20]) { } + field(3; Quantity; Decimal) { } + } + + keys + { + key(PK; "Cell No.") { Clustered = true; } + } +} + +codeunit 50374 "Perf Temp Totals Bad" +{ + procedure SumDisplayedItemTotals(var TempCells: Record "Perf Cell" temporary) DisplayedTotal: Decimal + var + TempScan: Record "Perf Cell" temporary; + ItemTotal: Decimal; + begin + TempScan.Copy(TempCells, true); + if TempCells.FindSet() then + repeat + TempScan.Reset(); + TempScan.SetRange("Item No.", TempCells."Item No."); + ItemTotal := 0; + if TempScan.FindSet() then + repeat + ItemTotal += TempScan.Quantity; + until TempScan.Next() = 0; + DisplayedTotal += ItemTotal; + until TempCells.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/temporary-tables-have-no-database-cost.good.al b/microsoft/knowledge/performance/temporary-tables-have-no-database-cost.good.al new file mode 100644 index 0000000..c02da0c --- /dev/null +++ b/microsoft/knowledge/performance/temporary-tables-have-no-database-cost.good.al @@ -0,0 +1,39 @@ +// Caller supplies an unfiltered temporary buffer that does not change during this call. +table 50373 "Perf Cell" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "Cell No."; Integer) { } + field(2; "Item No."; Code[20]) { } + field(3; Quantity; Decimal) { } + } + + keys + { + key(PK; "Cell No.") { Clustered = true; } + } +} + +codeunit 50374 "Perf Temp Totals Good" +{ + procedure SumDisplayedItemTotals(var TempCells: Record "Perf Cell" temporary) DisplayedTotal: Decimal + var + TotalsByItem: Dictionary of [Code[20], Decimal]; + ItemTotal: Decimal; + begin + if TempCells.FindSet() then + repeat + if TotalsByItem.Get(TempCells."Item No.", ItemTotal) then + TotalsByItem.Set(TempCells."Item No.", ItemTotal + TempCells.Quantity) + else + TotalsByItem.Add(TempCells."Item No.", TempCells.Quantity); + until TempCells.Next() = 0; + + if TempCells.FindSet() then + repeat + DisplayedTotal += TotalsByItem.Get(TempCells."Item No."); + until TempCells.Next() = 0; + end; +} diff --git a/microsoft/knowledge/performance/temporary-tables-have-no-database-cost.md b/microsoft/knowledge/performance/temporary-tables-have-no-database-cost.md index 3fd8072..a392e0b 100644 --- a/microsoft/knowledge/performance/temporary-tables-have-no-database-cost.md +++ b/microsoft/knowledge/performance/temporary-tables-have-no-database-cost.md @@ -15,8 +15,12 @@ A temporary table stores its rows in Business Central Server memory instead of a ## Best Practice -Do not apply SQL-specific findings such as missing `SetLoadFields`, lock contention, or N+1 database round-trips to a temporary record. Still assess memory volume and repeated scans or lookups. For a pure key-to-value collection, consider an AL `Dictionary`; keep a temporary table when record fields, keys, filtering, or ordered iteration are required. +Do not apply SQL-specific findings such as missing `SetLoadFields`, lock contention, or N+1 database round-trips to a temporary record. Still assess memory volume and repeated scans or lookups. In a matrix, if each cell re-sums the same group, calculate the totals once at the complete group key and reuse them; invalidate or adjust totals if cells change. For a pure key-to-value collection, consider an AL `Dictionary`; keep a temporary table when record fields, keys, filtering, or ordered iteration are required. Measure AL time and peak memory, not just SQL time. + +See sample: [`temporary-tables-have-no-database-cost.good.al`](temporary-tables-have-no-database-cost.good.al). ## Anti Pattern Claiming that every temporary-table access pattern is free because no SQL is involved. A nested scan over a large in-memory buffer can still dominate service-tier CPU, while adding `SetLoadFields` to that buffer addresses a database cost that does not exist. + +See sample: [`temporary-tables-have-no-database-cost.bad.al`](temporary-tables-have-no-database-cost.bad.al). diff --git a/microsoft/knowledge/performance/use-setautocalcfields-for-per-row-flowfields.md b/microsoft/knowledge/performance/use-setautocalcfields-for-per-row-flowfields.md index b5f9d6a..e23cc98 100644 --- a/microsoft/knowledge/performance/use-setautocalcfields-for-per-row-flowfields.md +++ b/microsoft/knowledge/performance/use-setautocalcfields-for-per-row-flowfields.md @@ -15,12 +15,12 @@ application-area: [all] ## Best Practice -Call `SetAutoCalcFields` before `FindSet` when every returned row needs the same FlowField for a comparison, branch, or per-record action. Use `CalcSums` instead when the required result is one aggregate over the filtered set (see `calcsums-instead-of-calcfields-in-loop.md`). +Call `SetAutoCalcFields` before `FindSet` when every returned row needs the same FlowField for a comparison, branch, or per-record action. For one total of a **stored source field**, consider `CalcSums` instead (see [stored-field totals versus FlowFields](calcsums-instead-of-calcfields-in-loop.md)). If the required result is a total of selected FlowField values, derive the underlying source filters from `CalcFormula`; do not sum the FlowField directly with `CalcSums`. See sample: [`use-setautocalcfields-for-per-row-flowfields.good.al`](use-setautocalcfields-for-per-row-flowfields.good.al). ## Anti Pattern -Calling `CalcFields` inside the loop when every iteration reads the same FlowField. Each `CalcFields` request requires a separate SQL statement unless a compatible recent result is cached. Do not replace row-specific decisions with `CalcSums`; an aggregate cannot preserve which rows met the condition. +Calling `CalcFields` inside the loop when every iteration reads the same FlowField. A compatible recent result can be cached, so do not equate each call with a SQL statement. Do not replace row-specific decisions with `CalcSums`; an aggregate cannot preserve which rows met the condition. See sample: [`use-setautocalcfields-for-per-row-flowfields.bad.al`](use-setautocalcfields-for-per-row-flowfields.bad.al). diff --git a/microsoft/knowledge/performance/use-setloadfields-for-partial-records.bad.al b/microsoft/knowledge/performance/use-setloadfields-for-partial-records.bad.al index c9b4ce2..c7054f3 100644 --- a/microsoft/knowledge/performance/use-setloadfields-for-partial-records.bad.al +++ b/microsoft/knowledge/performance/use-setloadfields-for-partial-records.bad.al @@ -1,14 +1,18 @@ codeunit 50219 "Perf Sample LoadFields Bad" { - procedure ListUSCustomerNames() + procedure CollectUSCustomerNamesAndCities(var DisplayNames: List of [Text]) var Customer: Record Customer; begin - // Loads every Customer column on every row, when only Name is read. Customer.SetRange("Country/Region Code", 'US'); if Customer.FindSet() then repeat - Message(Customer.Name); + DisplayNames.Add(CustomerDisplayText(Customer)); until Customer.Next() = 0; end; + + local procedure CustomerDisplayText(Customer: Record Customer): Text + begin + exit(Customer.Name + ' ' + Customer.City); + end; } diff --git a/microsoft/knowledge/performance/use-setloadfields-for-partial-records.good.al b/microsoft/knowledge/performance/use-setloadfields-for-partial-records.good.al index a5bee5f..c663bc4 100644 --- a/microsoft/knowledge/performance/use-setloadfields-for-partial-records.good.al +++ b/microsoft/knowledge/performance/use-setloadfields-for-partial-records.good.al @@ -1,17 +1,22 @@ codeunit 50218 "Perf Sample LoadFields Good" { - procedure ListUSCustomerNames() + procedure CollectUSCustomerNamesAndCities(var DisplayNames: List of [Text]) var Customer: Record Customer; begin Customer.SetRange("Country/Region Code", 'US'); - Customer.SetLoadFields(Name); + Customer.SetLoadFields(Name, City); if Customer.FindSet() then repeat - Message(Customer.Name); + DisplayNames.Add(CustomerDisplayText(Customer)); until Customer.Next() = 0; end; + local procedure CustomerDisplayText(Customer: Record Customer): Text + begin + exit(Customer.Name + ' ' + Customer.City); + end; + procedure LookupSkuPolicy(LocationCode: Code[10]) Policy: Enum "SKU Creation Method" var Location: Record Location; diff --git a/microsoft/knowledge/performance/use-setloadfields-for-partial-records.md b/microsoft/knowledge/performance/use-setloadfields-for-partial-records.md index de92bb1..5bd9bb7 100644 --- a/microsoft/knowledge/performance/use-setloadfields-for-partial-records.md +++ b/microsoft/knowledge/performance/use-setloadfields-for-partial-records.md @@ -17,7 +17,7 @@ Its position relative to `SetRange`/`SetFilter` does not change the projection: ## Best Practice -Before a `Get`, `FindSet`, or `FindFirst` that the procedure follows by reading only a handful of the table's fields, call `SetLoadFields` listing exactly those fields. For example, `SetLoadFields(...); if Record.Get(...) then ...` selects fields before the read. Place the call immediately before the read, after any `SetRange`/`SetFilter`, so a reader can see at a glance which read the selection governs and any projection-changing operation is easy to spot. Skip `SetLoadFields` when the table has few fields (under ten), when the code reads most of them (above 60 %), when the loop runs ten or fewer iterations, or when the table is exempt for other reasons ([singleton setup tables](singleton-setup-tables-need-no-access-optimization.md), [temporary tables](temporary-tables-have-no-database-cost.md)). The numeric cutoffs are BCQuality review heuristics, not Microsoft platform thresholds. For report dataitems, use `AddLoadFields` in `OnPreDataItem` instead (see [report partial loads](addloadfields-in-report-onpredataitem.md)). +Before a `Get`, `FindSet`, or `FindFirst` that the complete read path follows by reading only a handful of the table's fields, call `SetLoadFields` listing the normal fields used by the caller **and its helpers**. For example, `SetLoadFields(...); if Record.Get(...) then ...` selects fields before the read. Place the call immediately before the read, after any `SetRange`/`SetFilter`, so a reader can see at a glance which read the selection governs and any projection-changing operation is easy to spot. Check for later `Reset` and for unloaded fields read by a [by-value helper](pass-var-record-to-preserve-partial-load-enumerator.md); a JIT load can be served from cache, so it is not automatically a SQL round trip. Skip `SetLoadFields` when the table has few fields (under ten), when the code reads most of them (above 60 %), when the loop runs ten or fewer iterations, or when the table is exempt for other reasons ([singleton setup tables](singleton-setup-tables-need-no-access-optimization.md), [temporary tables](temporary-tables-have-no-database-cost.md)). The numeric cutoffs are BCQuality review heuristics, not Microsoft platform thresholds. For report dataitems, use `AddLoadFields` in `OnPreDataItem` instead (see [report partial loads](addloadfields-in-report-onpredataitem.md)). See sample: [`use-setloadfields-for-partial-records.good.al`](use-setloadfields-for-partial-records.good.al). diff --git a/microsoft/skills/review/al-performance-review.md b/microsoft/skills/review/al-performance-review.md index cfaf9f7..6eae659 100644 --- a/microsoft/skills/review/al-performance-review.md +++ b/microsoft/skills/review/al-performance-review.md @@ -39,13 +39,16 @@ Narrow the relevant files to the subset that applies to the changes under review - The changed AL object names and types — especially tables, pages with SourceTable bindings, reports, queries, and codeunits performing record iteration. - The changed procedures and triggers, weighted toward those that perform loops, Find/FindSet/FindFirst calls, CalcFields, SetAutoCalcFields, CalcSums, FlowField access, Commit calls, checkpoint helpers, record copying, RecordRef conversion, Modify/Delete calls, or cross-table navigation. -- Tokens extracted from the diff that relate to data access, hot-path costs, and background scheduling (`SetRange`, `SetFilter`, `SetLoadFields`, `SetCurrentKey`, `FindSet`, `ReadIsolation`, `LockTable`, `ModifyAll`, `DeleteAll`, `Modify`, `Delete`, `Commit`, `checkpoint`, `Copy`, `RecordRef`, `GetTable`, `TextBuilder`, `Dictionary`, `temporary`, `repeat`, `until`, `CalcFields`, `SetAutoCalcFields`, `CalcSums`, `FlowField`, `Visible`, `Job Queue Entry`, `Job Queue Category Code`, `Confirm`, `RunModal`, `GuiAllowed`, `TryFunction`, `Codeunit.Run`, `HttpClient`, `Status`, `On Hold`, `stop request`, `TaskScheduler.CreateTask`, `TaskScheduler.TaskExists`, `Page.RunModal`, `Report.RunModal`, `Report.Run`, `Xmlport.Run`, `UseRequestPage`). +- Tokens extracted from the diff that relate to data access, hot-path costs, and background scheduling (`key`, `IncludedFields`, `SumIndexFields`, `SetRange`, `SetFilter`, `SetLoadFields`, `SetCurrentKey`, `FindSet`, `FindLast`, `IsEmpty`, `ReadIsolation`, `LockTable`, `Insert`, `ModifyAll`, `DeleteAll`, `Modify`, `Delete`, `Validate`, `Commit`, `checkpoint`, `Copy`, `RecordRef`, `GetTable`, `TextBuilder`, `Dictionary`, `temporary`, `repeat`, `until`, `CalcFields`, `SetAutoCalcFields`, `CalcSums`, `CalcFormula`, `FlowField`, `Query.Open`, `Query.Read`, `Visible`, `Job Queue Entry`, `Job Queue Category Code`, `Confirm`, `RunModal`, `GuiAllowed`, `TryFunction`, `Codeunit.Run`, `HttpClient`, `Status`, `On Hold`, `stop request`, `TaskScheduler.CreateTask`, `TaskScheduler.TaskExists`, `Page.RunModal`, `Report.RunModal`, `Report.Run`, `Xmlport.Run`, `UseRequestPage`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. Apply these targeted cues even when simple token overlap would rank the article below the worklist cutoff: -- Worklist `use-setautocalcfields-for-per-row-flowfields.md` when a record loop calls `CalcFields`, or when every row reads the same FlowField for a comparison, branch, or per-record action. Worklist `calcsums-instead-of-calcfields-in-loop.md` instead when the loop only accumulates one set total. +- Worklist `design-covering-keys-from-read-pattern.md` for a changed secondary key alongside a filtered reader of its table, and `review-overlapping-keys-before-adding-an-index.md` when added or changed keys have overlapping leading fields. A changed key alone is not a finding; read and write workloads determine whether either rule applies. +- Worklist `preserve-buffered-inserts-by-separating-target-reads.md` when a loop calls `Insert` and interleaves operations on the insert target or `Commit`. Worklist `aggregate-before-persisting-intermediate-results.md` when repeated grouping calculations and persistent intermediate summaries appear in the same processing path. Do not infer either pattern from `Insert` or `CalcSums` alone. +- Worklist `cache-repeated-filtered-results-with-explicit-scope.md` only when the code or workload establishes repeated **complete** lookup keys (for example, querying the same filtered set in multiple passes, or measured key reuse), or shows a cache that omits result-affecting inputs. A single loop over possibly distinct keys does not establish reuse or justify a cache finding. Worklist `avoid-repeating-unchanged-validation.md` for repeated `Validate` of the same field in one path; do not worklist it from a single validation call. +- Worklist `use-setautocalcfields-for-per-row-flowfields.md` when a record loop calls `CalcFields`, or when every row reads the same FlowField for a comparison, branch, or per-record action. Also worklist `calcsums-instead-of-calcfields-in-loop.md` when the loop accumulates one set total: use `CalcSums` directly only for stored source fields, never directly on FlowFields; a FlowField total requires deriving equivalent source filters from its `CalcFormula`. - Worklist `hidden-flowfields-still-calculate-before-bc26-opt-in.md` when a page control directly sources a FlowField and sets `Visible = false` or a visibility expression. Suppress it when the target is known to have BC26's **Calculate only visible FlowFields** feature enabled, or when the FlowField is cheap and intentionally preloaded. - Worklist `avoid-commit-inside-loops.md` when `Commit()` is inside a record-iteration body or a checkpoint loop lacks persisted progress that excludes completed work on retry. Do not match a commit after a complete business unit when the same transaction persists a restart-safe watermark/state and errors propagate. Still match a full-tail `FindSet` with periodic commits as unbounded retrieval; restart safety does not make it `TOP X`. - Worklist `prefer-modifyall-over-per-row-modify.md` for a constant-assignment `Modify(false)` loop with no validation or per-row semantics. Worklist `triggers-and-media-field-regress-modifyall.md` when table trigger code, related subscribers, security filtering, `Media`/`MediaSet`, or companion fields affect a bulk path. A progress dialog does not generically exempt a loop; accept it only when the equivalent bulk call already falls back to individual operations and semantics are preserved. From 164b27d0b235f01ce3155cc7bafb0121867e7352 Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Tue, 29 Sep 2026 17:29:36 +0200 Subject: [PATCH 34/35] Restore deterministic review fixture coverage (#202) Co-authored-by: Jesper Schulz-Wedde Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- evaluation/review-fixtures.json | 52 ++++++++++++++++--- ...ust-not-restate-what-code-already-shows.md | 2 +- .../pages-must-not-contain-business-logic.md | 2 +- .../testing/test-feature-scenario-tags.md | 2 +- 4 files changed, 49 insertions(+), 9 deletions(-) diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index 7732e7e..a43ec1f 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -11,6 +11,21 @@ "breaking-changes": { "article": "do-not-expose-sensitive-data-through-public-api" }, + "data-modeling": { + "articles": [ + "check-blocked-in-referencing-code-not-in-master", + "code-must-not-change-workdate", + "pictures-must-use-media-not-blob", + "table-design-must-match-bc-table-type-conventions" + ] + }, + "error-handling": { + "articles": [ + "collect-validation-errors-with-errorbehavior", + "defensive-vs-offensive-code-must-match-blast-radius", + "log-writes-must-survive-rollback" + ] + }, "events": { "article": "reset-ishandled-only-when-the-value-can-carry-over" }, @@ -54,7 +69,9 @@ "use-setautocalcfields-for-per-row-flowfields", "temporary-tables-have-no-database-cost", "use-setloadfields-for-partial-records", - "prefer-modifyall-over-per-row-modify" + "prefer-modifyall-over-per-row-modify", + "al-methods-limited-during-write-transactions", + "avoid-user-prompts-inside-transactions" ] }, "privacy": { @@ -98,13 +115,16 @@ "security": { "articles": [ "al-has-no-built-in-htmlencode", - "do-not-concatenate-external-text-into-setfilter" + "do-not-concatenate-external-text-into-setfilter", + "exposed-objects-must-be-in-a-permission-set" ] }, "style": { "articles": [ "label-comment-explains-placeholders", - "dateformula-evaluate-needs-language-independent-literals" + "dateformula-evaluate-needs-language-independent-literals", + "al-comments-must-not-restate-what-code-already-shows", + "pages-must-not-contain-business-logic" ] }, "telemetry": { @@ -113,11 +133,30 @@ "testing": { "articles": [ "ui-handlers-in-tests", - "reset-per-test-state-before-the-isinitialized-guard" + "reset-per-test-state-before-the-isinitialized-guard", + "asserterror-needs-expectederror-and-code", + "bcpt-scenarios-must-be-app-specific", + "commit-shared-test-fixture-inside-lazy-initialize", + "given-blocks-must-cover-full-precondition-chain", + "table-relation-test-exclude-known-invalid-relations-via-event", + "test-feature-scenario-tags", + "test-one-when-per-test", + "transactionmodel-attribute-governs-test-transactions", + "ui-test-codeunit-naming", + "use-assert-isfalse-not-asserterror-for-boolean-checks" + ] + }, + "ui": { + "articles": [ + "default-descending-sort-on-historical-pages", + "page-design-must-match-bc-page-type-conventions" ] }, "upgrade": { - "article": "initvalue-does-not-update-existing-rows", + "articles": [ + "initvalue-does-not-update-existing-rows", + "upgrade-tag-logic-must-not-nest-deeply" + ], "context": "The extended table existed in the previous app version and already contains rows." }, "web-services": { @@ -126,7 +165,8 @@ "handle-httpclient-platform-failure-before-response-access", "check-http-status-before-consuming-response-body", "check-json-null-before-converting-values", - "format-exchanged-values-with-standard-format-9" + "format-exchanged-values-with-standard-format-9", + "api-page-least-privilege-write-access" ] } } diff --git a/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.md b/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.md index 09a2ea4..52c3c0a 100644 --- a/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.md +++ b/microsoft/knowledge/style/al-comments-must-not-restate-what-code-already-shows.md @@ -1,7 +1,7 @@ --- bc-version: [all] domain: style -keywords: [comments, verbosity, self-documenting, restate, tutorial-style] +keywords: [comments, verbosity, self-documenting, restate, tutorial-style, credit-memo-routing] technologies: [al] countries: [w1] application-area: [all] diff --git a/microsoft/knowledge/style/pages-must-not-contain-business-logic.md b/microsoft/knowledge/style/pages-must-not-contain-business-logic.md index 3326a25..ed5a4cb 100644 --- a/microsoft/knowledge/style/pages-must-not-contain-business-logic.md +++ b/microsoft/knowledge/style/pages-must-not-contain-business-logic.md @@ -1,7 +1,7 @@ --- bc-version: [all] domain: style -keywords: [pages, business-logic, codeunit, separation-of-concerns, presentation-layer] +keywords: [pages, business-logic, codeunit, separation-of-concerns, presentation-layer, rec-modify] technologies: [al] countries: [w1] application-area: [all] diff --git a/microsoft/knowledge/testing/test-feature-scenario-tags.md b/microsoft/knowledge/testing/test-feature-scenario-tags.md index 2247c7e..89198fb 100644 --- a/microsoft/knowledge/testing/test-feature-scenario-tags.md +++ b/microsoft/knowledge/testing/test-feature-scenario-tags.md @@ -1,7 +1,7 @@ --- bc-version: [all] domain: testing -keywords: [feature, scenario, given, when, then, tags, bdd, atdd, comments] +keywords: [feature, scenario, given, when, then, tags, bdd, atdd, comments, subtype-test] technologies: [al] countries: [w1] application-area: [all] From fd599197788ff4c11d01d98fb809f4eb4b6d6095 Mon Sep 17 00:00:00 2001 From: Michael Dieringer <65093775+MichaelDieringer@users.noreply.github.com> Date: Wed, 30 Sep 2026 13:22:38 +0200 Subject: [PATCH 35/35] 9 AL/BC patterns: document distribution, price calculation & barcode extensibility (#175) * Add 5 AL/BC patterns: document distribution (Report Selections, Document Sending Profile, Find Entries, TransferFields) 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 * Fix four merge-critical blockers from Jesper's review; add 4 more patterns 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 * Fix 5 merge-critical issues from Jesper's 2026-09-24 review round - 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 * Align price-source and barcode routing cues with corrected articles - Price-source cue now accepts UpdateUnitPrice, or the explicit PlanPriceCalcByField + UpdateUnitPriceByField sequence; bare UpdateUnitPriceByField does not count. Both APIs added to tokens. - Barcode cue no longer flags manual delimiters as a category; routes only demonstrably invalid/provider-font-mismatched hand encoding, and requires ValidateInput + EncodeFont for 1D, EncodeFont only for 2D. Co-Authored-By: Claude Opus 5.5 * Make barcode bad fixture self-contained: 1D EncodeFont without ValidateInput 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 * Fix three merge-critical items from Jesper's 2026-09-29 review - 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 * Clarify TrySendToEMail comment in print/email good sample Make explicit that TrySendToEMail is also correct *because* it never reads the customer's assigned profile (local record, E-Mail option set by the helper itself), and name Get/GetDefaultForCustomer + Send as the anti-pattern. Matches the article's Best Practice and BaseApp's own Sales Invoice Header.EmailRecords. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Sonnet 5 --- evaluation/review-fixtures.json | 11 +- ...on-handler-via-onfindsupportedsetup.bad.al | 74 +++++++++++++ ...n-handler-via-onfindsupportedsetup.good.al | 90 ++++++++++++++++ ...lation-handler-via-onfindsupportedsetup.md | 98 +++++++++++++++++ ...h-must-not-bypass-report-selections.bad.al | 20 ++++ ...-must-not-bypass-report-selections.good.al | 31 ++++++ ...patch-must-not-bypass-report-selections.md | 69 ++++++++++++ ...ons-call-report-selections-directly.bad.al | 45 ++++++++ ...ns-call-report-selections-directly.good.al | 63 +++++++++++ ...actions-call-report-selections-directly.md | 100 ++++++++++++++++++ ...ies-navigate-for-new-document-types.bad.al | 35 ++++++ ...es-navigate-for-new-document-types.good.al | 68 ++++++++++++ ...entries-navigate-for-new-document-types.md | 93 ++++++++++++++++ ...type-must-sync-document-subset-enum.bad.al | 14 +++ ...ype-must-sync-document-subset-enum.good.al | 19 ++++ ...rce-type-must-sync-document-subset-enum.md | 68 ++++++++++++ ...ection-usage-for-new-document-types.bad.al | 47 ++++++++ ...ction-usage-for-new-document-types.good.al | 87 +++++++++++++++ ...-selection-usage-for-new-document-types.md | 99 +++++++++++++++++ ...candidate-and-trigger-recalculation.bad.al | 25 +++++ ...andidate-and-trigger-recalculation.good.al | 38 +++++++ ...add-candidate-and-trigger-recalculation.md | 97 +++++++++++++++++ ...ode-module-and-production-font-name.bad.al | 41 +++++++ ...de-module-and-production-font-name.good.al | 54 ++++++++++ ...barcode-module-and-production-font-name.md | 99 +++++++++++++++++ ...d-fields-must-match-type-and-length.bad.al | 30 ++++++ ...-fields-must-match-type-and-length.good.al | 28 +++++ ...rored-fields-must-match-type-and-length.md | 87 +++++++++++++++ .../skills/review/al-data-modeling-review.md | 19 +++- tools/Test-ReviewFixtures.ps1 | 1 + 30 files changed, 1644 insertions(+), 6 deletions(-) create mode 100644 microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.bad.al create mode 100644 microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.good.al create mode 100644 microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.md create mode 100644 microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.bad.al create mode 100644 microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.good.al create mode 100644 microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.md create mode 100644 microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.bad.al create mode 100644 microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.good.al create mode 100644 microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.md create mode 100644 microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.bad.al create mode 100644 microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.good.al create mode 100644 microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.md create mode 100644 microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.bad.al create mode 100644 microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.good.al create mode 100644 microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.md create mode 100644 microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.bad.al create mode 100644 microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.good.al create mode 100644 microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.md create mode 100644 microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.bad.al create mode 100644 microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.good.al create mode 100644 microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.md create mode 100644 microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.bad.al create mode 100644 microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.good.al create mode 100644 microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.md create mode 100644 microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.bad.al create mode 100644 microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.good.al create mode 100644 microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.md diff --git a/evaluation/review-fixtures.json b/evaluation/review-fixtures.json index a43ec1f..5f0e50a 100644 --- a/evaluation/review-fixtures.json +++ b/evaluation/review-fixtures.json @@ -13,10 +13,19 @@ }, "data-modeling": { "articles": [ + "activate-new-price-calculation-handler-via-onfindsupportedsetup", "check-blocked-in-referencing-code-not-in-master", "code-must-not-change-workdate", + "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-price-source-type-must-sync-document-subset-enum", + "extend-report-selection-usage-for-new-document-types", + "new-price-source-must-add-candidate-and-trigger-recalculation", "pictures-must-use-media-not-blob", - "table-design-must-match-bc-table-type-conventions" + "report-barcodes-must-use-barcode-module-and-production-font-name", + "table-design-must-match-bc-table-type-conventions", + "transferfields-mirrored-fields-must-match-type-and-length" ] }, "error-handling": { diff --git a/microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.bad.al b/microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.bad.al new file mode 100644 index 0000000..6a02378 --- /dev/null +++ b/microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.bad.al @@ -0,0 +1,74 @@ +enumextension 50102 "Sample Price Calc Handler Ext" extends "Price Calculation Handler" +{ + value(50102; "Sample Special Price") + { + Caption = 'Sample Special Price'; + Implementation = "Price Calculation" = "Sample Price Calc - Special"; + } +} + +// Demonstration-only AL: every method below is stubbed. This article is +// about activating a handler through OnFindSupportedSetup, not about the +// "Price Calculation" interface's own pricing logic. +codeunit 50103 "Sample Price Calc - Special" implements "Price Calculation" +{ + procedure Init(LineWithPrice: Interface "Line With Price"; PriceCalculationSetup: Record "Price Calculation Setup") + begin + end; + + procedure GetLine(var Line: Variant) + begin + end; + + procedure ApplyDiscount() + begin + end; + + procedure ApplyPrice(CalledByFieldNo: Integer) + begin + end; + + procedure CountDiscount(ShowAll: Boolean) Result: Integer + begin + end; + + procedure CountPrice(ShowAll: Boolean) Result: Integer + begin + end; + + procedure FindDiscount(var TempPriceListLine: Record "Price List Line"; ShowAll: Boolean) Found: Boolean + begin + end; + + procedure FindPrice(var TempPriceListLine: Record "Price List Line"; ShowAll: Boolean) Found: Boolean + begin + end; + + procedure IsDiscountExists(ShowAll: Boolean) Result: Boolean + begin + end; + + procedure IsPriceExists(ShowAll: Boolean) Result: Boolean + begin + end; + + procedure PickDiscount() + begin + end; + + procedure PickPrice() + begin + end; + + procedure ShowPrices(var TempPriceListLine: Record "Price List Line") + begin + end; +} + +// WRONG: no subscriber to Price Calculation Mgt.'s OnFindSupportedSetup. +// "Sample Special Price" is a real, working implementation of the Price +// Calculation interface - it simply has no Price Calculation Setup row +// naming it, so Price Calculation Mgt. never selects it for any sale, +// purchase, or job line, whether through the Default fallback or through +// a "Dtld. Price Calculation Setup" row. It ships invisible until someone +// notices and configures a setup row for it by hand. diff --git a/microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.good.al b/microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.good.al new file mode 100644 index 0000000..8f27beb --- /dev/null +++ b/microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.good.al @@ -0,0 +1,90 @@ +enumextension 50102 "Sample Price Calc Handler Ext" extends "Price Calculation Handler" +{ + value(50102; "Sample Special Price") + { + Caption = 'Sample Special Price'; + Implementation = "Price Calculation" = "Sample Price Calc - Special"; + } +} + +// Demonstration-only AL: every method below is stubbed. This article is +// about activating a handler through OnFindSupportedSetup, not about the +// "Price Calculation" interface's own pricing logic. +codeunit 50103 "Sample Price Calc - Special" implements "Price Calculation" +{ + procedure Init(LineWithPrice: Interface "Line With Price"; PriceCalculationSetup: Record "Price Calculation Setup") + begin + end; + + procedure GetLine(var Line: Variant) + begin + end; + + procedure ApplyDiscount() + begin + end; + + procedure ApplyPrice(CalledByFieldNo: Integer) + begin + end; + + procedure CountDiscount(ShowAll: Boolean) Result: Integer + begin + end; + + procedure CountPrice(ShowAll: Boolean) Result: Integer + begin + end; + + procedure FindDiscount(var TempPriceListLine: Record "Price List Line"; ShowAll: Boolean) Found: Boolean + begin + end; + + procedure FindPrice(var TempPriceListLine: Record "Price List Line"; ShowAll: Boolean) Found: Boolean + begin + end; + + procedure IsDiscountExists(ShowAll: Boolean) Result: Boolean + begin + end; + + procedure IsPriceExists(ShowAll: Boolean) Result: Boolean + begin + end; + + procedure PickDiscount() + begin + end; + + procedure PickPrice() + begin + end; + + procedure ShowPrices(var TempPriceListLine: Record "Price List Line") + begin + end; +} + +codeunit 50104 "Sample Price Calc Setup Install" +{ + [EventSubscriber(ObjectType::Codeunit, Codeunit::"Price Calculation Mgt.", 'OnFindSupportedSetup', '', false, false)] + local procedure AddSampleSpecialPriceSetup(var TempPriceCalculationSetup: Record "Price Calculation Setup" temporary) + begin + TempPriceCalculationSetup.Init(); + TempPriceCalculationSetup.Code := 'SAMPLE-SPECIAL'; + TempPriceCalculationSetup.Method := TempPriceCalculationSetup.Method::"Lowest Price"; + TempPriceCalculationSetup.Type := TempPriceCalculationSetup.Type::Sale; + TempPriceCalculationSetup."Asset Type" := TempPriceCalculationSetup."Asset Type"::" "; + TempPriceCalculationSetup.Implementation := TempPriceCalculationSetup.Implementation::"Sample Special Price"; + TempPriceCalculationSetup.Enabled := true; + // Default := true here because this row is meant as the fallback + // for Method = Lowest Price / Type = Sale / Asset Type = " " (all) + // - the combination Price Calculation Mgt.'s FindSetup selects via + // its own SetRange(Default, true) branch when no "Dtld. Price + // Calculation Setup" row names a more specific match. A handler + // meant to be picked only through such a specific, explicit + // detailed-setup row would not need Default := true at all. + TempPriceCalculationSetup.Default := true; + TempPriceCalculationSetup.Insert(); + end; +} diff --git a/microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.md b/microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.md new file mode 100644 index 0000000..3654468 --- /dev/null +++ b/microsoft/knowledge/data-modeling/activate-new-price-calculation-handler-via-onfindsupportedsetup.md @@ -0,0 +1,98 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [price-calculation, price-calculation-handler, price-calculation-setup, integration-event, pricing] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Activate a new Price Calculation Handler through OnFindSupportedSetup, not just by implementing it + +## Description + +`enum 7011 "Price Calculation Handler"` (`implements "Price +Calculation"`) is how a new pricing engine plugs into Business Central — +extend the enum with a value pointing at a codeunit that implements the +`Price Calculation` interface. That alone does not make the new handler +usable on any document. `codeunit 7001 "Price Calculation Mgt."` decides +which handler applies to a given line by looking up `table 7006 "Price +Calculation Setup"`, a table of `(Code, Method, Type, Asset Type, +Implementation, Enabled, Default)` rows populated at startup by its own +`OnFindSupportedSetup` event — every implementation codeunit is expected +to subscribe to that event and insert its own setup row(s). A handler +enum value with no matching setup row is real and selectable in the enum +itself, but never chosen for any actual sale, purchase, or job line, +because `Price Calculation Mgt.` has no setup row that names it. + +`FindSetup` resolves a handler in two stages, and only the second one +looks at `Default`. It first asks `codeunit 7004 "Price Calculation Dtld. +Setup"` to match the line against `table 7008 "Dtld. Price Calculation +Setup"` ("Detailed Price Calculation Setup", keyed to an exact +`Method`/`Type`/`Asset Type`/`Source`/`Asset No.` combination via its own +`"Setup Code"`); on a match it does `PriceCalculationSetup.Get(... +"Setup Code")` directly, with no `Default` filter. Only when no detailed +row matches does it fall back to `SetRange(Default, true)` plus +`SetRange(Method, ...)` to pick the one catch-all row for that +combination. A row without `Default := true` is invisible to *that* +fallback, but not invisible outright — a detailed-setup row can still +select it by naming its `Code`. A row whose `Method` matches neither path +is invisible either way — same symptom, different cause. + +## Best Practice + +Ship a new `Price Calculation Handler` value together with an +`OnFindSupportedSetup` subscriber that inserts at least one `Price +Calculation Setup` record naming it as the `Implementation`, for the +relevant `Method` (e.g. `"Lowest Price"`), `Type` (`Sale`/`Purchase`), and +`Asset Type`. `Default := true` is required only when this row is the +*fallback* for that combination — the row `FindSetup`'s own +`SetRange(Default, true)` branch selects when no more specific setup +applies. A handler meant to be selected only for specific customers or +items should instead be reachable through a matching `"Dtld. Price +Calculation Setup"` row; `FindSetup` resolves that before it ever checks +`Default`, so it needs no `Default := true`. + +See sample: [`activate-new-price-calculation-handler-via-onfindsupportedsetup.good.al`](activate-new-price-calculation-handler-via-onfindsupportedsetup.good.al). + +## Anti Pattern + +Extending `Price Calculation Handler` and implementing the `Price +Calculation` interface, without subscribing to `OnFindSupportedSetup` to +insert a setup record. The new handler exists, compiles, and can even be +selected manually if a user creates their own `Price Calculation Setup` +row through the UI — but ships with no default row, so it's never active +for anyone until someone notices it's missing and configures it by hand. + +See sample: [`activate-new-price-calculation-handler-via-onfindsupportedsetup.bad.al`](activate-new-price-calculation-handler-via-onfindsupportedsetup.bad.al). + +## Source + +BCApps (`src/Layers/W1/BaseApp/Pricing/Calculation/`): +`PriceCalculationHandler.Enum.al` (`enum 7011 "Price Calculation Handler" +implements "Price Calculation"`); `PriceCalculationMgt.Codeunit.al` +(`OnFindSupportedSetup(var TempPriceCalculationSetup: Record "Price +Calculation Setup" temporary)`, and `FindSetup(...): Boolean`, which +first calls `PriceCalculationDtldSetup.FindSetup(DtldPriceCalcSetup)` and +on a match does `PriceCalculationSetup.Get(... "Setup Code")` with no +`Default` filter — only on failure does it fall back to +`SetRange(Enabled, true)`, `SetRange(Default, true)`, `SetRange(Method, +...)`); `PriceCalculationSetup.Table.al` (`table 7006 "Price Calculation +Setup"`: `Code`, `Method`, `Type`, `"Asset Type"`, `Implementation`, +`Enabled`, `Default`); `PriceCalculationDtldSetup.Codeunit.al` (`codeunit +7004 "Price Calculation Dtld. Setup"`, `FindSetup(var DtldPriceCalcSetup: +Record "Dtld. Price Calculation Setup"): Boolean`, matching progressively +looser `Source Group`/`Source No.`/`Asset Type`/`Asset No.` combinations — +never `Default`); `DtldPriceCalculationSetup.Table.al` (`table 7008 "Dtld. +Price Calculation Setup"`, Caption "Detailed Price Calculation Setup", +`"Setup Code"` relates to `"Price Calculation Setup".Code where(Enabled = +const(true))` — no `Default` condition). + +Microsoft Learn, "Extending Price Calculations": "Each codeunit that +implements the Price Calculation interface must subscribe to the +OnFindSupportedSetup() event... to fill the price calculation setup +table." Same article: "You can enter detailed setup records for +non-default setup lines... If a matching setup is found its +implementation is used... If there is no matching setup exception, we +use the default implementation." +(https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-extending-best-price-calculations) diff --git a/microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.bad.al b/microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.bad.al new file mode 100644 index 0000000..fbff442 --- /dev/null +++ b/microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.bad.al @@ -0,0 +1,20 @@ +codeunit 50102 "Sample Posted Invoice Send" +{ + procedure SendPostedInvoice(SalesInvoiceHeader: Record "Sales Invoice Header") + var + Customer: Record Customer; + begin + Customer.Get(SalesInvoiceHeader."Bill-to Customer No."); + Customer.TestField("E-Mail"); + + // WRONG: the report is hardcoded instead of resolved through the + // registered "S.Invoice" usage in Report Selections. This alone is + // the defect - no hand-built email is needed for it: a Report + // Selections row or a per-customer "Document Layouts" override + // that points this usage at a different report or layout is + // silently ignored, and the only way to change what this code + // prints is a code change and a new release. + SalesInvoiceHeader.SetRecFilter(); + Report.RunModal(Report::"Standard Sales - Invoice", false, false, SalesInvoiceHeader); + end; +} diff --git a/microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.good.al b/microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.good.al new file mode 100644 index 0000000..f19b00a --- /dev/null +++ b/microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.good.al @@ -0,0 +1,31 @@ +codeunit 50102 "Sample Posted Invoice Send" +{ + procedure SendPostedInvoice(SalesInvoiceHeader: Record "Sales Invoice Header") + var + ReportSelections: Record "Report Selections"; + ReportDistributionMgt: Codeunit "Report Distribution Management"; + begin + // Custom validation specific to this dispatch stays here... + CheckReadyToSend(SalesInvoiceHeader); + + // ...but dispatch goes through the registered usage. "S.Invoice" + // resolves to a report built on "Sales Invoice Header" (by default + // report 1306 "Standard Sales - Invoice"), so the record passed in + // matches what the selected report expects, and per-account + // report/layout overrides and email attachment/body configuration + // on Report Selections all apply automatically. + SalesInvoiceHeader.SetRecFilter(); + ReportSelections.SendEmailToCust( + "Report Selection Usage"::"S.Invoice".AsInteger(), SalesInvoiceHeader, SalesInvoiceHeader."No.", + ReportDistributionMgt.GetFullDocumentTypeText(SalesInvoiceHeader), true, + SalesInvoiceHeader."Bill-to Customer No."); + end; + + local procedure CheckReadyToSend(SalesInvoiceHeader: Record "Sales Invoice Header") + var + Customer: Record Customer; + begin + Customer.Get(SalesInvoiceHeader."Bill-to Customer No."); + Customer.TestField("E-Mail"); + end; +} diff --git a/microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.md b/microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.md new file mode 100644 index 0000000..f6b15f9 --- /dev/null +++ b/microsoft/knowledge/data-modeling/custom-document-dispatch-must-not-bypass-report-selections.md @@ -0,0 +1,69 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [report-selections, document-layouts, custom-report-layout, email-attachment, bespoke-dispatch] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Custom document dispatch must not bypass Report Selections + +## Description + +A codeunit that hardcodes which report to run (`Report.RunModal(MyReportId, ...)`), +or builds its own email directly, instead of registering the document +through `table 77 "Report Selections"` and calling its own +Print/Email procedures, works for the one case it was written for — and +loses everything the platform's registry provides for free. Either +bypass is a defect on its own: a hardcoded report ignores the registered +report and any per-account layout override even when no email is +involved, and a hand-built email ignores the registry's attachment and +email-body configuration even when the report itself came from it. `Report +Selections` carries its own attachment/email-body configuration per usage +(`"Use for Email Attachment"`, `"Use for Email Body"`, `"Email Body Layout +Code"`, `"Email Body Layout Type"`), plus a separate per-usage layout +override, `"Custom Report Layout Code"`, and +`table 9657 "Custom Report Selection"` (the "Document Layouts" page on the +Customer/Vendor card) lets one specific account override the report or +layout without touching code at all. None of that exists for a document +whose dispatch was hand-rolled: there is no registry row to point +"Document Layouts" at, so an admin who goes looking for where to change +this document's layout — the same place they'd look for every other +document in the system — finds nothing, because the document was never +registered there. + +## Best Practice + +Register the document under a `Report Selection Usage` value (see +`extend-report-selection-usage-for-new-document-types.md`) and dispatch +through `Report Selections`' own Print/Email procedures (see +`document-print-and-email-actions-call-report-selections-directly.md`), +even when the surrounding business logic — which counterparty to use, +what validation must pass before sending — is genuinely specific to the +document. Custom logic belongs around the call to `Report Selections`, +not instead of it. + +See sample: [`custom-document-dispatch-must-not-bypass-report-selections.good.al`](custom-document-dispatch-must-not-bypass-report-selections.good.al). + +## Anti Pattern + +A codeunit that runs a hardcoded report ID, or builds its own email +message directly, for a document that has (or should have) a +`Report Selections` usage — each is independently a bypass, and the +sample shows the first on its own. It works for the default case, but the report/layout cannot be changed per account +without a code change and a new release, and the document is invisible to +"Document Layouts" — the standard place every other document's +distribution is configured. + +See sample: [`custom-document-dispatch-must-not-bypass-report-selections.bad.al`](custom-document-dispatch-must-not-bypass-report-selections.bad.al). + +## Source + +BCApps `ReportSelections.Table.al` (table 77 — field 7, +`"Custom Report Layout Code"`; fields 19–26 for email attachment/body +configuration; `SendEmailToCust`/`PrintWithDialogForCust` as the +registry-backed dispatch entry points) and +`CustomReportSelection.Table.al` (table 9657, the per-account override +backing the "Document Layouts" page) — both under +`src/Layers/W1/BaseApp/Foundation/Reporting/`. diff --git a/microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.bad.al b/microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.bad.al new file mode 100644 index 0000000..a8799c0 --- /dev/null +++ b/microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.bad.al @@ -0,0 +1,45 @@ +page 50101 "Sample Posted Invoice Card" +{ + PageType = Card; + SourceTable = "Sales Invoice Header"; + ApplicationArea = All; + Editable = false; + + actions + { + area(Processing) + { + action(EmailDocument) + { + ApplicationArea = All; + Caption = 'Email'; + Image = Email; + + trigger OnAction() + var + SalesInvoiceHeader: Record "Sales Invoice Header"; + DocumentSendingProfile: Record "Document Sending Profile"; + ReportDistributionMgt: Codeunit "Report Distribution Management"; + begin + // WRONG: this is a plain, on-demand "Email" button, not + // part of a combined Post-and-Send action - but this + // loads the customer's ACTUAL assigned profile (or the + // tenant default, if none is assigned - the same lookup + // Sales-Post and Send performs) and calls Send on it, so + // the outcome now silently depends on that profile. A + // profile set up for Post-and-Send printing only (say, + // Printer = Yes, "E-Mail" = No) turns this button into a + // silent no-op, with no indication an unrelated setup + // field is why. + SalesInvoiceHeader := Rec; + CurrPage.SetSelectionFilter(SalesInvoiceHeader); + DocumentSendingProfile.GetDefaultForCustomer(Rec."Bill-to Customer No.", DocumentSendingProfile); + DocumentSendingProfile.Send( + "Report Selection Usage"::"S.Invoice".AsInteger(), SalesInvoiceHeader, Rec."No.", + Rec."Bill-to Customer No.", ReportDistributionMgt.GetFullDocumentTypeText(Rec), + SalesInvoiceHeader.FieldNo("Bill-to Customer No."), SalesInvoiceHeader.FieldNo("No.")); + end; + } + } + } +} diff --git a/microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.good.al b/microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.good.al new file mode 100644 index 0000000..c68724b --- /dev/null +++ b/microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.good.al @@ -0,0 +1,63 @@ +page 50101 "Sample Posted Invoice Card" +{ + PageType = Card; + SourceTable = "Sales Invoice Header"; + ApplicationArea = All; + Editable = false; + + actions + { + area(Processing) + { + action(EmailDocument) + { + ApplicationArea = All; + Caption = 'Email'; + Image = Email; + + trigger OnAction() + var + SalesInvoiceHeader: Record "Sales Invoice Header"; + ReportSelections: Record "Report Selections"; + ReportDistributionMgt: Codeunit "Report Distribution Management"; + begin + // Calls Report Selections directly - the button's outcome + // depends only on this customer's registered report/layout, + // not on any Document Sending Profile setting. Calling + // DocumentSendingProfile.TrySendToEMail(...) instead would + // also be correct, because it never reads the customer's + // assigned profile: it only uses a local record that it + // never retrieves with Get, and sets its "E-Mail" option + // itself. The + // anti-pattern is Get/GetDefaultForCustomer followed by + // Send, which makes the outcome depend on that profile. + // "S.Invoice" resolves to a report on "Sales Invoice + // Header", which is the record passed here. + SalesInvoiceHeader := Rec; + CurrPage.SetSelectionFilter(SalesInvoiceHeader); + ReportSelections.SendEmailToCust( + "Report Selection Usage"::"S.Invoice".AsInteger(), SalesInvoiceHeader, Rec."No.", + ReportDistributionMgt.GetFullDocumentTypeText(Rec), true, Rec."Bill-to Customer No."); + end; + } + action(PrintDocument) + { + ApplicationArea = All; + Caption = 'Print'; + Image = Print; + + trigger OnAction() + var + SalesInvoiceHeader: Record "Sales Invoice Header"; + ReportSelections: Record "Report Selections"; + begin + SalesInvoiceHeader := Rec; + CurrPage.SetSelectionFilter(SalesInvoiceHeader); + ReportSelections.PrintWithDialogForCust( + "Report Selection Usage"::"S.Invoice", SalesInvoiceHeader, true, + SalesInvoiceHeader.FieldNo("Bill-to Customer No.")); + end; + } + } + } +} diff --git a/microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.md b/microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.md new file mode 100644 index 0000000..f331619 --- /dev/null +++ b/microsoft/knowledge/data-modeling/document-print-and-email-actions-call-report-selections-directly.md @@ -0,0 +1,100 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [report-selections, document-sending-profile, print, email, post-and-send] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# A document's own Print/Email actions call Report Selections directly; Document Sending Profile is scoped to Post-and-Send + +## Description + +`table 60 "Document Sending Profile"` is not a general gateway for every +print/email path — it exists specifically for the combined **Post and +Send** action: "You can set each customer up with a preferred method of +sending sales documents, so that you do not have to select a sending +option every time you choose the Post and Send action" (Microsoft Learn, +"Set Up Document Sending Profiles"). A document's own, ordinary +Print/Email actions are unaffected by any *configured* profile either +way: the unposted Sales Order's "Print Confirmation"/"Email +Confirmation" (`codeunit "Document-Print"`, +`PrintSalesOrder`/`EmailSalesHeader`) and the posted `Purch. Inv. +Header`'s `PrintRecords` call `Report Selections` literally directly +(`PrintWithDialogForCust`/`SendEmailToCust`/`PrintWithDialogForVend`), +while the posted `Sales Invoice Header`'s `PrintRecords`/`EmailRecords` +and the unposted `Purchase Header`'s `PrintRecords` go through +`DocumentSendingProfile.TrySendToPrinter`/`TrySendToEMail`/ +`TrySendToPrinterVendor` instead. Those three helpers each declare a +fresh, local, never-`Get`'d profile record, hardcode its +`Printer`/`"E-Mail"` field to a "Yes" option themselves, and feed it into +`SendToPrinter`/`SendToEMailGroupedMultipleSelection` — which resolve +into Report Selections just like the direct route. The table is a +throwaway options carrier here, not the counterparty's configuration. + +Only a genuinely configured profile changes the outcome, and that only +happens for the combined Post-and-Send flow: `Sales-Post and Send` loads +the customer's assigned profile (`Get(Customer."Document Sending +Profile")`, or the tenant default) before `Sales Invoice +Header.SendProfile` → `DocumentSendingProfile.Send`, which gates +`SendToPrinter`/`SendToEMail`/`SendToDisk` on whatever that record holds. + +Whether a document needs outbound distribution isn't determined by +Customer vs. Vendor, but by whether it's genuinely *outbound* to that +party: a posted Purchase Invoice records what a vendor already billed, +so the posted `Purch. Inv. Header` has only a bare `PrintRecords`; a +Purchase *Order* is still outbound before posting, so the rich +`SendProfile`/`SendRecords`/`PrintRecords` triplet lives there instead. + +## Best Practice + +For a document's own interactive Print/Email actions, either call the +relevant `Report Selections` procedure directly — +`PrintForCust`/`PrintWithDialogForCust`/`SendEmailToCust` for a +customer-facing document, `PrintWithDialogForVend`/`SendEmailToVendor` +for a vendor-facing one — or call one of `Document Sending Profile`'s +stateless `TrySendToPrinter`/`TrySendToEMail`/`TrySendToPrinterVendor` +helpers, using the usage value registered per +`extend-report-selection-usage-for-new-document-types.md`. Both are +equally correct; neither reads the counterparty's assigned profile. +Reserve a genuine `Get`/`GetDefaultForCustomer`/`GetDefaultForVendor` +lookup and `Send`/`SendVendor` for Post-and-Send. + +See sample: [`document-print-and-email-actions-call-report-selections-directly.good.al`](document-print-and-email-actions-call-report-selections-directly.good.al). + +## Anti Pattern + +Loading the counterparty's *actually assigned* `Document Sending +Profile` (or the tenant default, via `Get`/`GetDefaultForCustomer`/ +`GetDefaultForVendor` — the same lookup `Sales-Post and Send` performs) +and calling `Send`/`SendVendor` on it from a plain, on-demand "Email" +button, instead of `ReportSelections.SendEmailToCust`/`SendEmailToVendor` +directly. The button's outcome now silently depends on a profile +configured for Post-and-Send — if its `"E-Mail"` option is `No`, +clicking "Email" does nothing observable. A second version of the same +mistake: an email action on a document that only receives from its +counterparty and was never meant to send anything back. + +See sample: [`document-print-and-email-actions-call-report-selections-directly.bad.al`](document-print-and-email-actions-call-report-selections-directly.bad.al). + +## Source + +BCApps `DocumentPrint.Codeunit.al` (`EmailSalesHeader`/`DoPrintSalesHeader`/ +`PrintSalesOrder` → `ReportSelections.SendEmailToCust`/`PrintForCust`/ +`PrintWithDialogForCust` directly), `SalesInvoiceHeader.Table.al` +(`PrintRecords`/`EmailRecords`, lines 1453/1528 → `TrySendToPrinter`/ +`TrySendToEMail`, lines 1462/1541, on a local never-`Get`'d record), +`PurchaseHeader.Table.al` (`PrintRecords` line 6357 → +`TrySendToPrinterVendor` line 6374; `SendProfile` line 6387 → +`SendVendor` line 6403), `PurchInvHeader.Table.al` (`PrintRecords` → +`ReportSelection.PrintWithDialogForVend` directly, no send capability), +`SalesPostandSend.Codeunit.al`/`SalesPost.Codeunit.al` +(`ConfirmPostAndSend` loads `Get(Customer."Document Sending +Profile")`/`GetDefault`; `SendPostedDocumentRecord` line 7660 → +`SalesInvHeader.SendProfile` lines 7680/7699 → +`DocumentSendingProfile.Send`), `DocumentSendingProfile.Table.al` (table +60; `TrySendToPrinter`/`TrySendToEMail` lines 536/562, +`TrySendToPrinterVendor` line 552, `GetDefaultForCustomer` line 195, +`Send`/`SendVendor` lines 482/506) — all under `src/Layers/W1/BaseApp/`. +Microsoft Learn, "Set Up Document Sending Profiles": https://learn.microsoft.com/dynamics365/business-central/sales-how-setup-document-send-profiles diff --git a/microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.bad.al b/microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.bad.al new file mode 100644 index 0000000..486eee8 --- /dev/null +++ b/microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.bad.al @@ -0,0 +1,35 @@ +table 50104 "Sample Posted Document Header" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "No."; Code[20]) { Caption = 'No.'; } + field(2; "Posting Date"; Date) { Caption = 'Posting Date'; } + } + + keys + { + key(PK; "No.") { Clustered = true; } + } +} + +codeunit 50103 "Sample Navigate Subscribers" +{ + // WRONG: registers the row, so it appears in the Find Entries result + // list with a correct table name and record count - but there is no + // OnBeforeShowRecords subscriber for this table. ShowRecords()'s own + // case statement has no branch and no else for it either, so + // selecting this row and choosing "Show records" does nothing, + // silently, with no error. + [EventSubscriber(ObjectType::Page, Page::Navigate, 'OnAfterFindRecords', '', false, false)] + local procedure OnAfterFindRecords(var DocumentEntry: Record "Document Entry"; DocNoFilter: Text; PostingDateFilter: Text) + var + SampleDocHeader: Record "Sample Posted Document Header"; + begin + SampleDocHeader.SetFilter("No.", DocNoFilter); + SampleDocHeader.SetFilter("Posting Date", PostingDateFilter); + DocumentEntry.InsertIntoDocEntry( + Database::"Sample Posted Document Header", SampleDocHeader.TableCaption(), SampleDocHeader.Count()); + end; +} diff --git a/microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.good.al b/microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.good.al new file mode 100644 index 0000000..c0d658b --- /dev/null +++ b/microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.good.al @@ -0,0 +1,68 @@ +table 50104 "Sample Posted Document Header" +{ + DataClassification = CustomerContent; + + fields + { + field(1; "No."; Code[20]) { Caption = 'No.'; } + field(2; "Posting Date"; Date) { Caption = 'Posting Date'; } + } + + keys + { + key(PK; "No.") { Clustered = true; } + } +} + +page 50104 "Sample Posted Document" +{ + PageType = Card; + SourceTable = "Sample Posted Document Header"; + UsageCategory = None; + ApplicationArea = All; + + layout + { + area(Content) + { + field("No."; Rec."No.") { ApplicationArea = All; } + field("Posting Date"; Rec."Posting Date") { ApplicationArea = All; } + } + } +} + +codeunit 50103 "Sample Navigate Subscribers" +{ + [EventSubscriber(ObjectType::Page, Page::Navigate, 'OnAfterFindRecords', '', false, false)] + local procedure OnAfterFindRecords(var DocumentEntry: Record "Document Entry"; DocNoFilter: Text; PostingDateFilter: Text) + var + SampleDocHeader: Record "Sample Posted Document Header"; + begin + SampleDocHeader.SetFilter("No.", DocNoFilter); + SampleDocHeader.SetFilter("Posting Date", PostingDateFilter); + DocumentEntry.InsertIntoDocEntry( + Database::"Sample Posted Document Header", SampleDocHeader.TableCaption(), SampleDocHeader.Count()); + end; + + // Without this second subscriber, the row added above shows up in the + // Find Entries result list with a correct count, but "Show records" + // has nothing to open it with - see the .bad.al sample. + [EventSubscriber(ObjectType::Page, Page::Navigate, 'OnBeforeShowRecords', '', false, false)] + local procedure OnBeforeShowRecords(var TempDocumentEntry: Record "Document Entry" temporary; DocNoFilter: Text; PostingDateFilter: Text; ItemTrackingSearch: Boolean; ContactNo: Code[250]; ExtDocNo: Code[250]; var IsHandled: Boolean) + var + SampleDocHeader: Record "Sample Posted Document Header"; + begin + if TempDocumentEntry."Table ID" <> Database::"Sample Posted Document Header" then + exit; + + SampleDocHeader.SetFilter("No.", DocNoFilter); + SampleDocHeader.SetFilter("Posting Date", PostingDateFilter); + if TempDocumentEntry."No. of Records" = 1 then begin + SampleDocHeader.FindFirst(); + Page.Run(Page::"Sample Posted Document", SampleDocHeader); + end else + Page.Run(0, SampleDocHeader); + + IsHandled := true; + end; +} diff --git a/microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.md b/microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.md new file mode 100644 index 0000000..468756e --- /dev/null +++ b/microsoft/knowledge/data-modeling/extend-find-entries-navigate-for-new-document-types.md @@ -0,0 +1,93 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [navigate, find-entries, document-entry, integration-event, drill-down] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Extend Find Entries (Navigate) for new document or transaction tables + +## Description + +`page 344 Navigate` (caption "Find entries") lets a user enter a document +number and posting date and see, across every document and ledger entry +table BC knows about, how many matching records exist — then drill into +any of those rows. It works over a temporary `table "Document Entry"` +that gets populated, one row per source table, by dozens of separate +lookups hardcoded into the page (`Rec.InsertIntoDocEntry(Database::"Sales +Invoice Header", ...)` and similar, one per table). A new custom document +or transaction table is invisible to Find Entries by default — nobody +searching by document number will ever see it in the result list — until +it registers itself. + +Registration is a two-sided integration event, and only implementing one +side produces a page that is worse than not participating at all. The +`OnAfterFindRecords` event lets a subscriber add a row to the result list +for a custom table. But the subsequent "show records" action, `procedure +ShowRecords`, resolves which page to open through its own hardcoded `case +Rec."Table ID" of` — the same shape as the row-population code, and just +as unaware of any table added by an extension. That `case` statement has +no `else` branch. A custom table's row can appear in the result list, +with a correct count, and be entirely un-clickable: the user selects it, +chooses "Show records", and nothing happens, silently. + +## Best Practice + +Subscribe to both `Navigate::OnAfterFindRecords` and +`Navigate::OnBeforeShowRecords` together, as one unit of work, for any +custom table that should be searchable by document number: + +- In `OnAfterFindRecords`, filter the custom table by the given + `DocNoFilter`/`PostingDateFilter` and call + `DocumentEntry.InsertIntoDocEntry(Database::"My Table", TableCaption, + Count)` to add it to the result list. +- In `OnBeforeShowRecords`, check whether + `TempDocumentEntry."Table ID" = Database::"My Table"`; if so, re-apply + the same filters, open the appropriate card or list page, and set + `IsHandled := true` so the page's own unrelated `case` statement is + never reached for this table. +- If `OnAfterFindRecords` filters the custom table by a field that is not + already that table's own unique key — for example an external + reference number received from a counterparty, rather than the + table's own `No.` — add a key combining that field with `Posting Date`, + the same way BCApps does for `Purch. Inv. Header`'s `"Vendor Invoice + No."` (see Source). This does not apply when filtering the table's own + primary key, which is already unique on its own: `Sales Invoice + Header` filters `"No."` and `"Posting Date"` through two separate, + uncombined keys, with no compound key between them, because `"No."` + alone is already sufficient. + +See sample: [`extend-find-entries-navigate-for-new-document-types.good.al`](extend-find-entries-navigate-for-new-document-types.good.al). + +## Anti Pattern + +Subscribing only to `OnAfterFindRecords` (or only to +`OnBeforeShowRecords`). Registering the row without handling its +drill-down produces a search result that looks complete — the table name +and a correct record count both show up — but leads nowhere when +selected, with no error and no indication to the user that anything is +wrong. + +See sample: [`extend-find-entries-navigate-for-new-document-types.bad.al`](extend-find-entries-navigate-for-new-document-types.bad.al). + +## Source + +BCApps `Navigate.Page.al` (page 344, `src/Layers/W1/BaseApp/Foundation/Navigate/`): +- `[IntegrationEvent(true, false)] local procedure OnAfterFindRecords(var DocumentEntry: Record "Document Entry"; DocNoFilter: Text; PostingDateFilter: Text)` +- `[IntegrationEvent(true, false)] local procedure OnBeforeShowRecords(var TempDocumentEntry: Record "Document Entry" temporary; DocNoFilter: Text; PostingDateFilter: Text; ItemTrackingSearch: Boolean; ContactNo: Code[250]; ExtDocNo: Code[250]; var IsHandled: Boolean)` +- `procedure ShowRecords()`'s `case Rec."Table ID" of ... end;` has no `else` branch — confirmed by reading the full case block, which ends directly with `end;` followed by `OnAfterShowRecords(...)`. + +BCApps `DocumentEntry.Table.al` (table backing page 344): +`procedure InsertIntoDocEntry(DocTableID: Integer; DocTableName: Text; DocNoOfRecords: Integer)` — the registration entry point called from `OnAfterFindRecords` subscribers. + +BCApps `SalesInvoiceHeader.Table.al` (`src/Layers/W1/BaseApp/Sales/History/`): +`key(Key1; "No.")` (`Clustered = true`) and `key(Key9; "Posting Date")` are +two separate, uncombined keys — no compound key exists between them. + +BCApps `PurchInvHeader.Table.al` (`src/Layers/W1/BaseApp/Purchases/History/`): +`key(Key4; "Vendor Invoice No.", "Posting Date")` — a compound key +combining a non-unique, externally-supplied reference number with +`Posting Date`, distinct from `key(Key1; "No.")`, its own unique primary +key. diff --git a/microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.bad.al b/microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.bad.al new file mode 100644 index 0000000..0435992 --- /dev/null +++ b/microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.bad.al @@ -0,0 +1,14 @@ +enumextension 50100 "Sample Price Source Ext" extends "Price Source Type" +{ + value(50100; "Sample.LoyaltyTier") + { + Caption = 'Loyalty Tier'; + Implementation = "Price Source" = "Price Source - Customer", "Price Source Group" = "Price Source Group - Customer"; + } +} + +// WRONG: no matching value was added to "Sales Price Source Type" (or the +// purchase/job equivalents). "Sample.LoyaltyTier" compiles, installs, and +// is a real value on "Price Source Type" - it just never appears as an +// Applies-to Type option on the Sales Price List page, because that page +// is driven by the separate subset enum, not the base one. diff --git a/microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.good.al b/microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.good.al new file mode 100644 index 0000000..8acd6c6 --- /dev/null +++ b/microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.good.al @@ -0,0 +1,19 @@ +enumextension 50100 "Sample Price Source Ext" extends "Price Source Type" +{ + value(50100; "Sample.LoyaltyTier") + { + Caption = 'Loyalty Tier'; + Implementation = "Price Source" = "Price Source - Customer", "Price Source Group" = "Price Source Group - Customer"; + } +} + +enumextension 50101 "Sample Sales Price Source Ext" extends "Sales Price Source Type" +{ + // Same numeric ID (50100) as the Price Source Type value above. That + // match is what makes "Sample.LoyaltyTier" show up as a selectable + // Applies-to Type on an actual sales price list. + value(50100; "Sample.LoyaltyTier") + { + Caption = 'Loyalty Tier'; + } +} diff --git a/microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.md b/microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.md new file mode 100644 index 0000000..02e6287 --- /dev/null +++ b/microsoft/knowledge/data-modeling/extend-price-source-type-must-sync-document-subset-enum.md @@ -0,0 +1,68 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [price-calculation, price-source, price-source-type, enumextension, pricing] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Extend Price Source Type and its matching document subset enum together, with the same ID + +## Description + +`enum 7003 "Price Source Type"` (`implements "Price Source", "Price Source +Group"`) is the base list of who a price can apply to — Customer, Vendor, +Customer Price Group, Campaign, and so on. It is not, by itself, what +drives the "Applies-to Type" field on an actual sales, purchase, or job +price list. Each document area has its own subset enum — +`enum 7006 "Sales Price Source Type"`, the equivalent purchase and job +enums — and these are what the price list pages actually expose. Every +value the two enums share today uses the identical numeric ID: `All +Customers`/`Customer`/`Customer Price Group`/`Customer Disc. +Group`/`Campaign`/`Contact` are 10/11/12/13/50/51 in both `Price Source +Type` and `Sales Price Source Type`. + +Adding a new value to `Price Source Type` alone does nothing for a sales +price list: the base enum and the document subset enum are two separate +extensible enums, linked only by convention, not by any platform +mechanism that keeps their IDs in sync. Give the new value a different ID +in each enum, or extend only the base enum, and the source is real and +selectable in some contexts (the base enum is used elsewhere, such as +the generic `Price Source` table) but absent from the specific document +price list a developer actually tested against. + +## Best Practice + +When a new price source should be usable in a sales, purchase, or job +price list, extend `Price Source Type` and the matching document subset +enum (`Sales Price Source Type`, `Purchase Price Source Type`, `Job Price +Source Type`) together, using the identical numeric ID in both. + +See sample: [`extend-price-source-type-must-sync-document-subset-enum.good.al`](extend-price-source-type-must-sync-document-subset-enum.good.al). + +## Anti Pattern + +Extending `Price Source Type` with a new value intended for sales price +lists, without extending `Sales Price Source Type` with a value of the +same ID — or giving it a different ID. Either way, the new source is +absent from the "Applies-to Type" options on an actual sales price list, +with no error anywhere: the base enum extension compiles and installs +cleanly on its own. + +See sample: [`extend-price-source-type-must-sync-document-subset-enum.bad.al`](extend-price-source-type-must-sync-document-subset-enum.bad.al). + +## Source + +BCApps (`src/Layers/W1/BaseApp/`): `Pricing/Source/PriceSourceType.Enum.al` +(`enum 7003 "Price Source Type"`, values `10/11/12/13/50/51` for `All +Customers`/`Customer`/`Customer Price Group`/`Customer Disc. +Group`/`Campaign`/`Contact`) and `Sales/Pricing/SalesPriceSourceType.Enum.al` +(`enum 7006 "Sales Price Source Type"`, the same six values at the same +six IDs). Microsoft Learn, "Extending Price Calculations": "The Price +Source Type enum implements the Applies-to Type field in the header of +the price list. Additionally, the Sales Price Source Type, Purchase Price +Source Type, and Job Price Source Type are subsets of the Price Source +Type enum... For compatibility, the new value must have the same ID in +both enums." +(https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-extending-best-price-calculations) diff --git a/microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.bad.al b/microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.bad.al new file mode 100644 index 0000000..d09d34a --- /dev/null +++ b/microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.bad.al @@ -0,0 +1,47 @@ +enumextension 50100 "Sample Report Selection Usage Ext" extends "Report Selection Usage" +{ + value(50100; "Sample.SettlementDoc") + { + Caption = 'Sample Settlement Document'; + } +} + +report 50100 "Sample Settlement Document" +{ + UsageCategory = ReportsAndAnalysis; + ApplicationArea = All; + + dataset + { + dataitem(Customer; Customer) + { + column(No_Customer; "No.") { } + } + } +} + +codeunit 50100 "Sample Report Selection Install" +{ + procedure InstallDefaultReportSelection() + var + ReportSelections: Record "Report Selections"; + begin + ReportSelections.InsertRecord( + "Report Selection Usage"::"Sample.SettlementDoc", '1', Report::"Sample Settlement Document"); + // Registration ends here. No enumextension was added to + // "Custom Report Selection Sales" (or "Report Selection Usage + // Vendor"), and no subscriber was added to + // OnAfterOnMapTableUsageValueToPageValue, OnValidateUsage2OnCaseElse, + // or OnAfterFilterCustomerUsageReportSelections / + // OnAfterFilterVendorUsageReportSelections. + // + // The tenant-wide default works, so the gap isn't visible in + // testing - but on the Document Layouts page for a specific + // customer or vendor: an existing row for this usage shows blank in + // the Usage column (no map event), a user cannot pick this usage + // from the Usage dropdown at all (no validate event and no + // page-facing enum value to pick), and "Copy from Report Selection" + // never lists it either (no filter event). No error, no visible + // sign that anything is missing. + end; +} diff --git a/microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.good.al b/microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.good.al new file mode 100644 index 0000000..065e802 --- /dev/null +++ b/microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.good.al @@ -0,0 +1,87 @@ +enumextension 50100 "Sample Report Selection Usage Ext" extends "Report Selection Usage" +{ + value(50100; "Sample.SettlementDoc") + { + Caption = 'Sample Settlement Document'; + } +} + +// This document is only ever issued to a customer, so only the customer-side +// page-facing enum is extended - not the vendor-side one too. This mirrors +// BCApps' ReportSelectionHandlerCZZ, which extends "Custom Report Selection +// Sales" for its customer-only usages and "Report Selection Usage Vendor" +// for its vendor-only usages, never both for the same one-sided value. +enumextension 50101 "Sample Cust. Rep. Sel. Sales Ext" extends "Custom Report Selection Sales" +{ + value(50100; "Sample.SettlementDoc") + { + Caption = 'Sample Settlement Document'; + } +} + +report 50100 "Sample Settlement Document" +{ + UsageCategory = ReportsAndAnalysis; + ApplicationArea = All; + + dataset + { + dataitem(Customer; Customer) + { + column(No_Customer; "No.") { } + } + } +} + +codeunit 50100 "Sample Report Selection Install" +{ + procedure InstallDefaultReportSelection() + var + ReportSelections: Record "Report Selections"; + begin + ReportSelections.InsertRecord( + "Report Selection Usage"::"Sample.SettlementDoc", '1', Report::"Sample Settlement Document"); + end; +} + +codeunit 50101 "Sample Report Selection Subscribers" +{ + // Customer-only document: all three subscribers below are on + // "Customer Report Selections" only. There are no matching subscribers + // on "Vendor Report Selections" - subscribing there too would be the + // overbroad mistake this sample avoids (see the .bad.al companion and + // the article's Anti Pattern #2). + + // 1) Map: lets an existing row display in the Usage column instead of + // showing blank. + [EventSubscriber(ObjectType::Page, Page::"Customer Report Selections", 'OnAfterOnMapTableUsageValueToPageValue', '', false, false)] + local procedure AddSampleUsageOnAfterOnMapTableUsageValueToPageValue(var Usage2: Enum "Custom Report Selection Sales"; CustomReportSelection: Record "Custom Report Selection") + begin + if CustomReportSelection.Usage = "Report Selection Usage"::"Sample.SettlementDoc" then + Usage2 := "Custom Report Selection Sales"::"Sample.SettlementDoc"; + end; + + // 2) Validate: lets a user pick the new value from the Usage dropdown. + [EventSubscriber(ObjectType::Page, Page::"Customer Report Selections", 'OnValidateUsage2OnCaseElse', '', false, false)] + local procedure AddSampleUsageOnValidateUsage2OnCaseElse(var CustomReportSelection: Record "Custom Report Selection"; ReportUsage: Option) + begin + if ReportUsage = "Custom Report Selection Sales"::"Sample.SettlementDoc".AsInteger() then + CustomReportSelection.Usage := "Report Selection Usage"::"Sample.SettlementDoc"; + end; + + // 3) Filter: wires "Copy from Report Selection" - the piece most + // guidance stops at, appending to whatever filter already exists rather + // than replacing it. + [EventSubscriber(ObjectType::Page, Page::"Customer Report Selections", 'OnAfterFilterCustomerUsageReportSelections', '', false, false)] + local procedure AddSampleUsageOnAfterFilterCustomerUsageReportSelections(var ReportSelections: Record "Report Selections") + begin + ReportSelections.SetFilter(Usage, GetUsageFilter(ReportSelections)); + end; + + local procedure GetUsageFilter(var ReportSelections: Record "Report Selections") UsageFilter: Text + begin + UsageFilter := Format("Report Selection Usage"::"Sample.SettlementDoc"); + if ReportSelections.GetFilter(Usage) <> '' then + UsageFilter := StrSubstNo('%1|%2', ReportSelections.GetFilter(Usage), UsageFilter); + end; +} diff --git a/microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.md b/microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.md new file mode 100644 index 0000000..3750645 --- /dev/null +++ b/microsoft/knowledge/data-modeling/extend-report-selection-usage-for-new-document-types.md @@ -0,0 +1,99 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [report-selections, report-selection-usage, enumextension, document-layouts, custom-report-selection] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Register a new document type through Report Selections, and wire it into Document Layouts correctly + +## Description + +A custom document that needs printing/emailing should be registered +through `table 77 "Report Selections"`. `enum 77 "Report Selection Usage"` +is `Extensible = true` for exactly this: add a value via `enumextension`, +then `ReportSelections.InsertRecord(Usage, Sequence, ReportID)` for a +tenant-wide default — the mechanism every standard document uses. + +That alone does not make the value usable in "Document Layouts" +(`page 9657 "Customer Report Selections"` / `page 9658 "Vendor Report +Selections"`, table 9657 "Custom Report Selection"). Both pages hide +`enum 77` behind their own page-facing enum — `enum 9657 "Custom Report +Selection Sales"` (customer) / `enum 9658 "Report Selection Usage Vendor"` +(vendor) — in a field named `Usage2`. A new value stays invisible there +until that page enum is extended too and three events are handled: +`OnAfterOnMapTableUsageValueToPageValue` / `OnMapTableUsageValueToPage +ValueOnCaseElse` (Usage column display), `OnValidateUsage2OnCaseElse` +(picking it from the dropdown), and `OnAfterFilterCustomerUsageReport +Selections` / `OnAfterFilterVendorUsageReportSelections` (the **"Copy from +Report Selection"** action only — a hardcoded-list filter, nothing more). + +Which side(s) need this depends on the counterparty the document actually +applies to — not "always both." BCApps' `ReportSelectionHandlerCZZ` +(Advance Payments) partitions strictly: `"Sales Advance..."` usages get +only the customer-side triad, `"Purchase Advance..."` only the vendor-side +triad. `ReportSelectionHandlerCZC` (Compensation) subscribes both sides — +legitimately, since that document posts to both ledgers, not by default. + +## Best Practice + +1. Add the usage value (`enumextension ... extends "Report Selection + Usage"`) and register the tenant-wide default. +2. Decide which counterparty(ies) apply — customer, vendor, or both. +3. For each applicable side, extend the matching page enum + (`"Custom Report Selection Sales"` / `"Report Selection Usage Vendor"`) + and subscribe to that page's map, validate, and filter events — + appending with `StrSubstNo('%1|%2', ReportSelections.GetFilter(Usage), + UsageFilter)`, never overwriting. +4. Do not subscribe the other side for a one-sided document: skip the + triad and the value is unreachable in Document Layouts; wire both sides + needlessly and the picker is cluttered with a value that never applies. + +See sample: [`extend-report-selection-usage-for-new-document-types.good.al`](extend-report-selection-usage-for-new-document-types.good.al) +(customer-only document — only the customer-side enum and triad added). + +## Anti Pattern + +1. Register the usage value but add no page-enum extension and no + subscribers. Works via the tenant-wide default, so it's invisible in + testing — but Document Layouts shows the value's rows blank, can't offer + it in the Usage dropdown, and "Copy from Report Selection" never lists + it. See sample: [`extend-report-selection-usage-for-new-document-types.bad.al`](extend-report-selection-usage-for-new-document-types.bad.al). +2. Subscribe both counterparties' triads for a one-sided document. This is + the overbroad default Jesper Schulz-Wedde's review caught: it + contradicts how `ReportSelectionHandlerCZZ` actually partitions its + usages, and clutters the other counterparty's picker with a value that + will never resolve a report there. + +## Source + +`ReportSelections.Table.al` (table 77, `InsertRecord` line 344), +`ReportSelectionUsage.Enum.al` (enum 77, `Extensible = true`), +`CustomReportSelection.Table.al` (table 9657) — all under +`src/Layers/W1/BaseApp/Foundation/Reporting/`. + +`CustomerReportSelections.Page.al` (page 9657, `.../Sales/Setup/`): +`FilterCustomerUsageReportSelections` (307), +`OnAfterFilterCustomerUsageReportSelections` (335), +`OnAfterOnMapTableUsageValueToPageValue` (325), +`OnValidateUsage2OnCaseElse` (330); enum `CustomReportSelectionSales.Enum.al` +(9657, same folder). `VendorReportSelections.Page.al` (page 9658, +`.../Purchases/Setup/`): `FilterVendorUsageReportSelections` (281), +`OnAfterFilterVendorUsageReportSelections` (296), +`OnMapTableUsageValueToPageValueOnCaseElse` (301), +`OnValidateUsage2OnCaseElse` (306); enum `ReportSelectionUsageVendor.Enum.al` +(9658, same folder). + +Partitioning precedent: `.../AdvancePaymentsLocalization/app/Src/Codeunits/ +ReportSelectionHandlerCZZ.Codeunit.al` (codeunit 31420) — customer-only +triad (47, 58, 69) for `"Sales Advance..."`, vendor-only triad (80, 91, +102) for `"Purchase Advance..."`, never both for one usage. Enum +extensions: `CustomReportSelSalesCZZ.EnumExt.al` (31008), `ReportSelUsage +VendorCZZ.EnumExt.al` (11708). + +Contrast (two-sided): `.../CompensationLocalization/app/Src/Codeunits/ +ReportSelectionHandlerCZC.Codeunit.al` (codeunit 11765) subscribes both +triads (16/27/38, 44/55/66) for `"Compensation CZC"`, which posts to both +a customer and a vendor ledger. (Lines as of `main`; may shift by version.) diff --git a/microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.bad.al b/microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.bad.al new file mode 100644 index 0000000..6132c60 --- /dev/null +++ b/microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.bad.al @@ -0,0 +1,25 @@ +tableextension 50105 "Sample Sales Line Ext" extends "Sales Line" +{ + fields + { + // WRONG: no OnValidate trigger. The field is registered as a + // price source below via OnAfterAddSources, so new lines price + // correctly - but changing this field on an existing line never + // triggers a recalculation (e.g. via UpdateUnitPrice), so the + // unit price silently keeps its old value. + field(50100; "Sample Loyalty Customer No."; Code[20]) + { + Caption = 'Sample Loyalty Customer No.'; + TableRelation = Customer; + } + } +} + +codeunit 50106 "Sample Sales Line Price Sources" +{ + [EventSubscriber(ObjectType::Codeunit, Codeunit::"Sales Line - Price", 'OnAfterAddSources', '', false, false)] + local procedure AddLoyaltyCustomerSource(SalesHeader: Record "Sales Header"; SalesLine: Record "Sales Line"; PriceType: Enum "Price Type"; var PriceSourceList: Codeunit "Price Source List") + begin + PriceSourceList.Add(Enum::"Price Source Type"::Customer, SalesLine."Sample Loyalty Customer No."); + end; +} diff --git a/microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.good.al b/microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.good.al new file mode 100644 index 0000000..6f8b157 --- /dev/null +++ b/microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.good.al @@ -0,0 +1,38 @@ +tableextension 50105 "Sample Sales Line Ext" extends "Sales Line" +{ + fields + { + field(50100; "Sample Loyalty Customer No."; Code[20]) + { + Caption = 'Sample Loyalty Customer No.'; + TableRelation = Customer; + + trigger OnValidate() + begin + // Second half of the wiring: without this call, changing + // the field on an existing line never re-runs price + // calculation, even though the source is already a known + // candidate via OnAfterAddSources below. + // + // UpdateUnitPriceByField(CalledByFieldNo) only recalculates + // if PlanPriceCalcByField(CalledByFieldNo) was already + // called for that same field - calling it alone is a + // silent no-op. UpdateUnitPrice(CalledByFieldNo) does both + // steps in the right order (plan, then update) in one + // call; it's the same method the base app itself calls + // from outside Sales Line to trigger recalculation for a + // field it just changed. + UpdateUnitPrice(FieldNo("Sample Loyalty Customer No.")); + end; + } + } +} + +codeunit 50106 "Sample Sales Line Price Sources" +{ + [EventSubscriber(ObjectType::Codeunit, Codeunit::"Sales Line - Price", 'OnAfterAddSources', '', false, false)] + local procedure AddLoyaltyCustomerSource(SalesHeader: Record "Sales Header"; SalesLine: Record "Sales Line"; PriceType: Enum "Price Type"; var PriceSourceList: Codeunit "Price Source List") + begin + PriceSourceList.Add(Enum::"Price Source Type"::Customer, SalesLine."Sample Loyalty Customer No."); + end; +} diff --git a/microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.md b/microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.md new file mode 100644 index 0000000..828fc8c --- /dev/null +++ b/microsoft/knowledge/data-modeling/new-price-source-must-add-candidate-and-trigger-recalculation.md @@ -0,0 +1,97 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [price-calculation, price-source, onafteraddsources, recalculation, pricing] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# A new price source needs both a calculation candidate and a recalculation trigger + +## Description + +Making a custom field usable as a price source on a sales line is two +separate, independent pieces of wiring, and doing only one produces a +line that looks like it's using the new source without ever actually +being priced by it. `codeunit "Sales Line - Price"` publishes +`OnAfterAddSources(SalesHeader: Record "Sales Header"; SalesLine: Record +"Sales Line"; PriceType: Enum "Price Type"; var PriceSourceList: Codeunit +"Price Source List")` — subscribing here and calling +`PriceSourceList.Add(SourceType, SourceNo)` makes the source a candidate +the calculation considers. But nothing about that subscription causes +the price to be *recalculated* when the source field's value changes on +an existing line. That's the second, separate piece, and it needs to be +wired correctly: `Sales Line`'s `procedure +UpdateUnitPriceByField(CalledByFieldNo: Integer)` only recalculates if +the field was already *planned* — internally it exits immediately unless +`procedure PlanPriceCalcByField(CurrPriceFieldNo: Integer)` was already +called for that same field number. Calling `UpdateUnitPriceByField` on +its own, without a matching `PlanPriceCalcByField` call first, compiles +fine and looks correct, but silently recalculates nothing. `Sales Line` +also exposes `procedure UpdateUnitPrice(CalledByFieldNo: Integer)`, a +convenience wrapper that does both steps in the right order (plan, then +update) in one call — this is the method the base app itself calls from +*outside* `Sales Line` to trigger recalculation for a field it just +changed (see `Inventory/Item/Catalog/ItemReferenceManagement.Codeunit.al`: +`SalesLine.UpdateUnitPrice(SalesLine.FieldNo("Item Reference No."))`), and +it's what a custom price source field's own trigger should call too — the +same way Microsoft's own Location example is wired from a `Sales Line` +validation event, not from the price source registration itself. + +Add the source without wiring recalculation, and the failure hides +easily: a *new* line still prices correctly, because the field already +holds its value when calculation first runs on insert. The gap only +shows up when someone *changes* the source field's value on an existing +line — the price silently keeps its old value until something unrelated +happens to trigger recalculation. + +## Best Practice + +Wire both halves together whenever a field becomes a price source: an +`OnAfterAddSources` subscriber that adds it via `PriceSourceList.Add`, and +a trigger on the field itself (its own `OnValidate`, or a matching +`OnAfterValidate` integration event) that calls +`SalesLine.UpdateUnitPrice(SalesLine.FieldNo())`. Calling +`UpdateUnitPriceByField` directly, without first calling +`PlanPriceCalcByField` for that same field number, is *not* equivalent — +it exits immediately and recalculates nothing. `UpdateUnitPrice` does +both calls, in the correct order, in one step. + +See sample: [`new-price-source-must-add-candidate-and-trigger-recalculation.good.al`](new-price-source-must-add-candidate-and-trigger-recalculation.good.al). + +## Anti Pattern + +Subscribing to `OnAfterAddSources` to register a custom field as a price +source, without also triggering recalculation (via `UpdateUnitPrice`, or +the `PlanPriceCalcByField` + `UpdateUnitPriceByField` pair) from that +field's own validation. The field is a genuine, working calculation +candidate — new lines price correctly — but editing the field on an +existing line leaves the unit price stale, with nothing to indicate why. + +See sample: [`new-price-source-must-add-candidate-and-trigger-recalculation.bad.al`](new-price-source-must-add-candidate-and-trigger-recalculation.bad.al). + +## Source + +BCApps (`src/Layers/W1/BaseApp/`): `Sales/Pricing/SalesLinePrice.Codeunit.al` +(`local procedure OnAfterAddSources(SalesHeader: Record "Sales Header"; +SalesLine: Record "Sales Line"; PriceType: Enum "Price Type"; var +PriceSourceList: Codeunit "Price Source List")`); `Pricing/Source/PriceSourceList.Codeunit.al` +(`procedure Add(SourceType: Enum "Price Source Type"; SourceNo: Code[20])`); +`Sales/Document/SalesLine.Table.al` (`procedure +PlanPriceCalcByField(CurrPriceFieldNo: Integer)`; `procedure +UpdateUnitPrice(CalledByFieldNo: Integer)`; `procedure +UpdateUnitPriceByField(CalledByFieldNo: Integer)`, which exits immediately +unless `FieldCausedPriceCalculation` already equals `CalledByFieldNo` — +the state `PlanPriceCalcByField` sets). External, idiomatic use of the +one-call form: `Inventory/Item/Catalog/ItemReferenceManagement.Codeunit.al` +(`SalesLine.UpdateUnitPrice(SalesLine.FieldNo("Item Reference No."))`). + +Microsoft Learn, "Extending Price Calculations" (Location example): "To +recalculate the price, we can subscribe to events that pass the sales +line by reference... We'll call the UpdateUnitPriceByLocationCode() +method, which is a simplified version of the UpdateUnitPriceByField() +method... To add the location in the source list for price calculations, +we'll subscribe to the OnAfterAddSources event of Codeunit 'Sales Line - +Price,' and add the Location Code as a source." +(https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-extending-best-price-calculations) diff --git a/microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.bad.al b/microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.bad.al new file mode 100644 index 0000000..a60692b --- /dev/null +++ b/microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.bad.al @@ -0,0 +1,41 @@ +report 50110 "Sample Item Barcode Label" +{ + UsageCategory = Tasks; + ApplicationArea = All; + Caption = 'Sample Item Barcode Label'; + + dataset + { + dataitem(Item; Item) + { + column(No_; "No.") { } + column(Barcode; BarcodeText) { } + + trigger OnAfterGetRecord() + var + BarcodeFontProvider: Interface "Barcode Font Provider"; + begin + // WRONG: a one-dimensional IDAutomation provider path that + // calls EncodeFont without ValidateInput. "Barcode Font + // Provider" (1D) declares both, and IDAutomation 1D + // Provider's EncodeFont does not validate on its own - it + // hands the text straight to the font encoder. Code 39 + // accepts only 0-9, A-Z, space and - . $ / + % *, but an + // Item "No." can legally contain characters outside that + // set (e.g. "_" or "#"). Such a value is never rejected; + // it silently reaches the font as an unscannable barcode. + BarcodeFontProvider := Enum::"Barcode Font Provider"::IDAutomation1D; + BarcodeText := BarcodeFontProvider.EncodeFont("No.", BarcodeSymbology); + end; + } + } + + var + BarcodeSymbology: Enum "Barcode Symbology"; + BarcodeText: Text; + + trigger OnInitReport() + begin + BarcodeSymbology := Enum::"Barcode Symbology"::Code39; + end; +} diff --git a/microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.good.al b/microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.good.al new file mode 100644 index 0000000..8364ad8 --- /dev/null +++ b/microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.good.al @@ -0,0 +1,54 @@ +report 50110 "Sample Item Barcode Label" +{ + UsageCategory = Tasks; + ApplicationArea = All; + Caption = 'Sample Item Barcode Label'; + + dataset + { + dataitem(Item; Item) + { + column(No_; "No.") { } + column(Barcode1D; BarcodeText) { } + column(Barcode2D; QRCodeText) { } + + trigger OnAfterGetRecord() + var + BarcodeFontProvider: Interface "Barcode Font Provider"; + BarcodeFontProvider2D: Interface "Barcode Font Provider 2D"; + begin + // One-dimensional: "Barcode Font Provider" declares both + // ValidateInput and EncodeFont - call both. + BarcodeFontProvider := Enum::"Barcode Font Provider"::IDAutomation1D; + BarcodeFontProvider.ValidateInput("No.", BarcodeSymbology); + BarcodeText := BarcodeFontProvider.EncodeFont("No.", BarcodeSymbology); + + // Two-dimensional: "Barcode Font Provider 2D" declares only + // EncodeFont - there is no ValidateInput to call here. + BarcodeFontProvider2D := Enum::"Barcode Font Provider 2D"::IDAutomation2D; + QRCodeText := BarcodeFontProvider2D.EncodeFont("No.", BarcodeSymbology2D); + end; + } + } + + var + BarcodeSymbology: Enum "Barcode Symbology"; + BarcodeSymbology2D: Enum "Barcode Symbology 2D"; + BarcodeText: Text; + QRCodeText: Text; + + trigger OnInitReport() + begin + BarcodeSymbology := Enum::"Barcode Symbology"::Code39; + BarcodeSymbology2D := Enum::"Barcode Symbology 2D"::"QR-Code"; + end; + + // Layout requirement (can't be enforced in AL, so it's stated here): + // the Barcode1D column's text box must use the real, purchased font + // name - IDAutomationHC39M for Code 39 - never an evaluation name + // like "IDAutomationSHC39M Demo". Per Microsoft Learn, using the + // evaluation name in a Business Central online production + // environment means "the barcode won't render" at all. The + // Barcode2D column's font name is IDAutomation2D (IDAutomation2D + // MaxiCode for Maxicode specifically). +} diff --git a/microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.md b/microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.md new file mode 100644 index 0000000..e85d7e1 --- /dev/null +++ b/microsoft/knowledge/data-modeling/report-barcodes-must-use-barcode-module-and-production-font-name.md @@ -0,0 +1,99 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [barcode, qr-code, barcode-font-provider, barcode-font-provider-2d, report-layout, saas, idautomation, code-39, checksum] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Generate report barcodes through the Barcode module, with the production font name + +## Description + +Business Central's barcode support lives in the System Application's +`Barcode` module (`src/System Application/App/Barcode`): `interface +"Barcode Font Provider"` / `"Barcode Font Provider 2D"`, `enum "Barcode +Symbology"` / `"Barcode Symbology 2D"`, and built-in implementations +(`codeunit 9215`/`9221`). A report encodes a data string via this API; +the layout then displays it using a barcode *font*. + +The two interfaces are not symmetric: `"Barcode Font Provider"` (1D) +declares both `ValidateInput` and `EncodeFont`; `"Barcode Font Provider +2D"` declares only `EncodeFont` (see Source). BCApps' `Item GTIN Label` +report reflects that split exactly — it validates then encodes through +the 1D provider, but only encodes through the 2D provider, for the same +"No." value. + +On Business Central online this needs no setup ("the IDAutomation fonts +are automatically available as part of the service" — Microsoft Learn), +unlike on-premises, where fonts must be purchased and installed. That +ease hides a SaaS-specific trap the API doesn't cover: naming the actual +font. IDAutomation ships both a purchased font and a same-looking +evaluation font per version (Code 39: `IDAutomationHC39M` purchased vs. +`IDAutomationSHC39M Demo`) — per Microsoft Learn, "be sure to use the +purchased font name... If you use the evaluation font name, the barcode +won't render." The wrong name produces nothing, in the layout not AL, so +no reviewer catches it reading the object. + +## Best Practice + +Encode through the real API, matching the calls to what the chosen +interface actually declares. One-dimensional: declare `Interface +"Barcode Font Provider"` and call both `ValidateInput` and `EncodeFont` +— skipping validation lets a value outside the character set, or one +needing a checksum setting never applied, reach the font unchecked. +Two-dimensional: declare `Interface "Barcode Font Provider 2D"` and call +`EncodeFont` alone — there is no `ValidateInput` on this interface. + +Treat naming the production font in the layout as equally required, not +an afterthought. Two-dimensional symbologies other than Maxicode use +`IDAutomation2D` (Maxicode: `IDAutomation2D MaxiCode`); one-dimensional +symbologies use the purchased version name (e.g. `IDAutomationHC39M` for +Code 39), never a name containing `Demo`. + +See sample: [`report-barcodes-must-use-barcode-module-and-production-font-name.good.al`](report-barcodes-must-use-barcode-module-and-production-font-name.good.al). + +## Anti Pattern + +Constructing a barcode string by hand where that construction has a +concrete, independently provable defect: a source value that can contain +characters outside the symbology's character set is never validated, a +checksum the symbology or setup requires is never applied, or there is +concrete evidence of an incompatible font binding. + +The delimiter itself is not the defect. `*value*` is a documented, valid +Code 39 form for IDAutomation fonts (Microsoft Learn's font table and +IDAutomation's own manual both give `*` as start/stop); the `(`/`)` that +IDAutomation 1D Provider's encoder emits (BCApps test: +`EncodeFont('1234', Code39) = '(1234)'`) is an alternative start/stop +form the same fonts accept, used to keep `*` out of the human-readable +text. Never flag delimiter choice alone. + +The same validation gap exists when the module *is* used: a 1D path that +calls `EncodeFont` on `"Barcode Font Provider"` without `ValidateInput` +(IDAutomation 1D Provider's `EncodeFont` does not validate on its own). +The sample shows this variant, visible in AL alone. A last version: +encoding correctly but naming the evaluation font, which BC online +refuses to render. + +See sample: [`report-barcodes-must-use-barcode-module-and-production-font-name.bad.al`](report-barcodes-must-use-barcode-module-and-production-font-name.bad.al). + +## Source + +BCApps (`src/System Application/App/Barcode/src/`): +`Barcode Provider/Font/BarcodeFontProvider.Interface.al` (1D: +`ValidateInput` + `EncodeFont`); `IDAutomation 1D Provider/ +IDAutomation1DProvider.Codeunit.al` (`EncodeFont` goes straight to the +symbology encoder; only `ValidateInput` calls `IsValidInput`); `Barcode Provider 2D/Font/BarcodeFontProvider2D.Interface.al` +(2D: only `EncodeFont`). `IDAutomation 1D Provider/Encoders/IDA1DCode39Encoder.Codeunit.al` +(`codeunit 9204`, regex accepts literal `*`; `EncodeFont` → `DotNet FontEncoder.Code39`). +1D/2D split: `.../Inventory/Item/ItemGTINLabel.Report.al` (`report 6625`, +validates+encodes 1D, only encodes 2D). Encoder output form: `IDA1DCode39Test.Codeunit.al` +(`codeunit 135044`): `EncodeFontSuccessTest('1234', Code39, '(1234)')`. + +Microsoft Learn "Adding Barcodes to Reports" and "Barcode Fonts with +Business Central Online" — quoted above, incl. the Code39 row ("`*` is +used for both start and stop delimiters"). IDAutomation, "Code 39 Font +User Manual" (https://idautomation.com/barcode-fonts/code-39/fontnames/): +`*` start/stop, or parentheses to keep `*` out of the human-readable text. diff --git a/microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.bad.al b/microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.bad.al new file mode 100644 index 0000000..b91dba8 --- /dev/null +++ b/microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.bad.al @@ -0,0 +1,30 @@ +tableextension 50100 "Sample Sales Header Ext" extends "Sales Header" +{ + fields + { + field(50000; "Reference No."; Code[20]) + { + Caption = 'Reference No.'; + DataClassification = CustomerContent; + } + } +} + +tableextension 50101 "Sample Sales Invoice Header Ext" extends "Sales Invoice Header" +{ + fields + { + // WRONG: same field number 50000, but a shorter length than the + // Sales Header extension above. This compiles fine and posts + // fine for every "Reference No." of 10 characters or less - + // SalesInvHeader.TransferFields(SalesHeader) in + // SalesPost.Codeunit.al only throws once an actual value longer + // than 10 characters reaches posting, which typical test data + // never triggers. + field(50000; "Reference No."; Code[10]) + { + Caption = 'Reference No.'; + DataClassification = CustomerContent; + } + } +} diff --git a/microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.good.al b/microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.good.al new file mode 100644 index 0000000..9f6bcc3 --- /dev/null +++ b/microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.good.al @@ -0,0 +1,28 @@ +tableextension 50100 "Sample Sales Header Ext" extends "Sales Header" +{ + fields + { + field(50000; "Reference No."; Code[20]) + { + Caption = 'Reference No.'; + DataClassification = CustomerContent; + } + } +} + +tableextension 50101 "Sample Sales Invoice Header Ext" extends "Sales Invoice Header" +{ + fields + { + // Same field number, same type, same length as the Sales Header + // extension above. SalesInvHeader.TransferFields(SalesHeader) in + // SalesPost.Codeunit.al only bridges two fields that agree on all + // three - matching all three here is what makes this value + // survive posting for every possible "Reference No." value. + field(50000; "Reference No."; Code[20]) + { + Caption = 'Reference No.'; + DataClassification = CustomerContent; + } + } +} diff --git a/microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.md b/microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.md new file mode 100644 index 0000000..70feb22 --- /dev/null +++ b/microsoft/knowledge/data-modeling/transferfields-mirrored-fields-must-match-type-and-length.md @@ -0,0 +1,87 @@ +--- +bc-version: [all] +domain: data-modeling +keywords: [transferfields, field-number, posting-cascade, schema-design, custom-field] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +# Mirrored TransferFields cascade fields must match type and length exactly + +## Description + +Most custom fields genuinely belong to only one table — a status used +only before posting, a note relevant only afterwards, whatever the case +may be. That is the ordinary, unremarkable default, and it needs no +justification: `TransferFields` never touches a field that doesn't exist +on the destination. Per Microsoft's own documentation, a source field's +contents are copied "if such a field exists" on the destination with a +matching field number — a field defined on only one side of a posting +cascade is simply outside `TransferFields`' reach, not a gap to fix. + +The narrower case this rule addresses is when a field **is** deliberately +mirrored across a known cascade — the same field number reused on +another table specifically so the value survives posting, for example a +field added to both `Sales Header` (36) and `Sales Invoice Header` (112), +which `SalesPost.Codeunit.al` connects via +`SalesInvHeader.TransferFields(SalesHeader)`. The two definitions have to +agree on type and, less obviously, on length. A field defined `Text[100]` +on `Sales Header` and `Text[50]` on `Sales Invoice Header` compiles +cleanly on both sides, and the `TransferFields` call runs without error +for every value up to 50 characters. Per Microsoft's documentation, a +runtime error only occurs when there isn't "room for the actual length +of the contents of the field to be copied" — so nothing fails while test +data, or early production data, stays short. The error surfaces only the +day an actual value finally exceeds the shorter definition, on a document +type that may have been posting cleanly for months. + +See also `transferfields-skip-type-mismatch-can-drop-data.md`, which +covers `SkipFieldsNotMatchingType = true` silently skipping a *type* +mismatch between same-extension fields. That parameter has no effect on +length: two fields of the same type but different length still raise the +runtime error described above regardless of how `SkipFieldsNotMatchingType` +is set, which is the distinct failure mode this article addresses. + +## Best Practice + +When mirroring a field across a `TransferFields` cascade, define it with +the exact same field number, data type, and length on every table in +that cascade, at creation time. A field intentionally left local to one +table is unaffected by this and needs no mirroring at all — this is a +consistency requirement between definitions that are already meant to be +linked, not a mandate to check every field against every table on the +cascade. + +See sample: [`transferfields-mirrored-fields-must-match-type-and-length.good.al`](transferfields-mirrored-fields-must-match-type-and-length.good.al). + +## Anti Pattern + +The same field number added to two tables that `TransferFields` connects +in a posting cascade (e.g. `Sales Header` (36) and `Sales Invoice Header` +(112), linked by `SalesPost.Codeunit.al`), with a shorter length — or an +incompatible data type — on one side. Both definitions compile without +error; nothing fails until an actual value exceeds the shorter one, which +typical test data never does. + +See sample: [`transferfields-mirrored-fields-must-match-type-and-length.bad.al`](transferfields-mirrored-fields-must-match-type-and-length.bad.al). + +## Source + +Microsoft Learn, `Record.TransferFields(var Record [, Boolean])`: +"The `TransferFields` method copies fields based on the field number on +the fields. For each field in `Record` (the destination), the contents +of the field that has the same field number in `FromRecord` (the source) +will be copied, **if such a field exists**." And: "The fields must have +the *same data type* for the copying to succeed... There must be room +for the actual length of the contents of the field to be copied in the +field to which it is to be copied. If any one of these conditions aren't +fulfilled, a runtime error will occur." +(https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/methods-auto/record/record-transferfields-table-boolean-method) + +BCApps `SalesPost.Codeunit.al` (`src/Layers/W1/BaseApp/Sales/Posting/`): +`SalesShptHeader.TransferFields(SalesHeader);` (line 7104), +`ReturnRcptHeader.TransferFields(SalesHeader);` (line 7166), +`SalesInvHeader.TransferFields(SalesHeader);` (line 7220), +`SalesCrMemoHeader.TransferFields(SalesHeader);` (line 7275) — the real +cascade a mirrored field on `Sales Header` (36) is checked against. diff --git a/microsoft/skills/review/al-data-modeling-review.md b/microsoft/skills/review/al-data-modeling-review.md index a73f929..5f4cec7 100644 --- a/microsoft/skills/review/al-data-modeling-review.md +++ b/microsoft/skills/review/al-data-modeling-review.md @@ -16,7 +16,7 @@ application-area: [all] Reviews AL source changes against the `data-modeling` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`. -An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. Data-modeling findings are narrow by design — they apply when the review scope contains setup or master tables, their card pages, primary keys, number-series assignment, block enforcement, audit fields, dimension wiring, journal-based posting-routine structure, or Item Ledger Entry document-number lookups after a combined sales post. The skill returns `not-applicable` when none of those apply. +An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. Data-modeling findings are narrow by design — they apply when the review scope contains setup or master tables, their card pages, primary keys, number-series assignment, block enforcement, audit fields, document print/email/Post-and-Send actions, `Navigate` page subscribers, Report Selection registration or dispatch, price-calculation/price-source extensibility, `TransferFields`-based posting-cascade field mirroring, barcode/report-layout font-provider usage, dimension wiring, journal-based posting-routine structure, or Item Ledger Entry document-number lookups after a combined sales post. The skill returns `not-applicable` when none of those apply. ## Source @@ -37,9 +37,9 @@ Discard files that are not applicable. Retain conditionally applicable files (an Narrow the relevant files to the subset that applies to the changes under review. For each relevant file, compute overlap against: -- The changed AL object names and types — especially `* Setup` singleton tables and Card pages, custom master tables, tableextensions that add master-data fields, and document or journal lines that reference a master. -- The changed fields, keys, triggers, and procedures, weighted toward `Primary Key`, `No.`, `No. Series`, `Blocked`, `Last Date Modified`, `OnInsert`, `OnModify`, `OnRename`, reference-field `OnValidate`, and posting validation. -- Tokens extracted from the diff that relate to data modeling (`setup`, `master`, `Primary Key`, `Code[10]`, `Code[20]`, `AutoIncrement`, `SystemId`, `No.`, `No. Series`, `NoSeriesManagement`, `Codeunit "No. Series"`, `GetNextNo`, `IsManual`, `TestManual`, `Blocked`, `TestField`, `Last Date Modified`, `Today`, `WorkDate`, `InsertAllowed`, `DeleteAllowed`, `PageType = Card`, `OnOpenPage`, `GetRecordOnce`, `OnInsert`, `OnModify`, `OnRename`, `InitRecord`, `Round`, `Precision`, `Direction`, `TableRelation`, `tableextension`, `enumextension`, `Media`, `MediaSet`, `Item`, `Count`). +- The changed AL object names and types — especially `* Setup` singleton tables and Card pages, custom master tables, tableextensions that add master-data fields, document or journal lines that reference a master, document pages/codeunits exposing print/email/Post-and-Send actions, codeunits subscribing to `Navigate`, enumextensions to `"Report Selection Usage"`/`"Price Calculation Handler"`/`"Price Source Type"`, and report objects that render barcodes. +- The changed fields, keys, triggers, and procedures, weighted toward `Primary Key`, `No.`, `No. Series`, `Blocked`, `Last Date Modified`, `OnInsert`, `OnModify`, `OnRename`, reference-field `OnValidate`, posting validation, and posting-cascade `TransferFields` calls. +- Tokens extracted from the diff that relate to data modeling (`setup`, `master`, `Primary Key`, `Code[10]`, `Code[20]`, `AutoIncrement`, `SystemId`, `No.`, `No. Series`, `NoSeriesManagement`, `Codeunit "No. Series"`, `GetNextNo`, `IsManual`, `TestManual`, `Blocked`, `TestField`, `Last Date Modified`, `Today`, `WorkDate`, `InsertAllowed`, `DeleteAllowed`, `PageType = Card`, `OnOpenPage`, `GetRecordOnce`, `OnInsert`, `OnModify`, `OnRename`, `InitRecord`, `Round`, `Precision`, `Direction`, `TableRelation`, `tableextension`, `enumextension`, `Media`, `MediaSet`, `Item`, `Count`, `TransferFields`, `Navigate`, `OnAfterFindRecords`, `OnBeforeShowRecords`, `Report Selections`, `Report Selection Usage`, `InsertRecord`, `Document Sending Profile`, `PrintForCust`, `PrintWithDialogForCust`, `PrintWithDialogForVend`, `SendEmailToCust`, `SendEmailToVendor`, `Report.RunModal`, `Report.Run`, `Price Calculation Handler`, `Price Calculation`, `OnFindSupportedSetup`, `Price Calculation Setup`, `Price Source Type`, `PriceSourceList`, `OnAfterAddSources`, `UpdateUnitPrice`, `PlanPriceCalcByField`, `UpdateUnitPriceByField`, `Barcode Font Provider`, `Barcode Font Provider 2D`, `EncodeFont`, `ValidateInput`). A file enters the candidate worklist when its `keywords` intersect the extracted tokens or its topic (derived from the index entry's `path`, `title`, and `description`) matches a changed object type. Read an article's full file — its `## Best Practice` / `## Anti Pattern` bodies — only after it makes the worklist; candidate selection uses the index alone. When the diff contains no data-modeling changes by any of the above signals, return `outcome: "not-applicable"` without evaluating files. @@ -58,6 +58,15 @@ The following targeted checks cover every current `data-modeling` article. Treat - A `Media` or `MediaSet` field is assigned directly between different table types or different field IDs instead of registering each shared item with `MediaSet.Insert` — `share-mediaset-items-with-insert-not-field-assignment`. - A custom document header assigns defaults outside an `InitRecord` boundary, calls `InitRecord` before assigning its number, or places UI-independent defaults only in a page trigger — `initialize-document-defaults-in-initrecord`. - Directed `Round` calls use `'<'` as mathematical floor or `'>'` as mathematical ceiling, especially where negative amounts are possible — `round-direction-symbols-use-magnitude`. +- A codeunit dispatches a document by calling `Report.Run`/`Report.RunModal` with a hardcoded report ID, or by building its own email directly, instead of going through the `Report Selections` usage for that document — `custom-document-dispatch-must-not-bypass-report-selections`. Either bypass is a finding on its own; both need not be present. Scope this to customer/vendor-facing documents that have (or should have) a `Report Selection Usage` — a hardcoded `Report.Run` of an ordinary list/analysis report is not this anti-pattern. A call that already goes through `Report Selections`' own Print/Email procedures is not this anti-pattern. +- A document's own interactive Print/Email action routes through `Document Sending Profile` (`DocumentSendingProfile.Send`/`SendVendor`) instead of calling `Report Selections` (`PrintForCust`/`PrintWithDialogForCust`/`SendEmailToCust`/`PrintWithDialogForVend`/`SendEmailToVendor`) directly — `document-print-and-email-actions-call-report-selections-directly`. Do not flag `Document Sending Profile` usage that is genuinely part of a combined Post-and-Send action. +- An `EventSubscriber` is added for `Navigate::OnAfterFindRecords` (registering a custom table in Find Entries) without a matching `Navigate::OnBeforeShowRecords` subscriber for the same table, or vice versa — `extend-find-entries-navigate-for-new-document-types`. Both subscribers must be added together for the same table. +- An `enumextension` extends `"Report Selection Usage"` and registers a report via `ReportSelections.InsertRecord`, without subscribing to the matching *single* counterparty's full triad — the filter event (`OnAfterFilterCustomerUsageReportSelections` on `page 9657` for a sales usage, `OnAfterFilterVendorUsageReportSelections` on `page 9658` for a purchase usage) AND the page-facing usage-enum map/validate events (`enumextension` on `"Custom Report Selection Sales"`/`"Report Selection Usage Vendor"` plus the matching map/validate subscribers) — `extend-report-selection-usage-for-new-document-types`. Requiring or wiring *both* counterparties by default for a one-sided document is also the anti-pattern (`ReportSelectionHandlerCZZ` partitions strictly by counterparty); only a genuinely two-sided usage (as `ReportSelectionHandlerCZC` demonstrates for Compensation) needs both. +- The same field number is added as a new field on two or more tables connected by a `TransferFields` call in a posting cascade (e.g. a header table and the posted-document table `SalesPost.Codeunit.al`/`PurchPost.Codeunit.al` transfer into), with a different data type or length on one side — `transferfields-mirrored-fields-must-match-type-and-length`. A field defined on only one side of the cascade is out of scope; this cues only on a field deliberately mirrored across the cascade with a type or length mismatch. +- An `enumextension` extends `"Price Calculation Handler"` and implements the `Price Calculation` interface, without a matching `OnFindSupportedSetup` subscriber inserting a `Price Calculation Setup` record naming that implementation as the `Implementation` for a `Method`/`Type`/`Asset Type` — `activate-new-price-calculation-handler-via-onfindsupportedsetup`. `Default := true` is only required on that row when it is meant as the fallback for its `Method`/`Type`/`Asset Type` combination; a row meant to be selected only through an explicit, specific `"Dtld. Price Calculation Setup"` row does not need it, so do not flag a missing `Default := true` by itself — flag the missing setup row/subscriber entirely. +- An `enumextension` extends `"Price Source Type"` with a new value intended for a sales, purchase, or job price list, without extending the matching document subset enum (`"Sales Price Source Type"`, `"Purchase Price Source Type"`, `"Job Price Source Type"`) with a value at the same numeric ID — `extend-price-source-type-must-sync-document-subset-enum`. +- A codeunit subscribes to `"Sales Line - Price"`'s `OnAfterAddSources` to register a custom field as a price source via `PriceSourceList.Add`, but that field has no `OnValidate` (or matching `OnAfterValidate`) that triggers recalculation — either `SalesLine.UpdateUnitPrice()`, or the explicit `SalesLine.PlanPriceCalcByField()` followed by `SalesLine.UpdateUnitPriceByField()`. A bare `UpdateUnitPriceByField` without a preceding `PlanPriceCalcByField` for the same field number does not count as recalculation (it exits without recalculating) — `new-price-source-must-add-candidate-and-trigger-recalculation`. +- A report hand-constructs a barcode string only where a concrete, independently provable defect is visible: the source value can contain characters outside the symbology's character set and is never validated, a checksum the symbology/setup requires is never applied, or there is concrete evidence of an incompatible font binding. Do not flag manual start/stop delimiters by themselves — `*value*` is a documented, valid Code 39 form for IDAutomation fonts (IDAutomation also accepts parentheses), so delimiter choice alone is never a finding. Also flag module use that does not match the interface: a 1D `"Barcode Font Provider"` path must call both `ValidateInput` and `EncodeFont`; a 2D `"Barcode Font Provider 2D"` path calls `EncodeFont` only (the 2D interface has no `ValidateInput`, so its absence there is not a finding). Separately, flag an otherwise correctly encoded barcode whose report layout names an evaluation/demo font instead of the purchased production font name — `report-barcodes-must-use-barcode-module-and-production-font-name`. - A new field is typed `Code`/`Text` and its `OnValidate` calls `DimensionManagement`/`DimMgt`, or a table adds Shortcut Dimension fields, a `Dimension Set ID` field, or `AddDimSource`/`GetDefaultDimID` — `dimension-management-wiring`. A master table calling `SaveDefaultDim` and a document/journal table computing its own `Dimension Set ID` are two different valid shapes; do not flag a master table for lacking a `Dimension Set ID` field or a document for lacking `SaveDefaultDim`. - A journal-based posting codeunit is added or changed and validation, Journal-table access, ledger writes, and user-interaction (`Confirm`/dialogs) all occur in one procedure or one codeunit, rather than split across `Check Line`/`Post Line`/`Post Batch`-shaped companions — `check-post-line-batch-pattern`. A document posting routine calling `Post Line` directly without a `Post Batch` companion is not this anti-pattern. - An existing, already-published table's `keys` block adds, removes, or reorders a field in its primary key or any `Clustered = true` key — `do-not-change-primary-key`. A new table defining its own key for the first time is not this anti-pattern; requires repository/publication context to know the table has already shipped. @@ -91,7 +100,7 @@ Outcome selection: - `completed` — the skill evaluated every worklist item. - `no-knowledge` — no applicable data-modeling knowledge survived filtering. -- `not-applicable` — the diff touches no setup/master table, page, key, numbering, block-check, audit-field, dimension-wiring, posting-routine-structure, or Item-Ledger-Entry-document-number surface. +- `not-applicable` — the diff touches no setup/master table, page, key, numbering, block-check, or audit-field surface, and no document print/email/Post-and-Send action, `Navigate` subscriber, Report Selection registration/dispatch, price-calculation/price-source extensibility point, posting-cascade `TransferFields` mirroring, barcode/report-font-provider usage, dimension wiring, posting-routine structure, or Item-Ledger-Entry-document-number surface. - `partial` — a budget was hit before the worklist was exhausted. - `failed` — an unrecoverable error occurred. diff --git a/tools/Test-ReviewFixtures.ps1 b/tools/Test-ReviewFixtures.ps1 index 2941c02..f9be512 100644 --- a/tools/Test-ReviewFixtures.ps1 +++ b/tools/Test-ReviewFixtures.ps1 @@ -303,6 +303,7 @@ foreach ($domain in $leafDomains) { $caseList.Add($case) | Out-Null } } + } $cases = @($caseList)