Loading Workflows from JSON

Loading workflows from JSON is a great way to store workflows in a database or file system. This guide will show you how to load workflows from JSON files.

Console application

The most straightforward way to load workflows from JSON files is to simply load the contents of a JSON file, deserialise it and then execute the deserialised workflow.

1

Create Console Project

dotnet new console -n "ElsaConsole" -f net8.0
cd ElsaConsole
dotnet add package Elsa
dotnet add package Elsa.Testing.Shared.Integration

2

Update Program.cs

Here's a complete Program.cs file that demonstrates how to load a workflow from a JSON file and execute it:

Program.cs

using Elsa.Extensions;
using Elsa.Testing.Shared;
using Elsa.Workflows.Contracts;
using Elsa.Workflows.Management.Mappers;
using Elsa.Workflows.Management.Models;
using Microsoft.Extensions.DependencyInjection;

// Setup service container.
var services = new ServiceCollection();

// Add Elsa services.
services.AddElsa();

// Build service container.
var serviceProvider = services.BuildServiceProvider();

// Populate registries. This is only necessary for applications  that are not using hosted services.
await serviceProvider.PopulateRegistriesAsync();

// Import a workflow from a JSON file.
var workflowJson = await File.ReadAllTextAsync("HelloWorld.json");

// Get a serializer to deserialize the workflow.
var serializer = serviceProvider.GetRequiredService<IActivitySerializer>();

// Deserialize the workflow model.
var workflowDefinitionModel = serializer.Deserialize<WorkflowDefinitionModel>(workflowJson);

// Map the model to a Workflow object.
var workflowDefinitionMapper = serviceProvider.GetRequiredService<WorkflowDefinitionMapper>();
var workflow = workflowDefinitionMapper.Map(workflowDefinitionModel);

// Get a workflow runner to run the workflow.
var workflowRunner = serviceProvider.GetRequiredService<IWorkflowRunner>();

// Run the workflow.
await workflowRunner.RunAsync(workflow);

3

Create Workflow JSON file

Create a new file called HelloWorld.json in the root of the project and make sure it is configured to be copied to the output directory.

HelloWorld.json

{
  "id": "HelloWorld-v1",
  "definitionId": "HelloWorld",
  "name": "Hello World",
  "isLatest": true,
  "isPublished": true,
  "root": {
    "id": "Flowchart1",
    "type": "Elsa.Flowchart",
    "activities": [
      {
        "id": "WriteLine1",
        "type": "Elsa.WriteLine",
        "text": {
          "typeName": "String",
          "expression": {
            "type": "Literal",
            "value": "Hello World!"
          }
        }
      }
    ]
  }
}

4

Run the Program

Run the program:

dotnet run

The console should output the following:

Hello World!

Elsa Server

When you're hosting an Elsa Server, providing workflows from JSON files is even easier.

All you need to do is create a folder called Workflows and add any number of workflow JSON files to it.

Let's try it out:

1

Setup Elsa Server

Setup an Elsa Server project.

2

Create Workflows Folder

Create a new folder called Workflows.

3

Create Workflow JSON File

Create a new file called HelloWorld.json in the root of the project and make sure it is configured to be copied to the output directory.

HelloWorld.json

{
  "id": "HelloWorld-v1",
  "definitionId": "HelloWorld",
  "name": "Hello World",
  "isLatest": true,
  "isPublished": true,
  "root": {
    "id": "Flowchart1",
    "type": "Elsa.Flowchart",
    "activities": [
      {
        "id": "WriteLine1",
        "type": "Elsa.WriteLine",
        "text": {
          "typeName": "String",
          "expression": {
            "type": "Literal",
            "value": "Hello World!"
          }
        }
      }
    ]
  }
}

4

Run the Program

Run the program:

dotnet run --urls "https://localhost:5001"

5

Run the Workflow

Run the workflow using the following curl:

curl --location --request POST 'https://localhost:5001/elsa/api/workflow-definitions/HelloWorld/execute' \
--header 'Authorization: ApiKey {your-api-key}'

Alternatively, start an Elsa Studio container and run the workflow from there.

Loading Workflows from Blob Storage

If you need to load workflows from cloud blob storage (Azure Blob Storage, AWS S3, etc.), Elsa provides a dedicated workflow provider package:

dotnet add package Elsa.WorkflowProviders.BlobStorage

Note: Earlier documentation may have incorrectly referenced Elsa.WorkflowProviders.FluentStorage. The correct package name is Elsa.WorkflowProviders.BlobStorage.

The base provider handles .json files. To load the separate ElsaScript DSL from .elsa files, install the ElsaScript Blob Storage package and follow Loading Workflows from ElsaScript.

For provider behavior, reload operations, and custom external sources, see Workflow Providers.

Summary

In this guide, we've demonstrated configuring an Elsa Server to host workflows from JSON files. We covered loading a JSON file, deserialising it into the Workflow class, and executing the workflow.