foliot docs

Guides / Starting runs and sending signals

Starting runs and sending signals

Once a workflow is registered, your service can start runs and send signals from anywhere in your app. Two keys you provide make this safe:

Key Who sets it What it answers Where you use it
businessKey Your service Which business entity is this run about? Such as a user or account id. When starting a run and later to find that run (for example to send it a signal).
idempotencyKey Your service Is this the same request? One value per start or signal to recognize a repeat. When starting a run and sending a signal.

Keys in an example

Say the onboarding workflow from the Quickstart also waits at a step named email-verified until the new user confirms their email address. Here is what happens for user User123:

What happens businessKey idempotencyKey Result
User123 signs up and your service starts a run User123 onboarding:signup-9001 Foliot starts a new run.
Your service times out and resends the same request User123 onboarding:signup-9001 Foliot returns the run it already started. No second run is created.
User123 clicks the link in the verification email and your service sends the email-verified signal User123 email-verified:link-31 Foliot finds User123’s onboarding run by its businessKey and passes it the signal. The run moves on to the next step.
User123 clicks the link again, and your service sends the same signal again User123 email-verified:link-31 Foliot ignores the repeat. The run moves on only once.
A year later, User123 is onboarded again after a long break, and your service starts a run User123 onboarding:signup-9377 Foliot starts a new run, because this is a different request.

The businessKey stays User123 throughout, because every run and signal is about that user. The idempotencyKey should be changed for each new request and be repeated only when the same request is resent.

For each task your handler receives, Foliot also provides a stepKey. This is different from the above two keys and is intended to help prevent your handler from doing the same work twice. See Handlers for details.

Start a run

const foliot = new FoliotClient({ baseUrl, token, app: process.env.FOLIOT_APP! });

await foliot.start(onboarding, {
  input: { userId: "User123", email: "ada@example.com" },
  businessKey: "User123",
  idempotencyKey: `onboarding:${signup.id}`,
});

An idempotencyKey must be unique across your app, so begin each one with the workflow’s name. Starting again with a key that was used before returns the existing run instead of starting a new one, so retrying a start is safe.

The SDK’s start also sends the current workflow version defined in your service. If you call the API directly, you should provide the version yourself. Without it, the run will use the default alias which points to the latest registered version, unless you set default to a specific version. Be careful not to pass a version identifier before registering the associated workflow definition. You can learn more about aliases here.

Send a signal

await foliot.signalByBusinessKey(onboarding, "User123", {
  name: "email-verified",
  payload: { verifiedAt: new Date().toISOString() },
  idempotencyKey: `email-verified:${link.id}`,
});

signalByBusinessKey finds the appropriate run using its businessKey, so your service does not need to store Foliot’s run id. Every call still returns it (starting a run returns the run details, including its id; sending a signal returns the runId the signal was sent to) so you can keep it if you like. If several active runs of the workflow share a business key, Foliot refuses the signal with a 409 as it cannot tell which one you are referring to and instead returns their run ids. You can route it to the desired run using foliot.signal(runId, …). If your service does keep the run id, you can use foliot.signal(runId, …) from the start to target that specific run by id.

Use an idempotencyKey that is the same for the same real-world event. When the sender of an event gives it an id, such as a webhook’s event id, that id might be a good choice.

Without the SDK

Ensure your application calls the POST /apps/{appId}/runs and POST /apps/{appId}/signals with the appropriate JSON body. Starting a new run returns a 201 status code, or 200 if the idempotencyKey was used before. Sending a signal returns 200, 404 when no active run has that business key, or 409 when several active runs share it. Repeating a signal that a run already received returns 200 either way.