Add Job Queue reliability and scheduling guidance

[Stefano Demiliani (demiliani)]

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

[Jesper Schulz-Wedde (JesperSchulz)]

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.

[Jesper Schulz-Wedde (JesperSchulz)]

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.