Skip to content

Import BPMN Files as Workflows

Available since

  • v5.0.1 and later

In Orkes Conductor, you can quickly convert BPMN (Business Process Model and Notation) files into workflow definitions. This simplifies the migration from BPMN-based systems by supporting standard XML and BPMN formats. Whether you’re transitioning from legacy tools or starting with predefined processes, the BPMN importer enables a fast, code-free transition into the Conductor ecosystem.

When to use it

Use the importer when you are migrating from a BPMN-based tool, or when you already have BPMN models and want Conductor workflows as a starting point. Treat the result as a first draft: it converts the supported BPMN structure, so review the generated workflow before running it.

Importing BPMN files

Use the Import BPMN File API (POST /api/metadata/workflow-importer/import-bpm) or go to Definitions > Workflow, select Import BPMN.

Import files using one of the following methods:

  • Select file: Upload a .bpmn file from your local device.
  • Drag and drop: Drop the BPMN files directly into the designated area in the UI.
  • Code: Paste the raw XML content of your BPMN directly in the code tab.

The Workflow Name is pre-filled from the file name. Edit it if you want a different name. Overwrite workflow is on by default, so an existing workflow with the same name is replaced. Turn it off to prevent overwriting. Then select Import.

The BPMN file is converted into workflow definitions in Orkes Conductor. Each process defined in the imported BPMN file is converted into an equivalent Orkes Conductor workflow definition.

After importing, the newly created workflows appear in the workflow definitions list.

The import will fail with an error if the BPMN file:

  • Contains a circular reference
  • Has multiple start events
  • Uses sequential lanes, which are not supported
  • Is incomplete or malformed

Validate the generated workflow

The BPMN importer converts supported BPMN structure into a Conductor workflow definition. After import, the workflow behaves like any other Conductor workflow: it can be versioned, started by API, tested, monitored, and edited. Inspect the generated workflow definition rather than trusting the visual shape alone.

{
  "name": "imported_order_process",
  "version": 1,
  "schemaVersion": 2,
  "tasks": [
    {
      "name": "validate_order",
      "taskReferenceName": "validate_order_ref",
      "type": "SIMPLE",
      "inputParameters": {
        "orderId": "${workflow.input.orderId}"
      }
    }
  ]
}

Check the following after every BPMN import:

  • Workflow name, version, description, and ownerEmail.
  • Task names and taskReferenceName values. Use stable reference names because downstream expressions and recovery operations depend on them.
  • Inputs expected by each task and output mappings used by downstream tasks.
  • Branches, joins, loops, waits, and sub-process equivalents.
  • Retry, timeout, and compensation behavior. Register task definitions for worker tasks, and add retryCount, retryLogic, timeoutSeconds, responseTimeoutSeconds, and pollTimeoutSeconds where needed.
  • Schemas, if workflow or task input contracts must be validated.
  • A failure workflow, if the process needs compensation.