Add Jobs, Notifications, and Scheduled Work
This chapter makes the operator side of your product honest.
The previous integration chapter showed request-time payment handoff and webhook reconciliation. This chapter shows the next step: how Shoppr tells operators that some work is still waiting on a job, provider callback, or export queue instead of pretending the request is the whole workflow.
Purpose
Use this chapter to understand three different seams:
- request-time customer behavior
- background or deferred operational work
- operator-facing pages that explain what the system is waiting on
Shoppr already has those seams in the checked-in app. You do not need to invent a fake
jobs.json file or a custom scheduler demo. The real files to read are the Shoppr development
runtime config, the payment operations template, the search ops template, the reports template,
the dedicated jobs template, and the shared admin dashboard template.
Start With The Runtime Config
The checked-in development config already turns on the queue backend you need locally:
[jobs]
backend = "redis"
This block lives in the Shoppr development runtime config file.
Why this file exists:
app.tomldescribes the product and enabled modulesplatform.dev.tomldescribes how the local runtime actually runs that product- the
[jobs]section is where local deferred work infrastructure is selected
What this section does:
- tells the runtime to use Redis-backed job execution in local development
- keeps background work out of the request path
- makes later operator pages truthful when they say a task is queued or waiting on follow-up
Exact next effect:
- when you run the local stack, the runtime has a real queue backend available
- payment follow-up, report-export readiness, and similar operator guidance now points at an actual subsystem, not a pretend browser-only state machine
Read The Payment Operations Page As A Jobs Surface
The clearest checked-in operator workflow is the payment queue in the Shoppr payment operations template.
The most important part of the file is not the table markup by itself. It is what the table is teaching the operator:
<section class="admin-panel">
<p class="admin-panel__eyebrow">Queue summary</p>
<div class="admin-card-grid">
<article class="admin-card">
<h2>Awaiting confirmation</h2>
<p>
<strong coil:text="${payment_operation_stats.awaiting_confirmation}">0</strong>
rows still need signed provider confirmation before the order can move forward.
</p>
</article>
<article class="admin-card">
<h2>Refund follow-up</h2>
<p>
<strong coil:text="${payment_operation_stats.refund_follow_up}">0</strong>
rows already have refund history and still need reconciliation or customer messaging.
</p>
</article>
</div>
</section>
The queue rows make the deferred-work seam explicit:
<td>
<strong coil:text="${payment.webhook_status_label}">
Awaiting signed Stripe webhook
</strong>
<p coil:text="${payment.integration_note}">
Payment confirmation is pending. The order will move forward after the provider callback arrives.
</p>
</td>
<td>
<p coil:text="${payment.next_job_label}">
Hold customer messaging until the payment-provider webhook confirms capture.
</p>
<p coil:if="${payment.has_refund_history}" coil:text="${payment.refund_history_label}">
1 refund event recorded
</p>
</td>
What the important sections do:
payment_operation_stats.*gives the operator a queue-level summarypayment.webhook_status_labelexplains the current provider statepayment.integration_noteexplains why the row is still waitingpayment.next_job_labeltells the operator what downstream work should happen next
Exact next effect:
- the operator can see that payment capture, refund reconciliation, and customer messaging are different stages
- the app stops implying that checkout is complete just because the HTTP request returned
Use Search And Reports As The Other Two Operator Lanes
Shoppr also exposes two ops pages that keep background work inside the shared admin shell: the search operations template and the reports template.
The search page teaches operators when not to reindex blindly:
<section class="admin-panel">
<p class="admin-panel__eyebrow">Search health</p>
<div class="admin-card-grid">
<article class="admin-card">
<h2>Watching</h2>
<p>
<strong coil:text="${search_stats.watching}">0</strong>
indexes are waiting on publication or rebuild follow-up.
</p>
</article>
</div>
</section>
<td coil:text="${row.trigger_summary}">Rebuilt by publication events.</td>
<td coil:text="${row.action_label}">
Rebuild only if browse drift is confirmed.
</td>
The reports page teaches operators that exports are deliberate queued work, not a hidden script:
<section class="admin-panel">
<p class="admin-panel__eyebrow">Export summary</p>
<div class="admin-card-grid">
<article class="admin-card">
<h2>Queued follow-up</h2>
<p>
<strong coil:text="${report_stats.queued}">0</strong>
definitions have active operational reasons to export now.
</p>
</article>
</div>
</section>
<td coil:text="${row.job_state_label}">Ready to export</td>
<td coil:text="${row.action_label}">
Queue export when operators need an external handoff.
</td>
What these files are doing:
search.htmlexposes reindex and drift-review decisions as operator workreports.htmlexposes export readiness and delivery mode as operator work- both pages keep background operations inside the same admin shell as orders, content, memberships, and events
Exact next effect:
- operators have one place to reason about payment follow-up, reindex pressure, and report exports
- jobs and scheduled work stop feeling like hidden infrastructure and become visible product behavior
Keep The Operator Entry Point Honest
The shared admin dashboard template is the page that ties those workflows together.
This is the part that matters:
<article class="admin-card" data-admin-filter-item="">
<h2>Monitor payment handoff</h2>
<a class="button" href="/admin/payments" coil:attr="href=${links.admin_payments}">
Open payments
</a>
</article>
<article class="admin-card" data-admin-filter-item="">
<h2>Inspect search and reports</h2>
<div class="admin-copy-row">
<a class="button" href="/admin/search" coil:attr="href=${links.admin_search}">
Open search
</a>
<a class="button button--secondary" href="/admin/reports" coil:attr="href=${links.admin_reports}">
Open reports
</a>
</div>
</article>
Why this file exists:
- it is the operator control room
- it tells the reader which pages are part of the daily workflow
- it keeps ops pages discoverable from the same shell as commerce and CMS work
Exact next effect:
- a new operator does not need to know internal route names first
- payment follow-up, search review, and report export appear as normal admin tasks
Read The Dedicated Jobs Page
Shoppr also has a dedicated jobs page in the shared admin shell.
apps/shoppr/templates/admin/jobs.html
<section class="admin-panel">
<p class="admin-panel__eyebrow">Queue summary</p>
<div class="admin-card-grid">
<article class="admin-card">
<h2>Total jobs</h2>
<p><strong coil:text="${job_stats.total}">0</strong> runtime jobs are registered.</p>
</article>
<article class="admin-card">
<h2>Event reactions</h2>
<p><strong coil:text="${job_stats.event_reactions}">0</strong> domain-event subscriptions currently route follow-up work into the jobs runtime.</p>
</article>
</div>
</section>
What this file does:
- shows the jobs runtime as operator-visible product state
- distinguishes direct operator jobs from event-driven follow-up work
- keeps queue and trigger visibility inside the shared admin shell
What Coil Does And Does Not Do Automatically
Coil gives you:
- the runtime job backend
- module-level job contracts
- operator routes that can explain queued work
- render-model data that can surface queue state in templates
Coil does not automatically decide:
- when your product should send customer-facing follow-up messages
- when a reindex is actually warranted
- when a report export should happen for support, audit, or launch work
- what operator guidance text belongs on those pages
That last step is customer-app work. Shoppr does it in the templates you just read.
Runnable Checkpoint
Run the focused server tests that already exercise these operator surfaces:
cargo test -p coil-runtime server_host_renders_checked_in_harbor_shop_payment_operations_surface -- --nocapture
cargo test -p coil-runtime server_host_supports_checked_in_harbor_shop_order_detail_and_refund_flow -- --nocapture
cargo test -p coil-runtime server_host_renders_checked_in_harbor_shop_admin_surfaces -- --nocapture
What each test proves:
server_host_renders_checked_in_harbor_shop_payment_operations_surfaceproves the payment queue renders provider state and follow-up guidanceserver_host_supports_checked_in_harbor_shop_order_detail_and_refund_flowproves refund-related operator follow-up is part of the real order workflowserver_host_renders_checked_in_harbor_shop_admin_surfacesproves the shared admin shell exposes the Shoppr operator routes
Exact next effect:
- after this chapter, your product has a real operator story for deferred work
- the next chapter can explain observability on top of those real admin and queue surfaces instead of introducing generic monitoring concepts in isolation