# Install Workflow Engine

This page walks through adding Workflow Engine to an [ASP.NET](https://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](https://docs.workflowengine.io/get-started/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:

```bash
dotnet new webapi -n WorkflowApi --framework net10.0
cd WorkflowApi
```

## Step 2: Install packages and register services

Choose your database provider. Each tab shows the NuGet packages to install and the corresponding `Program.cs` setup. You can also [download
Workflow Engine packages and samples](https://workflowengine.io/downloads/) from
[workflowengine.io](https://workflowengine.io/).

<Tabs items={['SQLite', 'MS SQL Server', 'MySQL', 'PostgreSQL', 'Oracle', 'MongoDB']}>
<Tab>

  ```bash
  dotnet add package OptimaJet.Workflow.Api
  dotnet add package OptimaJet.Workflow.Api.Sqlite
  dotnet add package Swashbuckle.AspNetCore
  ```

Configure Program.cs (copy and paste):

  ```csharp filename="Program.cs"
  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/swashbuckle
  builder.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();
      };
  }
  ```

  </Tab>
  <Tab>

  ```bash
  dotnet add package OptimaJet.Workflow.Api
  dotnet add package OptimaJet.Workflow.Api.Mssql
  dotnet add package Swashbuckle.AspNetCore
  ```

Configure Program.cs (copy and paste):

  ```csharp filename="Program.cs"
  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/swashbuckle
  builder.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();
      };
  }
  ```

  </Tab>
  <Tab>

  ```bash
  dotnet add package OptimaJet.Workflow.Api
  dotnet add package OptimaJet.Workflow.Api.Mysql
  dotnet add package Swashbuckle.AspNetCore
  ```

Configure Program.cs (copy and paste):

  ```csharp filename="Program.cs"
  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/swashbuckle
  builder.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();
      };
  }
  ```

  </Tab>
  <Tab>

  ```bash
  dotnet add package OptimaJet.Workflow.Api
  dotnet add package OptimaJet.Workflow.Api.Postgres
  dotnet add package Swashbuckle.AspNetCore
  ```

Configure Program.cs (copy and paste):

  ```csharp filename="Program.cs"
  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/swashbuckle
  builder.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();
      };
  }
  ```

  </Tab>
  <Tab>

  ```bash
  dotnet add package OptimaJet.Workflow.Api
  dotnet add package OptimaJet.Workflow.Api.Oracle
  dotnet add package Swashbuckle.AspNetCore
  ```

Configure Program.cs (copy and paste):

  ```csharp filename="Program.cs"
  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/swashbuckle
  builder.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();
      };
  }
  ```

  </Tab>
  <Tab>

  ```bash
  dotnet add package OptimaJet.Workflow.Api
  dotnet add package OptimaJet.Workflow.Api.Mongo
  dotnet add package Swashbuckle.AspNetCore
  ```

Configure Program.cs (copy and paste):

  ```csharp filename="Program.cs"
  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/swashbuckle
  builder.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();
      };
  }
  ```

  </Tab>
</Tabs>

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](https://trial.workflowengine.io) or use the API
at [/api/trial/llm](https://docs.workflowengine.io/evaluate/license-key/#via-api-for-llm-agents-and-automation). See the [License Key](https://docs.workflowengine.io/evaluate/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:

```bash
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):

```bash
npx @optimajet/workflow-designer http://localhost:5274/workflow-api/designer MyWorkflowScheme
```

- `http://localhost:5274/workflow-api/designer` - the URL of the Designer endpoint exposed by the Web API
- `MyWorkflowScheme` - 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](https://github.com/optimajet/WorkflowEngineApi.NET)

## Next steps

- [Create Your First Workflow](https://docs.workflowengine.io/get-started/create-your-first-workflow/) - save a scheme and create a process instance
- [Integrate the Designer](https://docs.workflowengine.io/get-started/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?**

For the Data API and RPC API endpoints, yes: they are capabilities of Workflow Engine NEO and need its license key. Without a key, the Web
API still serves the Workflow Designer, readiness probes, and liveness checks, so [Workflow Engine
Free](https://workflowengine.io/products/community-edition/) can use it for the Designer. Get a trial key at
[trial.workflowengine.io](https://trial.workflowengine.io) or buy one through [contact sales](https://workflowengine.io/contacts/) at
[hello@optimajet.com](mailto:hello@optimajet.com). Set the key in the `SetupWorkflowApiCore` method.

Without a license key, the following endpoints still work:

- `POST /designer` - Workflow Designer operations
- `GET /readiness` - readiness probe
- `GET /tenant-readiness` - tenant readiness probe
- `GET /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](https://docs.workflowengine.io/get-started/framework-agnostic-install/).