Konfiguration

External Tasks werden in der next.config.ts aktiviert und können pro Handler feingranular konfiguriert werden.

next.config.ts

Die Funktion withApplicationSdk erweitert die Next.js-Konfiguration mit External-Task-Unterstützung:

next.config.ts


const { withApplicationSdk } = require('@5minds/processcube_app_sdk/server');
 
const nextConfig = {
  serverExternalPackages: ['esbuild'],
  applicationSdk: {
    useExternalTasks: true,
  },
};
 
module.exports = withApplicationSdk(nextConfig);

applicationSdk-Optionen

Option	Typ	Standard	Beschreibung
`useExternalTasks`	`boolean`	`false`	Aktiviert die automatische Erkennung und Registrierung von External Task Workern
`customExternalTasksDirPath`	`string`	—	Individueller Pfad zum Verzeichnis mit External Tasks (relativ zum Projektroot)

Ohne useExternalTasks: true werden keine Worker gestartet, selbst wenn external_task.ts-Dateien vorhanden sind.

customExternalTasksDirPath

Standardmäßig sucht das SDK nach External Tasks in app/ oder src/app/. Mit customExternalTasksDirPath kann ein anderer Pfad verwendet werden.

next.config.ts


const nextConfig = {
  serverExternalPackages: ['esbuild'],
  applicationSdk: {
    useExternalTasks: true,
    customExternalTasksDirPath: 'workers',
  },
};
 
module.exports = withApplicationSdk(nextConfig);

Diese Option ist nicht dazu gedacht, alle External Tasks in einem separaten Ordner zu bündeln oder Topics zu kürzen. Sie existiert für Projekte, die den Pages-Router verwenden oder aus anderen Gründen das App-Verzeichnis nicht nutzen können. Der Pfad ist relativ zum Projektroot.

Handler-Konfiguration

Jeder Handler kann individuell konfiguriert werden, indem ein config-Objekt exportiert wird:

app/filter_email/external_task.ts


import type { ExternalTaskConfig } from '@5minds/processcube_app_sdk/server';
 
export const config: ExternalTaskConfig = {
  lockDuration: 60000,
  maxTasks: 5,
  longpollingTimeout: 15000,
};
 
export default async function filterEmail(payload: any) {
  return { is_spam: false };
}

Verfügbare Optionen

Option	Typ	Standard	Beschreibung
`lockDuration`	`number`	`30000`	Dauer in ms, für die ein Task gesperrt wird. Ein `ExtendLock` verlängert um denselben Betrag.
`maxTasks`	`number`	`10`	Maximale Anzahl gleichzeitig verarbeiteter Tasks pro Fetch-and-Lock
`longpollingTimeout`	`number`	`10000`	Wartezeit in ms für eine Fetch-and-Lock-Anfrage
`idleTimeout`	`number`	`500`	Wartezeit in ms vor einem erneuten Fetch-and-Lock, wenn keine Tasks vorhanden waren
`payloadFilter`	`RegExp`	—	Regulärer Ausdruck, der nur External Tasks mit übereinstimmender Payload verarbeitet

Die lockDuration beeinflusst, wie schnell ein Boundary Event einen laufenden Task abbrechen kann. Ein niedrigerer Wert ermöglicht schnellere Reaktionen, erzeugt aber mehr Netzwerk-Traffic durch häufigere Lock-Verlängerungen. Siehe AbortSignal.

Beispiel: Konfiguration mit Payload-Filter

app/process_order/external_task.ts


export const config = {
  lockDuration: 60000,
  maxTasks: 1,
  payloadFilter: /priority:\s*"high"/,
};
 
export default async function processOrder(payload: any) {
  // Verarbeitet nur Tasks mit priority: "high" in der Payload
  return { processed: true };
}

Umgebungsvariablen

External Tasks benötigen Zugriff auf die ProcessCube® Engine und optional auf die Authority. Die Konfiguration erfolgt über Umgebungsvariablen in der .env-Datei.

Engine

Wenn die Engine nicht unter der Standardadresse http://localhost:10560 erreichbar ist:

.env


PROCESSCUBE_ENGINE_URL="http://localhost:8000"

Authority

Wenn die ProcessCube® Authority zur Authentifizierung verwendet wird, werden drei Umgebungsvariablen benötigt:

.env


PROCESSCUBE_AUTHORITY_URL="http://localhost:11560"
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_ID="external_task_worker"
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_SECRET="external_task_worker_secret"

Client ID und Client Secret sollten niemals in öffentlichen Repositories gespeichert werden. Verwenden Sie .env.local und tragen Sie die Datei in .gitignore ein.

Die Werte müssen mit der Konfiguration der Authority übereinstimmen. Das SDK verwendet diese Credentials, um per client_credentials-Grant ein Token mit dem Scope engine_etw zu beziehen.

Übersicht der Umgebungsvariablen

Variable	Pflicht	Standard	Beschreibung
`PROCESSCUBE_ENGINE_URL`	Nein	`http://localhost:10560`	URL der ProcessCube® Engine
`PROCESSCUBE_AUTHORITY_URL`	Nein	—	URL der ProcessCube® Authority. Wenn gesetzt, wird Token-Management aktiviert.
`PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_ID`	Wenn Authority	—	OAuth 2.0 Client-ID
`PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_SECRET`	Wenn Authority	—	OAuth 2.0 Client-Secret