External Tasks (AppSDK)

External Tasks in der AppSDK-App werden datei-basiert definiert. Das AppSDK-Plugin erkennt sie automatisch beim Start und registriert Worker-Prozesse.

Konvention


app/{topic}/external_task.ts

Verzeichnisname = BPMN-Topic (z.B. appsdk_greeting → Topic appsdk_greeting)
Dateiname muss external_task.ts (oder .js) sein
Das AppSDK-Plugin scannt app/ beim Start rekursiv

Beispiel: Greeting Handler

app/appsdk_greeting/external_task.ts


export default async function handleExternalTask(payload: any) {
  const greeting = payload?.greeting || 'Hallo';
  const greeting_back = `Antwort auf "${greeting}": Schoen, von dir zu hoeren!`;
 
  console.log(`[appsdk_greeting] ${greeting} -> ${greeting_back}`);
 
  return { greeting_back };
}

Signatur


export default async function handler(
  payload: any,          // Token-Daten aus dem BPMN-Prozess
  externalTask?: any,    // Vollständiges External Task Objekt
  signal?: AbortSignal   // Für Boundary Event Abbrüche
): Promise<Record<string, any>>

Parameter	Beschreibung
`payload`	Die Token-Daten des BPMN-Prozesses
`externalTask`	Das vollständige External Task Objekt (optional)
`signal`	AbortSignal für Boundary Events (optional)
Rückgabe	Objekt mit Ergebnis-Daten, die in den Prozess-Token geschrieben werden

Auto-Discovery

Das AppSDK-Plugin (withApplicationSdk()) übernimmt die gesamte Worker-Verwaltung:

Worker-Verhalten

Eigenschaft	Beschreibung
Auto-Discovery	Alle `external_task.ts`-Dateien werden automatisch gefunden
Child Process	Jeder Worker läuft als eigener Prozess
Auto-Restart	Abgestürzte Worker werden mit exponentiellem Backoff neugestartet
Token-Management	OAuth2-Tokens werden automatisch erneuert
Hot-Reload	Im Dev-Modus werden Änderungen automatisch erkannt

Konfiguration

Die Worker-Authentifizierung wird über Umgebungsvariablen gesteuert:

.env.local


PROCESSCUBE_ENGINE_URL=http://engine:8000
PROCESSCUBE_AUTHORITY_URL=http://authority:11560
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_ID=external_task_worker
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_SECRET=external_task_worker_secret

Die Authority muss einen externalTaskWorkers-Client mit dem engine_etw-Scope konfiguriert haben. Im AppTemplate ist das bereits vorbereitet.

Mehrere Worker

Für jeden External Task Topic wird eine eigene Datei angelegt:


app/
├── appsdk_greeting/
│   └── external_task.ts    # Topic: appsdk_greeting
├── send_email/
│   └── external_task.ts    # Topic: send_email
└── validate_order/
    └── external_task.ts    # Topic: validate_order

Nächste Schritte

Beispielprozess — Kompletter Durchlauf mit External Task
UserTasks — Formulare für Benutzereingaben
App-SDK External Tasks — Ausführliche API-Dokumentation