Compare: 3.9.0...3.10.1

Elsa 3.10.1 — Release Notes

3.10.0 was an internal candidate and was not published. This is the first public 3.10 release, and it includes everything since 3.9.0.

Minor release. Core, Studio and Extensions packages are published together as 3.10.1 from this repository. Upgrade the Elsa.* packages you use to 3.10.1 together, except the packages listed below that stay at 3.9.0.

The headline is more reliable workflow dispatch and cancellation, tenant-scoped roles, and a combined Community image that serves Studio again. If you run JavaScript in workflows, host Elsa outside Development/Demo, or use a custom EF Core schema, read the upgrade notes before rolling out.

🌟 Highlights

• The combined Community image serves Studio again. elsaworkflows/elsa-server-and-studio-v3 hosts Studio (login and designer) and the Elsa Server API in one process. (#9201)
• The dispatch outbox delivers reliably. Outbox items are deleted only after delivery, a message for a channel the host cannot route no longer stalls every newer dispatch, and MassTransit honours SkipIfInstanceExists so a retry cannot start a duplicate child. (#8810, #8817, #8167, #8816, #8820, #8811)
• Cancelling a waiting dispatch cancels its children. Cancelling a DispatchWorkflow or BulkDispatchWorkflows that is still waiting withdraws the outbox item, cancels the child workflows, and retries a failed cancel page read instead of skipping children. When a dispatched child is cancelled, the parent can resume. (#8823, #8836, #8837, #8871, #8819, #8822, #8961, #8963)
• Roles are tenant-scoped. Role names are unique per tenant, and role ids are no longer derived from the role name, so two tenants that share a store can each have an admin role with the same name. (#8616, #8619, #8615)
• JavaScript is safer by default. The engine is Jint 4.17, the stack-overflow guard is on, and CLR access is opt-in. Deeply recursive scripts now fail with an error instead of crashing the host. (#9013, #8990, #8966)

🐛 Fixes

Runtime and dispatch

• Cancelling a waiting DispatchWorkflow or BulkDispatchWorkflows now cancels the child workflows, withdraws the outbox item, and retries a failed cancel page instead of leaving children running. (#8819, #8822, #8823, #8836, #8837, #8871)
• Unroutable outbox items are retried and then abandoned, and they no longer block later dispatches. (#8816, #8817)
• MassTransit dispatch honours SkipIfInstanceExists, so an outbox retry cannot create a duplicate child. (#8811, #8820)
• ProtoActorWorkflowClient.InstanceExistsAsync is implemented. (#8873, #8874)
• Background activities can persist and reload their bookmarks, and a background resume no longer writes duplicate bookmark ids. (#8804, #8808, #8809, #8996, #8879)
• A single transient exception no longer stops the workflow heartbeat for good, so recovery will not restart a healthy long-running activity. (#8753, #8788)
• Publishing a workflow no longer leaves a stale "not found" cache entry, or evicts the cache before the database write, which could cause 404s or faulted parents for up to a minute. (#8752, #8790, #8789)
• Stored trigger and bookmark payloads that come back as ExpandoObject or JsonElement deserialize again. (#8792, #8793, #8794, #8795)
• Switch resumes correctly from JSON-serialized state. (#7443, #8863)
• In token-based flowcharts, a WaitAny FlowJoin no longer completes the flowchart before the join runs. (#8464, #8513)
• A workflow run now reports which stored trigger started it. (#8919)
• A null cron expression is returned as a validation error instead of throwing. (#8827, #8826, #8828)

Persistence and migrations

• SQLite Label installs migrate cleanly on a fresh database and when upgrading from 3.9. MySQL Labels and Secrets migrations no longer require the database to be named Elsa. (#9108, #9110)
• SQL Server Labels and Secrets uniqueness migrations no longer fail with Incorrect syntax near 'CONCAT'. (#8764, #8358)
• Most EF Core modules honour a custom database schema. Secrets still hard-code the Elsa schema; see Known issues. (#8803)
• MySQL utf8mb4 installs no longer fail the runtime migration with "Specified key was too long". (#7441, #8865)
• Oracle: the default tenant id "" no longer fails startup (ORA-01400); Triggers.ActivityId and SerializedMetadata snapshots match the database; bulk upserts accept mixed null/value batches; runtime snapshots include the V3_7 Scheduling* indexes and NCLOB types; and StoredTrigger unique-index snapshots match the V3_6 migrations for PostgreSQL, SQLite and Oracle. (#8994, #9015, #8876, #9020, #8875, #9008, #8881, #8997, #8870, #8872, #8866, #8868)
• MongoDB definition updates are applied atomically. (#8654)
• The default tenant can see legacy Dapper roles stored with a null or empty tenant id. (#8618, #9012)
• A failed tenant-activation migration is no longer swallowed: remaining startup tasks are not skipped, and the server no longer reports healthy with an incomplete activity registry. (#8754, #8781)
• The Labels API returns a proper error for a duplicate label name or a name longer than 255 characters, instead of HTTP 500. (#8756, #8782, #8829)

Identity, tenancy and secrets

• Role names are scoped to the tenant and role ids are generated, so tenants that share a store can use the same role name. (#8615, #8616, #8619)
• [SingleNodeTask] now runs once per tenant rather than once overall. (#8637)
• Resolved secret values are no longer persisted in activity state (the workflow instance and the execution journal). (#8758, #8775)
• The configuration secret store only resolves configured secrets, not arbitrary application configuration keys. (#8757, #8774)

User tasks

• User tasks no longer treat bookmarks from other activities (Cron, Delay, Event) as user tasks, which used to fail the workflow commit. (#8760, #8784)
• GET /elsa/api/user-tasks/{id} no longer returns HTTP 500 for the claiming user. (#8761, #8785)
• The UserTask activity is registered, so it appears in the activity registry. (#8918)
• Server-side support for user-task actions in JSON workflows shipped (#8787, part of #8763). The Studio designer side is still open; see Known issues.

BPMN and Studio

• A BPMN terminate in the same step that starts new work no longer leaves the workflow suspended forever. (#8818, #8832)
• A faulted BPMN call-activity child is routed to the error path. (#8920)
• Studio keeps list paging when you select a workflow instance and navigate back. (#7447, #8864)
• The Agents menu is hidden when the Agents feature is disabled on the server. (#8801, #8830)

Agents

• The Agents kernel no longer adds its own Trace-level console logger, so prompts and chat history are not written to stdout. (#8799, #8992, #9019)
• Agent kernel services keep ILogger<T> resolvable. (#9026, #9030)

Dependency updates

• This release includes dependency updates. MySQL packages support .NET 8 and 9 only. (#9193)
• Microsoft.AspNetCore.WebUtilities is updated. (#9243)

📦 New packages

First published at 3.10.1 (no earlier versions on nuget.org):

• Elsa.Connections, Elsa.Connections.Credentials.Persistence.EFCore, Elsa.Connections.Credentials.Persistence.EFCore.PostgreSql, Elsa.Connections.Credentials.Workflows
• Elsa.Workflows.Admission, Elsa.Workflows.Admission.Persistence.EFCore, Elsa.Workflows.Admission.Persistence.EFCore.PostgreSql

Studio and Extensions packages that were previously published from their own repositories are produced from this repository at 3.10.1.

⚠️ Upgrade notes and breaking changes

Upgrade the Elsa. packages you use to 3.10.1 together*, except the packages that stay at 3.9.0 (below).

Upgrade steps

1. Token signing key is now required outside Development/Demo. The sample apps and container images no longer start with a built-in signing key in other environments: set Identity__Tokens__SigningKey (config Identity:Tokens:SigningKey). Tokens issued before the key is set or changed stop working once it changes, so users and clients need to sign in again or get new tokens. This applies to the elsa-server-and-studio-v3 image too: it starts without the key, but every request, including login, then fails with an empty HTTP 500, so always set Identity__Tokens__SigningKey when running these images outside Development. A clearer startup error is coming (#9106).
2. CLR access in JavaScript is now opt-in. Workflows whose JavaScript uses CLR types need JavaScript__AllowClrAccess=true (config JavaScript:AllowClrAccess).
3. Rotate default credentials if you ran older container tags. If you deployed one of the earlier container images, change the default admin user's password and the default API key.
4. Remove duplicate default-tenant labels (SQLite and MySQL) before upgrading. If an existing database has the same label name under both a NULL and an empty ('') tenant id, the 3.10 migration does not merge the duplicates, and the first start fails (SQLite: unique-constraint error; MySQL: error 1295). Remove or rename the duplicate labels first; the next start then completes normally.

Behaviour changes

• [SingleNodeTask] now runs once per tenant instead of once overall (#8637). Review third-party SingleNodeTask implementations for per-tenant execution.
• The workflow dispatch outbox now deletes items only after delivery and fires Dispatching/Dispatched once, at delivery (#8810). On hosts whose dispatcher can't route channels (no MassTransit), channels are still ignored as before. On hosts that can route channels, items for a channel the host cannot route are retried, then abandoned at MaxOutboxDeliveryAttempts (default 10) with a warning naming the channel (#8817); fix the channel config. The old processor constructor is [Obsolete] and uses the old non-durable delivery; switch to the new constructor.
• Elsa 3.10 updates the JavaScript engine to Jint 4.17 and turns its stack-overflow guard on by default (#8990, #9013, #8966). Check scripts that depend on these behaviours:
  • JSON.parse now accepts trailing commas.
  • JSON.stringify output no longer depends on the server's locale.
  • parseInt handles some edge cases differently.
  • Deeply recursive scripts now stop with an error instead of crashing the process. If you need the old behaviour, set JintOptions.EnableStackOverflowGuard = false.

Packages not republished in 3.10

• The legacy Elsa.Secrets.Api, Elsa.Secrets.Core, Elsa.Secrets.Management, Elsa.Secrets.Models and Elsa.Secrets.Scripting packages aren't republished in 3.10 and stay at 3.9.0.
• Elsa.Templates stays at 3.9.0 for this release.

MySQL

MySQL packages support .NET 8 and 9 only (#9193).

Custom EF Core schema

Since #8803, every EF Core module can use a custom database schema except Secrets. The Secrets module still hard-codes the schema Elsa, so its migrations fail when you set a custom schema. Keep Secrets on the default Elsa schema for now. See Known issues (#8807).

🚧 Known issues

• A user task can still remain in Completing after the workflow has finished, until the reconciler runs, or go straight to Completed without a TaskId. This is still open in 3.10.1. (#8762)
• Timer and cron triggers still only fire for the default tenant. The Quartz tenant-scope fix is not in this release. (#9120)
• Updating, revoking or deleting a * (wildcard) secret from a tenant still returns HTTP 500. (#8759)
• Secrets EF Core migrations still hard-code the Elsa schema, so they fail when you configure a custom schema. (#8807)
• User-task actions still cannot be defined in JSON / Studio-designed workflows (the action label is Input<string>). The server side shipped in #8787; the Studio side is still open. (#8763)
• Drain force-cancel still does not reach running activities through their cancellation token. An interrupted instance can end up Finished or Cancelled instead of resumable. (#8489)
• #8541 is only partly addressed. This release includes the per-tenant SingleNodeTask change (#8637); the rest of the tenant startup-performance work is still open.
• #8777 and #8778 are still open.

🐳 Docker images

3.10.1 publishes elsaworkflows/elsa-server-v3 and elsaworkflows/elsa-server-and-studio-v3, tagged 3.10.1, 3.10 and latest. The combined image serves Studio again (#9201). Set Identity__Tokens__SigningKey when running these images outside Development (see upgrade step 1).