Tutorial: BPMN Custom Properties

In diesem Tutorial erweitern Sie den BPMN-Editor um eigene Property-Felder für BPMN-Elemente. Damit können Sie z.B. einem Service Task zusätzliche Konfigurationsfelder geben.

Was Sie lernen

Custom Properties für BPMN-Elemente registrieren
Pane als Property-Editor erstellen
BPMN-Element-Selektion abfragen
Properties über BPMN-Commands setzen

Überblick

Projektstruktur

- index.ts
- package.json
- - CustomPropertyPane.tsx

Schritt 1: Property-Pane erstellen

Die Pane zeigt die Custom Properties an, wenn ein passendes BPMN-Element selektiert ist:


// panes/CustomPropertyPane.tsx
import React, { useState, useEffect } from 'react';
import { PaneProvider, FormInput } from '@5minds/processcube_studio_sdk';
 
function CustomPropertyContent(props: any): JSX.Element {
  const { studio, bpmnModel } = props;
  const [selectedElement, setSelectedElement] = useState<any>(null);
  const [priority, setPriority] = useState('');
 
  useEffect(() => {
    if (!bpmnModel) return;
 
    const handler = () => {
      const selection = bpmnModel.selection.getSelectedElements();
      if (selection.length === 1) {
        setSelectedElement(selection[0]);
        // Bestehenden Wert lesen
        const existing = selection[0].extensionProperties?.priority || '';
        setPriority(existing);
      } else {
        setSelectedElement(null);
      }
    };
 
    bpmnModel.selection.on('changed', handler);
    return () => bpmnModel.selection.off('changed', handler);
  }, [bpmnModel]);
 
  if (!selectedElement) {
    return <div style={{ padding: '12px' }}>Kein Element ausgewählt.</div>;
  }
 
  const handlePriorityChange = (newValue: string) => {
    setPriority(newValue);
    // Property im BPMN-XML setzen
    studio.commands.executeCommand(
      'bpmn.setExtensionProperty',
      selectedElement,
      'priority',
      newValue,
    );
  };
 
  return (
    <div style={{ padding: '12px' }}>
      <h4>Custom Properties</h4>
      <p>Element: {selectedElement.name || selectedElement.id}</p>
      <FormInput
        label="Priorität"
        value={priority}
        onChange={handlePriorityChange}
        placeholder="z.B. hoch, mittel, niedrig"
      />
    </div>
  );
}
 
export const paneProvider: PaneProvider = {
  getPaneTitle: () => 'Custom Properties',
  Pane: CustomPropertyContent,
  PaneContent: CustomPropertyContent,
};

Schritt 2: Registrierung


// index.ts
import { Studio } from '@5minds/processcube_studio_sdk';
 
export function onLoad(studio: Studio): void {
  // Icon registrieren
  studio.icons.registerIcons({
    'customProps/icon': 'fad fa-sliders-h',
  });
 
  // Pane im rechten Bereich (Inspector) registrieren
  studio.panes.registerPaneGroup('right', 'customProps/pane-group', [
    studio.panes.getPaneViaPaneProvider(
      'customProps/property-pane',
      'customProps/provider',
      require('./panes/CustomPropertyPane'),
    ),
  ]);
}

BPMN-Commands

Die BPMN-Extension stellt Commands bereit, um Elemente zu manipulieren:

Command	Beschreibung
`bpmn.setExtensionProperty`	Extension-Property setzen
`bpmn.getExtensionProperty`	Extension-Property lesen
`bpmn.updateProperties`	Standard-Properties aktualisieren
`bpmn.addElement`	Element zum Diagramm hinzufügen
`bpmn.removeElement`	Element entfernen


// Extension-Property setzen
studio.commands.executeCommand(
  'bpmn.setExtensionProperty',
  element,   // Das BPMN-Element
  'key',     // Property-Name
  'value',   // Property-Wert
);
 
// Standard-Property aktualisieren (z.B. Name)
studio.commands.executeCommand(
  'bpmn.updateProperties',
  element,
  { name: 'Neuer Name' },
);

Verwenden Sie immer die BPMN-Commands, um Properties zu setzen — nie direkt das Element-Objekt modifizieren. Nur über Commands wird die Undo/Redo-Historie korrekt gepflegt.

Known Custom Properties

Statt einer komplett eigenen Pane können Sie auch “Known Custom Properties” registrieren. Dabei werden die Properties automatisch im Standard-Property-Panel des BPMN-Editors angezeigt:


export function onLoad(studio: Studio): void {
  // Custom Property für Script Tasks registrieren
  studio.commands.executeCommand('bpmn.registerKnownCustomProperty', {
    elementType: 'bpmn:ScriptTask',     // BPMN-Element-Typ
    propertyName: 'timeout',             // Property-Name
    label: 'Timeout (ms)',               // Angezeigtes Label
    type: 'string',                      // Eingabetyp
    defaultValue: '30000',               // Standardwert
  });
}

Nächste Schritte

API-Referenz — Vollständige Dokumentation aller SDK-Methoden
Architektur — Tiefere Einblicke in die Studio-Architektur