Background work
Anything that outlives a request — a reminder every minute, an import, a multi-step process — runs on Temporal. A plugin declares its workflows; core runs them on worker pools with the plugin’s own services.
Declare
Section titled “Declare”workers: workflows: ./workers/workflows activities: ./workers/activities registrations: - { name: af.sales.reminders.v1, export: reminders, versioning: autoUpgrade, } schedules: - { id: reminders, workflow: af.sales.reminders.v1, cron: '* * * * *' }versioning:pinnedkeeps running executions on the code they started with;autoUpgrademoves them to new code (fine for short or stateless workflows).- Schedules are created when the workers start, as
af/<plugin id>/<schedule id>, in UTC, never overlapping. - Add
@antfabric/sdk-workflowto the plugin’spackage.json.
Workflows: deterministic orchestration
Section titled “Workflows: deterministic orchestration”import { pluginActivities } from '@antfabric/sdk-workflow';import type activities from './activities';
const acts = pluginActivities<typeof activities>('af.sales', { startToCloseTimeout: '50 seconds', retry: { maximumAttempts: 3 },});
export async function reminders() { const untouched = await acts.followUpUntouched(); const followUps = await acts.remindFollowUps(); return { untouched, followUps };}Workflow code runs in Temporal’s sandbox: no database, no network, no clock — only activity calls,
sleep and the helpers from @antfabric/sdk-workflow. The bundler fails on a disallowed import.
Child workflows, long jobs and heavy steps
Section titled “Child workflows, long jobs and heavy steps”import { continueAsNew, pluginActivities, pluginWorkflows } from '@antfabric/sdk-workflow';
const children = pluginWorkflows('af.example');// One child per item: its own history, retries and status. Only your own registrations.await children.executeChild<typeof greet>('af.example.greet.v1', { key: `${key}.${i}`, args: [name] });
// Long jobs in pages: a fresh history, same workflow id.await continueAsNew<typeof greetMany>({ names, done: done + PAGE });
// CPU-bound steps on plugin-heavy (plugin.yaml: workers.heavyActivities: true).const heavy = pluginActivities<typeof activities>('af.example', { …, queue: 'heavy' });- A child’s id is
<instance>/<plugin>/<workflow>/<key>, like a start, and its activities act for the user who started the root workflow. - The workers start
plugin-heavyby themselves when a plugin has heavy work. - Reference:
af.example.greet-many.v1inplugins/example/workers/workflows.ts.
Activities: the I/O
Section titled “Activities: the I/O”export default defineActivities((sdk) => ({ async remindFollowUps(): Promise<number> { const due = await sdk.db!.transaction(/* select due, not yet reminded */); for (const f of due) await sdk.notifications.send({ type: 'af.sales.follow-up-due', recipients: [f.owner_id], context: { followUpId: f.id }, idempotencyKey: `follow-up-${f.id}-${seconds(f.due_at)}`, }); // then mark them reminded return due.length; },}));Each attempt gets the plugin’s own SDK: db (its role), config, secrets, files, audit,
events, notifications, workflows, contracts (other plugins’ contracts, acting for the person
who started the workflow), metrics, tracer, heartbeat, cancelled, log, and context
(workflow id, attempt, the person who started it).
Your plugin’s module also boots in the workers process, so contracts work here. Start listeners
only where they belong: PluginContext.process is 'api' or 'workers'.
Periodic upkeep without a workflow
Section titled “Periodic upkeep without a workflow”For small, regular upkeep (expire drafts, refresh a cache table) use PluginJobs instead of a
timer. It runs once per period across every replica, wherever your module boots:
constructor(private readonly jobs: PluginJobs) {}
onModuleInit() { this.jobs.every('expired-drafts', 10 * 60_000, () => this.drafts.removeExpired(500));}Keep a run idempotent and short (batches). Work that needs retries, history or heavy activities is
a schedule in plugin.yaml instead.
Make activities safe to repeat. Send first, mark afterwards, with an idempotency key — a crash in between sends again and the key makes that a no-op.
Starting a workflow from a request
Section titled “Starting a workflow from a request”await this.workflows.start({ workflow: 'af.notes.archive.v1', key: `archive-${noteId}`, // the same key never starts twice input: { noteId }, transaction: tx, // started only if the change commits});Pools and the local UI
Section titled “Pools and the local UI”| Pool | Runs |
|---|---|
plugin-default |
Plugin workflows and activities |
core-notifications |
Notification delivery |
plugin-heavy |
Long or heavy plugin work (started when a plugin needs it) |
pnpm dev runs the workers next to the API. The Temporal UI is at http://localhost:8233. In
development the workers keep the build id dev, so editing workflow code never strands running
pinned workflows; an incompatible change shows up as a non-determinism error in the UI.