Skip to content

Add Job Queue reliability and scheduling guidance - #148

Merged
Jesper Schulz-Wedde (JesperSchulz) merged 6 commits into
microsoft:mainfrom
demiliani:jobqueue
Sep 14, 2026
Merged

Jesper Schulz-Wedde (JesperSchulz) merged 6 commits into
microsoft:mainfrom
demiliani:jobqueue

Conversation

@demiliani

Copy link
Copy Markdown
Contributor

Summary

Add six community performance rules that document reliability and scheduling behaviors for Business Central Job Queue and Task Scheduler workloads. Each rule includes focused good and bad AL examples so reviewers can distinguish unsafe code from intentional behavior.

What changed

  • Require external side effects to be idempotent across Job Queue retries. The good example sends the outbox SystemId as idempotencyKey in a JSON POST body and documents that the external service must atomically create only when the key is absent, returning the existing record on retries.
  • Keep Job Queue handlers independent of client UI and callbacks.
  • Propagate execution failures so the dispatcher can log failures and apply configured retries.
  • Use Job Queue Category Code to serialize jobs that require mutual exclusion.
  • Clarify that putting an entry On Hold prevents future runs but does not stop work already in progress, and demonstrate cooperative cancellation.
  • Persist scheduled-task GUIDs and check TaskScheduler.TaskExists before creating replacements.
  • Cross-reference the new retry-safety and duplicate-task guidance from the existing transaction and session-open articles.

Why

These behaviors depend on platform contracts that are easy to misread from otherwise valid AL code. Making the retry, background-session, concurrency, cancellation, and task-identity requirements explicit helps reviews identify real operational risks without flagging safe implementations.

Validation

  • Build-KnowledgeIndex.ps1: 278 articles indexed
  • Test-ReviewFixtures.ps1: 32 cases across 16 leaf domains passed
  • VS Code diagnostics: no errors in the performance knowledge folder
  • git diff --check: passed

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The overall set is useful, but four boundaries need correction before these become agent rules.

  1. The scheduled-task good sample exposes IsolatedStorage through a public procedure. store-scheduled-task-id-to-avoid-duplicate-tasks.good.al declares EnsureCleanupTask() without local/internal while it reads and writes IsolatedStorage. That contradicts microsoft/knowledge/security/isolatedstorage-access-must-be-local-or-internal.md and lets dependent extensions invoke the storage-backed scheduling operation. Make it internal (or put the storage access behind an internal helper if a deliberately public intent API is required).

  2. The cooperative-cancellation good sample processes one batch before checking an existing stop request. Its repeat ... until IsStopRequested(...) always executes once. Because the request is persisted, a later recurring run also processes one extra batch before exiting. Check before each unit, including the first (for example, a while not IsStopRequested(...) do loop), and state who clears the request when scheduling is resumed.

  3. Category serialization is company-scoped, not a general mutex. Job queue dispatch and the Waiting state coordinate entries in the same company/category. The article should explicitly say this does not serialize same-named categories across companies, environments, or non-job-queue workers; shared external/cross-company resources need another lock. Otherwise an agent can recommend a category that does not actually protect the stated resource.

  4. Job queue work is not unconditionally retried. job-queue-external-effects-must-be-idempotent.md says Business Central “retries the queued work,” but automatic rescheduling depends on recurrence and configured attempt limits; a failed entry can remain in Error and later be restarted manually. Phrase this as work that can be retried/rescheduled or rerun after rollback. The idempotency requirement still follows, without promising a retry on every failure.

The no-UI, failure-propagation, idempotency mechanism, On Hold semantics, and stored-task-ID approach are otherwise sound. All repository validators pass.

…bqueue

# Conflicts:
#	microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.bad.al
#	microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.good.al
#	microsoft/knowledge/performance/job-queue-category-code-serializes-conflicting-jobs.md
#	microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.bad.al
#	microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.good.al
#	microsoft/knowledge/performance/job-queue-external-effects-must-be-idempotent.md
#	microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.bad.al
#	microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.good.al
#	microsoft/knowledge/performance/job-queue-handlers-must-not-require-ui.md
#	microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.bad.al
#	microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.good.al
#	microsoft/knowledge/performance/job-queue-handlers-must-propagate-failures.md
#	microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.bad.al
#	microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.good.al
#	microsoft/knowledge/performance/job-queue-on-hold-does-not-stop-running-work.md
#	microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.bad.al
#	microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.good.al
#	microsoft/knowledge/performance/store-scheduled-task-id-to-avoid-duplicate-tasks.md

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The four concerns from the previous round are resolved, and all checks pass at this head. One fixture issue remains inline.

There is also an integration blocker outside the changed files: the six new articles are indexed, but microsoft/skills/review/al-performance-review.md has no deterministic Worklist route to them. Its token inventory and targeted cues omit the relevant Job Queue Entry/category, job-handler UI, external-effect, handled-failure, persisted-cancellation, and TaskScheduler.CreateTask/TaskExists signals; the performance fixture override still exercises only use-isempty-for-existence-check. Please update the owning skill with explicit selection cues and appropriate contextual exclusions, and add bad/good routing regressions for these rules. Otherwise all current validators can pass while agents never open or apply the new guidance.

The underlying guidance is valuable, but the executable sample and deterministic review routing need to be complete before these become authoritative agent rules.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous guidance, clean-company category fixture, and deterministic Worklist-route concerns are resolved. The practical exact-tree validators pass, and I found no new AL or platform-behavior issue.

One regression-contract issue remains inline. It is limited to the category case, but the added evaluation currently expects a finding after removing the only evidence needed by the rule's own contextual guard. Please preserve that case-specific context, then this should be ready for approval.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The category regression now preserves explicit shared-exclusive-resource evidence after fixture neutralization, while the good control correctly applies one shared non-empty category. All prior guidance, routing, evaluation, and AL/API concerns remain resolved, and the practical exact-tree validators pass. Approving.

@JesperSchulz
Jesper Schulz-Wedde (JesperSchulz) merged commit 8c26ba4 into microsoft:main Sep 14, 2026
5 of 6 checks passed
Michael Dieringer (MichaelDieringer) added a commit to Curabis/BCQuality that referenced this pull request Sep 21, 2026
…inks

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 microsoft#148's job-queue
additions to al-performance-review.md - both sets of worklist tokens
and cues are retained.
Michael Dieringer (MichaelDieringer) added a commit to Curabis/BCQuality that referenced this pull request Sep 21, 2026
- 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
microsoft#148 and microsoft#153; all sides' worklist tokens/cues retained.
Jesper Schulz-Wedde (JesperSchulz) pushed a commit that referenced this pull request Sep 29, 2026
…aking-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 <noreply@anthropic.com>

* Fix dimension-management-wiring.md: ValidateShortcutDimCode and CreateDim
do not exist on the current DimensionManagement codeunit

Verified against microsoft/BCApps: the real master-table validation
procedure is ValidateDimValueCode (or ValidateShortcutDimValues when a
DimSetID is also needed), and the real document-side inheritance
procedure is GetDefaultDimID, not CreateDim. Caught from Jesper
Schulz-Wedde's review thread, which had been partially hidden by
GitHub's comment folding.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Address second round of Jesper Schulz-Wedde's review on PR #156

- dimension-management-wiring.md/.good.al: split into the two distinct
  models the article was conflating - master data (Default Dimension
  records via ValidateDimValueCode/SaveDefaultDim) vs. transactional/
  document data (a single Dimension Set ID assembled via AddDimSource +
  GetDefaultDimID, verified against BCApps' ExchRateAdjmtProcess.Codeunit.al).
  Added a compiling document-table example alongside the existing master
  table one.
- Deleted api-page-flowfields-must-be-calcfields (.md/.good.al/.bad.al):
  Microsoft's own FlowFields documentation states a FlowField used as a
  control's direct source expression is automatically calculated on any
  page - no API-page exception is documented, and none could be
  reproduced.
- prefer-email-module.bad.al/.md: Codeunit Mail has no Send/GetErrorDesc
  members; fixed to the real current 7-argument CreateMessage signature,
  and corrected the claim that the legacy path "still runs" - its base
  implementation no longer sends anything, only raises integration events.
- check-post-line-batch-pattern.md/.good.al: reframed from a universal
  invariant to the standard shape, naming the real Gen./Item/CA/Res./Job/
  Insurance/Mfg. Item/FA Jnl.-Check Line/-Post Line/-Post Batch codeunits
  it's based on. Added the missing Check Line companion codeunit so the
  good fixture is internally complete.
- test-data-must-be-random-and-complete.good.al: removed leftover
  "collision-free" wording contradicting the already-corrected article text.
- fixed-choice-set-must-use-enum-not-integer.md: removed the reintroduced
  state-count heuristic ("the line is the state count"), aligned with
  binary-choice-must-be-boolean.md's semantics-based distinction.
- namespace-must-be-verified-from-source.md: removed the false claim that
  the compiler and AL Language Server use different namespace-resolution
  rules.
- intrinsic-al-functions-must-use-modern-casing.md: removed the unverified
  claim that PascalCase is the VS Code formatter's default output.

Worklist completeness: added cues for the 8 rules in data-modeling,
testing, performance, and web-services that had none (Jesper's explicit
ask), plus the same gap in all 7 style rules from this PR (not explicitly
named this round, but the identical systemic issue) - 15 cues total across
al-data-modeling-review.md, al-testing-review.md, al-performance-review.md,
al-web-services-review.md, and al-style-review.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Fix remaining correctness issues from Jesper's 2026-09-15 re-review

- dimension-management-wiring: SaveDefaultDim's third argument is the
  shortcut dimension number (1-8), not the field's AL field ID; the
  fixture passed FieldNo(...) = 10. GetDefaultDimID's InheritFromDimSetID
  must be 0 when recomputing after the linking record changes, not the
  document's existing Dimension Set ID (which would retain the previous
  customer's leftover dimensions). Verified against
  DimensionManagement.Codeunit.al and BankDepositHeader.Table.al in the
  BCApps reference clone.
- check-post-line-batch-pattern: "Post Line writes exactly one line to
  the ledger" overclaimed - Gen. Jnl.-Post Line alone calls InsertGLEntry
  from a dozen call sites (balancing entry, VAT, currency rounding,
  deferrals) and can write several G/L Entries per journal line.
  Reworded to "posts exactly one journal line" and softened the
  "distinct, non-overlapping responsibilities" absolute.
- namespace-must-be-verified-from-source.bad.al: dropped the "resolves
  in a local build, fails in VS Code" comment (taught an inherent
  compiler/language-server disagreement that isn't real); reframed as
  stale/cached symbols, matching the prose fix already made.
- file-datatype-saas.good.al: replaced the deprecated 5-argument
  UploadIntoStream overload with the current 2-argument one, and
  actually staged through TempBlob as the article's own Best Practice
  instructs (the declared TempBlob variable was previously unused).
- test-data-must-be-random-and-complete: no longer treats a
  short-but-valid value as defective merely for being "underfilled" -
  AL field lengths are maxima, not minimums. Scoped to missing values
  or a scenario with an explicit length/format requirement (e.g. a
  truncation test). Updated the al-testing-review.md routing cue to
  match.
- stored-derived-fields-must-not-be-exposed-directly: stopped mandating
  source-field exposure as part of the core pattern: the good fixture
  exposed only one of the derived value's two inputs (Hours Used, not
  Budgeted Hours), making the claimed "so the consumer can verify it"
  impossible. Reframed as an optional, all-or-nothing addition and
  fixed the fixture to expose both inputs.

Rebased onto upstream/main to resolve conflicts in
al-breaking-changes-review.md, al-data-modeling-review.md,
al-performance-review.md, and al-style-review.md against merged PRs
#148 and #153; all sides' worklist tokens/cues retained.

* Fix remaining READ-convention sample links across this PR's 18 articles

The same plain-backtick "See sample: \`x.good.al\`." form fixed on
al-methods-limited-during-write-transactions (PR #161) turned up
repo-wide on 15 more of this PR's articles - Knowledge-Retrieval.ps1
requires the markdown-link form to associate a sample with its
article. All 16 fixed; the four local validators (frontmatter,
knowledge-index, knowledge-retrieval, review-fixtures, skill-index)
pass.

* Fix two merge-critical correctness issues from Jesper's 2026-09-22 review

- api-page-key-fields-must-be-editable-on-insert.good.al and
  stored-derived-fields-must-not-be-exposed-directly.good.al: both were
  writable API pages missing DelayedInsert = true, contradicting this
  repo's own api-page-delayedinsert-true rule - the canonical "good"
  samples were teaching code BCQuality itself flags.
- dimension-management-wiring.good.al: UpdateDimensionSetID exited
  early when Customer.Get failed, leaving the previous customer's
  shortcut dimension and Dimension Set ID in place - the same staleness
  bug the InheritFromDimSetID = 0 fix (from the prior review round) was
  meant to prevent, just triggered by a failed lookup instead of a
  successful one. Now clears the shortcut field and recomputes with an
  empty source list on a failed lookup too, so GetDefaultDimID
  correctly returns an empty Dimension Set ID instead of never running.

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Jesper Schulz-Wedde (JesperSchulz) pushed a commit that referenced this pull request Sep 29, 2026
…#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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>
Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants