BPMN import and compatibility

APL is Abada’s process language, and BPMN 2.0 is the foundation it builds on. Abada keeps BPMN’s proven parts — events, gateways, human and service tasks, durable waits — and changes the semantics where strict BPMN deadlocks, guesses or runs unbounded (see Where APL improves on BPMN). BPMN remains a first-class import and backward-compatibility surface. Studio transpiles BPMN into APL at the import boundary, and the engine accepts BPMN 2.0 XML directly: a deployment source starting with < is validated and compiled through the canonical BPMN path, while version: abada.io/v1 goes through the native APL parser. Both compile to the same executable graph and share the runtime.

flowchart LR
    XML[BPMN XML]
    Detect[Detect compatibility profile]
    Validate[Validate namespaces and directives]
    Parse[Dialect-specific assignment parser]
    Canonical[Canonical process definition]
    Persist[(Immutable version + schema type)]
    Runtime[Transactional runtime]

    XML --> Detect --> Validate --> Parse --> Canonical --> Persist --> Runtime

Compatibility profiles

• standard-bpmn-2.0 accepts portable BPMN constructs and explicit standard resource assignments.
• abada-native-1 accepts Abada’s versioned extension namespace (https://abada.io/schema/bpmn).
• camunda-7 preserves existing supported Camunda definitions through a compatibility parser and deterministic migration tooling.

Each profile maps supported XML into shared canonical models. Conflicting or unknown execution directives produce stable validation codes. Deployment is atomic: invalid input persists neither a definition version nor a partial compatibility report. New execution semantics require a canonical representation, validation rules, persistence behavior and executable equivalence evidence — supporting Camunda input never makes vendor extensions part of the runtime model.

Supported execution subset

The 1.0 contract covers none start/end events, user tasks, embedded and external service tasks, script tasks, business rule tasks carrying a native abada:decisionTable, exclusive/inclusive/parallel/event-based gateways, and message/signal/duration-timer catch events. An event-based gateway requires at least two competing catch children: the first child to fire advances the instance and every sibling wait state (subscription, timer job and token) is cancelled atomically in the same transaction.

Interrupting timer and error boundary events are supported on user tasks and external service tasks, with the same runtime as APL on_timeout and on_error; a user task may declare abada:slaHours and abada:escalateTo. A user task with abada:outcomes="approve,reject" (and optionally abada:commentRequired="reject") is finished by a validated decision, like an APL review step: the engine writes <taskId>_outcome and <taskId>_comment, and the exclusive gateway after the task routes on the outcome. Unsupported constructs — such as subprocesses, other boundary events (non-interrupting, message, signal, escalation, compensation), multi-instance activities, compensation, complex gateways, cyclic timers, external DMN 1.3 decision files and CMMN — are rejected during deployment rather than treated as ambiguous pass-through nodes. A business rule task is supported only with an inline abada:decisionTable extension; a user task’s camunda:formKey maps to the canonical formKey (a project FORM resource) and reports a warning when it does not resolve.

The full element-by-element matrix with executable evidence lives in the BPMN support contract.

Importing into Studio

1. In Studio, choose Import BPMN (Upload icon) and select a .bpmn file. Studio transpiles it into a native-APL document — the file carries the [BPMN Imported] badge until you author further in APL.
2. Review the transpiled APL and the format pill; round-trip fidelity for the supported subset is verified by Studio’s kitchen-sink check.
3. Save and Deploy & Start as usual. The engine persists the exact deployed source with its schema type; nothing is silently rewritten.

Alternatively, deploy BPMN XML directly to the engine through the API — the source XML is preserved and the compatibility profile/report recorded.

Migrating from Camunda 7

Existing Camunda definitions keep working under the camunda-7 profile. When you are ready to move forward, run the deterministic migration tooling to convert preserved semantics into the stable Abada namespace, then author new changes natively in APL. BPMN remains deployable forever for compatibility; Insight optimization proposals, however, target only native APL definitions.

Version immutability

Redeploying a process key creates a new immutable version. New instances select the latest committed definition, while running instances retain their stored deployment ID. Parsed cache entries use that immutable ID, so redeployment cannot change an active instance’s semantics.

Note

Normative sources: the dialect compatibility ADR, the BPMN support contract and the migration/profile documents linked from the authoritative contracts index. APL-native authoring: Author processes in native APL.

Where APL improves on BPMN

Native APL and imported BPMN run on the same runtime, so both get these behaviors. Each one is covered by an engine test listed in the repository’s docs/reference/bpmn-support.md.

• No join deadlocks. A parallel-fork branch that ends before the join no longer blocks it, and paths of an exclusive choice that converge on a parallel gateway merge instead of waiting forever. Joins count execution tokens by id, and the token that forked continues after the join.
• Event races count once. An event-based gateway inside a parallel branch is one branch at the join; the losing waits are cancelled in the same transaction as the winner.
• Safe expressions. Conditions and decision rules are sandboxed CEL, compiled at deployment; an expression that cannot be evaluated fails the step instead of being read as false.
• Nothing ignored. Elements the engine does not execute are rejected at deployment.
• Governed AI steps. The agent node runs model calls outside the transaction and admits their output only after the engine checks it against a declared schema and confidence threshold.
• Bounded loops. A cycle must declare how many times the step it returns to may run (abada:maxIterations); past the limit the process takes its abada:onExhausted route or opens an incident. Unbounded cycles and loop or multi-instance markers are rejected at deployment.
• Decisions, not just completions. A review task with outcomes refuses an unknown outcome or a missing required comment, and records who decided what.
• No silent stalls. Work that fails for good takes its error route or opens a retryable incident; a timeout boundary cancels work that takes too long; a missed service level escalates the task instead of being a passive hint.

Abada does not claim full BPMN 2.0 conformance: the supported subset is explicit, and everything outside it is rejected.