Skip to Content
CubyPlugin-System

Plugin-System

Produkte können über das Plugin-Interface erweiterte Funktionalität bieten. Plugins sind npm-Pakete im @processcube-Scope mit dem Suffix .cuby.

Namenskonvention

  • Scope: @processcube
  • Suffix: .cuby
  • Beispiel: @processcube/example.cuby

Produkt-Typen

TypBeschreibungVerhalten
bpmnBPMN-ProzesseWird zur ProcessCube® Engine deployed
flowNode-RED FlowsWird zu ProcessCube® LowCode installiert
npxAusführbare ProgrammeWird als Prozess gestartet und überwacht

Die Typ-Erkennung erfolgt über das cuby-Feld in der package.json des Pakets:

{
  "name": "@processcube/example.cuby",
  "cuby": {
    "type": "npx",
    "plugin": "index.js"
  }
}

Ohne explizite Definition wird der Typ automatisch erkannt:

  • .bpmn-Dateien → bpmn
  • *flow*.json-Dateien → flow
  • bin-Feld in package.json → npx

Plugin-Interface

{
  // Route-Registrierung (Main-Thread)
  init(router, cuby, context) {},
 
  // Lifecycle-Methoden (Worker-Prozess)
  deploy(productDir, config, onProgress, cuby, context) {},
  start(productDir, cuby, context) {},
  stop(cuby, context) {},
  undeploy(productDir, cuby, context) {},
 
  // Konfiguration
  getConfig() {}
}
  • init() wird auf dem Main-Thread ausgeführt und registriert HTTP-Routes
  • deploy(), start(), stop(), undeploy() laufen in separaten Node.js-Child-Prozessen
  • getConfig() gibt die aktuelle Konfiguration zurück

Plugin-Routes

Plugins können eigene API-Endpunkte registrieren:

init(router, cuby, context) {
  router.get('/status', (req) => {
    return Response.json({ status: 'ok' });
  });
  router.post('/action', (req) => {
    // ...
  });
}

Die Routes sind erreichbar unter: /api/plugins/{instanceId}/{route}

Cuby-Kontext

Plugins erhalten einen cuby-Kontext mit folgenden Methoden:

MethodeBeschreibung
registerProcessCube(opts)ProcessCube® Engine/LowCode-Instanz registrieren
getProcessCubes()Alle registrierten Instanzen abrufen
reservePort(desiredPort)Port für das Plugin reservieren
releasePort(port)Port freigeben
setProcessCubeConfig(pcId, config)Konfiguration für eine ProcessCube®-Instanz setzen
getProcessCubeConfig(pcId)Konfiguration einer ProcessCube®-Instanz lesen
removeProcessCubeConfig(pcId)Konfiguration entfernen

Konfigurations-Komponente

Plugins können eine React-Komponente für den Konfigurationsdialog bereitstellen:

  • Datei: config-component.js im Paketverzeichnis
  • Wird als JSX im Browser transpiliert und gerendert
  • Erhält die aktuelle Konfiguration und Callbacks zum Speichern/Abbrechen

Der Dialog erscheint automatisch nach der Installation, wenn Konfiguration nötig ist.

Detail-Komponente

Plugins können eine React-Komponente für die Detail-Ansicht bereitstellen:

  • Datei: detail-component.js im Paketverzeichnis
  • Wird auf der Produkt-Detail-Seite eingebettet

Worker-Architektur

Lifecycle-Methoden laufen in separaten Node.js-Child-Prozessen (nicht im Bun-Hauptprozess):

  • Grund: Die kompilierte Bun-Binary löst transitive Dependencies bei dynamischem import() nicht korrekt auf
  • Kommunikation: JSON-Lines-Protokoll über stdin/stdout
  • RPC: Cuby-Methoden-Aufrufe werden vom Worker über das Protokoll an den Main-Thread weitergeleitet
  • Logs: Jede Lifecycle-Methode schreibt eine eigene Log-Datei (deploy.log, start.log, etc.)

ProcessCube®-Integration

Plugins können sich mit ProcessCube® Engine- und LowCode-Instanzen verbinden:

  1. Plugin ruft cuby.registerProcessCube() mit Engine-URL, LowCode-URL(s) und optionalen Auth-Daten auf
  2. Cuby wartet auf Health-Check der Instanz (bis zu 30 Versuche, je 2 Sekunden)
  3. Bei Authority-Konfiguration wird ein OAuth2-Token abgerufen
  4. Socket.IO-Verbindung zum LowCode-Endpoint /cuby wird hergestellt
  5. Konfigurationsaustausch über cuby:get, cuby:keys, cuby:update Events
ProduktverwaltungKonfiguration