BPMN

The entry point @tiptap-pro/extension-diagrams/bpmn draws process models stored as BPMN 2.0 XML, the standard format for business processes, with bpmn-js, and connects the bpmn-js modeler to change them. It draws no charts.
New tab

Quick start

bpmn-js is not a dependency of the package. Install it, serve its bundle, and use it under its own license. bpmnXml stands for the XML of a process:

npm install bpmn-js
import { Diagrams } from '@tiptap-pro/extension-diagrams'
import { bpmnDiagramRenderer } from '@tiptap-pro/extension-diagrams/bpmn'
import rendererUrl from '@tiptap-pro/extension-diagrams/bpmn-renderer?url&no-inline'
import viewerUrl from 'bpmn-js/dist/bpmn-viewer.production.min.js?url&no-inline'

Diagrams.configure({
  diagramRenderers: [bpmnDiagramRenderer({ viewerUrl, rendererUrl })],
})

editor.commands.insertFlowDiagram({ source: bpmnXml, format: 'bpmn', title: 'Payment check' })

The editor shows the process as bpmn-js draws it. Install Diagrams has the complete editor around these lines.

Options

OptionTypeDefaultDescription
viewerUrlstringRequiredURL of a bpmn-js viewer or modeler bundle
rendererUrlstringRequiredURL of @tiptap-pro/extension-diagrams/bpmn-renderer
scriptNoncestring | nullnullNonce for a nonce-based Content Security Policy
idstring'bpmn'Names the Renderer
labelstring'BPMN'The name for a menu

How it draws

bpmn-js runs in one hidden iframe per web page, with sandbox="allow-scripts" and no network access. Renderers with a different viewerUrl, rendererUrl or scriptNonce get an iframe each. It loads for the first BPMN diagram, and drawings are cached by source.

The XML must carry its layout (BPMN DI, the positions of the shapes), as a modeler saves it. A process without one does not draw. Diagrams are black on their own white background, untouched by --tt-flow-diagram-*. In PNG, WebP, JPEG and Word exports, labels are SVG text, so files look like the editor. Exporting on a server is not possible, because bpmn-js lays out text in a browser.

The bpmn.io attribution

The Renderer's rules ask for a "Powered by bpmn.io" link with the bpmn.io logo, below each diagram and in every exported file. rendererRules cannot remove it, see Rules of your Renderer.

What a BPMN source is

A BPMN source is XML whose root element is definitions in the namespace http://www.omg.org/spec/BPMN/20100524/MODEL, under any prefix, declared on the root and closed at the end, such as </bpmn:definitions>. An XML declaration and comments may come first.

The document stores it as written, without a byte-order mark and outer white space. Empty source is allowed, for a process not modeled yet. Pasted BPMN XML gives a BPMN diagram, and detectDiagramInput returns { kind: 'bpmn', source } for it. insertFlowDiagram and updateFlowDiagram return false for anything else, and for source over 1,000,000 characters.

Editing in the modeler

Users change a BPMN diagram in the bpmn-js modeler, which connectBpmnEditor runs in an iframe you build. This example opens the first BPMN diagram of editor, which must hold one, and Save writes back what save() returns:

import { connectBpmnEditor } from '@tiptap-pro/extension-diagrams/bpmn'
import rendererUrl from '@tiptap-pro/extension-diagrams/bpmn-renderer?url&no-inline'
import fontUrl from 'bpmn-js/dist/assets/bpmn-font/css/bpmn-embedded.css?url&no-inline'
import bpmnStyleUrl from 'bpmn-js/dist/assets/bpmn-js.css?url&no-inline'
import diagramStyleUrl from 'bpmn-js/dist/assets/diagram-js.css?url&no-inline'
import modelerUrl from 'bpmn-js/dist/bpmn-modeler.production.min.js?url&no-inline'

const diagram = editor.storage.diagrams.listDiagrams().find(item => item.format === 'bpmn')

const dialog = document.createElement('dialog')
const frame = document.createElement('iframe')
const saveButton = document.createElement('button')
saveButton.textContent = 'Save'
saveButton.disabled = true
dialog.append(frame, saveButton)
document.body.append(dialog)
dialog.showModal()

const connection = connectBpmnEditor(frame, {
  modelerUrl,
  rendererUrl,
  styleUrls: [diagramStyleUrl, bpmnStyleUrl, fontUrl],
  source: diagram.source,
  onReady: () => (saveButton.disabled = false),
})

// Escape closes the dialog too
dialog.onclose = () => {
  connection.destroy()
  dialog.remove()
}

saveButton.onclick = async () => {
  const source = await connection.save()
  editor.commands.updateFlowDiagram({ pos: diagram.pos, source, format: 'bpmn' })
  dialog.close()
}

The embedded font stylesheet is needed, because the modeler's fonts must come from a data: URL or a stylesheet's origin. The modeler works on a copy, so a save replaces changes others made meanwhile.

connectBpmnEditor(frame, options)

Runs the modeler in frame, and sets its sandbox="allow-scripts" and srcdoc itself.

OptionTypeDefaultDescription
modelerUrlstringRequiredURL of bpmn-js/dist/bpmn-modeler.production.min.js
rendererUrlstringRequiredURL of the Renderer's bpmn-renderer file
styleUrlsreadonly string[]Requireddiagram-js.css, bpmn-js.css and bpmn-font/css/bpmn-embedded.css
scriptNoncestring | nullnullNonce for a nonce-based Content Security Policy
sourcestring''The BPMN XML to open. Empty opens a process with a start event
onReady()() => voidNoneCalled when the diagram can be edited
onChange()() => voidNoneCalled after every change
onError(message)(message) => voidNoneCalled when the modeler did not load within 30 seconds or open the source

It returns { save, destroy }:

FunctionReturns
save()A Promise of the BPMN XML. Rejects before onReady, after destroy(), and for XML that is not BPMN
destroy()Nothing. Stops listening, empties the iframe, rejects pending saves