# Import BPMN Diagrams

Import BPMN diagrams through the [Designer](https://docs.workflowengine.io/get-started/integrate-the-designer/) after registering
BpmnPlugin: select **Upload BPMN**, choose the main scheme code and overwrite policy, then inspect
the conversion log. The result is one or more native [schemes](https://docs.workflowengine.io/get-started/concepts/scheme/) that
you review, connect to application behavior, and execute with
[Workflow Runtime](https://docs.workflowengine.io/get-started/concepts/workflow-runtime/).

## Prepare an import

BPMN import requires a backend configured with a builder, a persistence provider, and a registered
BpmnPlugin instance. Register a [license](https://docs.workflowengine.io/evaluate/license-key/) with the BPMN capability before
adding the plugin, and reload the Designer after updating backend configuration.

Export BPMN 2.0 XML from the modeling tool, normally as a `.bpmn` file. A Visio document, screenshot,
or PDF diagram is not a BPMN interchange document. Files from external modelers still need review:
the converter supports particular BPMN structures and selected service-task attributes, rather than
the execution extensions of every modeling product.

Include BPMN diagram layout data when exporting from the modeler. Conversion can return definitions without
layout data, but some later split and merge build steps require integer Designer coordinates. For example, a
message catch with multiple outgoing transitions needs coordinates on its message activity to create the split.

For a first import, use a new scheme code and leave overwrite disabled. Successful verification means:

- The log reports successful saves for the intended main and dependency schemes.
- Every warning has been reviewed against the intended business behavior.
- The Designer displays the expected activities and transitions.
- The application's actions, conditions, command authorization, and timers have been verified on
  the converted scheme before business data is processed.

## Upload a diagram

BPMN Plugin adds **Upload BPMN** to the Designer menu. Open that menu and select **Upload BPMN**
to choose a BPMN file.

![Upload BPMN item highlighted in the Designer menu](https://docs.workflowengine.io/images/plugins/bpmn-plugin/import-bpmn-diagrams/upload-bpmn-menu.png)

After selecting the file, the Designer opens the import settings dialog.

![Main scheme code, overwrite checkbox, and Upload button](https://docs.workflowengine.io/images/plugins/bpmn-plugin/import-bpmn-diagrams/import-settings.png)

1. Set **Main Scheme Code**. The field initially contains the code of the scheme currently open
   in the Designer. Keep it to import into that code, enter a new code, or clear it to derive the
   main code from the BPMN process name or ID.
2. Set **Overwrite previously uploaded schemes** only when existing definitions should be replaced.
   The checkbox is unchecked by default. The policy applies to all converted schemes, including
   inline dependencies and other processes in the file.
3. Click **Upload**. The server converts the document, saves eligible schemes, and displays a log.
4. Read every conversion issue and save result. Use the copy button to copy the complete log for
   investigation or a support request.
5. Click **Rerender** when offered to display the returned scheme. Otherwise click **Close**, then
   open the required saved scheme by code.

![Conversion issues, copy-log control, and Rerender button](https://docs.workflowengine.io/images/plugins/bpmn-plugin/import-bpmn-diagrams/import-log.png)

The dialog offers **Rerender** only when the server returns a successfully saved main scheme whose
code matches the scheme currently open. A different code, a skipped or failed main save, or clearing
Main Scheme Code can leave only **Close** even when other schemes were saved. Read the log rather
than interpreting the button as the overall import result.

![Import log showing an existing scheme skipped and only the Close button offered](https://docs.workflowengine.io/images/plugins/bpmn-plugin/import-bpmn-diagrams/import-close-button.png)

In this example, overwrite is disabled and the main scheme already exists. The importer skips
that definition, so the dialog offers **Close** rather than replacing the open scheme.

The importer also places conversion warnings in comments on relevant activities and transitions.
Review those comments when configuring the converted workflow; a successful save does not certify
that unsupported BPMN semantics have been preserved.

![Message catch event properties with an invalid message reference warning in the Comment field](https://docs.workflowengine.io/images/plugins/bpmn-plugin/import-bpmn-diagrams/element-import-warning.png)

The message catch event in this example has an unresolved BPMN message reference. Its comment
explains why the importer did not create the expected command, identifying the integration that
must be corrected before the workflow can wait for that message.

## Review saved schemes

BPMN import can produce several definitions from a single file. Each top-level BPMN process becomes
a separate scheme; pools referring to separate processes therefore produce separate schemes too.
Nonempty embedded subprocesses become additional inlineable schemes referenced by inline activities
in their parents. Lanes are ignored.

Table: Scheme naming during conversion

| Definition | Derived code |
|------------|--------------|
| First eligible non-inline top-level process | Main Scheme Code, when supplied; otherwise the normal process naming rule. |
| Other top-level process | BPMN process name, falling back to its ID. If top-level process names repeat, IDs distinguish those processes. |
| Embedded subprocess | BPMN subprocess name, falling back to its ID. |

Keep derived codes distinct, particularly subprocess names. The main-code override does not rename
every converted definition, and duplicate dependency names can prevent the upload handler from
ordering schemes for saving. The converter reads positions from the first BPMN diagram; it does
not combine every diagram layout in the document.

Name-to-ID fallback treats only an absent (`null`) name as missing; names are not trimmed. An empty
or whitespace-only name is retained unless the duplicate top-level-name rule selects IDs for those
processes. A top-level process with neither a name nor an ID receives a generated GUID code. Supply
nonblank, distinct names or IDs for processes and inline dependencies.

The upload handler saves inline dependencies before the schemes that reference them. It skips
results marked `DontSave` and, unless overwrite is enabled, codes already stored in the request's
tenant. It assigns that tenant to definitions before saving them through the runtime builder.

Saving is sequential, with a separate result for each scheme. The upload is not a batch transaction:
earlier successful saves remain if a later scheme fails. A dependency skipped because it already
exists may also leave a newly saved parent referencing that existing definition. Inspect all codes
and save results together before executing the main workflow.

An exception can replace the accumulated log with an `Import failed` message and stack trace.
Previously saved definitions still remain, so inspect stored scheme codes before retrying when the
final log does not list every earlier save.

Import saves definitions; it does not create process instances. Reimport with overwrite replaces
definitions rather than merging edits. Apply the application's normal running-scheme update policy
when already-created instances must adopt changes.

## Inspect conversion results

`BpmnConverter.ConvertBpmnDocument` also supports conversion without the Designer. It accepts a
`TextReader` containing BPMN XML or an already deserialized `TDefinitions`, plus optional
`mainSchemeCode`, and returns `List<ConvertedProcess>`. The converter itself does not save schemes,
run the runtime builder's system steps, or start processes.

Table: ConvertedProcess result contract

| Member | Meaning |
|--------|---------|
| `ProcessDefinition` | Native definition produced by the converter; includes inline scheme references where required. |
| `Issues` | Immutable list of conversion messages. Inspect each message before deciding whether to save. |
| `HasIssues` | `true` when the issue list is nonempty. Warnings do not automatically prohibit saving. |
| `Hint` | Optional hint with `HintType` and explanatory `Message`. |
| `DontSave` | `true` when the hint type is `ConvertedProcessHintType.DontSave`, for example an empty top-level process. |

An empty result list is also possible when the document contains no top-level process elements.
Applications using the converter directly must decide whether that is an acceptable input.

[Customize BPMN Import](https://docs.workflowengine.io/plugins/bpmn-plugin/customize-bpmn-import/) supplies a complete C# preview
program that prints codes, issue messages, and save hints without modifying storage. For application-managed
saving, preserve dependency order, honor `DontSave`, set the tenant, and inspect the tuple returned
by `SaveProcessSchemeAsync`: `success`, `errors`, and `failedStep`. Do not save every result blindly.

## Connect application behavior

BPMN import preserves supported structure while application integration remains explicit. For
example, a service task named `ReserveStock` can reference an
[action](https://docs.workflowengine.io/get-started/concepts/action/) implemented by the host. If the integration waits for an
external result, a message catch becomes a [command](https://docs.workflowengine.io/get-started/concepts/command/) wait; the host's
message handler correlates the result to a process and executes that command.

Review the following behavior before running the imported scheme:

- Implement every referenced action and [condition](https://docs.workflowengine.io/get-started/concepts/condition/). Service
  task implementation strings name actions; importing them does not implement a REST call or worker.
- Add [actors and rules](https://docs.workflowengine.io/get-started/concepts/rule/) to restrict user commands. User Task does not
  automatically create a form, approver list, or authorized command.
- Review [timer](https://docs.workflowengine.io/get-started/concepts/timer/) values, clock interpretation, and unsupported timer cycles.
- Check transition classifiers and parallel creation/merge behavior against the intended workflow.
- Create a process instance through the host application. A message or timer start event waits
  inside that created instance; it does not register an external process-start subscription.

For user commands, retrieve the available commands for the current user with
`GetAvailableCommandsAsync`, then select the requested command, fill its parameters, and execute it
with `ExecuteCommandAsync` for the same user. Restrictions are checked during retrieval. To repeat
the check during execution, use `ExecuteCommandWithRestrictionCheckAsync` or
`ExecuteCommandAsync` with `checkRestrictions: true`.

If the host uses Workflow Engine Web API, BPMN upload travels
through the Designer endpoint, by default `POST /workflow-api/designer`, and its
`bpmnplugin_uploadbpmn` operation. Use the application's configured base and endpoint paths when
they differ from these defaults. The API forwards
form fields and the first uploaded file to the runtime's Designer API and applies its configured
security and server tenant context. The POST operation ID is `workflow-api.designer`; the endpoint's
configured authorization controls apply to that operation. There is no separate BPMN-specific REST operation group in the
current production API. Configure and authorize the Designer endpoint rather than assuming a
separate BPMN import service exists.

## Diagnose import results

The BPMN import log distinguishes conversion warnings, skipped definitions, save failures, and
conversion exceptions. Inspect it even when the Designer request succeeds: failures caught by the
upload handler are returned in `ResultLog`, while the outer response still has `hasError: false`.

Table: Import symptoms and checks

| Symptom | What to check |
|---------|---------------|
| BPMN palette or Upload BPMN is missing | Confirm registration and license succeeded; reload the Designer with compatible frontend assets. |
| License does not include the Bpmn plugin | Obtain and register a license with the `Bpmn` capability before plugin registration. |
| Scheme already exists and will not be overwritten | Choose a new code or deliberately enable overwrite after reviewing the existing definition. |
| Only Close appears after upload | Check the saved codes and log; Rerender requires a returned scheme matching the currently open code. |
| Some schemes saved and another failed | Inspect errors and the failed build step; earlier saves remain. Review dependencies before retrying. |
| Split or merge building fails while parsing coordinates | Check that the BPMN export contains diagram coordinates for the affected activities, or assign integer Designer coordinates before programmatic saving. |
| Circular reference detected | Review inline dependency cycles and duplicate scheme codes. |
| Message became an automatic transition | Check the message reference and event definition; unsupported or invalid definitions generate warnings. |
| Multiple start events without event definitions are not supported | Reduce the process to one generic start or revise its start-event structure. |
| A recurring timer no longer waits | `timeCycle` is unsupported. Review the warning and implement the required scheduling behavior explicitly. |
| Visio or another modeler's file fails to import | Export actual BPMN 2.0 XML, then check the supported elements and vendor-specific extensions. |

Older Designer assets could produce `ReferenceError: designer is not defined` in the upload dialog.
The published [21.1.2 release notes](https://docs.workflowengine.io/release-notes/21.1.2/) identify the Designer fix. If this exact
historical error appears, update the Designer assets/packages used by the application.

## Frequently asked questions

**Which file format does BPMN Plugin import?**

BPMN Plugin deserializes BPMN 2.0 XML, normally supplied as a `.bpmn` file. A modeling tool's
proprietary document or an image of a process is not an equivalent input.

**Why are there several saved schemes after one BPMN upload?**

Top-level processes become separate schemes, and nonempty embedded subprocesses become inlineable
dependency schemes. The Designer displays one main scheme at a time.

**Can I inspect BPMN conversion without saving anything?**

Yes. Call `BpmnConverter.ConvertBpmnDocument` and inspect each `ConvertedProcess`, including
`Issues`, `Hint`, and `DontSave`. Saving and process creation are separate operations.

**Does a successful upload mean the BPMN behavior is fully preserved?**

No. Unsupported constructs can become ordinary activities or automatic transitions with warnings.
Review those warnings and complete the host application's integration before execution.

**Will a new BPMN import merge my Designer changes?**

No. With overwrite disabled, existing codes are skipped; with overwrite enabled, definitions are
replaced. Reconcile source BPMN and native scheme changes explicitly.