# BPMN and Native Schemes

[BPMN Plugin](https://docs.workflowengine.io/plugins/bpmn-plugin/) converts BPMN diagrams into native Workflow Engine
[schemes](https://docs.workflowengine.io/get-started/concepts/scheme/). Native activities, transitions, and dependent process instances define
execution after import. Understanding this mapping helps you preserve the source process's intended behavior when
adding application code, command handling, authorization, and parallel execution to an imported diagram.

Workflow Engine executes the converted native scheme rather than BPMN XML directly. BPMN-shaped elements help
modelers recognize tasks, gateways, and events in the Designer, but the plugin implements a selected subset of BPMN
behavior. Review [Supported Elements](https://docs.workflowengine.io/plugins/bpmn-plugin/supported-elements/) before choosing the import path.

## Compare model building blocks

BPMN specializes nodes into tasks, gateways, and events. Workflow Engine expresses executable flow through
[activities](https://docs.workflowengine.io/get-started/concepts/activity/) and [transitions](https://docs.workflowengine.io/get-started/concepts/transition/). The configuration
of both elements determines how a native scheme behaves; a rectangular activity is not necessarily a BPMN Task.

| BPMN concept | Native scheme relationship |
|---|---|
| Task | Usually becomes an activity; supported service-task implementation names reference native actions. |
| Gateway | Becomes an ordinary or custom activity plus routing settings on transitions. |
| Event | Becomes an initial, final, or intermediate activity, or a trigger attached to a transition. |
| Sequence Flow | Becomes a transition, possibly with command, timer, condition, or parallel settings. |

An activity can execute [actions](https://docs.workflowengine.io/get-started/concepts/action/) while its outgoing transitions control the next step.
An activity with command-triggered transitions can represent an event wait while still running implementation code
when entered. An activity with parallel-start transitions can create dependent branches. A custom BPMN shape helps
display that intent without changing the native execution model.

## Compare sequence flows and transitions

A BPMN Sequence Flow connects source and target nodes, while event and gateway definitions contribute additional
execution semantics. A native transition combines the destination with the trigger, condition, access restrictions,
and subprocess settings that determine how execution can move there.

| Native transition setting | Responsibility after import |
|---|---|
| Automatic trigger | Continue without waiting for a command or timer when conditions permit. |
| [Command](https://docs.workflowengine.io/get-started/concepts/command/) trigger | Wait for the application or a user to execute the named command. |
| [Timer](https://docs.workflowengine.io/get-started/concepts/timer/) trigger | Wait for a native timer derived from a supported BPMN timer definition. |
| [Condition](https://docs.workflowengine.io/get-started/concepts/condition/) | Select routing using a named condition implementation or native expression. |
| [Rule](https://docs.workflowengine.io/get-started/concepts/rule/) restriction | Filter available commands for application identities or roles; restrictions can also be checked during execution. |
| Parallel start/finalization | Create and coordinate dependent subprocess branches. |

For example, a BPMN message catch event becomes a command wait on an outgoing transition. The application handles
the external message and executes that command for the correct process instance. The plugin does not infer broker
subscriptions or access-control rules from the visual event or its lane.

A typical controller calls `GetAvailableCommandsAsync` for the user, finds the requested command by
name in the returned list, fills its parameters, and executes that `WorkflowCommand` with
`ExecuteCommandAsync` for the same user. Restrictions are checked when commands are retrieved;
execution does not repeat that check by default.

Use `ExecuteCommandWithRestrictionCheckAsync` or `ExecuteCommandAsync` with `checkRestrictions: true`
when the command is created directly or restrictions need to be checked again during execution.

## Compare parallel execution models

BPMN describes concurrent paths using tokens. A Parallel Gateway explicitly creates paths; multiple outgoing flows
from some tasks or events can also express parallelism. Several tokens can remain active inside one BPMN process
until the model merges or ends those paths.

Workflow Engine represents parallel execution with dependent
[subprocesses](https://docs.workflowengine.io/get-started/concepts/subprocess/). Each subprocess is a separate
[process instance](https://docs.workflowengine.io/get-started/concepts/process-instance/) with its own ID and one current activity. Parallel-start
transitions create those instances, and finalization transitions coordinate their completion with the parent.
The process tree relates the root, parent, and child instances so application code can inspect and manage the branches.

To list the current activities of the root process and all its descendants, call
`GetProcessInstancesTreeAsync(rootProcessId)`, include the returned tree's `Id` and every ID from
`GetAllChildrenIds()`, then call `GetCurrentActivityNameAsync` for each ID. The native model tracks one current
activity per instance while the process tree represents the concurrent branches.

Runtime operations can also manage the related instances together. For example, `DeleteInstanceAsync(rootProcessId)`
deletes the root process and all descendant subprocesses. Apply the host application's authorization before invoking
such operations.

BPMN Plugin translates supported implicit and explicit parallel flows into these native settings. Its Parallel
Gateway custom activity and build steps prepare the split/join structure and add the `BPMNMerge` condition where
needed. Recognizable gateway shapes do not remove the need to validate native fork/join structure or review
unsupported inclusive and complex gateway semantics.

## Distinguish nested flows from subprocesses

A BPMN Subprocess contains a nested flow within a process model and can be displayed expanded or collapsed in BPMN
notation. The BPMN term does not mean the same thing as a
Workflow Engine runtime subprocess. BPMN Plugin maps nonempty embedded subprocesses through
[Scheme Inlining](https://docs.workflowengine.io/glossary/designing-workflows/#reuse-and-versioning), which expands another scheme at build time.

| Term | Meaning in Workflow Engine |
|---|---|
| Inline Activity | A parent-scheme placeholder that references another scheme by code. |
| Inlinable Scheme | A reusable scheme whose activities and transitions are embedded into the parent's built definition. |
| Runtime Subprocess | A dependent process instance created by a parallel-start transition, with a separate lifecycle and identity. |

The importer creates both an Inline Activity in the parent and an inlinable scheme for the nested BPMN flow. Store
both schemes so the builder can resolve the reference. Inlining alone executes as part of one process instance;
parallel transitions inside the expanded scheme can still create runtime subprocesses.

Native inlinable schemes can be reused by several parent schemes. The default Call Activity converter does not
automatically invoke the BPMN `calledElement`; it creates an ordinary activity with a warning. Use a
[custom visitor](https://docs.workflowengine.io/plugins/bpmn-plugin/customize-bpmn-import/#replace-call-activity-conversion)
when a Call Activity should reference a reusable native scheme or another application operation.

## Prepare an executable native scheme

BPMN XML can describe a business process without providing the code and integrations needed to execute it.
BPMN Plugin provides structural conversion; the application supplies the native execution contract and verifies that
the converted behavior matches the business process.

| Application responsibility | What to verify after import |
|---|---|
| Action and condition implementations | Imported service-task action names and named gateway conditions resolve to your providers or code actions. |
| Message handling | External event handlers locate the correct process and execute its imported command. |
| Access control | Rules define allowed identities or roles. Check restrictions when retrieving available commands or during execution. Lane membership does not grant authorization. |
| Instance creation | The application creates instances explicitly; imported message/timer starts control an existing instance's outgoing transitions. |
| Persistence and scheme dependencies | Parent, pool, and inlinable schemes are stored with the expected scheme codes. |
| Execution verification | Import issues, unsupported-event fallbacks, timer waits, branches, joins, and termination match the intended result. |

Native [Workflow Runtime](https://docs.workflowengine.io/get-started/concepts/workflow-runtime/) also exposes direct activity/state-setting APIs
for administrative or application-directed movement. This is separate from executing an ordinary transition and
must follow the application's own authorization. For ordinary imported nodes, a BPMN name becomes the native state
and enables state setting; unnamed nodes do not become state targets automatically. Give state targets unambiguous
names when direct state selection is part of the integration.

BPMN Plugin does not synchronize later changes between the BPMN source and the imported native scheme, and it
provides no BPMN export API. Keep the native scheme as the editing and execution artifact after import. If both
models continue to change, the application or modeling process must reconcile them explicitly.

## See also

The BPMN Plugin reference and import guide connect these execution differences to concrete configuration and
conversion steps.

- [Supported Elements](https://docs.workflowengine.io/plugins/bpmn-plugin/supported-elements/): Check exact mappings and limitations for each BPMN element family.
- [Import BPMN Diagrams](https://docs.workflowengine.io/plugins/bpmn-plugin/import-bpmn-diagrams/): Convert diagrams, inspect issues, and save native schemes.
- [Overview](https://docs.workflowengine.io/plugins/bpmn-plugin/overview/): Register the plugin and understand its native runtime integration.

## Frequently asked questions

**Does Workflow Engine execute BPMN XML directly?**

No. BPMN Plugin converts supported BPMN elements into native schemes, and Workflow Runtime executes those schemes.
Unsupported semantics can require changes or custom conversion.

**Is a Workflow Engine activity the same as a BPMN task?**

No. An activity can represent a task, gateway, or event, depending on its implementation and outgoing transitions.
BPMN-shaped custom activities express selected behavior using the same native scheme model.

**Does an imported BPMN subprocess create another process instance?**

A nonempty embedded BPMN Subprocess imports as Scheme Inlining, which expands its flow into the parent's definition.
Separate runtime subprocess instances are created by native parallel-start transitions.

**Can I export an edited native scheme back to BPMN?**

BPMN Plugin exposes import without a corresponding BPMN export API. Native scheme edits and later BPMN source changes
are independent and require explicit reconciliation.