Activities and the allow-list
An activity is a unit of work with side effects that a durable function asks the engine to carry out: call an API, write to a data table, send a message. The function waits for the result; the engine runs the activity, retries it when it fails, and records the outcome in the history so a replay never runs it twice.
Running a node as an activity
ctx.run runs one operation of a FluidGrids node through the same path a canvas node uses, with the same sandbox, connections and log scrubbing:
const charge = await ctx.run(n.stripe.createCharge, {
args: { amount: order.amountCents, customer: order.customerId, idempotencyKey: order.id },
connection: 'stripe-live',
retry: { maxRetries: 3, retryDelay: 2000, backoffMultiplier: 2 },
startToCloseTimeout: '30s',
summary: 'Charge the customer',
});
| Option | Meaning |
|---|---|
args | The operation's arguments, typed from the node's fields. They are passed as values; expressions such as {{ $json.x }} are not evaluated in activity arguments |
connection | The connection to use, by name |
retry | maxRetries, retryDelay, backoffMultiplier, maxDelay, retryOnErrorTypes, nonRetryableErrorTypes |
startToCloseTimeout | How long one attempt may take. Default 5 minutes when no schedule-to-close timeout is set |
scheduleToCloseTimeout | How long the activity may take across all attempts |
heartbeatTimeout | How long an attempt may go without a heartbeat before it is retried |
summary | A label for the activity in the History tab |
Without a retry option, an activity is retried with a delay that starts at 1 second and doubles up to 100 seconds, until it succeeds, fails with a non-retryable error, or reaches its schedule-to-close timeout. Canvas nodes keep their own default of no retry.
ctx.info.activityId is the same across attempts. ctx.run passes it to operations that accept an idempotency key, so a retried call does not charge or send twice.
Which nodes can run as activities
| Node | As an activity? |
|---|---|
| Store and registry nodes (integrations, custom nodes) | Yes |
| HTTP Request, Data Table, Set, Code | Yes |
| Send and Wait for Response | Yes, with run control: the activity waits until the person answers (see Run control) |
| Triggers, IF, Switch, Loop, Merge, Wait, Subworkflow, Code workflow, Wait for Signal, Respond to Webhook and the other built-in nodes | No |
Control flow belongs in the function itself: use if, loops, ctx.sleep and ctx.signalReceived instead of the routing and waiting nodes. A node type that is not allowed is refused when you push or validate, and again when a run tries to schedule it.
Other activities that would wait for a person (a human request or a tool approval inside a node) fail in durable runs with a non-retryable ApprovalRequiredInDurableRun error. Use Send and Wait for Response as an activity, or a signal, for approvals instead.
Failures
When an activity has used up its retries, ctx.run throws an ActivityFailure whose cause is the last error. Catch it to compensate, or let it fail the run:
const saga = ctx.saga();
try {
const reservation = await ctx.run(n.warehouse.reserve, { args: { items } });
saga.add(() => ctx.run(n.warehouse.release, { args: { id: reservation.id } }));
await ctx.run(n.stripe.createCharge, { args: { amount } });
} catch (err) {
await saga.compensate();
throw err;
}
User activities on your own workers
Code that needs your own network, files or libraries runs as a user activity on a self-hosted worker. You declare the activity in the workflow code and implement it in the worker:
const charge = declareActivity<{ amount: number }, { id: string }>('billing.charge', {
taskQueue: 'payments',
});
// in the workflow
const result = await ctx.activity(charge, { args: { amount: 10 }, startToCloseTimeout: '30s' });
The worker connects outbound to FluidGrids with a worker token, takes work from its task queue, and runs the activity with heartbeats, cancellation and the connections you allow it. A user activity cannot run on the managed queue: fluidgrids push refuses a workflow whose user activity would end up there. ctx.localActivity(declaration, options) runs a short user activity inside the workflow task on the same worker instead.
Next steps
- Timers
- Self-hosted workers
- Run control: pause, reset and complete activities
- Standalone activities: run one activity without writing a workflow