Frequently Asked Questions
Answers to common Elsa Workflows questions about designing, starting, waiting, versioning, and operating workflows.
This page is a route into the documentation, not a replacement for the task-specific guides. The answers describe Elsa 3.8.0 behavior; follow the linked guide when you need configuration or a complete example.
Designing workflows
What is the difference between a workflow definition and a workflow instance?
A workflow definition is the versioned plan: its activities, connections, inputs, outputs, and triggers. A workflow instance is one execution of a definition, with its own state, variables, bookmarks, journal, and status.
Use the definition when you are designing or publishing behavior. Use the instance when you are investigating or changing one execution. Start with Core Concepts, then see Workflow Definition Version Lifecycle for drafts, published versions, and Studio history.
Should I use a trigger or a blocking activity?
Use a trigger when an external event should start a new workflow instance, such as an HTTP request, timer, or message. Use a blocking activity when an already-running instance must wait for a callback, approval, signal, or other stimulus before continuing.
For example, a timer trigger can start a new instance every time its schedule fires. An inline Delay or a custom bookmark pauses the current instance. See Using a Trigger and Long-Running Workflows.
Why does my workflow show Running while it is waiting?
In Elsa, Running also covers an instance that is waiting for external stimulus. A blocking activity creates a bookmark; creating a bookmark causes the workflow to suspend after pending activities have completed, and the bookmark records how the instance can be resumed.
Do not treat Running alone as proof that the next activity is executing. Open the instance journal and bookmark information to distinguish active work from durable waiting. See Workflow State and Journal and Bookmark Resume Tokens.
Starting and versioning
What is the quickest way to run a workflow?
Choose the entry point that matches the caller:
Elsa Studio: a designer or domain specialist can select a definition and use its run/execute action.
POST /elsa/api/workflow-definitions/{definitionId}/execute: an HTTP caller needs a result from a bounded workflow interaction.POST /elsa/api/workflow-definitions/{definitionId}/dispatch: an integration hands work to the runtime and continues; the response includes an instance ID for later observation.A trigger: a business event should start instances automatically from matching published definitions.
See Running Workflows for the API, Studio, and library options, and Bulk Dispatch Workflows when one caller should start one instance per item.
Why does the API run an older version than the one I see in Studio?
The 3.8.0 execute and dispatch endpoints use the published version by default. Saving a draft in Studio does not make it the runtime version. Publish the version you intend to run, or request a different version explicitly when your integration is designed to do so.
Publishing a new version retracts the previous published version for that definition. A running instance is different: the runtime resolves its graph from the instance's stored definition-version ID, so publishing a new version does not silently rewrite an instance that is already running.
See Workflow Definition Version Lifecycle and Loading Workflows from JSON.
Why does a trigger work in a draft but not in production?
Only published workflow definitions contribute triggers to the runtime trigger index. A draft can be visible in Studio and still be absent from the trigger index. Publish the definition, confirm that the relevant trigger module is registered, and verify the endpoint or message-broker configuration for the host.
For HTTP workflows, also check the endpoint's authentication and permission configuration. See HTTP Workflows, HTTP Endpoint Security, and Using a Trigger.
What is the difference between execute and dispatch?
Both select a workflow definition and start an instance, but they have different request lifecycles:
executestarts through the workflow starter and keeps the request involved long enough to return the resulting workflow state or fault when the workflow completes in that request.dispatchsends a background command to the runtime and returns after the dispatch is accepted. Use the instance ID to observe the result later.
Use execute for a bounded request/response interaction. Use dispatch for long-running, fire-and-forget, or integration work where the caller should not wait for completion. See Bulk Dispatch Workflows for the related fan-out case.
Waiting, resuming, and diagnosing
How do I resume a waiting workflow?
Resume the bookmark created by the waiting activity. Elsa exposes GET /bookmarks/resume and POST /bookmarks/resume; both require a valid bookmark resume token, and POST can carry input in the request body. The endpoint accepts an async option when the resume should be queued.
Treat the token as a bearer credential. The release endpoint is intentionally anonymous because the token authorizes the resume; protect token generation, transport, logging, and any public entry point around it. See Bookmark Resume Tokens and Long-Running Workflows.
My workflow failed or appears stuck. What should I inspect first?
Use this order:
Open the workflow instance and check its status, sub-status, and incidents.
Read the journal to find the last transition and the activity that was executing.
Inspect activity execution records and host logs for the exception, external call, or missing configuration.
If the instance is waiting, inspect its bookmarks and the stimulus or token used to resume it.
In a multi-node deployment, check readiness, persistence, distributed coordination, and worker/broker health before retrying side effects.
Start with Investigate a Workflow Instance, then use Monitoring & Observability, Incidents, and the Troubleshooting Guide.
How should I test a workflow before deploying it?
Test the smallest boundary that can prove the behavior: use an activity fixture for one custom activity, a workflow fixture for routing and outcomes, and an integration host for persistence, authentication, HTTP, or broker behavior. Then inspect a real instance through Studio or the runtime APIs when the failure depends on deployment configuration. See Testing & Debugging Workflows.
Further help
If the question is about an official release, source behavior, or a reproducible bug, include the Elsa package versions, host shape, workflow definition or minimal reproduction, and relevant logs/journal entries when asking for help. Use Community & Resources to choose the appropriate channel.
Release-source checks
The runtime-specific statements on this page were checked against the 3.8.0 release source:
Last updated