Add workflow export functionality and update changelog (#7357)

* Add `IWorkflowDefinitionExporter` for workflow export functionality

Introduced `IWorkflowDefinitionExporter` interface and its implementation to export workflow definitions as JSON or ZIP archives. Simplified `Export` endpoint logic by utilizing the new exporter service. Updated package version to 3.6.1.

* Remove duplicate `ExportAsync` method from `IWorkflowDefinitionExporter` and its implementation in `WorkflowDefinitionExporter`.

* Remove deprecated test from `WorkflowDefinitionExporterTests`, regression tests are covered in `WorkflowReferenceGraphBuilderTests`.

* Update GitHub Actions workflow to support version 3.6.1 deployment

* Update src/modules/Elsa.Workflows.Management/Services/WorkflowDefinitionExporter.cs

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Move `WorkflowDefinitionExporterRegressionTests` to separate test file for clarity

* Add `DefaultFileNameSanitizer` for sanitizing file names and update `WorkflowDefinitionExporter` to use it. Implement unit tests for the sanitizer.

* Update test assertion for exported workflow file name in `WorkflowDefinitionExporterRegressionTests`.

* Simplify file naming in `WorkflowDefinitionExporter` by removing duplicate ID from JSON file names.

* Update test/unit/Elsa.Workflows.Management.UnitTests/Services/DefaultFileNameSanitizerTests.cs

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: sfmskywalker

.github/workflows/packages.yml

@@ -202,7 +202,7 @@ jobs:
     name: Deploy coverage to GitHub Pages
     needs: test
     runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop/3.6.0' || github.ref == 'refs/heads/release/3.6.0'
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop/3.6.1' || github.ref == 'refs/heads/release/3.6.1'
     permissions:
       pages: write
       id-token: write

src/modules/Elsa.Workflows.Api/Endpoints/WorkflowDefinitions/Export/Endpoint.cs

@@ -1,13 +1,6 @@
-using System.IO.Compression;
-using System.Text.Json;
 using Elsa.Abstractions;
 using Elsa.Common.Models;
 using Elsa.Workflows.Management;
-using Elsa.Workflows.Management.Entities;
-using Elsa.Workflows.Management.Filters;
-using Elsa.Workflows.Management.Mappers;
-using Elsa.Workflows.Management.Models;
-using Humanizer;
 using JetBrains.Annotations;
 
 namespace Elsa.Workflows.Api.Endpoints.WorkflowDefinitions.Export;
@@ -16,26 +9,8 @@ namespace Elsa.Workflows.Api.Endpoints.WorkflowDefinitions.Export;
 /// Exports the specified workflow definition as JSON download.
 /// </summary>
 [UsedImplicitly]
-internal class Export : ElsaEndpoint<Request>
+internal class Export(IWorkflowDefinitionExporter exporter) : ElsaEndpoint<Request>
 {
-    private readonly IApiSerializer _serializer;
-    private readonly IWorkflowDefinitionStore _store;
-    private readonly IWorkflowReferenceGraphBuilder _workflowReferenceGraphBuilder;
-    private readonly WorkflowDefinitionMapper _workflowDefinitionMapper;
-
-    /// <inheritdoc />
-    public Export(
-        IWorkflowDefinitionStore store,
-        IApiSerializer serializer,
-        WorkflowDefinitionMapper workflowDefinitionMapper,
-        IWorkflowReferenceGraphBuilder workflowReferenceGraphBuilder)
-    {
-        _store = store;
-        _serializer = serializer;
-        _workflowDefinitionMapper = workflowDefinitionMapper;
-        _workflowReferenceGraphBuilder = workflowReferenceGraphBuilder;
-    }
-
     /// <inheritdoc />
     public override void Configure()
     {
@@ -48,165 +23,33 @@ public override void Configure()
     public override async Task HandleAsync(Request request, CancellationToken cancellationToken)
     {
         if (request.DefinitionId != null)
-            await DownloadSingleWorkflowAsync(request.DefinitionId, request.VersionOptions, request.IncludeConsumingWorkflows, cancellationToken);
-        else if (request.Ids != null)
-            await DownloadMultipleWorkflowsAsync(request.Ids, request.IncludeConsumingWorkflows, cancellationToken);
-        else await Send.NoContentAsync(cancellationToken);
-    }
-
-    private async Task DownloadMultipleWorkflowsAsync(ICollection<string> ids, bool includeConsumingWorkflows, CancellationToken cancellationToken)
-    {
-        var definitions = (await _store.FindManyAsync(new()
-        {
-            Ids = ids
-        }, cancellationToken)).ToList();
-
-        if (includeConsumingWorkflows)
-            definitions = await IncludeConsumersAsync(definitions, cancellationToken);
-
-        if (!definitions.Any())
-        {
-            await Send.NoContentAsync(cancellationToken);
-            return;
-        }
-
-        await WriteZipResponseAsync(definitions, cancellationToken);
-    }
-
-    private async Task DownloadSingleWorkflowAsync(string definitionId, string? versionOptions, bool includeConsumingWorkflows, CancellationToken cancellationToken)
-    {
-        var parsedVersionOptions = string.IsNullOrEmpty(versionOptions) ? VersionOptions.Latest : VersionOptions.FromString(versionOptions);
-        var definition = (await _store.FindManyAsync(new()
-        {
-            DefinitionId = definitionId,
-            VersionOptions = parsedVersionOptions
-        }, cancellationToken)).FirstOrDefault();
-
-        if (definition == null)
         {
-            await Send.NotFoundAsync(cancellationToken);
-            return;
-        }
-
-        if (includeConsumingWorkflows)
-        {
-            var definitions = await IncludeConsumersAsync([definition], cancellationToken);
-            await WriteZipResponseAsync(definitions, cancellationToken);
-            return;
-        }
-
-        var model = await CreateWorkflowModelAsync(definition, cancellationToken);
-        var binaryJson = await SerializeWorkflowDefinitionAsync(model, cancellationToken);
-        var fileName = GetFileName(model);
-
-        await Send.BytesAsync(binaryJson, fileName, cancellation: cancellationToken);
-    }
+            var versionOptions = string.IsNullOrEmpty(request.VersionOptions) ? VersionOptions.Latest : VersionOptions.FromString(request.VersionOptions);
+            var result = await exporter.ExportAsync(request.DefinitionId, versionOptions, request.IncludeConsumingWorkflows, cancellationToken);
 
-    /// <summary>
-    /// Recursively discovers all consuming workflow definitions and includes them.
-    /// Consumers are always resolved at <see cref="VersionOptions.Latest"/>, regardless of the version used for the initial definitions.
-    /// </summary>
-    private async Task<List<WorkflowDefinition>> IncludeConsumersAsync(List<WorkflowDefinition> definitions, CancellationToken cancellationToken)
-    {
-        var initialDefinitionIds = definitions.Select(d => d.DefinitionId).ToList();
-        var graph = await _workflowReferenceGraphBuilder.BuildGraphAsync(initialDefinitionIds, cancellationToken);
-        
-        // Find any consumer definitions not already in our list.
-        var newDefinitionIds = graph.ConsumerDefinitionIds.Except(initialDefinitionIds).ToList();
-
-        if (newDefinitionIds.Count > 0)
-        {
-            var consumerDefinitions = await _store.FindManyAsync(new WorkflowDefinitionFilter
+            if (result == null)
             {
-                DefinitionIds = newDefinitionIds.ToArray(),
-                VersionOptions = VersionOptions.Latest
-            }, cancellationToken);
+                await Send.NotFoundAsync(cancellationToken);
+                return;
+            }
 
-            definitions = definitions.Concat(consumerDefinitions).ToList();
+            await Send.BytesAsync(result.Data, result.FileName, cancellation: cancellationToken);
         }
-
-        return definitions;
-    }
-
-    private async Task WriteZipResponseAsync(List<WorkflowDefinition> definitions, CancellationToken cancellationToken)
-    {
-        var zipStream = new MemoryStream();
-        var sortedDefinitions = definitions.OrderBy(d => d.DefinitionId).ToList();
-        
-        // NOTE:
-        // - ZIP timestamps cannot be earlier than 1980-01-01 (the ZIP format's minimum).
-        // - We intentionally use a fixed timestamp (instead of DateTimeOffset.UtcNow) to keep exports deterministic.
-        //   This avoids producing different ZIP bytes for identical exports, which helps tests, caching, and diffing.
-        var zipEpoch = new DateTimeOffset(1980, 1, 1, 0, 0, 0, TimeSpan.Zero);
-        
-#if NET10_0_OR_GREATER
-        await using (var zipArchive = new ZipArchive(zipStream, ZipArchiveMode.Create, true))
+        else if (request.Ids != null)
         {
-            // Create a JSON file for each workflow definition:
-            foreach (var definition in sortedDefinitions)
+            var result = await exporter.ExportManyAsync(request.Ids, request.IncludeConsumingWorkflows, cancellationToken);
+
+            if (result == null)
             {
-                var model = await CreateWorkflowModelAsync(definition, cancellationToken);
-                var binaryJson = await SerializeWorkflowDefinitionAsync(model, cancellationToken);
-                var fileName = GetFileName(model);
-                var entry = zipArchive.CreateEntry(fileName, CompressionLevel.Optimal);
-                entry.LastWriteTime = zipEpoch;
-                await using var entryStream = await entry.OpenAsync(cancellationToken);
-                await entryStream.WriteAsync(binaryJson, cancellationToken);
+                await Send.NoContentAsync(cancellationToken);
+                return;
             }
+
+            await Send.BytesAsync(result.Data, result.FileName, cancellation: cancellationToken);
         }
-#else
-        using (var zipArchive = new ZipArchive(zipStream, ZipArchiveMode.Create, true))
+        else
         {
-            // Create a JSON file for each workflow definition:
-            foreach (var definition in sortedDefinitions)
-            {
-                var model = await CreateWorkflowModelAsync(definition, cancellationToken);
-                var binaryJson = await SerializeWorkflowDefinitionAsync(model, cancellationToken);
-                var fileName = GetFileName(model);
-                var entry = zipArchive.CreateEntry(fileName, CompressionLevel.Optimal);
-                entry.LastWriteTime = zipEpoch;
-                await using var entryStream = entry.Open();
-                await entryStream.WriteAsync(binaryJson, cancellationToken);
-            }
+            await Send.NoContentAsync(cancellationToken);
         }
-#endif
-        
-        // Send the zip file to the client:
-        zipStream.Position = 0;
-        await Send.BytesAsync(zipStream.ToArray(), "workflow-definitions.zip", cancellation: cancellationToken);
-    }
-
-    private string GetFileName(WorkflowDefinitionModel definition)
-    {
-        var hasWorkflowName = !string.IsNullOrWhiteSpace(definition.Name);
-        var workflowName = hasWorkflowName ? definition.Name!.Trim() : definition.DefinitionId;
-        var fileName = $"workflow-definition-{workflowName.Underscore().Dasherize().ToLowerInvariant()}-{definition.DefinitionId}.json";
-        return fileName;
-    }
-
-    private async Task<byte[]> SerializeWorkflowDefinitionAsync(WorkflowDefinitionModel model, CancellationToken cancellationToken)
-    {
-        var serializerOptions = _serializer.GetOptions();
-        var document = JsonSerializer.SerializeToDocument(model, serializerOptions);
-        var rootElement = document.RootElement;
-
-        using var output = new MemoryStream();
-        await using var writer = new Utf8JsonWriter(output);
-
-        writer.WriteStartObject();
-        writer.WriteString("$schema", "https://elsaworkflows.io/schemas/workflow-definition/v3.0.0/schema.json");
-
-        foreach (var property in rootElement.EnumerateObject())
-            property.WriteTo(writer);
-
-        writer.WriteEndObject();
-
-        await writer.FlushAsync(cancellationToken);
-        return output.ToArray();
-    }
-
-    private async Task<WorkflowDefinitionModel> CreateWorkflowModelAsync(WorkflowDefinition definition, CancellationToken cancellationToken)
-    {
-        return await _workflowDefinitionMapper.MapAsync(definition, cancellationToken);
     }
 }

src/modules/Elsa.Workflows.Management/Contracts/IFileNameSanitizer.cs

@@ -0,0 +1,13 @@
+namespace Elsa.Workflows.Management;
+
+/// <summary>
+/// Sanitizes file names by replacing invalid characters with safe alternatives.
+/// </summary>
+public interface IFileNameSanitizer
+{
+    /// <summary>
+    /// Replaces invalid file name characters in the specified value.
+    /// </summary>
+    string Sanitize(string value);
+}
+

src/modules/Elsa.Workflows.Management/Contracts/IWorkflowDefinitionExporter.cs

@@ -0,0 +1,46 @@
+using Elsa.Common.Models;
+using Elsa.Workflows.Management.Entities;
+using Elsa.Workflows.Management.Models;
+
+namespace Elsa.Workflows.Management;
+
+/// <summary>
+/// Exports workflow definitions as serialized JSON or ZIP archives.
+/// </summary>
+public interface IWorkflowDefinitionExporter
+{
+    /// <summary>
+    /// Exports a single workflow definition as a JSON byte array, optionally including consuming workflows as a ZIP archive.
+    /// </summary>
+    /// <param name="definitionId">The definition ID.</param>
+    /// <param name="versionOptions">The version options. Defaults to <see cref="VersionOptions.Latest"/>.</param>
+    /// <param name="includeConsumingWorkflows">When true, includes all consuming workflow definitions in the export as a ZIP archive.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>An export result containing the binary content and a suggested file name, or null if the definition was not found.</returns>
+    Task<WorkflowDefinitionExportResult?> ExportAsync(string definitionId, VersionOptions? versionOptions = null, bool includeConsumingWorkflows = false, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Exports multiple workflow definitions as a ZIP archive.
+    /// </summary>
+    /// <param name="ids">A list of workflow definition version IDs.</param>
+    /// <param name="includeConsumingWorkflows">When true, includes all consuming workflow definitions in the export.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>An export result containing the ZIP binary content and a suggested file name, or null if no definitions were found.</returns>
+    Task<WorkflowDefinitionExportResult?> ExportManyAsync(ICollection<string> ids, bool includeConsumingWorkflows = false, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Serializes a single workflow definition entity to a JSON byte array (with $schema header).
+    /// </summary>
+    /// <param name="definition">The workflow definition entity.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The serialized JSON bytes and suggested file name.</returns>
+    Task<WorkflowDefinitionExportResult> ExportDefinitionAsync(WorkflowDefinition definition, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Exports multiple workflow definition entities as a ZIP archive.
+    /// </summary>
+    /// <param name="definitions">The workflow definitions to export.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The ZIP archive bytes and suggested file name.</returns>
+    Task<WorkflowDefinitionExportResult> ExportDefinitionsAsync(ICollection<WorkflowDefinition> definitions, CancellationToken cancellationToken = default);
+}

src/modules/Elsa.Workflows.Management/Features/WorkflowManagementFeature.cs

@@ -272,6 +272,8 @@ public override void Apply()
              .AddScoped<IWorkflowReferenceGraphBuilder, WorkflowReferenceGraphBuilder>()
              .AddScoped(_workflowDefinitionPublisher)
              .AddScoped<IWorkflowDefinitionImporter, WorkflowDefinitionImporter>()
+             .AddScoped<IWorkflowDefinitionExporter, WorkflowDefinitionExporter>()
+             .AddSingleton<IFileNameSanitizer, DefaultFileNameSanitizer>()
              .AddScoped<IWorkflowDefinitionManager, WorkflowDefinitionManager>()
              .AddScoped<IWorkflowInstanceManager, WorkflowInstanceManager>()
              .AddScoped<IWorkflowReferenceUpdater, WorkflowReferenceUpdater>()

src/modules/Elsa.Workflows.Management/Models/WorkflowDefinitionExportResult.cs

@@ -0,0 +1,8 @@
+namespace Elsa.Workflows.Management.Models;
+
+/// <summary>
+/// Represents the result of exporting one or more workflow definitions.
+/// </summary>
+/// <param name="Data">The binary content (JSON or ZIP).</param>
+/// <param name="FileName">The suggested file name.</param>
+public record WorkflowDefinitionExportResult(byte[] Data, string FileName);

src/modules/Elsa.Workflows.Management/Services/DefaultFileNameSanitizer.cs

@@ -0,0 +1,33 @@
+namespace Elsa.Workflows.Management.Services;
+
+/// <inheritdoc />
+public class DefaultFileNameSanitizer : IFileNameSanitizer
+{
+    private static readonly char[] InvalidFileNameCharacters = Path.GetInvalidFileNameChars();
+
+    /// <inheritdoc />
+    public string Sanitize(string value)
+    {
+        for (var i = 0; i < value.Length; i++)
+        {
+            if (!IsInvalidFileNameCharacter(value[i]))
+                continue;
+
+            return string.Create(value.Length, (value, i), static (buffer, state) =>
+            {
+                state.value.AsSpan(0, state.i).CopyTo(buffer);
+
+                for (var j = state.i; j < state.value.Length; j++)
+                {
+                    var character = state.value[j];
+                    buffer[j] = IsInvalidFileNameCharacter(character) ? '-' : character;
+                }
+            });
+        }
+
+        return value;
+    }
+
+    private static bool IsInvalidFileNameCharacter(char character) => character is '/' or '\\' || Array.IndexOf(InvalidFileNameCharacters, character) >= 0;
+}
+