Skip to content

5minds/ProcessCube.App.SDK

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1,681 Commits
.github
.github
 
 
src
src
 
 
test-app
test-app
 
 
todos
todos
 
 
.gitignore
.gitignore
 
 
.prettierrc.js
.prettierrc.js
 
 
.prettierrc.json
.prettierrc.json
 
 
CLAUDE.md
CLAUDE.md
 
 
Changelog-Dev.md
Changelog-Dev.md
 
 
Changelog.md
Changelog.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
build-css.cjs
build-css.cjs
 
 
build.js
build.js
 
 
client.d.ts
client.d.ts
 
 
common.d.ts
common.d.ts
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
server.d.ts
server.d.ts
 
 
tailwind.config.js
tailwind.config.js
 
 
tsconfig.base.json
tsconfig.base.json
 
 
tsconfig.client.json
tsconfig.client.json
 
 
tsconfig.common.json
tsconfig.common.json
 
 
tsconfig.server.json
tsconfig.server.json
 
 

Repository files navigation

ProcessCube App SDK

Das @5minds/processcube_app_sdk ist ein TypeScript-SDK zur Entwicklung von ProcessCube-Anwendungen mit Next.js. Es stellt React-Komponenten, Server-Funktionen und gemeinsam genutzte Utilities für Prozessvisualisierung (BPMN), dynamische Formulare und die Integration mit der ProcessCube-Engine bereit.

Überblick

Features

  • Next.js 15+ App Router mit React 19 Server Components
  • Vollständig typisiert durch TypeScript-Support
  • OAuth 2.0 Authentifizierung via Authority-Integration (NextAuth + Client Credentials)
  • Ready-to-use React-Komponenten für BPMN-Viewer, Prozess-Inspektion und dynamische Formulare
  • Sichere Engine-Kommunikation über Server-Side Functions und Server Actions
  • Automatische Worker-Registrierung für External Tasks
  • Authority Client für Server-to-Server User-Administration

Architektur

Das SDK hat eine Drei-Schichten-Modulstruktur mit strikter Trennung:

graph TD
  subgraph SDK["@5minds/processcube_app_sdk"]
    direction TB
    Common["Common<br/><code>@5minds/processcube_app_sdk</code><br/><br/>Gemeinsame Typen, Komponenten<br/>und Funktionen"]

    Server["Server<br/><code>@5minds/processcube_app_sdk/server</code><br/><br/>Engine-Client, Server Actions,<br/>External Tasks, Auth, Authority Client"]

    Client["Client<br/><code>@5minds/processcube_app_sdk/client</code><br/><br/>React-Komponenten:<br/>BPMNViewer, DynamicUi,<br/>ProcessInstanceInspector"]
  end

  Server -->|importiert| Common
  Client -->|importiert| Common

  Engine["ProcessCube Engine"]
  Authority["ProcessCube Authority"]
  Browser["Browser / React"]

  Server -->|HTTP| Engine
  Server -->|OAuth2 / HTTP| Authority
  Client --> Browser
Loading

Export-Map

Das Paket hat drei Einstiegspunkte — jeder mit ESM- und CJS-Support. Komponenten-CSS wird beim Import automatisch vom Consumer-Bundler aufgelöst.

graph LR
  subgraph Imports
    I1["import _ from<br/>'@5minds/processcube_app_sdk'"]
    I2["import _ from<br/>'@5minds/processcube_app_sdk/server'"]
    I3["import _ from<br/>'@5minds/processcube_app_sdk/client'"]
  end

  I1 --> Common["common/index.mjs<br/><small>.cjs</small>"]
  I2 --> Server["server/index.mjs<br/><small>.cjs</small>"]
  I3 --> Client["client/index.mjs<br/><small>.cjs + CSS auto-import</small>"]
Loading
Import-Pfad Inhalt Umgebung
@5minds/processcube_app_sdk Gemeinsame Typen, RemoteUserTask, hasClaim, Auth-Callbacks Client + Server
@5minds/processcube_app_sdk/server Engine-Funktionen, Server Actions, Auth, Authority Client, External Tasks Nur Server
@5minds/processcube_app_sdk/client React-Komponenten (BPMNViewer, DynamicUi, ProcessInstanceInspector, …). CSS wird automatisch mitgeladen. Nur Client
…/client/styles Tailwind-Basisstyles (optional, nur wenn separat benötigt) CSS-Import

Installation

Voraussetzungen

  • Node.js >= 24
  • Next.js >= 15
  • React >= 19

Paket installieren

npm install @5minds/processcube_app_sdk

Next.js konfigurieren

Die einfachste Konfiguration mit dem SDK-Plugin:

// next.config.ts
import { withApplicationSdk } from '@5minds/processcube_app_sdk/server';

export default withApplicationSdk({
  applicationSdk: {
    useExternalTasks: true,
  },
});

Ohne External Tasks reicht:

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  serverExternalPackages: ['esbuild'],
};

export default nextConfig;

CSS einbinden

Komponenten-CSS wird automatisch geladen — beim Import einer Client-Komponente wird das zugehörige Stylesheet vom Consumer-Bundler (webpack/turbopack) mit aufgelöst. Ein manueller CSS-Import ist in den meisten Fällen nicht nötig.

Falls die Tailwind-Basisstyles (Resets, Utilities) separat benötigt werden:

// app/layout.tsx
import '@5minds/processcube_app_sdk/client/styles';

Umgebungsvariablen

Erstelle eine .env.local im Projekt-Root:

# Pflicht
PROCESSCUBE_ENGINE_URL=http://localhost:10560

# Für Authentifizierung (optional)
PROCESSCUBE_AUTHORITY_URL=http://localhost:11560
NEXTAUTH_CLIENT_ID=my_client_id
NEXTAUTH_SECRET=my_secret

Die vollständige Liste aller Umgebungsvariablen findest du im Abschnitt Konfiguration.

Authentifizierung

Das SDK bietet zwei Authentifizierungs-Strategien für unterschiedliche Anwendungsfälle:

flowchart TD
  Start["Authentifizierung benötigt"] --> Q1{"Wer handelt?"}

  Q1 -->|"Eingeloggter Benutzer<br/>(Browser-Session)"| UserPath["User-Identity<br/><code>getIdentity()</code>"]
  Q1 -->|"Server/Service<br/>(kein Benutzerkontext)"| ServerPath["Server-Identity<br/><code>getServerIdentity()</code>"]

  UserPath --> U1["NextAuth JWT aus Cookie"]
  U1 --> U2["Automatischer Token-Refresh"]
  U2 --> U3["Identity: { token, userId }"]

  ServerPath --> S1["Client Credentials Grant"]
  S1 --> S2["Token-Cache mit Auto-Refresh"]
  S2 --> S3["Identity: { token, userId }"]

  U3 --> UseCase1["Server Components<br/>Server Actions<br/>API Routes"]
  S3 --> UseCase2["External Tasks<br/>Cron-Jobs<br/>Authority Admin API"]

  style UserPath fill:#e0f0ff
  style ServerPath fill:#fff0e0
Loading

User-Identity (NextAuth-basiert)

Für Server Components und Server Actions, die im Kontext eines eingeloggten Benutzers laufen:

getIdentity()

Gibt die Identity des aktuell eingeloggten Benutzers zurück. Nutzt das NextAuth-JWT aus dem Session-Cookie.

import { getIdentity } from '@5minds/processcube_app_sdk/server';

export default async function MyPage() {
  const identity = await getIdentity();
  // identity.token  — Access Token
  // identity.userId — User ID (sub Claim)
}

Der Token wird automatisch erneuert, wenn er abgelaufen ist. Voraussetzung: PROCESSCUBE_AUTHORITY_URL, NEXTAUTH_CLIENT_ID und NEXTAUTH_SECRET sind gesetzt.

hasClaim()

Prüft, ob der aktuelle Benutzer einen bestimmten Claim besitzt. Funktioniert sowohl in Server Components als auch im Client.

import { hasClaim } from '@5minds/processcube_app_sdk';

const isAdmin = await hasClaim('admin');

Auth-Callbacks für NextAuth

Das SDK exportiert vorkonfigurierte Callbacks für die NextAuth-Konfiguration:

import { authConfigJwtCallback, authConfigSessionCallback } from '@5minds/processcube_app_sdk';

export const authOptions = {
  callbacks: {
    jwt: authConfigJwtCallback,
    session: authConfigSessionCallback,
  },
  // ... weitere NextAuth-Konfiguration
};
Callback Aufgabe
authConfigJwtCallback Überträgt Access Token, ID Token und Refresh Token in das JWT. Erneuert abgelaufene Tokens automatisch.
authConfigSessionCallback Extrahiert Claims aus dem Access Token und stellt sie in session.user.claims bereit.

Server-Identity (Client Credentials)

Für Server-to-Server-Kommunikation ohne Benutzerkontext — typischerweise in External Tasks, Cron-Jobs oder Authority-Admin-Operationen:

getServerAccessToken()

Holt einen Access Token über den OAuth2 Client Credentials Grant. Der Token wird gecacht und automatisch vor Ablauf erneuert.

import { getServerAccessToken } from '@5minds/processcube_app_sdk/server';

const token = await getServerAccessToken();
sequenceDiagram
  participant App as Anwendung
  participant Cache as Token-Cache
  participant Auth as Authority

  App->>Cache: getServerAccessToken()
  alt Token im Cache und gültig
    Cache-->>App: Gecachter Token
  else Kein Token oder abgelaufen
    Cache->>Auth: POST /token<br/>(client_credentials)
    alt Erfolg
      Auth-->>Cache: { access_token, expires_in }
      Note over Cache: Token speichern<br/>(Ablauf × 0.85 Buffer)
      Cache-->>App: Neuer Token
    else Fehler (401/403 — Client gesperrt)
      Auth-->>Cache: HTTP Error
      Cache-->>App: Error wird geworfen
    end
  end
Loading

Optionen:

interface ServerAccessTokenOptions {
  clientId?: string; // Default: PROCESSCUBE_SERVER_CLIENT_ID
  clientSecret?: string; // Default: PROCESSCUBE_SERVER_CLIENT_SECRET
  scopes?: string; // Default: PROCESSCUBE_SERVER_SCOPES oder 'upe_admin engine_read engine_write'
  authorityUrl?: string; // Default: PROCESSCUBE_AUTHORITY_URL
  skipCache?: boolean; // Cache umgehen und frischen Token holen
}

getServerIdentity()

Wrapper um getServerAccessToken(), der direkt ein Identity-Objekt zurückgibt:

import { getServerIdentity } from '@5minds/processcube_app_sdk/server';

const identity = await getServerIdentity();
// identity.token  — Access Token
// identity.userId — Service-Account User ID

Authority Client

Der AuthorityClient bietet authentifizierten Zugriff auf die ProcessCube Authority API — in zwei Stufen:

classDiagram
  class AuthorityClient {
    -authorityUrl: string
    -tokenOptions: ServerAccessTokenOptions
    +constructor(options?: AuthorityClientOptions)
    +request(method, path, body?) AuthorityResponse~T~
    +updateClaim(username, claimName, claimValue) AuthorityResponse
    +addScope(username, scopeName) AuthorityResponse
    +addGroup(username, groupName) AuthorityResponse
    +deleteUser(username, options?) AuthorityResponse
  }

  class AuthorityResponse~T~ {
    +ok: boolean
    +status: number
    +data: T
  }

  AuthorityClient --> AuthorityResponse : gibt zurück
Loading

Stufe 1 — Allgemein: request()

Für beliebige Authority-API-Aufrufe. Der Token wird automatisch beschafft und als Cookie gesendet:

import { AuthorityClient } from '@5minds/processcube_app_sdk/server';

const authority = new AuthorityClient();

// Beliebiger API-Aufruf
const response = await authority.request('GET', '/acr/username_password/admin/users');
if (response.ok) {
  console.log(response.data);
}

Stufe 2 — Convenience-Methoden

Vordefinierte Methoden für häufige User-Admin-Operationen:

import { AuthorityClient } from '@5minds/processcube_app_sdk/server';

const authority = new AuthorityClient();

// Claim setzen
await authority.updateClaim('user@example.com', 'email_verified', true);

// Scope hinzufügen
await authority.addScope('user@example.com', 'premium_content');

// Gruppe zuweisen
await authority.addGroup('user@example.com', 'Partner-Netzwerk');

// User soft-deleten
const result = await authority.deleteUser('user@example.com', { fullDelete: false });
Methode HTTP Beschreibung
updateClaim(username, claimName, claimValue) PATCH Setzt einen Claim auf dem User-Account
addScope(username, scopeName) PATCH Fügt einen Scope zum User hinzu
addGroup(username, groupName) PATCH Fügt den User einer Gruppe hinzu
deleteUser(username, { fullDelete? }) DELETE Löscht oder soft-deleted einen User

Alle Methoden geben ein AuthorityResponse<T> zurück mit ok, status und data.

Beispiel: External Task mit Authority Client

Vorher (ohne SDK-Helper):

export default async function (payload: any) {
  const response = await fetch(`${process.env.PROCESSCUBE_AUTHORITY_URL}/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.PROCESSCUBE_SERVER_CLIENT_ID,
      client_secret: process.env.PROCESSCUBE_SERVER_CLIENT_SECRET,
      scope: 'upe_admin engine_read engine_write',
    }).toString(),
  });
  const { access_token } = await response.json();

  const result = await fetch(`${process.env.PROCESSCUBE_AUTHORITY_URL}/acr/username_password/admin/user/${payload.email}/delete`, {
    method: 'DELETE',
    headers: { Cookie: `access_token=${access_token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ fullDelete: false }),
  });
  return { completed_successful: result.ok };
}

Nachher (mit Authority Client):

import { AuthorityClient } from '@5minds/processcube_app_sdk/server';

export default async function (payload: any) {
  const authority = new AuthorityClient();
  const result = await authority.deleteUser(payload.email, { fullDelete: false });
  return { completed_successful: result.ok };
}

Konfiguration

withApplicationSdk Plugin

Das SDK-Plugin für Next.js konfiguriert die Anwendung automatisch und startet bei Bedarf External Task Worker:

import { withApplicationSdk } from '@5minds/processcube_app_sdk/server';

export default withApplicationSdk({
  applicationSdk: {
    useExternalTasks: true,
    customExternalTasksDirPath: './my-tasks', // Optional
  },
  // Weitere Next.js-Optionen hier
});
Option Typ Standard Beschreibung
useExternalTasks boolean false External Task Worker aktivieren
customExternalTasksDirPath string ./app oder ./src/app Verzeichnis für External Task Handler

Das Plugin fügt automatisch esbuild zu serverExternalPackages hinzu und startet Worker nur im Server-Modus (nicht während next build).

Umgebungsvariablen

Allgemein

Variable Pflicht Standard Beschreibung
PROCESSCUBE_ENGINE_URL Nein http://localhost:10560 URL der ProcessCube Engine
PROCESSCUBE_AUTHORITY_URL Nein — URL der ProcessCube Authority. Aktiviert Token-basierte Authentifizierung.

User-Identity (NextAuth)

Variable Pflicht Standard Beschreibung
NEXTAUTH_CLIENT_ID Wenn Authority — OAuth2 Client ID für den Benutzer-Login
NEXTAUTH_SECRET Wenn Authority — Secret für NextAuth JWT-Verschlüsselung
NEXTAUTH_URL Nein Auto-Detect URL der NextAuth-Instanz (für Token-Refresh)

Server-Identity (Client Credentials)

Variable Pflicht Standard Beschreibung
PROCESSCUBE_SERVER_CLIENT_ID Wenn Server-Identity — OAuth2 Client ID für Server-to-Server Auth
PROCESSCUBE_SERVER_CLIENT_SECRET Wenn Server-Identity — OAuth2 Client Secret
PROCESSCUBE_SERVER_SCOPES Nein upe_admin engine_read engine_write Scopes für den Server-Token

External Task Worker

Variable Pflicht Standard Beschreibung
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_ID Wenn Authority — Client ID für External Task Worker Auth
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_SECRET Wenn Authority — Client Secret für External Task Worker Auth
PROCESSCUBE_APP_SDK_ETW_RETRY Nein 6 Max. Reconnect-Versuche bei Verbindungsfehlern

Server-Funktionen

Übersicht

Alle Server-Funktionen werden aus @5minds/processcube_app_sdk/server importiert und können in Server Components, Server Actions und API Routes verwendet werden.

Kategorie Funktionen
Authentifizierung getIdentity, getServerAccessToken, getServerIdentity
Authority AuthorityClient
Process-Instanzen getProcessInstanceById, getActiveProcessInstances, retryProcessInstance, terminateProcessInstance, waitForProcessEnd, getFlowNodeInstancesByProcessInstanceId, getFlowNodeInstancesTriggeredByFlowNodeInstanceIds
User Tasks getUserTasks, getWaitingUserTasks, getWaitingUserTasksByProcessInstanceId, getWaitingUserTasksByFlowNodeId, getWaitingUserTaskByFlowNodeInstanceId, getWaitingUserTasksByCorrelationId, getReservedUserTasksByIdentity, getAssignedUserTasksByIdentity, waitForUserTask, finishUserTaskAndGetNext, reserveUserTask, cancelReservedUserTask
Server Actions startProcess, finishUserTask, finishManualTask, finishUntypedTask, finishTask, navigateToUrl
Engine getEngineClient
Plugin withApplicationSdk
External Tasks ExternalTaskConfig (Type)

Process-Instanzen

getProcessInstanceById

Gibt die Prozessinstanz mit der angegebenen ID zurück (inkl. BPMN-XML).

import { getProcessInstanceById } from '@5minds/processcube_app_sdk/server';

const instance = await getProcessInstanceById('process-instance-id');

getActiveProcessInstances

Gibt alle laufenden Prozessinstanzen zurück. Unterstützt Filterung und Paginierung.

import { getActiveProcessInstances } from '@5minds/processcube_app_sdk/server';

// Alle laufenden Instanzen
const result = await getActiveProcessInstances();

// Mit Filter
const filtered = await getActiveProcessInstances({
  query: { processModelId: 'OrderProcess' },
  options: { limit: 10, offset: 0 },
});

retryProcessInstance

Startet eine Prozessinstanz von einem bestimmten FlowNode neu.

import { retryProcessInstance } from '@5minds/processcube_app_sdk/server';

// Gesamten Prozess neu starten
await retryProcessInstance('process-instance-id');

// Ab einem bestimmten FlowNode
await retryProcessInstance('process-instance-id', 'flow-node-instance-id');

// Mit neuem Start-Token
await retryProcessInstance('process-instance-id', 'flow-node-instance-id', { orderId: 'new-123' });

terminateProcessInstance

Beendet eine Prozessinstanz sofort.

import { terminateProcessInstance } from '@5minds/processcube_app_sdk/server';

await terminateProcessInstance('process-instance-id');

waitForProcessEnd

Wartet, bis eine Prozessinstanz beendet, terminiert oder fehlerhaft ist. Nutzt Engine-Notifications (kein Polling).

import { waitForProcessEnd } from '@5minds/processcube_app_sdk/server';

const finishedInstance = await waitForProcessEnd({
  processInstanceId: 'process-instance-id',
});

getFlowNodeInstancesByProcessInstanceId

Gibt alle FlowNode-Instanzen einer Prozessinstanz zurück (sortiert nach Erstellungsdatum).

import { getFlowNodeInstancesByProcessInstanceId } from '@5minds/processcube_app_sdk/server';

const flowNodes = await getFlowNodeInstancesByProcessInstanceId('process-instance-id');

getFlowNodeInstancesTriggeredByFlowNodeInstanceIds

Gibt FlowNode-Instanzen zurück, die von den angegebenen FlowNode-Instanzen ausgelöst wurden.

import { getFlowNodeInstancesTriggeredByFlowNodeInstanceIds } from '@5minds/processcube_app_sdk/server';

const triggered = await getFlowNodeInstancesTriggeredByFlowNodeInstanceIds(['fni-1', 'fni-2']);

User Tasks

Blocking vs. Non-Blocking: Einige Funktionen blocken, bis ein Event eintritt. Das ist wichtig für die Wahl der richtigen Funktion:

Funktion Blockiert? Use-Case
waitForUserTask() Ja Server-seitig auf nächsten Task warten (Event-Sub)
getWaitingUserTasks() Nein Polling, UI-Abfragen, Server Components
getUserTasks() Nein Allgemeine Abfrage mit vollem Query-Objekt
waitForProcessEnd() Ja Warten bis Prozess beendet (Event-Sub)

getWaitingUserTasks

Gibt alle wartenden User Tasks zurück.

import { getWaitingUserTasks } from '@5minds/processcube_app_sdk/server';

const { userTasks, totalCount } = await getWaitingUserTasks();

getWaitingUserTasksByProcessInstanceId

Filtert wartende User Tasks nach Prozessinstanz.

import { getWaitingUserTasksByProcessInstanceId } from '@5minds/processcube_app_sdk/server';

const { userTasks } = await getWaitingUserTasksByProcessInstanceId('process-instance-id');

// Auch mit Array von IDs
const { userTasks: multiple } = await getWaitingUserTasksByProcessInstanceId(['id-1', 'id-2']);

getWaitingUserTaskByFlowNodeInstanceId

Gibt eine einzelne wartende User Task nach FlowNode-Instanz-ID zurück (oder null).

import { getWaitingUserTaskByFlowNodeInstanceId } from '@5minds/processcube_app_sdk/server';

const userTask = await getWaitingUserTaskByFlowNodeInstanceId('flow-node-instance-id');

waitForUserTask

Wartet auf die nächste wartende User Task. Falls bereits eine existiert, wird sie sofort zurückgegeben.

import { waitForUserTask } from '@5minds/processcube_app_sdk/server';

// Auf beliebige User Task warten
const userTask = await waitForUserTask();

// Mit Filter
const filtered = await waitForUserTask({
  processInstanceId: 'process-instance-id',
  flowNodeId: 'UserTask_Approve',
});

finishUserTaskAndGetNext

Schließt eine User Task ab und gibt die nächste wartende User Task zurück (falls vorhanden).

import { finishUserTaskAndGetNext } from '@5minds/processcube_app_sdk/server';

const nextTask = await finishUserTaskAndGetNext('flow-node-instance-id', { processInstanceId: 'process-instance-id' }, { approved: true });

reserveUserTask / cancelReservedUserTask

Reserviert eine User Task für einen bestimmten Benutzer oder hebt die Reservierung auf.

import { reserveUserTask, cancelReservedUserTask, getIdentity } from '@5minds/processcube_app_sdk/server';

const identity = await getIdentity();
await reserveUserTask(identity, 'flow-node-instance-id');

// Reservierung aufheben
await cancelReservedUserTask(identity, 'flow-node-instance-id');

Weitere User-Task-Funktionen

Funktion Beschreibung
getUserTasks(query, options?) Generische Abfrage mit vollem Query-Objekt
getWaitingUserTasksByFlowNodeId(flowNodeId, options?) Filter nach BPMN-FlowNode-ID
getWaitingUserTasksByCorrelationId(correlationId, options?) Filter nach Correlation-ID
getReservedUserTasksByIdentity(identity?, options?) Vom aktuellen User reservierte Tasks
getAssignedUserTasksByIdentity(identity?, options?) Dem aktuellen User zugewiesene Tasks

Alle Funktionen unterstützen einen identity-Parameter:

Wert Verhalten
true (Default) Nutzt die implizite User-Identity aus der NextAuth-Session
false Anonymer Zugriff — kein Auth-Header. Voraussetzung: Engine muss allowAnonymousRootAccess: true haben.
Identity-Objekt Explizite Identity (z.B. von getServerIdentity() oder getIdentity())

Server Actions

Server Actions sind für den Aufruf aus Client Components oder Formularen gedacht:

import { startProcess, finishUserTask, navigateToUrl } from '@5minds/processcube_app_sdk/server';
Action Beschreibung
startProcess(...) Startet eine Prozessinstanz (Argumente wie Engine-Client)
finishUserTask(flowNodeInstanceId, result, identity?) Schließt eine User Task ab
finishManualTask(flowNodeInstanceId, identity?) Schließt eine Manual Task ab
finishUntypedTask(flowNodeInstanceId, identity?) Schließt eine generische bpmn:Task ab
finishTask(flowNodeInstanceId, flowNodeType) Universelle Finish-Funktion (erkennt Task-Typ)
navigateToUrl(url) Server-seitige Weiterleitung via Next.js redirect()

Beispiel: Server Action in einem Formular

// app/tasks/page.tsx
import { finishUserTask, getWaitingUserTasks } from '@5minds/processcube_app_sdk/server';
import { revalidatePath } from 'next/cache';

export default async function TasksPage() {
  const { userTasks } = await getWaitingUserTasks();

  async function handleFinish(flowNodeInstanceId: string) {
    'use server';
    await finishUserTask(flowNodeInstanceId, { approved: true });
    revalidatePath('/tasks');
  }

  return (
    <ul>
      {userTasks.map((task) => (
        <li key={task.flowNodeInstanceId}>
          {task.flowNodeName}
          <form action={handleFinish.bind(null, task.flowNodeInstanceId)}>
            <button type="submit">Abschließen</button>
          </form>
        </li>
      ))}
    </ul>
  );
}

Engine Client

Für direkte Zugriffe auf die Engine-API, die nicht durch die SDK-Funktionen abgedeckt sind:

import { getEngineClient } from '@5minds/processcube_app_sdk/server';

const client = getEngineClient();
// Zugriff auf alle Engine-Client-APIs
const models = await client.processModels.getProcessModels();

Der Client ist ein Singleton und nutzt die PROCESSCUBE_ENGINE_URL.

Client-Komponenten

Alle Client-Komponenten werden aus @5minds/processcube_app_sdk/client importiert und müssen in Dateien mit 'use client' verwendet werden.

Übersicht

Komponente Beschreibung
BPMNViewer BPMN-Diagramm-Rendering mit Overlays und Markern
ProcessInstanceInspector Interaktive Prozessinstanz-Ansicht mit Token-Inspektion
DynamicUi Dynamischer Formular-Builder aus UserTask-Schemas
ProcessModelInspector Prozessmodell mit Heatmap-Visualisierung
DocumentationViewer Markdown-Dokumentation mit Syntax-Highlighting
SplitterLayout Größenveränderbares Panel-Layout
DropdownMenu Dropdown-Menü (Headless UI)
RemoteUserTask iFrame-basierte Remote User Task (Common)

CSS: Alle Komponenten laden ihr Stylesheet automatisch. Ein manueller CSS-Import ist nicht nötig.

BPMNViewer

Rendert BPMN-Diagramme und bietet eine Ref-API für Overlays, Marker und Heatmaps.

'use client';

import { BPMNViewerNextJS, BPMNViewerFunctions } from '@5minds/processcube_app_sdk/client';
import { useRef } from 'react';

export default function DiagramPage({ xml }: { xml: string }) {
  const viewerRef = useRef<BPMNViewerFunctions>(null);

  return (
    <BPMNViewerNextJS
      xml={xml}
      viewerRef={viewerRef}
      onSelectionChanged={(elements) => console.log('Ausgewählt:', elements)}
      onImportDone={() => console.log('Diagramm geladen')}
    />
  );
}

Props:

Prop Typ Pflicht Beschreibung
xml string Ja BPMN-XML des Diagramms
className string Nein CSS-Klasse für den Container
preselectedElementIds string[] Nein Vorausgewählte BPMN-Elemente
onSelectionChanged (elements) => void Nein Callback bei Auswahländerung
onImportDone () => void Nein Callback nach erfolgreichem Import
viewerRef ForwardedRef<BPMNViewerFunctions> Nein Nur bei BPMNViewerNextJS

Ref-API (BPMNViewerFunctions):

Methode Beschreibung
getOverlays() Gibt das Overlay-Modul zurück
getElementRegistry() Gibt die Element-Registry zurück
addMarker(elementId, className) Fügt einen CSS-Marker zu einem Element hinzu
removeMarker(elementId, className) Entfernt einen CSS-Marker
hasMarker(elementId, className) Prüft ob ein Marker gesetzt ist
showHeatmap(data) Zeigt Heatmap-Daten an ({ elementId: color })
clearHeatmap(data) Entfernt Heatmap-Daten

ProcessInstanceInspector

Interaktive Ansicht einer Prozessinstanz mit BPMN-Diagramm, Token-Inspektion, Retry und Kommandopalette.

'use client';

import { ProcessInstanceInspectorNextJS } from '@5minds/processcube_app_sdk/client';

export default function InspectorPage({ processInstanceId }: { processInstanceId: string }) {
  return (
    <ProcessInstanceInspectorNextJS
      processInstanceId={processInstanceId}
      showFinishTaskButton
      showProcessRetryButton
      showProcessTerminateButton
      showTokenInspectorButton
      onFinish={async ({ flowNodeInstanceId, taskType }) => {
        console.log(`Task ${flowNodeInstanceId} (${taskType}) abgeschlossen`);
      }}
    />
  );
}

Props:

Prop Typ Pflicht Beschreibung
processInstanceId string Ja ID der Prozessinstanz
showFinishTaskButton boolean Nein Play-Button zum Abschließen von Tasks
showFlowNodeExecutionCount boolean Nein Ausführungszähler auf FlowNodes
showFlowNodeInstancesListButton boolean Nein Liste der FlowNode-Instanzen
showGoToFlowNodeButton boolean Nein Navigation zu FlowNodes
showRetryFlowNodeInstanceButton boolean Nein Retry-Button auf FlowNode-Ebene
showProcessRefreshButton boolean Nein Daten-Refresh-Button
showProcessRetryButton boolean Nein Prozess-Retry-Button
showProcessTerminateButton boolean Nein Prozess-Terminate-Button
showTokenInspectorButton boolean Nein Token-Inspektor öffnen
loadingComponent ReactNode Nein Custom Loading-Indikator
onFinish (taskContext) => void Nein Callback nach Task-Abschluss

DynamicUi

Rendert dynamische Formulare basierend auf UserTask-FormField-Definitionen. Unterstützt 25+ Feldtypen und Custom Fields.

'use client';

import { DynamicUi } from '@5minds/processcube_app_sdk/client';

export default function TaskForm({ task }) {
  return (
    <DynamicUi
      task={task}
      onSubmit={async (result, rawFormData, task) => {
        console.log('Ergebnis:', result);
      }}
      title="Aufgabe bearbeiten"
    />
  );
}

Props:

Prop Typ Pflicht Beschreibung
task UserTaskInstance Ja Die User Task mit FormField-Definitionen
onSubmit (result, formData, task) => Promise<void> Ja Submit-Handler
headerComponent JSX.Element Nein Custom Header über dem Formular
className string Nein CSS-Klasse für den Root-Container
classNames Partial<Record<'wrapper' | 'base' | 'header' | 'body' | 'footer', string>> Nein CSS-Klassen für Unterelemente
title ReactNode Nein Titel des Formulars
customFieldComponents DynamicUiFormFieldComponentMap Nein Custom-Renderer für Feldtypen
state FormState Nein Externer Formular-State
onStateChange (newValue, formFieldId, formState) => void Nein Callback bei Wertänderung
darkMode true Nein Dark-Mode aktivieren 
graph TD
  Task["UserTaskInstance<br/>(mit FormField-Definitionen)"] --> DynUi["DynamicUi"]
  DynUi --> Fields["FormField-Renderer<br/>(25+ Typen)"]
  Custom["customFieldComponents<br/>(optional)"] --> DynUi
  State["state / onStateChange<br/>(optional)"] --> DynUi
  Fields --> Form["HTML-Formular"]
  Form -->|Submit| Handler["onSubmit(result, formData, task)"]
Loading

Unterstützte Feldtypen: Boolean, Checkbox, Color, Date, Datetime-Local, Decimal, Email, Enum, File, Header, Hidden, Integer, Month, Paragraph, Password, Radio, Range, Select, Confirm, String, Tel, Textarea, Time, URL, Week, Custom

Weitere Komponenten

ProcessModelInspector

Zeigt ein Prozessmodell mit optionaler Heatmap-Visualisierung.

import { ProcessModelInspectorNextJS } from '@5minds/processcube_app_sdk/client';
Prop Typ Pflicht Beschreibung
processModel any Nein Das Prozessmodell-Objekt
getInstancesFromDatabase (processModelId, hash, options?) => Promise<any[]> Nein Callback für Heatmap-Daten

DocumentationViewer

Rendert Markdown-Dokumentation.

import { DocumentationViewer } from '@5minds/processcube_app_sdk/client';

<DocumentationViewer documentation="# Titel\n\nBeschreibung..." />
Prop Typ Pflicht Beschreibung
documentation string Ja Markdown-String

SplitterLayout

Größenveränderbares Zwei-Panel-Layout.

import { SplitterLayout } from '@5minds/processcube_app_sdk/client';

<SplitterLayout vertical={false} primaryIndex={0} secondaryMinSize={200}>
  <div>Linkes Panel</div>
  <div>Rechtes Panel</div>
</SplitterLayout>
Prop Typ Standard Beschreibung
vertical boolean false Vertikale Teilung
percentage boolean false Größen in Prozent
primaryIndex number 0 Index des primären Panels
primaryMinSize number 0 Minimalgröße des primären Panels
secondaryMinSize number 0 Minimalgröße des sekundären Panels
secondaryDefaultSize number | null null Standard-Größe
customClassName string '' CSS-Klasse
onSizeChanged (size) => void null Callback bei Größenänderung
onDragStart (prev) => void null Callback bei Drag-Start
onDragEnd (prev, current) => void null Callback bei Drag-Ende

DropdownMenu

Dropdown-Menü basierend auf Headless UI.

import { DropdownMenu, DropdownMenuItem } from '@5minds/processcube_app_sdk/client';

<DropdownMenu>
  <DropdownMenuItem title="Bearbeiten" onClick={() => {}} />
  <DropdownMenuItem title="Löschen" onClick={() => {}} isDanger />
</DropdownMenu>

RemoteUserTask (Common)

Zeigt eine User Task als iFrame an. Importiert aus dem Common-Modul.

import { RemoteUserTask } from '@5minds/processcube_app_sdk';

<RemoteUserTask url="https://my-task-ui.example.com/task/123" />

External Tasks

External Tasks ermöglichen es, eigene Geschäftslogik in einer Next.js App auszuführen, die von der ProcessCube Engine als Aufgabe vergeben wird. Erreicht ein BPMN-Prozess einen External Service Task, veröffentlicht die Engine diesen unter einem Topic. Ein passender Worker in der App holt sich den Task ab, verarbeitet ihn und gibt das Ergebnis zurück.

Das App SDK übernimmt dabei die komplette Infrastruktur: Worker-Prozesse werden automatisch gestartet, überwacht und bei Fehlern neu gestartet. Der Entwickler schreibt nur die eigentliche Handler-Funktion.

Architektur

Das folgende Diagramm zeigt die drei beteiligten Schichten und ihre Kommunikation:

graph LR
  subgraph ProcessCube Engine
    E[Engine]
  end

  subgraph Next.js App – Hauptprozess
    A[ExternalTaskAdapter]
    W[File Watcher]
    T[Token Management]
  end

  subgraph Eigener Node.js Prozess je Topic
    WP1[Worker Process<br/>Topic: order/process]
    WP2[Worker Process<br/>Topic: invoice/send]
  end

  E -- "HTTP: Fetch & Lock /<br/>Finish / Error /<br/>Extend Lock" --> WP1
  E -- "HTTP: Fetch & Lock /<br/>Finish / Error /<br/>Extend Lock" --> WP2

  A -- "IPC: create / restart /<br/>updateIdentity" --> WP1
  A -- "IPC: create / restart /<br/>updateIdentity" --> WP2

  W -- "Dateiänderung erkannt" --> A
  T -- "Token-Refresh" --> A
Loading

Hauptkomponenten:

Komponente Aufgabe
ExternalTaskAdapter Läuft im Hauptprozess der Next.js App. Überwacht das Dateisystem, startet Worker-Prozesse, verwaltet Tokens und koordiniert Restarts.
ExternalTaskWorkerProcess Eigenständiger Node.js-Kindprozess (einer pro Topic). Lädt den transpilierten Handler, verbindet sich per HTTP-Long-Polling mit der Engine und verarbeitet Tasks.
ProcessCube Engine Verwaltet BPMN-Prozesse und vergibt External Tasks an Worker über das Fetch-and-Lock-Protokoll.

Lebenszyklus eines External Tasks

Das folgende Sequenzdiagramm zeigt, wie ein External Task von der Engine zum Worker gelangt, verarbeitet und abgeschlossen wird:

sequenceDiagram
  participant Engine as ProcessCube Engine
  participant Worker as Worker Process

  loop Polling-Schleife
    Worker->>Engine: POST /external_tasks/fetch_and_lock<br/>(workerId, topic, maxTasks, lockDuration)
    Note right of Engine: Long-Polling — Anfrage wartet<br/>bis Task verfügbar oder Timeout
    Engine-->>Worker: ExternalTask[] (mit Payload)
  end

  Note over Worker: Handler-Funktion wird aufgerufen:<br/>handler(payload, task, signal)

  loop Lock-Verlängerung
    Worker->>Engine: PUT /external_tasks/{id}/extend_lock<br/>(additionalDuration)
    Note right of Engine: Lock wird verlängert,<br/>damit der Task nicht abläuft
  end

  alt Erfolg
    Worker->>Engine: PUT /external_tasks/{id}/finish<br/>(result)
    Note right of Engine: Ergebnis wird als<br/>Prozessvariable gespeichert
  else Fehler
    Worker->>Engine: PUT /external_tasks/{id}/error<br/>(errorCode, errorMessage)
    Note right of Engine: Fehler wird im<br/>Prozess behandelt
  end
Loading

Ablauf im Detail:

  1. Der Worker pollt die Engine per HTTP-Long-Polling nach neuen Tasks für sein Topic.
  2. Sobald ein Task verfügbar ist, sperrt die Engine ihn (Lock) und liefert ihn mit dem Payload aus.
  3. Der Worker ruft die Handler-Funktion auf und übergibt Payload, Task-Metadaten und ein AbortSignal.
  4. Während der Verarbeitung verlängert der Worker automatisch den Lock, damit die Engine den Task nicht vorzeitig freigibt.
  5. Nach Abschluss meldet der Worker das Ergebnis (Finish) oder einen Fehler (Error) an die Engine.

Worker-Startup und IPC-Kommunikation

Das App SDK startet pro external_task.ts-Datei einen eigenen Node.js-Kindprozess. Die Kommunikation zwischen Hauptprozess (Adapter) und Kindprozess (Worker) läuft über IPC (Inter-Process Communication):

sequenceDiagram
  participant FS as Dateisystem
  participant Adapter as ExternalTaskAdapter<br/>(Hauptprozess)
  participant Worker as Worker Process<br/>(Kindprozess)
  participant Engine as ProcessCube Engine

  FS->>Adapter: Neue Datei erkannt:<br/>app/order/process/external_task.ts

  Adapter->>Adapter: Datei transpilieren (esbuild)
  Adapter->>Adapter: Topic ableiten: order/process

  Adapter->>Worker: fork() — neuer Node.js-Prozess

  Adapter->>Worker: IPC: { action: "create",<br/>topic, identity, moduleString }

  Worker->>Worker: Handler-Modul aus String laden
  Worker->>Engine: Polling starten (Fetch & Lock)
  Note over Worker,Engine: Worker verarbeitet Tasks…

  Note over FS: Datei wird geändert

  FS->>Adapter: Dateiänderung erkannt

  Adapter->>Adapter: Datei neu transpilieren
  Adapter->>Worker: IPC: { action: "restart",<br/>topic, identity, moduleString }

  Worker->>Worker: Alten Worker stoppen
  Worker->>Worker: Neuen Handler laden
  Worker->>Engine: Polling neu starten

  Note over Adapter: Token läuft ab (85% Lebensdauer)

  Adapter->>Adapter: Neuen Token holen (OpenID Connect)
  Adapter->>Worker: IPC: { action: "updateIdentity",<br/>identity }
Loading

IPC-Nachrichten:

Action Richtung Beschreibung
create Adapter → Worker Initialer Start: Übergibt Topic, Identity und transpilierten Handler-Code
restart Adapter → Worker Hot-Reload: Stoppt den alten Worker und startet mit neuem Code (gleiche Worker-ID)
updateIdentity Adapter → Worker Aktualisiert den Auth-Token auf dem laufenden Worker

Fehlerbehandlung und Restart-Strategie

Das System hat zwei Ebenen der Fehlerbehandlung: im Worker-Prozess selbst und im Adapter (Hauptprozess).

flowchart TD
  A[Fehler im Worker] --> B{Verbindungsfehler?<br/>ECONNREFUSED / ETIMEDOUT /<br/>ECONNRESET / etc.}

  B -- Ja --> C{Retries < Max?<br/>Standard: 6}
  C -- Ja --> D[Exponentieller Backoff<br/>1s → 2s → 4s → … → 30s max]
  D --> E[Erneut verbinden]
  E --> F{Verbindung OK?}
  F -- Ja --> G[Weiter arbeiten ✓]
  F -- Nein --> C

  C -- Nein --> H[Worker beenden<br/>Exit Code 3]

  B -- Nein --> I{Uncaught Exception?}
  I -- Ja --> J[Worker beenden<br/>Exit Code 4]
  I -- Nein --> K[Fehler loggen,<br/>Worker beenden<br/>Exit Code 3]

  H --> L[Adapter erkennt Exit]
  J --> L
  K --> L

  L --> M{Restarts < 6 in<br/>letzten 5 Minuten?}
  M -- Ja --> N[Exponentieller Backoff<br/>1s → 2s → 4s → … → 30s max]
  N --> O[Worker neu starten]
  O --> P{Start OK?}
  P -- Ja --> G
  P -- Nein --> L

  M -- Nein --> Q[Worker bleibt gestoppt ✗<br/>Manueller Eingriff nötig]
Loading

Worker-Level (Kindprozess):

  • Bei Verbindungsfehlern (ECONNREFUSED, ECONNRESET, ETIMEDOUT, ENOTFOUND, EAI_AGAIN, Socket Hang Up) versucht der Worker bis zu 6 Reconnects mit exponentiellem Backoff (1s → 2s → 4s → 8s → 16s → 30s max).
  • Die Anzahl der Retries ist über die Umgebungsvariable PROCESSCUBE_APP_SDK_ETW_RETRY konfigurierbar.
  • Nach Ausschöpfung der Retries beendet sich der Worker mit Exit Code 3.
  • Bei unbehandelten Exceptions beendet sich der Worker mit Exit Code 4.

Adapter-Level (Hauptprozess):

  • Erkennt der Adapter einen Worker-Exit mit Code 3 oder 4, wird ein Neustart versucht.
  • Maximal 6 Neustarts innerhalb eines 5-Minuten-Fensters sind erlaubt.
  • Die Backoff-Zeiten steigen exponentiell: 1s → 2s → 4s → 8s → 16s → 30s.
  • Wird das Limit erreicht, bleibt der Worker gestoppt — ein manueller Eingriff (z.B. App-Neustart) ist nötig.
  • Nach Ablauf des 5-Minuten-Fensters wird der Zähler zurückgesetzt.

Setup und Konfiguration

1. Next.js Plugin aktivieren

In der next.config.ts wird das SDK-Plugin eingebunden und External Tasks aktiviert:

// next.config.ts
import { withApplicationSdk } from '@5minds/processcube_app_sdk/server';

export default withApplicationSdk({
  applicationSdk: {
    useExternalTasks: true,
    // Optional: Eigenes Verzeichnis für External Tasks
    // customExternalTasksDirPath: './my-tasks',
  },
});

Das Plugin erkennt automatisch, ob die App im Development- oder Production-Modus läuft, und startet die Worker entsprechend. Während des Build-Prozesses (next build) werden keine Worker gestartet.

2. Handler-Datei anlegen

External Tasks werden durch Dateien mit dem Namen external_task.ts (oder .js) definiert. Das Verzeichnis, in dem die Datei liegt, bestimmt automatisch das Topic, unter dem sich der Worker bei der Engine registriert.

app/
├── order/
│   └── process/
│       └── external_task.ts    → Topic: order/process
├── invoice/
│   └── send/
│       └── external_task.ts    → Topic: invoice/send
└── notification/
    └── email/
        └── external_task.ts    → Topic: notification/email

Das SDK sucht Handler-Dateien standardmäßig in ./app oder ./src/app. Ein eigenes Verzeichnis kann über customExternalTasksDirPath konfiguriert werden.

Wichtig: Pro Verzeichnis darf nur eine external_task.ts oder external_task.js existieren. Beide Dateien im selben Verzeichnis führen zu einem Fehler.

Handler-Signatur

Der Handler wird als Default-Export der Datei definiert. Er erhält bis zu drei Parameter:

export default async function handleExternalTask(payload: any, task: ExternalTask<any>, signal: AbortSignal) {
  // Geschäftslogik hier
  return { result: 'done' };
}
Parameter Typ Beschreibung
payload any Die Prozessvariablen, die der BPMN-Prozess dem External Task mitgibt. Enthält die im Prozessmodell definierte Payload-Expression.
task ExternalTask<any> Metadaten des Tasks: id, workerId, topic, correlationId, processInstanceId, processDefinitionId, flowNodeInstanceId, lockExpirationTime, state, createdAt. Optional.
signal AbortSignal Wird ausgelöst, wenn ein Boundary Event (z.B. Timer) den Task abbricht. Optional.

Rückgabewert: Das zurückgegebene Objekt wird als Ergebnis an die Engine gemeldet und steht im BPMN-Prozess als Variable zur Verfügung.

Worker-Konfiguration

Über einen benannten config-Export können Worker-Einstellungen pro Handler angepasst werden:

import { ExternalTaskConfig } from '@5minds/processcube_app_sdk/server';

export const config: ExternalTaskConfig = {
  lockDuration: 5000, // Lock-Dauer in ms (Standard: 30000)
  maxTasks: 5, // Gleichzeitige Tasks pro Polling-Zyklus (Standard: 10)
};
Option Typ Standard Beschreibung
lockDuration number 30000 Dauer in Millisekunden, für die ein Task gesperrt wird. Bestimmt auch das Intervall der Lock-Verlängerung und die maximale Verzögerung bei Abort-Signalen.
maxTasks number 10 Maximale Anzahl gleichzeitig abgeholter Tasks pro Polling-Zyklus.

Abort-Handling bei Boundary Events

Wenn ein BPMN Boundary Event (z.B. ein Timer oder Signal) einen External Task abbricht, löst die Engine den Abbruch beim nächsten Lock-Renewal aus. Das AbortSignal im Handler wird daraufhin ausgelöst.

Wichtig: Die lockDuration bestimmt die maximale Verzögerung bis zum Abort, da die Engine den Abbruch erst beim nächsten Lock-Renewal mitteilen kann:

lockDuration Max. Verzögerung bis Abort
30000 (Standard) bis zu 30 Sekunden
5000 bis zu 5 Sekunden
1000 bis zu 1 Sekunde

Für zeitkritische Abbrüche sollte die lockDuration entsprechend reduziert werden.

Beispiel mit Abort-Handling:

import { ExternalTaskConfig } from '@5minds/processcube_app_sdk/server';

export const config: ExternalTaskConfig = {
  lockDuration: 5000,
};

export default async function handleExternalTask(payload: any, _task: any, signal: AbortSignal) {
  // Listener für Cleanup-Aktionen bei Abbruch
  signal.addEventListener(
    'abort',
    () => {
      console.log('Task wurde durch Boundary Event abgebrochen');
      // Hier ggf. Ressourcen freigeben
    },
    { once: true },
  );

  // Signal vor asynchronen Operationen prüfen
  if (signal.aborted) return;

  const result = await doWork(payload);

  // Signal nach asynchronen Operationen prüfen
  if (signal.aborted) return;

  return result;
}

ETW-Authentifizierung und Token-Management

Ist eine ProcessCube Authority konfiguriert, holt der Adapter automatisch Tokens per OpenID Connect Client Credentials Grant und verteilt sie an alle Worker.

sequenceDiagram
  participant Authority as OpenID Authority
  participant Adapter as ExternalTaskAdapter
  participant W1 as Worker 1
  participant W2 as Worker 2

  Adapter->>Authority: Client Credentials Grant<br/>(client_id, client_secret, scope: engine_etw)
  Authority-->>Adapter: TokenSet (access_token, expires_in)

  Adapter->>W1: IPC: create (mit Identity)
  Adapter->>W2: IPC: create (mit Identity)

  Note over Adapter: Token-Refresh bei 85%<br/>der Lebensdauer

  Adapter->>Authority: Client Credentials Grant (Refresh)
  Authority-->>Adapter: Neues TokenSet

  Adapter->>W1: IPC: updateIdentity
  Adapter->>W2: IPC: updateIdentity
Loading
  • Der Token wird bei 85% seiner Lebensdauer automatisch erneuert.
  • Alle aktiven Worker erhalten den neuen Token per IPC-Nachricht.
  • Der initiale Token-Abruf hat 10 Versuche mit exponentiellem Backoff (max. 30s).
  • Der periodische Token-Refresh versucht es unbegrenzt mit Backoff (max. 60s).
  • Ist keine Authority konfiguriert, wird eine Dummy-Identity verwendet (für lokale Entwicklung ohne Auth).

Vollständiges External-Task-Beispiel

Eine external_task.ts mit allen Features — Konfiguration, typisiertem Payload, Fehlerbehandlung und Abort-Support:

import { ExternalTaskConfig } from '@5minds/processcube_app_sdk/server';

// Worker-Konfiguration
export const config: ExternalTaskConfig = {
  lockDuration: 5000, // 5s Lock für schnelle Abort-Reaktion
  maxTasks: 3, // Maximal 3 Tasks gleichzeitig
};

// Typen für Payload und Ergebnis
interface OrderPayload {
  orderId: string;
  customerEmail: string;
  items: Array<{ productId: string; quantity: number }>;
}

interface OrderResult {
  confirmationId: string;
  processedAt: string;
}

export default async function handleExternalTask(payload: OrderPayload, task: any, signal: AbortSignal): Promise<OrderResult | undefined> {
  console.log(`Verarbeite Bestellung ${payload.orderId} (Task: ${task.id})`);

  // Abort-Handler für Cleanup
  signal.addEventListener(
    'abort',
    () => {
      console.log(`Bestellung ${payload.orderId} wurde abgebrochen`);
    },
    { once: true },
  );

  if (signal.aborted) return;

  // Geschäftslogik
  const confirmation = await processOrder(payload);

  if (signal.aborted) return;

  await sendConfirmationEmail(payload.customerEmail, confirmation);

  if (signal.aborted) return;

  return {
    confirmationId: confirmation.id,
    processedAt: new Date().toISOString(),
  };
}

Hot-Reload

Im Development-Modus überwacht das SDK die Handler-Dateien per File-Watcher. Änderungen an einer external_task.ts werden automatisch erkannt: Die Datei wird neu transpiliert und der Worker per IPC-Nachricht (restart) mit dem neuen Code neu gestartet — ohne die App neu starten zu müssen. Die Worker-ID bleibt dabei erhalten.

Entwicklung

Setup

Das SDK wird über npm gebaut:

npm ci
npm run build

Für ein Production-Build:

npm run build:prod

Verfügbare Befehle

Befehl Beschreibung
npm run build Development-Build (Code + Types + CSS parallel)
npm run build:prod Production-Build (clean + minify + tree-shake)
npm run build:types Nur .d.ts-Dateien generieren
npm run watch Watch-Modus (alle Build-Prozesse)
npm run format Code mit Prettier formatieren
npm run format:check Formatierung prüfen
npm run clean build/-Verzeichnis löschen

Lokale Entwicklung mit npm link

Um das SDK lokal in einer Consumer-App zu testen:

# Im SDK-Verzeichnis
npm link
npm run watch

# Im Zielprojekt
npm link @5minds/processcube_app_sdk

Bei Problemen mit React (doppelte React-Instanz):

npm link <pfad-zum-zielprojekt>/node_modules/react

Test-App

Im Verzeichnis test-app/ liegt eine Next.js-Beispielanwendung:

cd test-app

# Docker-Infrastruktur starten (Engine, Authority, PostgreSQL)
docker compose up

# App starten
npm run dev

Die Test-App enthält drei External Task Handler (test-task, doit, dothis) und BPMN-Beispielprozesse.

About

The SDK for ProcessCube Apps

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 33

v8.6.2 Latest
Apr 21, 2026
+ 32 releases

Packages

 
 
 

Contributors

Languages