Skip to Content
DocsApp SdkConfigurationPlugin System

Plugin System

Das ProcessCube® App-SDK stellt ein Plugin-System für Next.js bereit, das erweiterte Features wie automatische External Task Worker ermöglicht.

withApplicationSdk

Die withApplicationSdk Funktion erweitert Ihre Next.js Konfiguration mit ProcessCube®-spezifischen Features.

Basis-Verwendung

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

Das Plugin ist nur erforderlich, wenn Sie External Tasks oder andere erweiterte Features nutzen möchten.

Configuration Options

applicationSdk

Der applicationSdk Block in der Next.js Config enthält alle App-SDK-spezifischen Einstellungen:

next.config.ts
import type { NextConfig } from 'next';
 
const { withApplicationSdk, NextConfigWithApplicationSdkConfig } =
  require('@5minds/processcube_app_sdk/server');
 
const nextConfig: NextConfig = {
  serverExternalPackages: ['esbuild'],
};
 
const nextConfigWithApplicationSdk: NextConfigWithApplicationSdkConfig = {
  ...nextConfig,
  applicationSdk: {
    useExternalTasks: true,
    customExternalTasksDirPath: 'app/external-tasks',
  },
};
 
module.exports = withApplicationSdk(nextConfigWithApplicationSdk);

Verfügbare Optionen

OptionTypStandardBeschreibung
useExternalTasksbooleanfalseAktiviert automatische External Task Worker
customExternalTasksDirPathstringapp/external-tasksVerzeichnis für External Task Handler

External Tasks Setup

Plugin konfigurieren

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

External Task Handler erstellen

Erstellen Sie Dateien im app/external-tasks Verzeichnis:

app/external-tasks/send-email.ts
import type { ExternalTaskHandlerFunction } from '@5minds/processcube_app_sdk/server';
 
// Handler wird automatisch beim Server-Start registriert
const sendEmailHandler: ExternalTaskHandlerFunction = async (task) => {
  const { recipient, subject, body } = task.variables;
 
  // E-Mail senden
  await sendEmail({
    to: recipient,
    subject: subject,
    text: body,
  });
 
  // Ergebnis zurückgeben
  return {
    success: true,
    sentAt: new Date().toISOString(),
  };
};
 
export default sendEmailHandler;

Topic konfigurieren

Der Topic-Name wird aus dem Dateinamen abgeleitet:

  • send-email.ts → Topic: SendEmail
  • process-payment.ts → Topic: ProcessPayment
  • validate-data.ts → Topic: ValidateData

Oder explizit setzen:

app/external-tasks/custom-topic.ts
import type { ExternalTaskHandler } from '@5minds/processcube_app_sdk/server';
 
const handler: ExternalTaskHandler = {
  topic: 'CustomTopicName',
  handler: async (task) => {
    // Handler-Logik
    return { result: 'success' };
  },
};
 
export default handler;

Erweiterte Konfiguration

Custom External Tasks Directory

Verwenden Sie ein eigenes Verzeichnis für External Task Handler:

next.config.ts
const nextConfig = {
  applicationSdk: {
    useExternalTasks: true,
    customExternalTasksDirPath: 'lib/workers',
  },
};

Struktur:

lib/
└── workers/
    ├── send-email.ts
    ├── process-payment.ts
    └── validate-order.ts

Handler mit Optionen

app/external-tasks/advanced-handler.ts
import type { ExternalTaskHandler } from '@5minds/processcube_app_sdk/server';
 
const handler: ExternalTaskHandler = {
  topic: 'AdvancedTask',
  maxTasks: 5,
  lockDuration: 60000, // 60 Sekunden
  pollingInterval: 1000, // 1 Sekunde
 
  handler: async (task) => {
    console.log(`Processing task: ${task.id}`);
 
    // Komplexe Geschäftslogik
    const result = await processComplexTask(task.variables);
 
    return result;
  },
};
 
export default handler;

Error Handling

app/external-tasks/safe-handler.ts
import type { ExternalTaskHandlerFunction } from '@5minds/processcube_app_sdk/server';
 
const safeHandler: ExternalTaskHandlerFunction = async (task) => {
  try {
    // Potentiell fehleranfällige Operation
    const result = await riskyOperation(task.variables);
 
    return { success: true, result };
 
  } catch (error) {
    console.error('Task failed:', error);
 
    // Error an Engine melden
    throw new Error(`Processing failed: ${error.message}`);
  }
};
 
export default safeHandler;

Type Definitions

NextConfigWithApplicationSdkConfig

interface NextConfigWithApplicationSdkConfig extends NextConfig {
  applicationSdk?: {
    customExternalTasksDirPath?: string;
    useExternalTasks?: boolean;
  };
}

ExternalTaskHandlerFunction

type ExternalTaskHandlerFunction = (
  task: ExternalTask
) => Promise<Record<string, any>>;

ExternalTaskHandler

interface ExternalTaskHandler {
  topic: string;
  handler: ExternalTaskHandlerFunction;
  maxTasks?: number;
  lockDuration?: number;
  pollingInterval?: number;
}

ExternalTask

interface ExternalTask {
  id: string;
  topic: string;
  workerId: string;
  flowNodeInstanceId: string;
  processInstanceId: string;
  correlationId: string;
  variables: Record<string, any>;
  identity: Identity;
}

Vollständiges Beispiel

next.config.ts
const { withApplicationSdk, NextConfigWithApplicationSdkConfig } =
  require('@5minds/processcube_app_sdk/server');
 
const nextConfig = {
  // Standard Next.js Config
  serverExternalPackages: ['esbuild'],
 
  // App-SDK Konfiguration
  applicationSdk: {
    useExternalTasks: true,
    customExternalTasksDirPath: 'app/external-tasks',
  },
};
 
module.exports = withApplicationSdk(nextConfig);
app/external-tasks/order-processor.ts
import type { ExternalTaskHandler } from '@5minds/processcube_app_sdk/server';
 
const orderProcessor: ExternalTaskHandler = {
  topic: 'ProcessOrder',
  maxTasks: 10,
  lockDuration: 30000,
  pollingInterval: 2000,
 
  handler: async (task) => {
    const { orderId, customerId, items } = task.variables;
 
    console.log(`Processing order: ${orderId}`);
 
    // Order validieren
    const isValid = await validateOrder(orderId);
    if (!isValid) {
      throw new Error('Invalid order');
    }
 
    // Payment verarbeiten
    const payment = await processPayment(customerId, calculateTotal(items));
 
    // Inventory aktualisieren
    await updateInventory(items);
 
    // Order bestätigen
    await sendConfirmation(customerId, orderId);
 
    return {
      success: true,
      orderId,
      paymentId: payment.id,
      processedAt: new Date().toISOString(),
    };
  },
};
 
export default orderProcessor;
 
// Helper Functions
async function validateOrder(orderId: string): Promise<boolean> {
  // Validierung
  return true;
}
 
async function processPayment(
  customerId: string,
  amount: number
): Promise<{ id: string }> {
  // Payment-Logik
  return { id: 'payment-123' };
}
 
function calculateTotal(items: any[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}
 
async function updateInventory(items: any[]): Promise<void> {
  // Inventory-Update
}
 
async function sendConfirmation(customerId: string, orderId: string): Promise<void> {
  // Bestätigung senden
}

Debugging

Logging aktivieren

Das Plugin loggt automatisch beim Server-Start:

✓ Ready in 2.1s
○ Local:        http://localhost:3000
○ Network:      http://192.168.1.100:3000
 
ProcessCube App SDK:
  ✓ External Tasks enabled
  ✓ Loaded 3 task handlers:
    - SendEmail
    - ProcessPayment
    - ValidateOrder

Handler-Status prüfen

app/api/health/route.ts
import { getExternalTaskHandlers } from '@5minds/processcube_app_sdk/server';
 
export async function GET() {
  const handlers = getExternalTaskHandlers();
 
  return Response.json({
    handlersCount: handlers.length,
    handlers: handlers.map(h => ({
      topic: h.topic,
      status: 'active',
    })),
  });
}

Troubleshooting

Handler werden nicht geladen

Problem: External Task Handler werden nicht registriert

Lösungen:

  1. Überprüfen Sie useExternalTasks: true in config
  2. Prüfen Sie den Dateipfad: Standard ist app/external-tasks
  3. Handler müssen als default export exportiert werden
  4. Starten Sie den Development Server neu

Type Errors

Problem: TypeScript-Fehler bei Handler-Typen

Lösung: Importieren Sie die korrekten Typen:

import type {
  ExternalTaskHandler,
  ExternalTaskHandlerFunction,
} from '@5minds/processcube_app_sdk/server';

Worker verbindet nicht

Problem: Worker verbindet nicht zur Engine

Lösungen:

  1. Prüfen Sie PROCESSCUBE_ENGINE_URL in .env.local
  2. Stellen Sie sicher, dass die Engine läuft
  3. Überprüfen Sie die Console auf Verbindungsfehler

Nächste Schritte

Environment VariablesExamples