Install Workflow Engine
Install Workflow Engine in an ASP.NET Core project by adding NuGet packages, registering services, configuring the database provider, setting up CORS, and mapping API endpoints for the runtime, designer, and Swagger. Run the application, verify the API through Swagger UI, and optionally launch the standalone Designer connected to the local Web API.
This page walks through adding Workflow Engine to an ASP.NET Core application using the Web API packages. This is the recommended integration path for ASP.NET Core projects. For console apps, worker services, and non-ASP.NET hosts, see Framework-Agnostic Install.
For the full reference covering every option, see Web API Setup.
Prerequisites:
- .NET SDK 10.0
- A running database (SQL Server, PostgreSQL, MySQL, Oracle, MongoDB) - SQLite uses a local file and does not require a running server
Step 1: Create a new ASP.NET project
Create a web API project using the .NET SDK:
dotnet new webapi -n WorkflowApi --framework net10.0cd WorkflowApiStep 2: Install packages and register services
Choose your database provider. Each tab shows the NuGet packages to install and the corresponding Program.cs setup.
dotnet add package OptimaJet.Workflow.Apidotnet add package OptimaJet.Workflow.Api.Sqlitedotnet add package Swashbuckle.AspNetCoreConfigure Program.cs (copy and paste):
using System.Text.Json.Serialization;using Microsoft.AspNetCore.Mvc;using OptimaJet.Workflow.Api;using OptimaJet.Workflow.Api.Options;using OptimaJet.Workflow.Api.Sqlite;using OptimaJet.Workflow.Core.Runtime;var builder = WebApplication.CreateBuilder(args);// Configure JSON options for enum serialization.builder.Services.AddControllers().AddJsonOptions(ConfigureJson);// Configure Workflow API services.builder.Services.AddWorkflowApiSqlite();builder.Services.AddWorkflowApiCore(SetupWorkflowApiCore);builder.Services.AddWorkflowRuntime(SetupWorkflowRuntime);// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbucklebuilder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen();builder.Services.AddCors(options =>{ options.AddDefaultPolicy(policy => { policy.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader(); });});var app = builder.Build();// Enable middleware to serve generated OpenAPI as a JSON endpoint and the Swagger UI.app.UseSwagger();app.UseSwaggerUI();// Configure routing and map the Workflow API endpoints.app.UseRouting();app.UseCors();app.MapWorkflowApi();app.Run();void ConfigureJson(JsonOptions options){ options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());}void SetupWorkflowApiCore(WorkflowApiCoreOptions options){ // options.LicenseKey = "PUT YOUR LICENSE KEY HERE";}void SetupWorkflowRuntime(WorkflowTenantCreationOptions options){ options.ConnectionString = "Data Source=workflow_engine.db"; options.WorkflowRuntimeCreationOptions.ConfigureWorkflowRuntime = runtime => { runtime.AsSingleServer(); };}dotnet add package OptimaJet.Workflow.Apidotnet add package OptimaJet.Workflow.Api.Mssqldotnet add package Swashbuckle.AspNetCoreConfigure Program.cs (copy and paste):
using System.Text.Json.Serialization;using Microsoft.AspNetCore.Mvc;using OptimaJet.Workflow.Api;using OptimaJet.Workflow.Api.Options;using OptimaJet.Workflow.Api.Mssql;using OptimaJet.Workflow.Core.Runtime;var builder = WebApplication.CreateBuilder(args);// Configure JSON options for enum serialization.builder.Services.AddControllers().AddJsonOptions(ConfigureJson);// Configure Workflow API services.builder.Services.AddWorkflowApiMssql();builder.Services.AddWorkflowApiCore(SetupWorkflowApiCore);builder.Services.AddWorkflowRuntime(SetupWorkflowRuntime);// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbucklebuilder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen();builder.Services.AddCors(options =>{ options.AddDefaultPolicy(policy => { policy.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader(); });});var app = builder.Build();// Enable middleware to serve generated OpenAPI as a JSON endpoint and the Swagger UI.app.UseSwagger();app.UseSwaggerUI();// Configure routing and map the Workflow API endpoints.app.UseRouting();app.UseCors();app.MapWorkflowApi();app.Run();void ConfigureJson(JsonOptions options){ options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());}void SetupWorkflowApiCore(WorkflowApiCoreOptions options){ // options.LicenseKey = "PUT YOUR LICENSE KEY HERE";}void SetupWorkflowRuntime(WorkflowTenantCreationOptions options){ options.ConnectionString = "PUT YOUR CONNECTION STRING HERE"; options.WorkflowRuntimeCreationOptions.ConfigureWorkflowRuntime = runtime => { runtime.AsSingleServer(); };}dotnet add package OptimaJet.Workflow.Apidotnet add package OptimaJet.Workflow.Api.Mysqldotnet add package Swashbuckle.AspNetCoreConfigure Program.cs (copy and paste):
using System.Text.Json.Serialization;using Microsoft.AspNetCore.Mvc;using OptimaJet.Workflow.Api;using OptimaJet.Workflow.Api.Options;using OptimaJet.Workflow.Api.Mysql;using OptimaJet.Workflow.Core.Runtime;var builder = WebApplication.CreateBuilder(args);// Configure JSON options for enum serialization.builder.Services.AddControllers().AddJsonOptions(ConfigureJson);// Configure Workflow API services.builder.Services.AddWorkflowApiMysql();builder.Services.AddWorkflowApiCore(SetupWorkflowApiCore);builder.Services.AddWorkflowRuntime(SetupWorkflowRuntime);// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbucklebuilder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen();builder.Services.AddCors(options =>{ options.AddDefaultPolicy(policy => { policy.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader(); });});var app = builder.Build();// Enable middleware to serve generated OpenAPI as a JSON endpoint and the Swagger UI.app.UseSwagger();app.UseSwaggerUI();// Configure routing and map the Workflow API endpoints.app.UseRouting();app.UseCors();app.MapWorkflowApi();app.Run();void ConfigureJson(JsonOptions options){ options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());}void SetupWorkflowApiCore(WorkflowApiCoreOptions options){ // options.LicenseKey = "PUT YOUR LICENSE KEY HERE";}void SetupWorkflowRuntime(WorkflowTenantCreationOptions options){ options.ConnectionString = "PUT YOUR CONNECTION STRING HERE"; options.WorkflowRuntimeCreationOptions.ConfigureWorkflowRuntime = runtime => { runtime.AsSingleServer(); };}dotnet add package OptimaJet.Workflow.Apidotnet add package OptimaJet.Workflow.Api.Postgresdotnet add package Swashbuckle.AspNetCoreConfigure Program.cs (copy and paste):
using System.Text.Json.Serialization;using Microsoft.AspNetCore.Mvc;using OptimaJet.Workflow.Api;using OptimaJet.Workflow.Api.Options;using OptimaJet.Workflow.Api.Postgres;using OptimaJet.Workflow.Core.Runtime;var builder = WebApplication.CreateBuilder(args);// Configure JSON options for enum serialization.builder.Services.AddControllers().AddJsonOptions(ConfigureJson);// Configure Workflow API services.builder.Services.AddWorkflowApiPostgres();builder.Services.AddWorkflowApiCore(SetupWorkflowApiCore);builder.Services.AddWorkflowRuntime(SetupWorkflowRuntime);// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbucklebuilder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen();builder.Services.AddCors(options =>{ options.AddDefaultPolicy(policy => { policy.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader(); });});var app = builder.Build();// Enable middleware to serve generated OpenAPI as a JSON endpoint and the Swagger UI.app.UseSwagger();app.UseSwaggerUI();// Configure routing and map the Workflow API endpoints.app.UseRouting();app.UseCors();app.MapWorkflowApi();app.Run();void ConfigureJson(JsonOptions options){ options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());}void SetupWorkflowApiCore(WorkflowApiCoreOptions options){ // options.LicenseKey = "PUT YOUR LICENSE KEY HERE";}void SetupWorkflowRuntime(WorkflowTenantCreationOptions options){ options.ConnectionString = "PUT YOUR CONNECTION STRING HERE"; options.WorkflowRuntimeCreationOptions.ConfigureWorkflowRuntime = runtime => { runtime.AsSingleServer(); };}dotnet add package OptimaJet.Workflow.Apidotnet add package OptimaJet.Workflow.Api.Oracledotnet add package Swashbuckle.AspNetCoreConfigure Program.cs (copy and paste):
using System.Text.Json.Serialization;using Microsoft.AspNetCore.Mvc;using OptimaJet.Workflow.Api;using OptimaJet.Workflow.Api.Options;using OptimaJet.Workflow.Api.Oracle;using OptimaJet.Workflow.Core.Runtime;var builder = WebApplication.CreateBuilder(args);// Configure JSON options for enum serialization.builder.Services.AddControllers().AddJsonOptions(ConfigureJson);// Configure Workflow API services.builder.Services.AddWorkflowApiOracle();builder.Services.AddWorkflowApiCore(SetupWorkflowApiCore);builder.Services.AddWorkflowRuntime(SetupWorkflowRuntime);// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbucklebuilder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen();builder.Services.AddCors(options =>{ options.AddDefaultPolicy(policy => { policy.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader(); });});var app = builder.Build();// Enable middleware to serve generated OpenAPI as a JSON endpoint and the Swagger UI.app.UseSwagger();app.UseSwaggerUI();// Configure routing and map the Workflow API endpoints.app.UseRouting();app.UseCors();app.MapWorkflowApi();app.Run();void ConfigureJson(JsonOptions options){ options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());}void SetupWorkflowApiCore(WorkflowApiCoreOptions options){ // options.LicenseKey = "PUT YOUR LICENSE KEY HERE";}void SetupWorkflowRuntime(WorkflowTenantCreationOptions options){ options.ConnectionString = "PUT YOUR CONNECTION STRING HERE"; options.WorkflowRuntimeCreationOptions.ConfigureWorkflowRuntime = runtime => { runtime.AsSingleServer(); };}dotnet add package OptimaJet.Workflow.Apidotnet add package OptimaJet.Workflow.Api.Mongodotnet add package Swashbuckle.AspNetCoreConfigure Program.cs (copy and paste):
using System.Text.Json.Serialization;using Microsoft.AspNetCore.Mvc;using OptimaJet.Workflow.Api;using OptimaJet.Workflow.Api.Options;using OptimaJet.Workflow.Api.Mongo;using OptimaJet.Workflow.Core.Runtime;var builder = WebApplication.CreateBuilder(args);// Configure JSON options for enum serialization.builder.Services.AddControllers().AddJsonOptions(ConfigureJson);// Configure Workflow API services.builder.Services.AddWorkflowApiMongo();builder.Services.AddWorkflowApiCore(SetupWorkflowApiCore);builder.Services.AddWorkflowRuntime(SetupWorkflowRuntime);// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbucklebuilder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen();builder.Services.AddCors(options =>{ options.AddDefaultPolicy(policy => { policy.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader(); });});var app = builder.Build();// Enable middleware to serve generated OpenAPI as a JSON endpoint and the Swagger UI.app.UseSwagger();app.UseSwaggerUI();// Configure routing and map the Workflow API endpoints.app.UseRouting();app.UseCors();app.MapWorkflowApi();app.Run();void ConfigureJson(JsonOptions options){ options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());}void SetupWorkflowApiCore(WorkflowApiCoreOptions options){ // options.LicenseKey = "PUT YOUR LICENSE KEY HERE";}void SetupWorkflowRuntime(WorkflowTenantCreationOptions options){ options.ConnectionString = "PUT YOUR CONNECTION STRING HERE"; options.WorkflowRuntimeCreationOptions.ConfigureWorkflowRuntime = runtime => { runtime.AsSingleServer(); };}The ConnectionString value in SetupWorkflowRuntime needs to point to your database. For SQLite, the default Data Source=workflow_engine.db creates a local file - update the path to match your project. For other providers, replace PUT YOUR CONNECTION STRING HERE with your actual connection string.
The LicenseKey line in SetupWorkflowApiCore is commented out by default. If you have a license key, uncomment the line and replace PUT YOUR LICENSE KEY HERE with your actual key.
To obtain a trial key, visit trial.workflowengine.io or use the API at /api/trial/llm. See the License Key page for details.
Without a license key, the Web API still serves the Workflow Designer (POST /designer), readiness probes (GET /readiness, GET /tenant-readiness), and liveness checks (GET /liveness). All other endpoints require a valid license key.
Step 3: Run and verify
Start the application:
dotnet run -- --urls "http://localhost:5274/"Open the Swagger UI at http://localhost:5274/swagger to explore and test the API endpoints.
Optional: Run the Designer standalone
You can launch the Workflow Designer as a standalone web application without embedding it into your own frontend. Run it via npx (no installation required):
npx @optimajet/workflow-designer http://localhost:5274/workflow-api/designer MyWorkflowSchemehttp://localhost:5274/workflow-api/designer- the URL of the Designer endpoint exposed by the Web APIMyWorkflowScheme- the scheme code to open in the Designer on startup
This opens a browser tab with the full Designer UI connected to your local Web API. Use it to create and edit workflow schemes interactively.
GitHub sample
A complete sample project covering all database providers, JWT security, API client generation, and integration tests is available on GitHub:
https://github.com/optimajet/WorkflowEngineApi.NET
Next steps
- Create Your First Workflow - save a scheme and create a process instance
- Integrate the Designer - run standalone or embed in your app
- Web API Setup - full configuration reference: options tables, DI registries, troubleshooting
- Web API Security - add JWT authentication before production
Frequently asked questions
Do I need a license key?
Yes. The Web API requires a license key. Request one from our sales team at sales@optimajet.com or get a trial key at trial.workflowengine.io. Set the key in the SetupWorkflowApiCore method.
Without a license key, the following endpoints still work:
POST /designer- Workflow Designer operationsGET /readiness- readiness probeGET /tenant-readiness- tenant readiness probeGET /liveness- liveness probe
Which database providers are supported?
MSSQL, PostgreSQL, MySQL, Oracle, MongoDB, and SQLite. Each has a corresponding OptimaJet.Workflow.Api.* package. Install one and call the matching extension method.
Can I disable authentication during development?
The Web API uses ASP.NET Core security. Configure it through the standard ASP.NET Core middleware. See Web API Security.
Can I use Workflow Engine without ASP.NET Core?
Yes. For console applications, worker services, and any non-ASP.NET host, use the direct WorkflowRuntime setup. See Framework-Agnostic Install.