Diagram - BPMN Basics

#Usage

This component accepts an initial BPMN model and its page ID. Supply the records shown in a demo below. Copy the preset inspector files to the local import path and follow Setup for application styles and licensing.

<script setup lang="ts">
import { onBeforeUnmount } from 'vue';
import { Diagram, createDiagramStore, DiagramSymbolRegistry, type DiagramModel } from '@primeui/vue-diagram';
import { DiagramBpmnRoot, createDiagramBpmnModule, createDiagramBpmnLibrary } from '@primeui/vue-diagram/bpmn';
import { DiagramBpmnInspectorUI } from './components/primeui/diagram/bpmn';

const props = defineProps<{ model: DiagramModel; pageId: string }>();
const created = createDiagramStore(props.model, { notationModules: [createDiagramBpmnModule()] });
if (!created.ok) throw new Error(created.diagnostics.map((item) => item.message).join('; '));
const store = created.value;

const symbols = new DiagramSymbolRegistry();
for (const symbol of createDiagramBpmnLibrary().symbols) symbols.register(symbol);

onBeforeUnmount(() => {
    symbols.dispose();
    store.dispose();
});
</script>

<template>
    <Diagram.Root :store="store" :page-id="pageId" :symbols="symbols">
        <DiagramBpmnRoot>
            <Diagram.Viewport label="BPMN model" auto-fit style="height: 30rem" />
            <DiagramBpmnInspectorUI />
        </DiagramBpmnRoot>
    </Diagram.Root>
</template>

The model is read once during setup. For file loading or Reset, replace the store deliberately and dispose the previous caller-owned store. The root owns its session. The copied inspector follows selection and creates its own DiagramBpmnInspectorHost; a custom form uses that host with useDiagramBpmnInspector() in a child component. Its snapshots are readonly refs. Read .value in setup and use the documented actions to change drafts or selections. Mounting a form does not install the notation module.

Start with a Message Start, a User Task and an End. BPMN adds meaning and validation to the same nodes, connectors, selection and history used by the generic canvas.

#Start with a small process

Choose Focus review, or select Review order on the canvas. Use Edit selected element to inspect the task. Move it and Undo the change. The complete source tab contains the model, store setup, registered symbols and resource cleanup.

The example registers every symbol from createDiagramBpmnLibrary().symbols and installs createDiagramBpmnModule() when it creates the store. DiagramBpmnRoot supplies semantic editing beneath the generic root.

#Edit one task

Choose Focus task, then use Edit selected element. Change its Task profile. The copied form edits the saved semantic profile through typed actions. Read only disables writes while you can still navigate and inspect. Use Insert from palette to search and insert a profile by click, Enter or Space; the same target also accepts palette drag placement. New disconnected tasks produce completeness warnings.

Task type switching clears subtype-specific fields from the old profile. An already selected subtype keeps its properties. Activities explains script, rules, loops and calls without adding those controls to this first example.

#Author a flow deliberately

Choose Review order and Create sequence. Choose Complete and Reconnect target, then Undo to restore the former endpoint. Add annotation association connects Check stock to Review order with explicit association semantics. The source uses bpmn.connect/bpmn.reconnect with the actual scope and flow union. A generic drag connection does not infer BPMN metadata; supply a typed flow through this path or configure your application connection factory deliberately.

#Create records and flows

createDiagramBpmnNode(data, creation, name = '', model?) constructs one node. creation supplies id, pageId, layerId, bounds and optional parent/symbol creation fields. Pass the model as the fourth argument when names or collection markers depend on page catalogs. Events and gateways use square bounds; subprocesses receive fixed containers and boundaries receive attachment geometry.

Generated task titles align beneath the task symbol and use the available card width. Compact tasks use a row beside the symbol when bottom markers leave too little height for a line below it. Titles wrap and reflow when you resize the node; expanded subprocess names stay in the header. If the name exceeds the available space, the displayed text ends with an ellipsis while the full name remains saved and editable. Canvas, SVG and print use the same title placement.

Explicit imported BPMN DI label positions remain unchanged. Editing a label's position through the content editor opts out of automatic placement. For a custom position in a raw model, remove label.extensions.primeuiBpmnLabelLayout and set the label's local position.

createDiagramBpmnFlow(model, id, sourceId, targetId, data) requires existing endpoints and constructs the appropriate saved appearance. Factories do not commit or authorize an edit. For live insertion, use DiagramBpmnEditor.create and connect through the semantic root so editing/connection policy participates. IDs use letters/numbers and the supported _.:- punctuation, never spaces. Display labels are separate. Optional JSON fields should be omitted when unset.

bpmnEnvelope(data) produces the version-1 BPMN envelope. readDiagramBpmn(record) reads supported resolved semantics. validateDiagramBpmn(model) returns errors; inspectDiagramBpmn(model) returns { errors, warnings }. Keep diagnostics visible rather than catching an invalid fixture and showing an empty canvas.

#Node and flow profiles

Every node has processId and scopeId; these must agree with its actual ownership. Use a process page ID at the root, a participant ID inside its lanes, or a subprocess record ID for an inner scope. Lanes organize geometry without becoming BPMN scopes.

All flow data includes processId/scopeId. Conditions belong on outgoing flows of tasks/calls/non-event subprocesses or exclusive/inclusive/Complex gateways. A defaultFlowId names an actual outgoing sequence and that sequence carries no condition. Parallel and event-based gateways have no conditional/default choices.

#Authoring API and form ownership

DiagramBpmnEditor(store, session) requires a store with BPMN installed. Its creation, update, connection and specialized operations share ordinary history, current permissions, approval and controlled proposals. Rejections preserve the whole graph; completeness warnings describe valid unfinished work. One semantic edit, including related appearance changes, is one transaction/history operation.

For a reusable palette, createDiagramBpmnPalette(processId) returns the standard profiles. DiagramPaletteCollection and palette target/root parts are imported from @primeui/vue-diagram/palette; the demo shows their complete setup. createDiagramBpmnSymbol, createDiagramBpmnLibrary, diagramBpmnProfiles, bpmnSymbolId and bpmnFlowAppearance provide profile artwork/data when building custom content. Prefer factories and typed actions so materialized symbols, labels and markers agree with semantics.

BPMN here is descriptive. There is no process execution, script evaluation, message delivery or external call resolution. Use pools/messages for collaboration diagrams and reuse for copied graphs.

#Related Docs

• Choose a Notation
• Supported Profiles
• API