Skip to Content
DocsApp SdkFunctions

Functions

Das ProcessCube® App-SDK bietet Server-Side Helper Functions für die Interaktion mit der ProcessCube® Engine.

Übersicht

Alle Functions werden aus dem Server-Pfad importiert und können in Next.js Server Components und Server Actions verwendet werden.

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

Verfügbare Functions

User Task Functions

getWaitingUserTasks

Ruft alle wartenden User Tasks ab.

const { userTasks } = await getWaitingUserTasks();

getUserTaskByFlowNodeInstanceId

Ruft eine spezifische User Task ab.

const userTask = await getUserTaskByFlowNodeInstanceId(flowNodeInstanceId);

finishUserTask

Schließt eine User Task ab.

await finishUserTask({
  flowNodeInstanceId: 'task-123',
  userTaskResult: { approved: true }
});

Process Functions

getProcessModels

Ruft alle verfügbaren Prozessmodelle ab.

const processModels = await getProcessModels();

startProcessInstance

Startet eine Prozessinstanz.

const result = await startProcessInstance({
  processModelId: 'OrderProcess',
  startEventId: 'StartEvent_1',
  initialToken: { orderId: '12345' }
});

getProcessInstancesByCorrelationId

Ruft Prozessinstanzen nach Correlation ID ab.

const instances = await getProcessInstancesByCorrelationId(correlationId);

Correlation Functions

getActiveCorrelations

Ruft alle aktiven Correlations ab.

const correlations = await getActiveCorrelations();

Function Groups

GruppeFunctionsBeschreibung
User TasksgetWaitingUserTasks, finishUserTask, getUserTaskByFlowNodeInstanceIdUser Task Management
ProcessesgetProcessModels, startProcessInstance, getProcessInstancesByCorrelationIdProzess-Verwaltung
CorrelationsgetActiveCorrelationsCorrelation Management
External TasksgetAvailableExternalTasks, finishExternalTaskExternal Task Handling

Verwendung

In Server Components

app/tasks/page.tsx
import { getWaitingUserTasks } from '@5minds/processcube_app_sdk/server';
 
export default async function TasksPage() {
  const { userTasks } = await getWaitingUserTasks();
 
  return (
    <div>
      <h1>Meine Aufgaben</h1>
      {userTasks.map((task) => (
        <div key={task.flowNodeInstanceId}>
          {task.flowNodeName}
        </div>
      ))}
    </div>
  );
}

In Server Actions

app/actions.ts
'use server';
 
import { finishUserTask } from '@5minds/processcube_app_sdk/server';
import { revalidatePath } from 'next/cache';
 
export async function completeTask(flowNodeInstanceId: string, result: any) {
  await finishUserTask({
    flowNodeInstanceId,
    userTaskResult: result
  });
 
  revalidatePath('/tasks');
}

In API Routes

app/api/tasks/route.ts
import { getWaitingUserTasks } from '@5minds/processcube_app_sdk/server';
 
export async function GET() {
  const tasks = await getWaitingUserTasks();
 
  return Response.json(tasks);
}

TypeScript Support

Alle Functions sind vollständig typisiert:

import type {
  UserTask,
  ProcessModel,
  ProcessInstance
} from '@5minds/processcube_app_sdk/server';
 
const tasks: UserTask[] = await getWaitingUserTasks();
const processes: ProcessModel[] = await getProcessModels();

Error Handling

Behandeln Sie Fehler mit try-catch:

import { finishUserTask } from '@5minds/processcube_app_sdk/server';
 
try {
  await finishUserTask({
    flowNodeInstanceId: taskId,
    userTaskResult: result
  });
} catch (error) {
  console.error('Fehler beim Abschließen der Task:', error);
  throw error;
}

Best Practices

1. Server Components bevorzugen

Verwenden Sie Server Components statt Client-Side Fetching:

✅ Empfohlen:

// Server Component
export default async function Tasks() {
  const { userTasks } = await getWaitingUserTasks();
  return <TaskList tasks={userTasks} />;
}

❌ Nicht empfohlen:

// Client Component mit useEffect
'use client';
export default function Tasks() {
  const [tasks, setTasks] = useState([]);
  useEffect(() => {
    fetch('/api/tasks').then(r => r.json()).then(setTasks);
  }, []);
  return <TaskList tasks={tasks} />;
}

2. Custom Engine URL

Überschreiben Sie die Engine-URL wenn nötig:

const tasks = await getWaitingUserTasks({
  engineUrl: 'https://custom-engine.com'
});

3. Access Token für geschützte Engines

Verwenden Sie Access Tokens für gesicherte Engines:

import { getServerSession } from 'next-auth';
 
const session = await getServerSession();
 
const tasks = await getWaitingUserTasks({
  accessToken: session.accessToken
});

Vollständiges Beispiel

app/tasks/page.tsx
import { getWaitingUserTasks, finishUserTask } from '@5minds/processcube_app_sdk/server';
import { revalidatePath } from 'next/cache';
 
export default async function TasksPage() {
  const { userTasks } = await getWaitingUserTasks();
 
  async function handleComplete(flowNodeInstanceId: string) {
    'use server';
 
    await finishUserTask({
      flowNodeInstanceId,
      userTaskResult: { completed: true }
    });
 
    revalidatePath('/tasks');
  }
 
  return (
    <div className="container">
      <h1>Meine Aufgaben</h1>
 
      {userTasks.length === 0 ? (
        <p>Keine wartenden Aufgaben</p>
      ) : (
        <div className="grid gap-4">
          {userTasks.map((task) => (
            <div key={task.flowNodeInstanceId} className="card">
              <h3>{task.flowNodeName}</h3>
              <p>Prozess: {task.processName}</p>
 
              <form action={handleComplete.bind(null, task.flowNodeInstanceId)}>
                <button type="submit">Abschließen</button>
              </form>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

Nächste Schritte

ExamplesGetting Started