BPMN and Native Schemes
BPMN Plugin converts BPMN diagrams into native Workflow Engine schemes. 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 before choosing the import path.
Compare model building blocks
BPMN specializes nodes into tasks, gateways, and events. Workflow Engine expresses executable flow through activities and transitions. 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 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 trigger | Wait for the application or a user to execute the named command. |
| Timer trigger | Wait for a native timer derived from a supported BPMN timer definition. |
| Condition | Select routing using a named condition implementation or native expression. |
| 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. Each subprocess is a separate 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, 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 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 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
Check exact mappings and limitations for each BPMN element family.
Import BPMN Diagrams
Convert diagrams, inspect issues, and save native schemes.
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.