Skip to content
AntFabric Corev1.0.0local

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.

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: pinned keeps running executions on the code they started with; autoUpgrade moves 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-workflow to the plugin’s package.json.
workers/workflows.ts
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-heavy by themselves when a plugin has heavy work.
  • Reference: af.example.greet-many.v1 in plugins/example/workers/workflows.ts.
workers/activities.ts
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'.

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.

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
});
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.