Merge pull request #130 from elsa-workflows/copilot/fix-51759159-929553838-ecfda386-740d-4d8e-82eb-c991c272195e

docs: add 3.6.0 release notes

Author: sfmskywalker

doc/changelogs/3.6.0.md

@@ -0,0 +1,186 @@
+# 3.6.0 — Release Notes
+
+Compare: [`3.5.3...3.6.0`](https://github.com/elsa-workflows/elsa-extensions/compare/3.5.3...3.6.0)
+
+---
+
+## ⚠️ Breaking Changes / Upgrade Notes
+
+- **Repository rebranding & pervasive namespace changes**: The repository has been rebranded from *Elsa Integrations* to *Elsa Extensions*. All packages shipped from this repo carry updated namespaces. Consumers must update their `using` statements and package references accordingly:
+  - All `EntityFrameworkCore` namespaces → `EFCore` (e.g. `Elsa.EntityFrameworkCore` → `Elsa.EFCore`).
+  - `Elsa.ProtoActor.Core` → `Elsa.Actors.ProtoActor`.
+  - Persistence projects now include `Persistence` in their namespaces.
+  - ServiceBus projects now include `ServiceBus` in their namespaces.
+  - Storage projects now include `Storage` in their namespaces.
+  - Webhooks namespace now includes `Http`.
+  - Scripting namespace now includes `Scripting`.
+  - Scheduling namespace now includes `Scheduling`.
+  - The `Integrations` segment has been removed from all package/namespace names.
+
+  ([#40](https://github.com/elsa-workflows/elsa-extensions/pull/40), [#41](https://github.com/elsa-workflows/elsa-extensions/pull/41), [#42](https://github.com/elsa-workflows/elsa-extensions/pull/42))
+
+- **`Elsa.DevOps.GitHub` package rename**: The GitHub integration has been moved from the `Elsa.Integrations.GitHub` namespace/package to `Elsa.DevOps.GitHub`. Update your package reference and all `using` directives. ([#51](https://github.com/elsa-workflows/elsa-extensions/pull/51))
+
+- **Core EF Core projects removed from this repo**: EF Core persistence projects (e.g. SQL Server, PostgreSQL, SQLite providers) previously housed here have been moved back to `elsa-core`. Remove references to the `elsa-extensions` builds of these packages and depend on the equivalent packages from `elsa-core` instead. ([#86](https://github.com/elsa-workflows/elsa-extensions/pull/86))
+
+- **SQL Evaluator expression syntax changes** (`Elsa.Sql`): Hard-coded expression keys have been replaced with object-path navigation. Update any SQL expressions that use the old prefixes:
+
+  | Old expression | New expression |
+  |---|---|
+  | `{{Variables.foo}}` | `{{Variable.foo}}` |
+  | `{{Workflow.Definition.Id}}` | `{{Workflow.Identity.DefinitionId}}` |
+  | `{{Workflow.Definition.Version.Id}}` | `{{Workflow.Identity.Id}}` |
+  | `{{Workflow.Definition.Version}}` | `{{Workflow.Identity.Version}}` |
+  | `{{Workflow.Instance.Id}}` | `{{Activity.WorkflowExecutionContext.Id}}` |
+  | `{{Correlation.Id}}` | `{{Activity.WorkflowExecutionContext.CorrelationId}}` |
+
+  New context prefixes `Activity.`, `Execution.`, and `Workflow.` are now available for navigating nested properties, POCOs, `ExpandoObject`, `IDictionary`, arrays, lists, and JSON objects. ([#87](https://github.com/elsa-workflows/elsa-extensions/pull/87))
+
+- **Agents activity system refactored**: `ConfiguredAgentActivity` has been renamed to `AgentActivity`; `ConfigurationAgentActivityProvider` has been renamed to `AgentActivityProvider`. The code-first agent system and its related abstractions have been removed in favour of the new Microsoft Agent Framework–based approach. Update any direct references to these types. ([#99](https://github.com/elsa-workflows/elsa-extensions/pull/99), [#107](https://github.com/elsa-workflows/elsa-extensions/pull/107))
+
+---
+
+## ✨ New Features
+
+#### SQL (`Elsa.Sql`)
+
+- **SQL Integration module**: Ports the `Elsa.Sql` activities from `elsa-core` into this repo, including a fix for the upstream variable-retrieval bug and improvements to the SQL evaluator. ([#38](https://github.com/elsa-workflows/elsa-extensions/pull/38))
+- **Object-property navigation in SQL expressions**: Expressions can now dereference nested properties, array indices, and JSON fields directly using dot-path syntax. See the updated README for full examples. ([#87](https://github.com/elsa-workflows/elsa-extensions/pull/87))
+
+#### HTTP (`Elsa.Http.OpenApi`)
+
+- **OpenAPI documentation for HTTP workflow triggers**: New `Elsa.Http.OpenApi` extension auto-generates an OpenAPI 3.0 specification from published workflow HTTP trigger endpoints, with an interactive ReDoc UI served at `/documentation`.
+
+  ```csharp
+  // Registration
+  elsa.UseHttp(http => http.UseOpenApi());
+
+  // Middleware
+  app.MapWorkflowOpenApi();
+  ```
+
+  ([#80](https://github.com/elsa-workflows/elsa-extensions/pull/80), [#108](https://github.com/elsa-workflows/elsa-extensions/pull/108))
+
+#### AI / Agents (`Elsa.Agents`)
+
+- **AI Copilot app-bar component**: A new in-Studio AI Copilot panel lets users generate workflows from natural language prompts, with email integration and agent communication built in. ([#70](https://github.com/elsa-workflows/elsa-extensions/pull/70))
+- **Microsoft Agent Framework integration**: Multi-agent workflows powered by the Microsoft Agent Framework; code-first agent definitions with strongly typed inputs/outputs. ([#99](https://github.com/elsa-workflows/elsa-extensions/pull/99))
+- **Service provider discovery endpoint**: New `/ai/service-providers` API endpoint exposes available AI service provider names; the Studio "edit service" panel now dynamically populates from this endpoint. ([#60](https://github.com/elsa-workflows/elsa-extensions/pull/60))
+- **GitHub DevOps integration** (`Elsa.DevOps.GitHub`): GitHub workflow activities (create/delete/get comments, etc.) using `Octokit`. ([#47](https://github.com/elsa-workflows/elsa-extensions/pull/47), [#51](https://github.com/elsa-workflows/elsa-extensions/pull/51))
+
+#### Data Processing
+
+- **CSV module** (`Elsa.Csv`): New `ReadCsv` activity reads and parses CSV data from strings, streams, or files. Supports configurable headers, delimiters, and strongly-typed record mapping. Registered via `CsvFeature`. ([#91](https://github.com/elsa-workflows/elsa-extensions/pull/91))
+- **IO module** (`Elsa.IO`): Ports the IO activity set from `elsa-core 3.5` to this repo. ([#74](https://github.com/elsa-workflows/elsa-extensions/pull/74), [#75](https://github.com/elsa-workflows/elsa-extensions/pull/75), [#76](https://github.com/elsa-workflows/elsa-extensions/pull/76), [#77](https://github.com/elsa-workflows/elsa-extensions/pull/77))
+
+#### Logging (`Elsa.Logging`)
+
+- **Modular logging framework**: Introduces a `Log` activity for emitting structured log entries from within workflows, backed by pluggable sinks (console and Serilog included). Replaces the deprecated `WorkflowContexts` module. ([#83](https://github.com/elsa-workflows/elsa-extensions/pull/83))
+
+#### Scheduling (`Elsa.Scheduling.Quartz`)
+
+- **Clustering convenience API**: New `QuartzFeature.ConfigureClusteringIdentity()` method configures sensible defaults (`instanceId = AUTO`, scheduler name `ElsaScheduler`) for cluster-safe operation in multi-pod / Kubernetes deployments. ([#110](https://github.com/elsa-workflows/elsa-extensions/pull/110))
+
+#### Azure Service Bus (`Elsa.ServiceBus.AzureServiceBus`)
+
+- **Custom client overloads for `UseAzureServiceBus`**: New overloads accept a pre-built `ServiceBusClient`, enabling token-credential–based auth (`DefaultAzureCredential`, managed identity, etc.) instead of being limited to connection strings. ([#100](https://github.com/elsa-workflows/elsa-extensions/pull/100))
+
+#### Platform
+
+- **`.NET 10 (LTS)` target framework**: All library packages now multi-target `net8.0`, `net9.0`, and `net10.0`. `System.Linq.Async` is conditionally excluded on .NET 10 where it is now part of the runtime. Existing .NET 8/9 consumers are unaffected. ([#94](https://github.com/elsa-workflows/elsa-extensions/pull/94))
+
+---
+
+## 🔧 Improvements
+
+#### AI / Agents
+
+- **`IKernelFactory` extensibility**: The Semantic Kernel `IKernelFactory` interface is now public, allowing host applications to customise or replace the `Kernel` instance — useful for injecting MCP servers or other external tools. ([#64](https://github.com/elsa-workflows/elsa-extensions/pull/64))
+- **Handlebars prompting in `AgentInvoker`**: Agent prompt rendering switched to Handlebars for richer template support and consistency with Elsa Studio. ([#69](https://github.com/elsa-workflows/elsa-extensions/pull/69))
+- **External tool support via `ChatCompletion`**: The agent invocation path now calls `ChatCompletion` directly (instead of an SK prompt function), enabling external tools such as MCP server plugins. ([#64](https://github.com/elsa-workflows/elsa-extensions/pull/64))
+
+#### Scheduling / Quartz.NET
+
+- **Shared resilience module**: Quartz job resilience migrated to the shared `Elsa.Resilience.Core` package; database-specific transient exception detectors removed. ([#104](https://github.com/elsa-workflows/elsa-extensions/pull/104))
+- **Idempotent job & trigger registration**: `RegisterJobsTask` and `QuartzWorkflowScheduler` now gracefully handle `ObjectAlreadyExistsException`, preventing startup failures in concurrent multi-node deployments. ([#110](https://github.com/elsa-workflows/elsa-extensions/pull/110), [#114](https://github.com/elsa-workflows/elsa-extensions/pull/114))
+- **SQLite clustering parameter**: `UseEFCoreSQLite()` extension now accepts a `useClustering` parameter (defaults to `false`), consistent with the SqlServer/PostgreSQL/MySQL extensions. ([#110](https://github.com/elsa-workflows/elsa-extensions/pull/110))
+
+#### Azure Service Bus
+
+- **Configuration validation**: `UseAzureServiceBus` now throws a descriptive exception when the connection string or name is missing or unresolvable, rather than failing silently at runtime. ([#114](https://github.com/elsa-workflows/elsa-extensions/pull/114))
+- **Factory delegate deduplication**: Fixed an issue where calling `UseAzureServiceBus` more than once would concatenate factory delegates instead of replacing them, causing multiple `ServiceBusAdministrationClient` instances to be created. ([#114](https://github.com/elsa-workflows/elsa-extensions/pull/114))
+
+#### Databases / Persistence
+
+- **`IWorkflowReferenceQuery` abstraction**: `DatabaseFacadeExtensions` removed; replaced by the new `IWorkflowReferenceQuery` interface with default implementations, giving consumers a cleaner extension point. ([#71](https://github.com/elsa-workflows/elsa-extensions/pull/71))
+- **V3.6 schema migrations**: PostgreSQL, MySQL, and Oracle providers include updated schema migrations for the V3.6 data structure. ([#71](https://github.com/elsa-workflows/elsa-extensions/pull/71))
+
+---
+
+## 🐛 Fixes
+
+- **SQL Integration** (`Elsa.Sql`): Fixed off-by-one error in the substring index used during variable retrieval. ([#55](https://github.com/elsa-workflows/elsa-extensions/pull/55))
+- **SQL Integration** (`Elsa.Sql`): SQL evaluator now correctly resolves the `Variables.` prefix in expressions. ([#57](https://github.com/elsa-workflows/elsa-extensions/pull/57))
+- **MongoDB** (`Elsa.Persistence.MongoDb`): `FindManyAsync` wrapped in try-catch to prevent unhandled exceptions from propagating to callers. ([#81](https://github.com/elsa-workflows/elsa-extensions/pull/81))
+- **MongoDB** (`Elsa.Persistence.MongoDb`): Fixes to `MongoDbStore`, `MongoDbFeature`, `ExpressionHelpers`, and `WorkflowInstanceStore`. ([#65](https://github.com/elsa-workflows/elsa-extensions/pull/65), [#66](https://github.com/elsa-workflows/elsa-extensions/pull/66), [#67](https://github.com/elsa-workflows/elsa-extensions/pull/67), [#68](https://github.com/elsa-workflows/elsa-extensions/pull/68))
+- **Dapper Migrations** (`Elsa.Dapper`): Fixed `AggregateFaultCount` column in the V3.5 migration: `.WithDefault(0)` was incorrectly resolving to `SystemMethods.NewGuid` (enum ordinal 0); corrected to `.WithDefaultValue(0)`. ([#97](https://github.com/elsa-workflows/elsa-extensions/pull/97))
+- **Drop-in Monitor**: Fixed unhandled exceptions thrown by asynchronous filesystem events in the drop-in workflow monitor. ([#59](https://github.com/elsa-workflows/elsa-extensions/pull/59))
+
+---
+
+## 🧪 Tests
+
+- Added unit and component tests for `Elsa.Scheduling.Quartz`, covering transient-retry behaviour and job resilience. ([#104](https://github.com/elsa-workflows/elsa-extensions/pull/104))
+- Fixed resource leak in `AppComponentTest` by properly disposing service scopes. ([#105](https://github.com/elsa-workflows/elsa-extensions/pull/105))
+- Refactored `QuartzJobTransientRetryTests` to use manually constructed job instances consistently. ([#106](https://github.com/elsa-workflows/elsa-extensions/pull/106))
+
+---
+
+## 📦 Full Changelog
+
+- Sql Integration, new README-TEMPLATE, and solution folder grouping. ([#38](https://github.com/elsa-workflows/elsa-extensions/pull/38))
+- Rebrand repo to Extensions; move non-core projects from `elsa-core`. ([#40](https://github.com/elsa-workflows/elsa-extensions/pull/40))
+- Realign core and extension repos. ([#41](https://github.com/elsa-workflows/elsa-extensions/pull/41))
+- Apply code changes from old project files. ([#42](https://github.com/elsa-workflows/elsa-extensions/pull/42))
+- Remove SasToken project. ([#45](https://github.com/elsa-workflows/elsa-extensions/pull/45))
+- Add GitHub integration (initial). ([#47](https://github.com/elsa-workflows/elsa-extensions/pull/47))
+- Refactor GitHub integration to `Elsa.DevOps.GitHub`. ([#51](https://github.com/elsa-workflows/elsa-extensions/pull/51))
+- Fix substring index for variable retrieval in SQL. ([#55](https://github.com/elsa-workflows/elsa-extensions/pull/55))
+- SQL evaluator supports `Variables.` prefix. ([#57](https://github.com/elsa-workflows/elsa-extensions/pull/57))
+- Fix unhandled exceptions in drop-in monitor. ([#59](https://github.com/elsa-workflows/elsa-extensions/pull/59))
+- Agents: add `/ai/service-providers` discovery endpoint. ([#60](https://github.com/elsa-workflows/elsa-extensions/pull/60))
+- Agents: `IKernelFactory` interface + external tool support via `ChatCompletion`. ([#64](https://github.com/elsa-workflows/elsa-extensions/pull/64))
+- MongoDB store fixes. ([#65](https://github.com/elsa-workflows/elsa-extensions/pull/65), [#66](https://github.com/elsa-workflows/elsa-extensions/pull/66), [#67](https://github.com/elsa-workflows/elsa-extensions/pull/67), [#68](https://github.com/elsa-workflows/elsa-extensions/pull/68))
+- Improve Agents module: Handlebars prompting, dependency updates, alteration background job scope fix. ([#69](https://github.com/elsa-workflows/elsa-extensions/pull/69))
+- Agents: AI Copilot, document query plugin, OpenAI embedding generator. ([#70](https://github.com/elsa-workflows/elsa-extensions/pull/70))
+- Database extensions refactor + V3.6 migrations for PostgreSQL, MySQL, Oracle. ([#71](https://github.com/elsa-workflows/elsa-extensions/pull/71))
+- Add IO module from `elsa-core`. ([#74](https://github.com/elsa-workflows/elsa-extensions/pull/74), [#75](https://github.com/elsa-workflows/elsa-extensions/pull/75), [#76](https://github.com/elsa-workflows/elsa-extensions/pull/76), [#77](https://github.com/elsa-workflows/elsa-extensions/pull/77))
+- MongoDB: try-catch in `FindManyAsync`. ([#81](https://github.com/elsa-workflows/elsa-extensions/pull/81))
+- Add OpenAPI documentation extension for HTTP workflow triggers. ([#80](https://github.com/elsa-workflows/elsa-extensions/pull/80))
+- Add Logging features from `elsa-core 3.5`; replace WorkflowContexts module; move Slack to Communication folder. ([#83](https://github.com/elsa-workflows/elsa-extensions/pull/83))
+- Remove core EF Core projects (moved to `elsa-core`). ([#86](https://github.com/elsa-workflows/elsa-extensions/pull/86))
+- BREAKING: Enhance SQL evaluator — object-property navigation, new context prefixes, deprecated key removal. ([#87](https://github.com/elsa-workflows/elsa-extensions/pull/87))
+- Add CSV data processing module. ([#91](https://github.com/elsa-workflows/elsa-extensions/pull/91))
+- Add `.NET 10 (LTS)` target framework support. ([#94](https://github.com/elsa-workflows/elsa-extensions/pull/94))
+- Fix `AggregateFaultCount` int column default in Dapper V3.5 migration. ([#97](https://github.com/elsa-workflows/elsa-extensions/pull/97))
+- Microsoft Agent Framework integration; code-first agents; multi-agent workflows. ([#99](https://github.com/elsa-workflows/elsa-extensions/pull/99))
+- `UseAzureServiceBus` overloads for custom `ServiceBusClient`. ([#100](https://github.com/elsa-workflows/elsa-extensions/pull/100))
+- Fix resource leak in `AppComponentTest`. ([#105](https://github.com/elsa-workflows/elsa-extensions/pull/105))
+- Refactor `QuartzJobTransientRetryTests`. ([#106](https://github.com/elsa-workflows/elsa-extensions/pull/106))
+- Refactor agent activity system; rename `ConfiguredAgentActivity` → `AgentActivity`. ([#107](https://github.com/elsa-workflows/elsa-extensions/pull/107))
+- Add `Elsa.Http.OpenApi` project to solution. ([#108](https://github.com/elsa-workflows/elsa-extensions/pull/108))
+- Quartz.NET resilience via `Elsa.Resilience.Core`; add retry unit tests. ([#104](https://github.com/elsa-workflows/elsa-extensions/pull/104))
+- Quartz.NET clustering hardening: `ConfigureClusteringIdentity`, idempotent job/trigger registration. ([#110](https://github.com/elsa-workflows/elsa-extensions/pull/110))
+- Azure Service Bus factory fix; Quartz `ObjectAlreadyExistsException` handling; ASB config validation. ([#114](https://github.com/elsa-workflows/elsa-extensions/pull/114))
+- `chore`: update Elsa and ElsaStudio versions to 3.6.0. ([e626ace](https://github.com/elsa-workflows/elsa-extensions/commit/e626ace4ec43ce74cefede02ddae60d9fbda30b4))
+
+---
+
+## 👋 New Contributors
+
+- [@mohdali](https://github.com/mohdali) — drop-in monitor fix & agents service-provider endpoint ([#59](https://github.com/elsa-workflows/elsa-extensions/pull/59), [#60](https://github.com/elsa-workflows/elsa-extensions/pull/60))
+- [@pugafran](https://github.com/pugafran) — `IKernelFactory` & external tool support ([#64](https://github.com/elsa-workflows/elsa-extensions/pull/64))
+- [@lukhipolito-nexxbiz](https://github.com/lukhipolito-nexxbiz) / [@lukhipolito](https://github.com/lukhipolito) — IO module port ([#74](https://github.com/elsa-workflows/elsa-extensions/pull/74)–[#77](https://github.com/elsa-workflows/elsa-extensions/pull/77))
+- [@mhichb](https://github.com/mhichb) — MongoDB `FindManyAsync` fix ([#81](https://github.com/elsa-workflows/elsa-extensions/pull/81))
+- [@cristinamudura](https://github.com/cristinamudura) — `Elsa.Http.OpenApi` extension ([#80](https://github.com/elsa-workflows/elsa-extensions/pull/80))
+- [@kremi151](https://github.com/kremi151) — Dapper migration column default fix ([#97](https://github.com/elsa-workflows/elsa-extensions/pull/97))