Start runs from your code

Most runs start from your own code, at the moment there’s work to do: a user signs up, an order comes in, someone clicks a button. Your code calls run, Nelkap records the run, and your code moves on without waiting for the workflow.

Start a run

Call run with the workflow function and its payload:

const { runId } = await nelkap.run(
  onboardUser,
  'user_42',
);

You pass the function itself rather than its name. TypeScript then checks the payload against the workflow’s argument, and the SDK finds the name the function was registered under. The function must be one you passed to registerWorkflows. run returns once Nelkap has recorded the run, with its ID. It doesn’t wait for the workflow to finish, so you can call it from a request handler and answer right away. If Nelkap turns the run down, for example because the workflow isn’t registered, run throws a NelkapError that names the reason.

The payload

The payload is what the run works on. Nelkap passes it to your workflow as its only argument, on every call of the run:

export async function shipOrder(order: {
  id: string;
  address: string;
}) {
  await nelkap.step.run('label', () =>
    createShippingLabel(order.address),
  );
}

await nelkap.run(shipOrder, {
  id: 'ord_42',
  address: '1 Main St, Springfield',
});

It can be any JSON value: a string, a number, an object, or a list.
It’s sent as JSON, so a Date reaches your workflow as a string.
It shows on the run’s page, so you can see what each run worked on.
Its size is limited by your plan. See Limits.

A workflow that needs no input takes no payload: nelkap.run(sendDigest). Keep the payload small, like an ID your workflow uses to load the rest. The run then works on the latest data, and every call carries less.

When the run starts

A new run is pending until its turn comes. Nelkap starts pending runs every minute, so a run starts within a minute of being created, unless it waits for room under a concurrency limit.

Start a run from a workflow

A workflow can start runs of other workflows, for example one for each item of a list. Call run inside a step, so the new run starts once, even when the first run picks up again later:

await nelkap.step.run('invoice run', () =>
  nelkap.run(sendInvoice, orderId),
);

The two runs are independent: the first goes on without waiting for the second. See Split a job across runs.

Other ways to start a run

Your code knows exactly which workflow to start. When it doesn’t, or when the work comes from somewhere else, start runs another way:

How	When to use it
Events	Something happened, and any number of workflows may want to react.
Schedules	The work repeats at fixed times, like a weekly report.
Webhooks	Another service, like a payment provider, tells you something happened.
Replay	You want to run a past run again, for example after fixing a bug.

A workflow can use several at once, and every workflow can be started from your code, whatever else starts it.

How each run started

Each run shows its trigger, so you can tell how it started:

Trigger	Started by
API	`run`
Event	An event emitted with `emit`, or received by a webhook.
Cron	A schedule.
Manual	A replay.

Get started

Concepts

Frameworks

Triggers

Write workflows

Deploy

Monitor

Manage

Help

Start runs from your code

Start a run

The payload

Tags

When the run starts

Start a run from a workflow

Other ways to start a run

How each run started

​Start a run

​The payload

​Tags

​When the run starts

​Start a run from a workflow

​Other ways to start a run

​How each run started

Start a run

The payload

Tags

When the run starts

Start a run from a workflow

Other ways to start a run

How each run started