19. FAQ

Q: Does the pipeline automatically give my job tenant scoping, a distributed lock, and notification delivery just by routing through IBackgroundJobExecutionPipeline? A: No. This is the single most important misconception to avoid — see AP-01. The shipped pipeline only does a cancellation check, invokes your delegate, and classifies-and-rethrows on exception. Tenant context and distributed locking are real, working, separately-injectable services you must compose explicitly around your executor call if your job needs them. See §4 — Runtime Pipeline.

Q: My job needs to prevent two workers from processing the same database row twice. Should I use IBackgroundJobDistributedLock? A: No — this is explicitly the wrong layer. Use an atomic, per-row database claim (WHERE Status = Pending AND WorkerToken IS NULL) owned by whichever domain framework owns that row, exactly like the Notification Framework's ClaimAsync for retry entries and campaign executions. A job-level distributed lock would serialize your entire batch, not just the contested rows. See §9.4.

Q: Should I call IBackgroundJobScheduler to register my new recurring job? A: You can — it's fully functional — but be aware that none of the six currently-migrated production jobs actually use it. All six register directly via raw Hangfire.RecurringJob.AddOrUpdate<TPipelineJob>(...) in ApplicationBuilderExtensions.cs, following the established migration recipe. Using IBackgroundJobScheduler instead is architecturally sound but would be a deliberate departure from current convention — confirm with the team before doing so for consistency's sake. See §10 — Scheduler.

Q: How do I add a new job to the pipeline? A: Follow the exact recipe in §14.4 and the worked example in §12.7 — three new ERP-side files (job adapter, Hangfire bridge, application interface), never touching the 5 framework packages.

Q: Can I migrate Product Import, Tenant Provisioning, or DatabaseInitializer onto this pipeline the same way? A: Not without a new, separately approved initiative — these three are explicitly deferred, not permanently excluded, but the change policy requires fresh approval for them specifically, regardless of how similar the mechanical steps would be to the six already-completed migrations. See §14.5.

Q: Can I give my job's own [AutomaticRetry(...)] policy instead of relying on Hangfire's default? A: Yes — nothing in the framework prevents this, and doing so is arguably overdue (see AP-04, a documented, open gap). Just be aware that no existing job does this today, so there's no established convention to follow yet — you'd be setting the precedent.

Q: Is IBackgroundJobNotificationAdapter a working way to send a notification when my job completes? A: No — its registered implementation, BackgroundJobNotificationBoundaryAdapter, is a permanent no-op stub (AP-03). If your job needs to notify someone on completion, call the Notification Framework directly from your own business worker, exactly as all six migrated jobs already do.

Q: Does this framework replace the Notification Framework's dispatch logic? A: No, and it never will — there is no package dependency in either direction. This framework only owns scheduling and executing a job; the Notification Framework owns everything about what a notification is and how it's delivered. See §1.7.

Q: Can a second ERP host (not Shumoul.Saas.Api) consume this framework today? A: Architecturally, yes — nothing in the framework references any ERP-specific type, and the integration mechanics are documented in §13.2. Practically, this has not yet been exercised by a real second host — reusability is proven by design, not yet by a second production consumer.

Q: Is this framework's public API allowed to change? A: Only in ways that respect the LTS/semver policy — see §1.6 and §15.6. Bug fixes and additive changes are ordinary maintenance; anything touching a Stable type's signature, namespace, or observable behavior requires a MAJOR version bump, an ADR, and a migration guide.

Q: Where do I find the actual list of what's frozen vs. what can still change? A: Chapter 15 — Architecture Decisions § What "Closed" Permits is the authoritative, binding list.