Skip to Content
DocsApp SdkGetting Started

Getting Started

Das ProcessCube® App-SDK ermöglicht die schnelle Entwicklung von Next.js-basierten Anwendungen mit direkter Integration zur ProcessCube® Engine.

Voraussetzungen

Node.js Installation

  • Node.js 18  oder neuer
  • macOS, Windows und Linux werden unterstützt

Next.js Projekt

Ein bestehendes Next.js Projekt (Version 13+ mit App Router empfohlen)

Falls noch kein Projekt vorhanden ist:

npx create-next-app@latest my-processcube-app
cd my-processcube-app

Installation

App-SDK installieren

Installieren Sie das ProcessCube® App-SDK in Ihrem Next.js Projekt:

npm install @5minds/processcube_app_sdk@latest

Das App-SDK ist kompatibel mit Next.js 13, 14 und 15.

Next.js Konfiguration

Für Next.js 14.2.2+

Fügen Sie in der next.config.js folgende Konfiguration hinzu:

next.config.js
const nextConfig = {
  experimental: {
    serverComponentsExternalPackages: ['esbuild'],
  },
};
 
module.exports = nextConfig;

Für Next.js 15+

Fügen Sie in der next.config.ts folgende Konfiguration hinzu:

next.config.ts
import type { NextConfig } from 'next';
 
const nextConfig: NextConfig = {
  serverExternalPackages: ['esbuild'],
};
 
export default nextConfig;

Diese Konfiguration ist erforderlich, damit das App-SDK korrekt mit Next.js Server Components funktioniert.

Environment Variables

Erstellen Sie eine .env.local Datei im Projekt-Root:

.env.local
# ProcessCube Engine
PROCESSCUBE_ENGINE_URL=http://localhost:10560
 
# ProcessCube Authority (optional, bei Authentifizierung)
PROCESSCUBE_AUTHORITY_URL=http://localhost:11235

Wenn die Engine auf dem Standard-Port 10560 läuft, kann die Variable weggelassen werden.

Weitere Environment Variables finden Sie in der Configuration.

Erste Schritte

User Tasks abrufen

Erstellen Sie eine einfache Seite, die wartende User Tasks abruft:

app/page.tsx
import { getWaitingUserTasks } from '@5minds/processcube_app_sdk/server';
 
export default async function Page() {
  // User Tasks von der Engine abrufen
  const userTaskList = await getWaitingUserTasks();
 
  return (
    <div>
      <h1>Wartende User Tasks</h1>
      <ul>
        {userTaskList.userTasks.map((userTask) => (
          <li key={userTask.flowNodeInstanceId}>
            {userTask.flowNodeName}
          </li>
        ))}
      </ul>
    </div>
  );
}

Development Server starten

npm run dev

Öffnen Sie http://localhost:3000  im Browser. Sie sollten nun eine Liste der wartenden User Tasks sehen.

API Struktur

Das App-SDK bietet zwei Import-Pfade:

Server-Side Functions

Für Next.js Server Components und Server Actions:

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

Client-Side Components

Für React Client Components:

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

Server-Side Functions sollten bevorzugt werden, da sie keine Authentifizierung im Browser erfordern.

Vollständiges Beispiel

Ein vollständiges Beispiel mit User Task Handling:

app/tasks/page.tsx
import { getWaitingUserTasks, finishUserTask } from '@5minds/processcube_app_sdk/server';
import { revalidatePath } from 'next/cache';
 
export default async function TasksPage() {
  const userTaskList = await getWaitingUserTasks();
 
  // Server Action zum Abschließen einer Task
  async function handleFinishTask(flowNodeInstanceId: string) {
    'use server';
 
    await finishUserTask({
      flowNodeInstanceId,
      userTaskResult: { completed: true },
    });
 
    // Seite neu laden
    revalidatePath('/tasks');
  }
 
  return (
    <div className="container mx-auto p-4">
      <h1 className="text-2xl font-bold mb-4">Meine Aufgaben</h1>
 
      {userTaskList.userTasks.length === 0 ? (
        <p className="text-gray-500">Keine wartenden Aufgaben</p>
      ) : (
        <div className="space-y-4">
          {userTaskList.userTasks.map((task) => (
            <div
              key={task.flowNodeInstanceId}
              className="border rounded-lg p-4"
            >
              <h3 className="font-semibold">{task.flowNodeName}</h3>
              <p className="text-sm text-gray-600">
                Prozess: {task.processName}
              </p>
 
              <form action={handleFinishTask.bind(null, task.flowNodeInstanceId)}>
                <button
                  type="submit"
                  className="mt-2 px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
                >
                  Abschließen
                </button>
              </form>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

Mit Authentifizierung

Wenn Ihre Engine mit ProcessCube® Authority abgesichert ist:

app/tasks/page.tsx
import { getWaitingUserTasks } from '@5minds/processcube_app_sdk/server';
import { getServerSession } from 'next-auth';
 
export default async function TasksPage() {
  // Session abrufen (z.B. mit NextAuth.js)
  const session = await getServerSession();
 
  if (!session) {
    return <div>Bitte melden Sie sich an</div>;
  }
 
  // User Tasks mit Access Token abrufen
  const userTaskList = await getWaitingUserTasks({
    accessToken: session.accessToken,
  });
 
  return (
    <div>
      {/* Tasks anzeigen */}
    </div>
  );
}

Mehr zur Authentifizierung finden Sie in den Examples.

Project Structure

Empfohlene Projektstruktur:

my-processcube-app/
├── app/
│   ├── tasks/           # User Task Seiten
│   ├── processes/       # Prozess-Verwaltung
│   └── page.tsx         # Homepage
├── components/          # Shared Components
├── lib/                # Helper Functions
├── .env.local          # Environment Variables
├── next.config.ts      # Next.js Config
└── package.json

Nächste Schritte

Troubleshooting

esbuild Error

Problem: Error: Cannot find module 'esbuild'

Lösung: Fügen Sie die serverComponentsExternalPackages bzw. serverExternalPackages Konfiguration hinzu (siehe oben).

Engine nicht erreichbar

Problem: ECONNREFUSED oder Cannot connect to engine

Lösungen:

  • Prüfen Sie, ob die Engine läuft
  • Überprüfen Sie PROCESSCUBE_ENGINE_URL in .env.local
  • Testen Sie die Engine-URL: curl http://localhost:10560

Type Errors

Problem: TypeScript-Fehler beim Import

Lösung: Stellen Sie sicher, dass Sie die neueste Version des App-SDK installiert haben:

npm install @5minds/processcube_app_sdk@latest

Best Practice: Verwenden Sie Server Components wann immer möglich - sie sind performanter und sicherer als Client Components.

FunctionsProcessCube® Authority