Skip to main content

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',
});
OptionMeaning
argsThe 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
connectionThe connection to use, by name
retrymaxRetries, retryDelay, backoffMultiplier, maxDelay, retryOnErrorTypes, nonRetryableErrorTypes
startToCloseTimeoutHow long one attempt may take. Default 5 minutes when no schedule-to-close timeout is set
scheduleToCloseTimeoutHow long the activity may take across all attempts
heartbeatTimeoutHow long an attempt may go without a heartbeat before it is retried
summaryA 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​

NodeAs an activity?
Store and registry nodes (integrations, custom nodes)Yes
HTTP Request, Data Table, Set, CodeYes
Send and Wait for ResponseYes, 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 nodesNo

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​