@5minds/processcube_app_sdk 8.2.3-develop-d7a750-mnizx1s1 → 8.2.3-develop-3d0fa4-mnj8o7cm
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +36 -44
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -85,11 +85,11 @@ graph LR
|
|
|
85
85
|
|
|
86
86
|
**Hauptkomponenten:**
|
|
87
87
|
|
|
88
|
-
| Komponente
|
|
89
|
-
|
|
90
|
-
| **ExternalTaskAdapter**
|
|
88
|
+
| Komponente | Aufgabe |
|
|
89
|
+
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
90
|
+
| **ExternalTaskAdapter** | Läuft im Hauptprozess der Next.js App. Überwacht das Dateisystem, startet Worker-Prozesse, verwaltet Tokens und koordiniert Restarts. |
|
|
91
91
|
| **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. |
|
|
92
|
-
| **ProcessCube Engine**
|
|
92
|
+
| **ProcessCube Engine** | Verwaltet BPMN-Prozesse und vergibt External Tasks an Worker über das Fetch-and-Lock-Protokoll. |
|
|
93
93
|
|
|
94
94
|
#### Lebenszyklus eines External Tasks
|
|
95
95
|
|
|
@@ -173,11 +173,11 @@ sequenceDiagram
|
|
|
173
173
|
|
|
174
174
|
**IPC-Nachrichten:**
|
|
175
175
|
|
|
176
|
-
| Action
|
|
177
|
-
|
|
178
|
-
| `create`
|
|
179
|
-
| `restart`
|
|
180
|
-
| `updateIdentity` | Adapter → Worker | Aktualisiert den Auth-Token auf dem laufenden Worker
|
|
176
|
+
| Action | Richtung | Beschreibung |
|
|
177
|
+
| ---------------- | ---------------- | ---------------------------------------------------------------------------------- |
|
|
178
|
+
| `create` | Adapter → Worker | Initialer Start: Übergibt Topic, Identity und transpilierten Handler-Code |
|
|
179
|
+
| `restart` | Adapter → Worker | Hot-Reload: Stoppt den alten Worker und startet mit neuem Code (gleiche Worker-ID) |
|
|
180
|
+
| `updateIdentity` | Adapter → Worker | Aktualisiert den Auth-Token auf dem laufenden Worker |
|
|
181
181
|
|
|
182
182
|
#### Fehlerbehandlung und Restart-Strategie
|
|
183
183
|
|
|
@@ -276,21 +276,17 @@ Das SDK sucht Handler-Dateien standardmäßig in `./app` oder `./src/app`. Ein e
|
|
|
276
276
|
Der Handler wird als **Default-Export** der Datei definiert. Er erhält bis zu drei Parameter:
|
|
277
277
|
|
|
278
278
|
```typescript
|
|
279
|
-
export default async function handleExternalTask(
|
|
280
|
-
payload: any,
|
|
281
|
-
task: ExternalTask<any>,
|
|
282
|
-
signal: AbortSignal,
|
|
283
|
-
) {
|
|
279
|
+
export default async function handleExternalTask(payload: any, task: ExternalTask<any>, signal: AbortSignal) {
|
|
284
280
|
// Geschäftslogik hier
|
|
285
281
|
return { result: 'done' };
|
|
286
282
|
}
|
|
287
283
|
```
|
|
288
284
|
|
|
289
|
-
| Parameter | Typ
|
|
290
|
-
|
|
291
|
-
| `payload` | `any`
|
|
292
|
-
| `task`
|
|
293
|
-
| `signal`
|
|
285
|
+
| Parameter | Typ | Beschreibung |
|
|
286
|
+
| --------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
287
|
+
| `payload` | `any` | Die Prozessvariablen, die der BPMN-Prozess dem External Task mitgibt. Enthält die im Prozessmodell definierte Payload-Expression. |
|
|
288
|
+
| `task` | `ExternalTask<any>` | Metadaten des Tasks: `id`, `workerId`, `topic`, `correlationId`, `processInstanceId`, `processDefinitionId`, `flowNodeInstanceId`, `lockExpirationTime`, `state`, `createdAt`. Optional. |
|
|
289
|
+
| `signal` | `AbortSignal` | Wird ausgelöst, wenn ein Boundary Event (z.B. Timer) den Task abbricht. Optional. |
|
|
294
290
|
|
|
295
291
|
**Rückgabewert:** Das zurückgegebene Objekt wird als Ergebnis an die Engine gemeldet und steht im BPMN-Prozess als Variable zur Verfügung.
|
|
296
292
|
|
|
@@ -302,15 +298,15 @@ export default async function handleExternalTask(
|
|
|
302
298
|
import { ExternalTaskConfig } from '@5minds/processcube_app_sdk/server';
|
|
303
299
|
|
|
304
300
|
export const config: ExternalTaskConfig = {
|
|
305
|
-
lockDuration: 5000,
|
|
306
|
-
maxTasks: 5,
|
|
301
|
+
lockDuration: 5000, // Lock-Dauer in ms (Standard: 30000)
|
|
302
|
+
maxTasks: 5, // Gleichzeitige Tasks pro Polling-Zyklus (Standard: 10)
|
|
307
303
|
};
|
|
308
304
|
```
|
|
309
305
|
|
|
310
|
-
| Option
|
|
311
|
-
|
|
312
|
-
| `lockDuration` | `number` | `30000`
|
|
313
|
-
| `maxTasks`
|
|
306
|
+
| Option | Typ | Standard | Beschreibung |
|
|
307
|
+
| -------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
308
|
+
| `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. |
|
|
309
|
+
| `maxTasks` | `number` | `10` | Maximale Anzahl gleichzeitig abgeholter Tasks pro Polling-Zyklus. |
|
|
314
310
|
|
|
315
311
|
#### Abort-Handling bei Boundary Events
|
|
316
312
|
|
|
@@ -318,11 +314,11 @@ Wenn ein BPMN Boundary Event (z.B. ein Timer oder Signal) einen External Task ab
|
|
|
318
314
|
|
|
319
315
|
**Wichtig:** Die `lockDuration` bestimmt die maximale Verzögerung bis zum Abort, da die Engine den Abbruch erst beim nächsten Lock-Renewal mitteilen kann:
|
|
320
316
|
|
|
321
|
-
| lockDuration
|
|
322
|
-
|
|
323
|
-
| `30000` (Standard) | bis zu 30 Sekunden
|
|
324
|
-
| `5000`
|
|
325
|
-
| `1000`
|
|
317
|
+
| lockDuration | Max. Verzögerung bis Abort |
|
|
318
|
+
| ------------------ | -------------------------- |
|
|
319
|
+
| `30000` (Standard) | bis zu 30 Sekunden |
|
|
320
|
+
| `5000` | bis zu 5 Sekunden |
|
|
321
|
+
| `1000` | bis zu 1 Sekunde |
|
|
326
322
|
|
|
327
323
|
Für zeitkritische Abbrüche sollte die `lockDuration` entsprechend reduziert werden.
|
|
328
324
|
|
|
@@ -392,13 +388,13 @@ sequenceDiagram
|
|
|
392
388
|
|
|
393
389
|
#### Umgebungsvariablen
|
|
394
390
|
|
|
395
|
-
| Variable
|
|
396
|
-
|
|
397
|
-
| `PROCESSCUBE_ENGINE_URL`
|
|
398
|
-
| `PROCESSCUBE_AUTHORITY_URL`
|
|
399
|
-
| `PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_ID`
|
|
400
|
-
| `PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_SECRET` | Wenn Authority | —
|
|
401
|
-
| `PROCESSCUBE_APP_SDK_ETW_RETRY`
|
|
391
|
+
| Variable | Pflicht | Standard | Beschreibung |
|
|
392
|
+
| ------------------------------------------------ | -------------- | ------------------------ | ---------------------------------------------------------------------------------------- |
|
|
393
|
+
| `PROCESSCUBE_ENGINE_URL` | Nein | `http://localhost:10560` | URL der ProcessCube Engine |
|
|
394
|
+
| `PROCESSCUBE_AUTHORITY_URL` | Nein | — | URL des OpenID-Providers. Wenn gesetzt, wird Token-basierte Authentifizierung aktiviert. |
|
|
395
|
+
| `PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_ID` | Wenn Authority | — | Client-ID für den OpenID Client Credentials Grant |
|
|
396
|
+
| `PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_SECRET` | Wenn Authority | — | Client-Secret für den OpenID Client Credentials Grant |
|
|
397
|
+
| `PROCESSCUBE_APP_SDK_ETW_RETRY` | Nein | `6` | Maximale Anzahl der Reconnect-Versuche im Worker-Prozess bei Verbindungsfehlern |
|
|
402
398
|
|
|
403
399
|
#### Vollständiges Beispiel
|
|
404
400
|
|
|
@@ -409,8 +405,8 @@ import { ExternalTaskConfig } from '@5minds/processcube_app_sdk/server';
|
|
|
409
405
|
|
|
410
406
|
// Worker-Konfiguration
|
|
411
407
|
export const config: ExternalTaskConfig = {
|
|
412
|
-
lockDuration: 5000,
|
|
413
|
-
maxTasks: 3,
|
|
408
|
+
lockDuration: 5000, // 5s Lock für schnelle Abort-Reaktion
|
|
409
|
+
maxTasks: 3, // Maximal 3 Tasks gleichzeitig
|
|
414
410
|
};
|
|
415
411
|
|
|
416
412
|
// Typen für Payload und Ergebnis
|
|
@@ -425,11 +421,7 @@ interface OrderResult {
|
|
|
425
421
|
processedAt: string;
|
|
426
422
|
}
|
|
427
423
|
|
|
428
|
-
export default async function handleExternalTask(
|
|
429
|
-
payload: OrderPayload,
|
|
430
|
-
task: any,
|
|
431
|
-
signal: AbortSignal,
|
|
432
|
-
): Promise<OrderResult | undefined> {
|
|
424
|
+
export default async function handleExternalTask(payload: OrderPayload, task: any, signal: AbortSignal): Promise<OrderResult | undefined> {
|
|
433
425
|
console.log(`Verarbeite Bestellung ${payload.orderId} (Task: ${task.id})`);
|
|
434
426
|
|
|
435
427
|
// Abort-Handler für Cleanup
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@5minds/processcube_app_sdk",
|
|
3
|
-
"version": "8.2.3-develop-
|
|
3
|
+
"version": "8.2.3-develop-3d0fa4-mnj8o7cm",
|
|
4
4
|
"description": "The SDK for ProcessCube Apps",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "build/common/index.cjs",
|
|
@@ -98,8 +98,8 @@
|
|
|
98
98
|
"react": "^19.1.0"
|
|
99
99
|
},
|
|
100
100
|
"dependencies": {
|
|
101
|
-
"@5minds/processcube_engine_client": "6.
|
|
102
|
-
"@5minds/processcube_engine_sdk": "7.
|
|
101
|
+
"@5minds/processcube_engine_client": "^6.3.0-develop.2",
|
|
102
|
+
"@5minds/processcube_engine_sdk": "^7.3.0-develop.2",
|
|
103
103
|
"@headlessui/react": "^2.2.1",
|
|
104
104
|
"@heroicons/react": "^2.2.0",
|
|
105
105
|
"@heroui/react": "^2.7.6",
|