> For the complete documentation index, see [llms.txt](https://docs.elsaworkflows.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elsaworkflows.io/guides.md).

# Guides

- [V2 to V3 Migration Guide](https://docs.elsaworkflows.io/guides/migration-v2-to-v3.md): Complete migration guide from Elsa Workflows V2 to V3, covering breaking changes, custom activities, workflows, and concepts.
- [Architecture](https://docs.elsaworkflows.io/guides/architecture.md): High-level overview of Elsa Workflows v3 architecture, covering workflow execution flow, core concepts like bookmarks and triggers, workflow runtimes, and multitenancy.
- [Execution Model](https://docs.elsaworkflows.io/guides/architecture/execution-model.md): Release-backed guide to Elsa's execution model in 3.8.0, covering direct execution, dispatched execution, triggers, bookmarks, stimuli, persistence, and recovery.
- [Workflow Dispatcher Architecture](https://docs.elsaworkflows.io/guides/architecture/workflow-dispatcher.md): Deep dive into IWorkflowDispatcher: the core dispatching abstraction for queuing and executing workflows, covering request types, event ordering, and custom dispatcher implementations.
- [Workflow Dispatch Outbox](https://docs.elsaworkflows.io/guides/architecture/workflow-dispatch-outbox.md): Release-backed guidance for configuring, operating, and diagnosing Elsa's transactional outbox for workflow dispatch.
- [Runtime Coordination Storage](https://docs.elsaworkflows.io/guides/architecture/runtime-coordination-storage.md): Configure the key-value and distributed-lock providers that Elsa uses for durable outbox records and multi-node workflow coordination.
- [Standalone and Modular Hosting](https://docs.elsaworkflows.io/guides/architecture/standalone-and-modular-hosting.md): Release-backed configuration matrix for code-first Elsa hosts and the CShells-based modular server in Elsa 3.8.0.
- [Proto.Actor Workflow Runtime](https://docs.elsaworkflows.io/guides/architecture/protoactor-workflow-runtime.md): Configure the Elsa 3.8.0 Proto.Actor workflow runtime for actor-based coordination across hosts, with explicit persistence and cluster boundaries.
- [Onboarding](https://docs.elsaworkflows.io/guides/onboarding.md)
- [Hosting Elsa in an Existing App](https://docs.elsaworkflows.io/guides/onboarding/hosting-elsa-in-existing-app.md): Step-by-step guide to integrating Elsa Workflows into an existing ASP.NET Core application, including persistence setup, common pain points, and troubleshooting.
- [Authentication & Authorization](https://docs.elsaworkflows.io/guides/authentication.md): Choose and configure authentication and authorization for Elsa Server, Elsa Studio, users, and API clients.
- [Elsa Identity](https://docs.elsaworkflows.io/guides/authentication/elsa-identity.md): Configure Elsa's built-in identity system for users, roles, tokens, and API applications.
- [API Keys](https://docs.elsaworkflows.io/guides/authentication/api-keys.md): Authenticate machine-to-machine Elsa API clients with application API keys.
- [Direct OpenID Connect](https://docs.elsaworkflows.io/guides/authentication/direct-openid-connect.md): Release-backed guide to wiring Elsa Server and Elsa Studio to external OpenID Connect identity providers in Elsa 3.8.
- [External Authentication](https://docs.elsaworkflows.io/guides/authentication/external-authentication.md): Install, configure, operate, and migrate to Elsa's brokered External Authentication capability for Elsa Server and Elsa Studio.
- [Installation](https://docs.elsaworkflows.io/guides/authentication/external-authentication/installation.md): Install the Elsa 3.8 preview External Authentication broker, its OpenID Connect adapter, optional secret bridge, and durable persistence providers.
- [Configuration](https://docs.elsaworkflows.io/guides/authentication/external-authentication/configuration.md): Configure Elsa External Authentication connections, clients, callback URLs, secret bindings, identity policy, and permission mapping.
- [Keycloak Walkthrough](https://docs.elsaworkflows.io/guides/authentication/external-authentication/keycloak.md): A concrete end-to-end walkthrough for connecting Keycloak to Elsa External Authentication and signing in from Elsa Studio.
- [Studio Integration](https://docs.elsaworkflows.io/guides/authentication/external-authentication/studio-integration.md): Configure Elsa Studio as an Elsa External Authentication broker client in Elsa 3.8 preview.
- [Administration](https://docs.elsaworkflows.io/guides/authentication/external-authentication/administration.md): Manage Elsa External Authentication connections, identity links, and sessions from Elsa Studio 3.8 preview.
- [Extensibility](https://docs.elsaworkflows.io/guides/authentication/external-authentication/extensibility.md): Extend Elsa External Authentication with custom adapters, policies, matchers, permission grant sources, and Studio connection editors.
- [Production and Security](https://docs.elsaworkflows.io/guides/authentication/external-authentication/production.md): Operate Elsa External Authentication safely in production, including durable state, clustered deployments, migrations, key management, and verification.
- [REST API](https://docs.elsaworkflows.io/guides/authentication/external-authentication/api.md): Endpoint groups, concurrency rules, permissions, and safe automation patterns for the Elsa External Authentication REST API.
- [Migrate from Direct OIDC](https://docs.elsaworkflows.io/guides/authentication/external-authentication/migration-from-direct-oidc.md): Move Elsa Studio from direct OpenID Connect to the Elsa 3.8 preview External Authentication broker, with a staged rollout and rollback plan.
- [Troubleshooting](https://docs.elsaworkflows.io/guides/authentication/external-authentication/troubleshooting.md): Diagnose Elsa Studio External Authentication integration and administration issues in Elsa 3.8 preview.
- [Elsa API Permissions](https://docs.elsaworkflows.io/guides/authentication/permissions.md): Release-backed reference for Elsa API permission claims, Studio capabilities, and least-privilege role templates in Elsa 3.8.0.
- [Custom Authentication](https://docs.elsaworkflows.io/guides/authentication/custom-authentication.md): Integrate a host-provided ASP.NET Core authentication scheme with Elsa API permissions.
- [Disable Authentication in Development](https://docs.elsaworkflows.io/guides/authentication/disable-authentication.md): Disable Elsa API and Studio authorization for isolated development and test environments only.
- [Security & Hardening](https://docs.elsaworkflows.io/guides/security.md): Secure Elsa hosts, workflow ingress, bookmark resume URLs, and Studio deployments with focused production hardening guidance.
- [Production Hardening](https://docs.elsaworkflows.io/guides/security/production-hardening.md): Harden an Elsa and Elsa Studio deployment with explicit browser boundaries, TLS and proxy controls, monitoring, incident diagnostics, and a production checklist.
- [HTTP Endpoint Security](https://docs.elsaworkflows.io/guides/security/http-endpoint-security.md): Secure Elsa HTTP workflow endpoints in 3.8.0 by separating workflow ingress authorization from Elsa API permissions and Studio access.
- [Bookmark Resume Tokens](https://docs.elsaworkflows.io/guides/security/bookmark-resume-tokens.md): Secure Elsa bookmark resume URLs with expirations, single-use bookmarks, revocation procedures, logging, and ingress controls.
- [Secrets Management](https://docs.elsaworkflows.io/guides/security/secrets-management.md): Use Elsa's release-backed Secrets module to store, resolve, rotate, and reference sensitive values from workflows and Elsa Studio.
- [Deployment](https://docs.elsaworkflows.io/guides/deployment.md)
- [Configuration Management](https://docs.elsaworkflows.io/guides/deployment/configuration-management.md): Manage Elsa Server, Elsa Studio, and modular host configuration with appsettings, environment overrides, and source-backed section names for release 3.8.0.
- [Kubernetes Basics](https://docs.elsaworkflows.io/guides/deployment/kubernetes.md): Quick start guide for deploying Elsa Workflows to Kubernetes with PostgreSQL persistence, including configuration, troubleshooting, and production best practices.
- [Kubernetes Deployment](https://docs.elsaworkflows.io/guides/kubernetes-deployment.md): Complete Kubernetes deployment guide for Elsa Workflows including Helm charts, deployment configurations, ingress setup, autoscaling, monitoring, service mesh integration, and production best practice
- [Integration](https://docs.elsaworkflows.io/guides/integration.md)
- [Blazor Dashboard](https://docs.elsaworkflows.io/guides/integration/blazor-dashboard.md): Guide to integrating Elsa Studio with Blazor Server applications, covering hosting patterns, authentication configuration, and troubleshooting common issues.
- [Message Broker Topology](https://docs.elsaworkflows.io/guides/integration/message-broker-topology.md)
- [Clustering](https://docs.elsaworkflows.io/guides/clustering.md): Comprehensive guide to running Elsa Workflows in clustered and distributed production environments, covering architecture patterns, distributed locking, scheduling, and operational best practices.
- [Performance & Scaling](https://docs.elsaworkflows.io/guides/performance.md): Release-backed guidance for measuring and tuning Elsa 3.8.0 throughput without trading away workflow durability or operational visibility by accident.
- [Throughput Tuning](https://docs.elsaworkflows.io/guides/performance/throughput-tuning.md): Small, release-backed Elsa 3.8.0 configuration examples for testing commit, worker, and transactional-outbox tradeoffs under load.
- [API & Client](https://docs.elsaworkflows.io/guides/api-client.md): A release-3.8 reference for Elsa's management API, .NET client interfaces, endpoint permissions, and bookmark-resume callbacks.
- [Workflow-definition labels](https://docs.elsaworkflows.io/guides/workflow-definition-labels.md): Release-backed guide to organizing workflow definitions with labels in Elsa 3.8.0, including Studio setup, API usage, filtering, persistence, and permissions.
- [Persistence](https://docs.elsaworkflows.io/guides/persistence.md): Comprehensive guide to choosing, configuring, and tuning persistence providers for Elsa Workflows v3, covering EF Core, MongoDB, Dapper, and Elasticsearch, along with retention, migrations, and operat
- [SQL Server](https://docs.elsaworkflows.io/guides/persistence/sql-server.md): Complete guide to configuring SQL Server as the persistence provider for Elsa Workflows v3, including setup, configuration, and migration guidance.
- [EF Core Migrations](https://docs.elsaworkflows.io/guides/persistence/ef-migrations.md): Complete guide to working with Entity Framework Core migrations in Elsa Workflows v3, including custom migrations, DbContext management, and versioning strategies.
- [EF Core Setup](https://docs.elsaworkflows.io/guides/persistence/efcore-setup.md): Minimal example to enable Entity Framework Core persistence for Elsa Workflows, including database provider setup and migrations.
- [MongoDB Setup](https://docs.elsaworkflows.io/guides/persistence/mongodb-setup.md): Minimal example to enable MongoDB persistence for Elsa Workflows, including connection configuration and indexing notes.
- [Dapper Setup](https://docs.elsaworkflows.io/guides/persistence/dapper-setup.md): Minimal example to enable Dapper persistence for Elsa Workflows, including connection provider setup and migrations.
- [Elasticsearch Setup](https://docs.elsaworkflows.io/guides/persistence/elasticsearch-setup.md): Configure the Elsa 3.8.0 Elasticsearch extension for workflow-instance and execution-log persistence, with its provider boundaries and production caveats.
- [Indexing Notes](https://docs.elsaworkflows.io/guides/persistence/indexing-notes.md): Recommended database indexes for Elsa Workflows persistence stores to optimize common query patterns.
- [HTTP Workflows](https://docs.elsaworkflows.io/guides/http-workflows.md)
- [Tutorial](https://docs.elsaworkflows.io/guides/http-workflows/tutorial.md)
- [Programmatic](https://docs.elsaworkflows.io/guides/http-workflows/programmatic.md)
- [Designer](https://docs.elsaworkflows.io/guides/http-workflows/designer.md)
- [External Application Interaction](https://docs.elsaworkflows.io/guides/external-application-interaction.md): Configure Elsa 3.8.0 inbound webhook events and outbound webhook sinks, including custom activities, payloads, and endpoint security.
- [Loading Workflows from JSON](https://docs.elsaworkflows.io/guides/loading-workflows-from-json.md)
- [Plugins & Modules](https://docs.elsaworkflows.io/guides/plugins-modules.md): Complete guide to extending Elsa Workflows with custom modules, features, and activities. Learn how to create reusable plugins and distribute them as NuGet packages.
- [Package Manifests for Extensions](https://docs.elsaworkflows.io/guides/plugins-modules/package-manifests.md): Explain the Elsa 3.8 package manifest generated for CShells extension packages, including runtime compatibility, infrastructure requirements, and deploy-time settings.
- [Extensibility](https://docs.elsaworkflows.io/guides/modules-and-plugins.md): Learn how to extend Elsa Workflows v3 with custom modules and plugins. Covers module registration, contributing activities, services, and API endpoints with practical examples.
- [DropIns](https://docs.elsaworkflows.io/guides/modules-and-plugins/dropins.md): Package and discover server-side Elsa extensions from a DropIns directory in Elsa 3.8.0.
- [Testing & Debugging Workflows](https://docs.elsaworkflows.io/guides/testing-debugging.md): Test custom Elsa activities and workflows with the released Elsa testing fixtures, then diagnose real workflow instances with the journal and runtime tools.
- [Weaver and AI Workflow Assistance](https://docs.elsaworkflows.io/guides/ai-workflow-assistance.md): Configure and use Elsa's release-backed AI Host and Weaver Studio workspace for grounded, reviewable workflow assistance.
- [Agents Activities and Studio Administration](https://docs.elsaworkflows.io/guides/ai-agents.md): Configure Elsa Agents, expose agent activities and APIs, and manage agents from Elsa Studio.
- [Running Workflows](https://docs.elsaworkflows.io/guides/running-workflows.md)
- [Using Elsa Studio](https://docs.elsaworkflows.io/guides/running-workflows/using-elsa-studio.md)
- [Altering a Running Workflow Instance](https://docs.elsaworkflows.io/guides/running-workflows/altering-workflow-instances.md): Choose the right Elsa 3.8.0 alteration path, apply changes safely, and monitor the resulting workflow and alteration jobs.
- [Using a Trigger](https://docs.elsaworkflows.io/guides/running-workflows/using-a-trigger.md)
- [Timer and Scheduled Workflows](https://docs.elsaworkflows.io/guides/running-workflows/timer-and-scheduled-workflows.md)
- [Workflow Definition Version Lifecycle](https://docs.elsaworkflows.io/guides/running-workflows/workflow-definition-lifecycle.md)
- [Hangfire Integration](https://docs.elsaworkflows.io/guides/running-workflows/hangfire-integration.md): Configure Hangfire as Elsa's durable workflow scheduler.
- [Long-Running Workflows](https://docs.elsaworkflows.io/guides/running-workflows/long-running-workflows.md)
- [Dispatch Workflow Activity](https://docs.elsaworkflows.io/guides/running-workflows/dispatch-workflow-activity.md)
- [Bulk Dispatch Workflows Activity](https://docs.elsaworkflows.io/guides/running-workflows/bulk-dispatch-workflows.md)
- [Studio User Guide](https://docs.elsaworkflows.io/guides/studio.md): A comprehensive guide to using Elsa Studio, the visual designer and admin UI for Elsa Workflows v3.
- [Expressions](https://docs.elsaworkflows.io/guides/studio/expressions.md): Learn how Elsa Studio expression editors map to Elsa Server expression engines, how to access workflow variables, and which syntax choices are actually available in Elsa 3.8.
- [JavaScript IntelliSense Type Definitions](https://docs.elsaworkflows.io/guides/studio/javascript-type-definition-providers.md): Extend Elsa Studio JavaScript IntelliSense with release-backed TypeScript declarations from the Elsa Server.
- [Custom Activity Icons](https://docs.elsaworkflows.io/guides/studio/custom-icons.md): Add custom activity icons to Elsa Studio with a release-backed display settings provider.
- [Customization](https://docs.elsaworkflows.io/guides/studio/customization.md): Source-backed guide to the main Elsa Studio customization seams in release 3.8.0, including host composition, branding, menus, widgets, activity pickers, and editor extensibility.
- [Custom UI Components](https://docs.elsaworkflows.io/guides/studio/custom-ui-components.md): Source-backed guide to customizing Elsa Studio input editors in release 3.8.0 using backend UI hints, property UI handlers, and Studio UI hint handlers.
- [Integration](https://docs.elsaworkflows.io/guides/studio/integration.md): Source-backed guide to the Elsa Studio host models available in release 3.8.0, including standalone hosts, custom elements, backend configuration, and authentication.
- [Custom Elements Embedding](https://docs.elsaworkflows.io/guides/studio/integration/custom-elements.md): Source-backed cookbook for embedding Elsa Studio custom elements in release 3.8.0, including backend configuration, authentication, tenant headers, and React usage.
- [Platform Artifact Submission](https://docs.elsaworkflows.io/guides/studio/integration/platform-integration.md): Release-backed guidance for submitting Elsa Studio workflow definitions as Elsa Platform artifacts in Elsa Studio 3.8.0.
- [Workflow Patterns](https://docs.elsaworkflows.io/guides/patterns.md): A practical, pattern-based guide to designing and implementing common workflow patterns with Elsa Workflows v3. Each pattern provides grounded guidance, code snippets, pitfalls, and references to elsa
- [Troubleshooting](https://docs.elsaworkflows.io/guides/troubleshooting.md): Comprehensive troubleshooting guide for diagnosing and resolving common Elsa Workflows issues in development and production environments.
- [Frequently Asked Questions](https://docs.elsaworkflows.io/guides/faq.md): Answers to common Elsa Workflows questions about designing, starting, waiting, versioning, and operating workflows.
- [Community & Resources](https://docs.elsaworkflows.io/guides/community-resources.md): Find official Elsa learning, support, release, and contribution resources.
- [Adoption Evidence and Case Studies](https://docs.elsaworkflows.io/guides/case-studies.md): Adoption evidence, reference architectures, and case-study guidance for Elsa Workflows.