Datentypen und Interfaces

Übersicht aller Datenstrukturen, die in der Cuby-API und im Plugin-System verwendet werden.

ProcessCubeInfo

Beschreibt eine registrierte ProcessCube-Instanz. Wird vom Studio über GET /api/processcubes abgefragt.


{
  productId: string;         // Eindeutige Produkt-ID
  name: string;              // Anzeigename
  engineUrl: string;         // URL der Engine (z.B. "http://localhost:8000")
  lowcodeUrls: string[];     // URLs der LowCode-Instanzen
  authorityUrl: string;      // URL der Authority
}

Product (Installiertes Produkt)

Beschreibt ein installiertes Produkt in config.json.


{
  instanceId: string;        // Eindeutige Instanz-ID ("id" oder "id__alias")
  id: string;                // Produkt-ID
  alias: string | null;      // Optionaler Alias für Mehrfach-Instanzen
  name: string;              // Anzeigename
  npmPackage: string;        // npm-Paketname (z.B. "@processcube/engine.cuby")
  version: string;           // Installierte Version
  url: string | null;        // URL des laufenden Produkts
  configured: boolean;       // Ob das Produkt konfiguriert wurde
  installedAt: string;       // ISO 8601 Zeitstempel
}

Product Status

Status eines laufenden Produkts (via GET /api/products/status oder Socket.IO).


{
  [instanceId: string]: {
    status: 'running' | 'stopped' | 'crashed';
    pid: number;             // Prozess-ID
    startedAt: string;       // ISO 8601 Zeitstempel
    restartCount: number;    // Anzahl Auto-Restarts
  }
}

Installation Progress

Fortschritt während der Produktinstallation (via Socket.IO install:status).


{
  productId: string;
  status: 'installing' | 'needs_config' | 'installed' | 'failed';
  progress: number;          // 0–100
  message: string;           // Fortschrittsmeldung
  error?: string;            // Fehlermeldung (bei status: 'failed')
}

Socket.IO Events

Cuby sendet Echtzeit-Updates über Socket.IO (Standard: http://localhost:3847).

Server → Client

Event	Payload	Beschreibung
`install:status`	`InstallationProgress`	Installationsfortschritt
`products:status`	`ProductStatus`	Status-Änderung aller Produkte
`product:log`	`{ instanceId, line }`	Log-Zeile eines Produkts
`processcube:registered`	`ProcessCubeInfo`	Neue ProcessCube-Instanz registriert
`processcube:unregistered`	`{ productId }`	ProcessCube-Instanz entfernt

Beispiel: Socket.IO Client


import { io } from 'socket.io-client';
 
const socket = io('http://localhost:3847');
 
socket.on('products:status', (status) => {
  console.log('Produkt-Status:', status);
});
 
socket.on('install:status', (progress) => {
  console.log(`${progress.productId}: ${progress.progress}% — ${progress.message}`);
});

Plugin Interface

Plugins können folgende Lifecycle-Methoden implementieren:


// Plugin Entry Point (index.js)
 
export async function init(cuby, context) {
  // Route-Registrierung, Socket-Handler
  // Wird einmalig beim Laden aufgerufen
}
 
export async function deploy(productDir, config, onProgress, cuby, context) {
  // Installationslogik
  // onProgress({ message, percent }) für Fortschrittsmeldungen
  await cuby.registerProcessCube({
    name: 'Mein Produkt',
    engineUrl: 'http://localhost:8000',
    lowcodeUrls: [],
    authorityUrl: '',
  });
}
 
export async function start() {
  // Produkt starten
}
 
export async function stop() {
  // Produkt stoppen
}
 
export async function undeploy(productDir, cuby, context) {
  // Deinstallation / Cleanup
}
 
export function getConfig() {
  // Aktuelle Konfiguration zurückgeben
}

Cuby-Kontext (Plugin API)

Plugins erhalten einen cuby-Kontext mit folgenden Methoden:

Methode	Beschreibung
`registerProcessCube(info)`	ProcessCube-Instanz registrieren
`getProcessCubes()`	Alle registrierten Instanzen abrufen
`reservePort(desiredPort)`	Port reservieren
`getSecret(name)`	Secret lesen (scoped auf Plugin)
`setSecret(name, value)`	Secret speichern
`deployProcesses(pcId, dir, strategy)`	BPMN-Prozesse zur Engine deployen
`deployFlows(pcId, flowsDir, url)`	Node-RED Flows zu LowCode deployen
`registerSocketEvents(events)`	Socket.IO Events für Plugin registrieren

Package.json — Cuby-Feld

Produkte definieren ihren Typ über das cuby-Feld in der package.json:


{
  "name": "@processcube/mein-produkt.cuby",
  "version": "1.0.0",
  "cuby": {
    "type": "npx",
    "plugin": "index.js",
    "url": "http://localhost:9000"
  }
}

Feld	Beschreibung
`type`	Produkt-Typ: `bpmn`, `flow` oder `npx`
`plugin`	Entry-Point für Plugin-Lifecycle (Standard: `index.js`)
`url`	URL des laufenden Produkts (für Dashboard-Link)

Weitere Informationen

API-Referenz — Alle REST-Endpoints im Detail
Plugin-System — Plugin-Entwicklung
Konfiguration — Konfigurationsdateien