# BPMN Support in the .NET Workflow Engine

Source: https://workflowengine.io/features/bpmn/
Site index for agents: https://workflowengine.io/llms.txt (products, licensing, documentation hosts, package names).

v22.1.0 · BPMN 2.0 import · [`WorkflowEngine.NETCore-BpmnPlugin`](https://www.nuget.org/packages/WorkflowEngine.NETCore-BpmnPlugin/) on NuGet · a licensed add-on, not part of Workflow Engine Free · Page last updated 22 September 2026

Your analysts draw in BPMN. That should not decide what your product runs on. Workflow Engine by Optimajet reads a BPMN 2.0 file, converts it into a scheme the engine executes, and names every element it could not carry across. The result runs in-process inside your own ASP.NET application, against your own database, with no JVM, no modeling server and no orchestration cluster to operate.

purchase-approval.bpmn · BpmnPlugin · import

BPMN 2.0, as your analyst drew it

convert

A Workflow Engine scheme, ready to execute

Every import ends with a log. It names the elements that converted, the ones that came in as plain activities, and the ones it skipped, with the reason for each. The same findings are attached as comments on the canvas, at the exact spot where you fix them.

## Import the diagram once and · BPMN becomes a process the engine runs

BPMN 2.0 is the OMG notation business analysts draw processes in. Tasks are rectangles, gateways are diamonds, events are circles, and the whole diagram serializes to XML. It is a notation, not a runtime, and a valid BPMN diagram may be an illustration that no engine can execute.

Workflow Engine is not a BPMN engine and does not pretend to be. It executes its own scheme format, built from three elements: activities, transitions, and commands. BPMN support is the bridge between the two. The plugin maps each BPMN element onto the closest runtime construct, and what it cannot map it records. The scheme it produces opens in [Workflow Designer](https://workflowengine.io/features/workflow-designer/) like any scheme drawn by hand, and runs on the same [.NET workflow engine](https://workflowengine.io/products/dotnet-workflow-engine/) as the rest of your processes.

### One file in, one scheme out

You upload a .bpmn file in Workflow Designer. The plugin reads the BPMN 2.0 XML and writes a Workflow Engine scheme into your database. From that moment the scheme is the thing that runs.

Initial activity

### It runs where your code runs

The engine is a NuGet package inside your own application. No BPMN platform to deploy, no JVM, no orchestration cluster, and no diagram leaving a network you control.

### One direction only

The plugin converts BPMN into a scheme and cannot convert a scheme back. Plan it as a one-way migration, with the Workflow Engine scheme as the editing format from then on.

### BPMN elements in the palette

Registering the plugin also adds a BPMN tab to the designer. The Parallel Gateway is worth having on its own, as the simplest way to fork and join subprocesses.

### Nothing is dropped in silence

Anything the importer cannot carry across is written to the import log with a reason, and commented on the affected element in the designer.

### A licensed add-on

BPMN import is licensed separately. The plugin checks that restriction when it is registered and throws if the license does not cover it, so you find out at startup rather than in production.

Current activity

## When BPMN import is the right tool

The importer reads BPMN 2.0 XML, so the tool that drew the file mostly does not matter. Camunda Modeler, Signavio, Bizagi and the browser-based editors all export the same standard, and Camunda's implementation attributes are read as well, so service tasks arrive with their action names attached. What decides whether this is worth doing is not the tool. It is the situation.

01

### Moving off a BPMN platform

You have a library of diagrams running on another engine, and re-drawing each one in a new designer is the reason the migration keeps getting postponed. Import them, add the runtime wiring, deploy. The flow structure transfers; commands, rules, actions and anything on the skipped list are the new work.

02

### Documentation that has to match production

Compliance keeps the approved process as a BPMN diagram in a modeling tool. Import that file and the executable scheme starts life as the approved design, so the audit question stops being whether the running process still resembles the document.

03

### A process someone hands you

A partner, a vendor or another department sends the integration workflow as BPMN 2.0 XML. Open the file rather than reading it and re-typing it into a designer, which is where transcription errors come from.

### And when it is not worth it

Two cases, said plainly. If you have three simple processes and no existing diagrams, drawing them in [Workflow Designer](https://workflowengine.io/features/workflow-designer/) takes less time than importing and re-wiring them. And if the elements on the skipped list are the point of your diagram, if you need certified conformance to the standard, or if the process is a choreography between organisations rather than something one application runs, then a BPMN engine is the right tool for that job and this is not it. Workflow Engine is a .NET workflow engine that reads BPMN. It has never claimed to be a BPMN engine, and the coverage below is written so you can check that against your own file before you spend a day on it.

## Which BPMN elements convert and which are skipped

Import is not lossless, so the question worth answering early is which parts of your diagram land on which side. Tasks, sequence flows, exclusive and parallel gateways, start and end events, and timer and message catch events convert into something the runtime executes. Boundary events, pools and their message flows, complex gateways, event subprocesses, data objects and artifacts are skipped and logged. Everything in between arrives as a plain activity that holds its place in the flow and waits for you.

| BPMN element | What it becomes in Workflow Engine |
| --- | --- |
| Start event | Initial activity, the first activity the runtime executes |
| End event | Final activity, completes the process instance |
| Service task | Intermediate activity with an auto-trigger |
| Exclusive (XOR) gateway | Custom activity type; outgoing transitions act as conditional branches |
| Parallel (AND) gateway | Custom activity type; enables concurrent execution paths |
| Timer catch event | Intermediate activity with a timer trigger |
| Message catch event | Intermediate activity that waits for an external command |
| Terminate event | Final activity that ends all parallel branches |

Runs as drawn

### Converts and runs

Sequence flows become transitions. Conditions on the outgoing flows of an exclusive gateway become the condition expressions on each transition. A parallel gateway produces concurrent outgoing transitions and the runtime executes every branch.

- Generic, Service and Receive tasks. The task ID becomes the activity name and the task name becomes the activity state.
- Exclusive, Parallel and Event-Based gateways. Both action-based conditions and expressions are supported on the exclusive gateway.
- Generic start and end events, plus the Terminate end event.
- Message and Timer intermediate catch events.
- Subprocesses, which become inline activities, so an embedded scheme can be reused by other schemes.
- Implicit parallelism, which is made explicit on import and drawn with dashed start and dash-dot join lines.

Needs a decision

### Imports whole, then waits on you

The structure arrives intact, and one choice is left open. Make it in Workflow Designer and the process behaves the way the diagram intended.

- Message and Timer start events. A start activity is created with an outgoing transition triggered by a command or a timer, and you confirm which.
- Several start events in one diagram. They merge into a single start activity with a transition for each original event.
- Service task action names. The importer reads camunda:topic, camunda:delegateExpression or the implementation property, splits that string on commas, and uses the parts as action names, so check that those names match actions you actually have.

Arrives empty

### Comes in as a plain activity you finish by hand

The element keeps its place in the flow, so the diagram still reads correctly, and its specialized behavior is yours to wire. Each one is named in the import log and commented on the canvas.

- User tasks. Support arrives with the plugin that integrates Workflow Engine with forms.
- Script, Manual, Send and Business Rule tasks.
- Inclusive gateways. Not supported by default because of how subprocesses are created, and Optimajet can add support quickly if it blocks you.
- Signal, Conditional and Link intermediate catch events, and every intermediate throw event.
- Call activities.

Not imported

### Skipped, with the reason in the log

These have no Workflow Engine equivalent, so the importer records them instead of guessing. Read this list first when you size a migration. It is where the re-drawing work comes from.

- Boundary events attached to activities.
- Pools and message flows between them.
- Complex gateways.
- Event subprocesses.
- Data objects and artifacts, which includes the text annotations analysts write the rules in.
- Lanes, which are ignored because Workflow Engine has no equivalent grouping.
- Custom extension elements, apart from the Camunda implementation attributes read on service tasks, and non-executable attributes such as documentation and graphical layout.

That is the outline. Every task, gateway and event is documented one at a time, with a screenshot of the converted result, in the [BPMN elements reference](https://workflowengine.io/documentation/bpmn-elements). Coverage is expanding: user tasks arrive with the forms integration, and the inclusive gateway can be added quickly on request.

## What your process gains once it runs on the engine

A BPMN diagram describes a process. A Workflow Engine scheme runs one, and a valid scheme is always ready to execute. That is what the import is for, and it is the other half of the decision you just weighed. Each item below is behavior a diagram can only annotate and the scheme actually enforces.

### Transitions that fire on their own

A sequence flow only points somewhere. A transition fires on a timer or a command, carries a condition, and decides whether the branch runs in parallel. The deadline your diagram documented in a text annotation becomes a timer the runtime actually honours.

### Commands restricted to real people

Actors are part of the scheme, so a command can be limited to named users or roles right where the process is drawn. That is access control the engine enforces, and BPMN has no way to state it on the diagram.

### Any state, on demand

A running process can be forced into any of its states. When a case goes wrong at two in the morning, support moves it instead of writing a database update, and the process carries on from there.

### The canvas shows it running

Pass a process id instead of a scheme code and [Workflow Designer](https://workflowengine.io/features/workflow-designer/) renders the live instance, highlighting the current activity as the process moves. The diagram your analyst drew becomes the screen your support team watches.

### Subprocesses you can manage together

Parallel branches become dependent subprocesses rather than extra tokens. You can list every activity the parent and its children are sitting in, and act on the whole family at once. Implicit parallelism in the diagram is made explicit on import, drawn with dashed start and dash-dot join lines.

### Your database and your deployment

The process runs in your application on your own storage: SQL Server, PostgreSQL, MongoDB, MySQL, Oracle, or SQLite outside production. One deployment can serve many customers, with the isolation model chosen per tenant on the [multi-tenant architecture](https://workflowengine.io/features/multi-tenancy/) page.

purchase-approval · before and after import · current activity

The note on the BPMN diagram is an artifact, and the importer skips it, because there was never anything in it to run. What it described is now on the scheme and enforced. A green pill is a command someone can run, and it carries the actor allowed to run it, so "Approve Manager" is one setting rather than a note about who ought to click. The question mark marks a transition with a condition, and the expression sits under it as a comment. Gray is what the runtime settles alone, which is why the three days are a gray timer. Orange marks where this instance is right now, and blue is both the way back and the way it ends.

[BPMN diagrams vs Workflow Engine schemes](https://workflowengine.io/documentation/bpmn-differences) · [Subprocesses and parallel processes](https://docs.workflowengine.io/evaluate/workflow-engine-features/parallel-processes/)

## How to enable BPMN import in a .NET app

One NuGet package and one registration on the runtime. There is no external modeler service to stand up and no second runtime to operate. Register the plugin where your `WorkflowRuntime` is built, restart, and Workflow Designer gains a BPMN tab on the elements panel and an Upload BPMN menu item. If your license does not cover BPMN, the plugin throws at that registration, so the failure is loud and happens at startup.

Install the plugin · bash

```bash
dotnet add package WorkflowEngine.NETCore-BpmnPlugin
```

Register it on the runtime · csharp

```csharp
var bpmnPlugin = new BpmnPlugin();

var runtime = new WorkflowRuntime()
    // ...your usual runtime configuration...
    .WithPlugin(bpmnPlugin)
    .Start();
```

### What the plugin registers

BpmnPlugin implements `IWorkflowPlugin` and adds eight custom activity types to the runtime: `ServiceTaskActivity`, `ExclusiveGateway`, `ParallelGateway`, `MessageCatchEvent`, `TimerCatchEvent`, `StartEvent`, `EndEvent` and `TerminateEvent`, plus the designer action `bpmnplugin_uploadbpmn`. They behave like any other activity type once they are there.

### Changing how an element converts

The importer is a set of visitor classes: `TaskNodeVisitor`, `GatewayNodeVisitor`, `EventNodeVisitor`, `SubprocessNodeVisitor`, `CallActivityNodeVisitor`, the matching flow visitors, and `ProcessVisitor` for the whole process. Inherit the one you care about, build a converter, and hand it to the plugin. Call activities, which the stock importer leaves as plain activities, are the usual first candidate.

Custom conversion for one element type · csharp

```csharp
BpmnConverter customBpmnConverter = BpmnConverterBuilder
    .Create()
    .WithCustomCallActivityNodeVisitor(new CustomCallActivityNodeVisitor())
    .Build();

var bpmnPlugin = new BpmnPlugin(customBpmnConverter);
```

Setup, the upload dialog and the full visitor list are covered in the [BPMN plugin guide](https://workflowengine.io/documentation/bpmn-plugin), and the rest of what ships alongside it, including how a plugin reaches the designer palette, is on [the Workflow Engine plugin system page](https://workflowengine.io/features/plugin-system/).

## From a modeler file to a running .NET process

The alternative to importing is re-drawing, and re-drawing is where process migrations die. Copying one diagram into a designer by hand takes hours, invites transcription errors, and leaves the design model and the running process drifting apart from day one. The import takes minutes per diagram and keeps the structure, so the work that is left is the work that was always going to be new: command bindings, rules, actions, and the elements on the skipped list.

1. 1

   ### Upload the .bpmn file

   Pick the file in the Upload BPMN dialog, set the main scheme code, and decide whether the import may overwrite schemes already in your database. That box is unchecked by default, so a re-import cannot quietly replace a scheme somebody has since adjusted.

2. 2

   ### The importer converts every element

   Tasks, gateways and events become their runtime counterparts, sequence flows become transitions, conditions on exclusive gateway flows become condition expressions, subprocesses become inline schemes, and implicit parallelism is made explicit.

3. 3

   ### Read the log before you touch anything

   The import log names what converted, what came in as a plain activity, and what was skipped, with a reason for each. You can copy it and send it to support. The same findings are attached as comments on the elements in the designer, so the gaps are marked where you will fix them.

4. 4

   ### Finish in the designer and start a process

   The result is an ordinary Workflow Engine scheme. Wire the remaining triggers, add code actions, set timer durations, then start processes against it. The BPMN file stays what it was, the input.

### Re-author by hand

Re-create every activity, transition, gateway and condition in the designer. Hours per process, transcription errors, and a design model that diverges from the running process from the first change.

### Import the diagram

Upload the BPMN 2.0 file, read the log, add the runtime wiring. Minutes per process, the core flow structure preserved, and the diagram your analysts maintain stays the one the engine runs.

One limit, stated plainly. The importer does not reproduce the behavior of the elements it skips, and it will not invent it. The structure survives, the log says exactly where the gaps are, and the designer is where you close them. Teams weighing this against staying on a JVM platform can read the [comparison of Java workflow engines](https://workflowengine.io/blog/java-workflow-engines-comparison/) first.

## What BPMN import costs

BPMN import is a paid add-on rather than something every tier carries, and the sooner you know that the better your plan. The BpmnPlugin checks for a BPMN license restriction when it is registered and throws on `OnPluginAdd` if the license does not include it, so a missing add-on shows up the first time you run the app. Workflow Engine Free cannot import BPMN. It still runs the engine and the full designer, so everything else on this page is yours to evaluate for nothing.

| Product and edition | BPMN import add-on |
| --- | --- |
| Workflow Engine Free | Not available |
| Workflow Engine Team and Complete | $2,500 one time |
| Workflow Engine NEO Subscription | $300 per year |
| Workflow Engine NEO Business | $3,500 one time |
| Workflow Engine NEO SaaS and Workflow Engine NEO Enterprise | Included |

Every license is perpetual on-premise per software product, with a subscription option also available, and there are no royalties and no per-execution fees. The full table sits on the [Workflow Engine pricing page](https://workflowengine.io/pricing/), and the tier that already bundles BPMN import alongside the multi-tenant API is covered on the [Workflow Engine NEO product page](https://workflowengine.io/products/workflow-engine-neo/).

## Common questions

Direct answers to what teams ask when they bring BPMN diagrams to a .NET application, including what converts automatically, which mappings need manual review, what the plugin costs, and what you can change.

1. ### Can I run BPMN 2.0 diagrams on .NET without a BPMN platform?

   Yes. Workflow Engine by Optimajet is a .NET library you add with NuGet and run in-process inside your own application. The BPMN Plugin converts supported parts of a BPMN 2.0 XML file into one or more native Workflow Engine schemes. After you review the conversion and complete any required runtime wiring, Workflow Runtime executes successfully converted and validated schemes in-process, using your configured persistence. You deploy your application and its persistence, but no separate JVM, BPMN modeling server, or orchestration cluster.

2. ### Which BPMN modeling tools can I import from?

   The importer accepts BPMN 2.0 XML. The documentation names Camunda Modeler, Signavio, and Bizagi as source examples; validate a representative export because supported elements, exporter versions, and vendor extensions vary. The importer also reads supported non-default Camunda implementation attributes on service tasks and turns them into Workflow Engine action names. It partially preserves the first BPMN DI diagram: activities keep their imported X/Y positions, and BPMN edge data supplies one calculated transition point. The importer preserves part of the diagram layout, but it does not turn BPMN documentation or other visual metadata into Workflow Engine behavior.

3. ### Is Workflow Engine a BPMN engine?

   No. Workflow Engine has its own execution model, so full conformance with the BPMN standard is not a goal. The BPMN Plugin adds BPMN elements to Workflow Designer and maps supported BPMN flow elements into native Workflow Engine schemes. A successfully converted scheme can run after you review the result and complete the application-specific actions, commands, rules, providers, and other required wiring.

4. ### Does BPMN import require a license?

   Yes. BPMN import is a paid add-on, and plugin registration fails when the current license does not include the BPMN entitlement. It is unavailable with Workflow Engine Free. The add-on is $2,500 one time for the Workflow Engine Team and Complete editions, $300 per year for Workflow Engine NEO Subscription, and $3,500 one time for Workflow Engine NEO Business. It is included with Workflow Engine NEO SaaS and Workflow Engine NEO Enterprise.

5. ### Which BPMN elements convert on import?

   The mapping depends on the exact element and topology. Generic start and end events become initial and final activities. Message and Timer start definitions map automatically to command or timer triggers; multiple event-defined starts can share an initial activity, while multiple generic starts are rejected. Service tasks become auto-triggered activities, and supported non-default Camunda implementation attributes can supply action names. A splitting Exclusive Gateway with several outgoing flows becomes a custom activity; its flow conditions become named Conditions or Expressions, while a join or single-outgoing gateway remains an ordinary activity. Parallel gateways create concurrent paths. Message and Timer Intermediate Catch Events have specialized command and timer mappings, but timer cycles and unsupported catch definitions produce issues. After an Event-Based Gateway, a supported catch-event or Receive Task node can be collapsed into a triggered transition. Non-empty subprocesses can create inline schemes, but event-start and loop or multi-instance semantics are not preserved automatically.

6. ### Which BPMN mappings are partial or unsupported?

   Supported BPMN flow elements are converted into native Workflow Engine activities and transitions, while some mappings need review. Interrupting Message and Timer Boundary Events become triggered transitions; other definitions and non-interrupting behavior may require manual adjustment and can produce an issue. Each root BPMN process can become a separate scheme, while pool and message-flow choreography is not reproduced. A Complex Gateway is imported as a regular Workflow Engine activity, and its outgoing flows become transitions; the importer reports that its BPMN semantics are not supported. An Event Subprocess follows the ordinary inline-subprocess path, so its event-start behavior is not preserved automatically. Data objects and artifacts do not become runtime constructs. Lanes, documentation, extensions, and other BPMN-specific details may need to be checked against the source diagram. BPMN DI layout is partially preserved.

7. ### What happens to elements the importer cannot map?

   The importer converts supported flow into native Workflow Engine activities and transitions. When a task or gateway has no direct mapping, it can still be represented as an ordinary activity or transition that you complete in Workflow Designer. Detected limitations are included in the import report and, when there is a corresponding Workflow Engine element, may also be added to that activity or transition as a comment. The report includes the save status of each generated scheme. Review the converted scheme against the source diagram and complete any application-specific wiring before execution.

8. ### Can I export a Workflow Engine scheme back to BPMN 2.0?

   No. The BpmnPlugin is import-only. A scheme edited in Workflow Designer or changed at runtime cannot be exported back to BPMN XML. Use the designer’s own scheme export for backups and the native Simple Process Notation for version control. Plan the import as a one-way migration, with the Workflow Engine scheme as the editing format from that point on.

9. ### Can I edit an imported BPMN process afterwards?

   Yes. After import, the result is a native Workflow Engine scheme that opens in Workflow Designer. You can edit ordinary activities and transitions and add actions, conditions, rules, and timers. BPMN custom activities keep BPMN-specific Designer behavior so they can follow the corresponding standard BPMN elements as closely as the Workflow Engine model allows.

10. ### How do I install the BPMN Plugin?

    Add the NuGet package with dotnet add package WorkflowEngine.NETCore-BpmnPlugin, register it on your runtime with .WithPlugin(new BpmnPlugin()), and restart the application. Workflow Designer then gains a BPMN tab on the elements panel and an Upload BPMN menu item. In the upload dialog you set the main scheme code and decide whether the import may overwrite schemes already in your database.

11. ### Can I change how a BPMN element is converted?

    Yes. The importer is built from visitor classes, including TaskNodeVisitor, GatewayNodeVisitor, EventNodeVisitor, SubprocessNodeVisitor, CallActivityNodeVisitor, the matching flow visitors, and ProcessVisitor for the whole process. Inherit the one you want to change, register it through BpmnConverterBuilder, and pass the resulting converter to the BpmnPlugin constructor. Call activities, for example, can get your own conversion logic without touching the engine.

12. ### Is this a realistic way to migrate off Camunda?

    It can provide a useful starting point. The importer accepts BPMN 2.0 XML; validate a representative export from Camunda Modeler, Signavio, or Bizagi. Supported structure can map into one or more native schemes. Review partial mappings and BPMN-specific behavior against the source diagram, then recreate or verify commands, actions, rules, providers, timers, and other application-specific behavior. Treat the import as a one-way migration aid, not a fidelity-preserving converter or a time estimate.

## Bring the diagram that has been hard to run

Send us a real .bpmn file, not a toy one. We import it together, read the log line by line, and you leave knowing which parts of your process run as drawn and which need a hand in the designer. The session runs an hour. If you would rather start in code first, Workflow Engine Free gets the engine and the full designer running inside your own application, and BPMN import is added with the license when you are ready for it.

In production since 2014 at Dell, KPMG, Bosch, and GE Honda Aero Engines.

### Still comparing options

Four documentation pages, in order, take you from the core concepts to a working import. This page is the decision; those are the reference.

01

#### [BPMN support overview](https://docs.workflowengine.io/evaluate/workflow-engine-features/bpmn-support/)

What the plugin is, the element mapping table, and where import fidelity ends.

Read it · 02

#### [BPMN diagrams vs Workflow Engine schemes](https://workflowengine.io/documentation/bpmn-differences)

The concepts behind the conversion, and why an activity is not a task.

Read it · 03

#### [BPMN elements support](https://workflowengine.io/documentation/bpmn-elements)

The element-by-element reference, every task, gateway and event, one at a time.

Read it · 04

#### [Using the BPMN plugin](https://workflowengine.io/documentation/bpmn-plugin)

Install it, upload a diagram, read the import log, and customize the conversion.

Read it

## Sitemap

[Sitemap of workflowengine.io](https://workflowengine.io/sitemap.md): every page of the site, with the description each page carries.