Academy
User Task programmieren

User Tasks programmieren

Erklärung

Im letzten Kapitel haben wir gelernt, wie man Prozesse starten kann. In diesem Kapitel beschäftigen wir uns nun mit User Tasks. Diese wurden bereits im Abschnitt zur Modellierung erläutert und verwendet. Wir haben also bereits modellierte Form Fields in den Prozessen integriert und im Studio ausgeführt. Jetzt wollen wir diese Form Fields auch in unserer Anwendung darstellen.

Bestellung erfassen

Um loszulegen, erstellen wir eine neue Seite und nutzen dabei die Funktionalitäten von Next.js.

Next.js ist ein Framework, welches Webseiten auf Basis von Ordnerstrukturen erstellt. Die Seiten werden dabei in Ordnern abgelegt, deren Namen für die Generierung der URLs verwendet werden.

Diese Struktur erlaubt es uns, Ordnerhierarchien zu erstellen, die die Prozessstruktur widerspiegeln. Das erleichtert sowohl die Wartung als auch die Erweiterung der Anwendung.

Beispiel

Wir möchten nun eine Seite erstellen, auf der die User Tasks "Bestellung erfassen" für den Prozess "Material-Bestellung" dargestellt werden. Der Pfad folgt dabei der Struktur: Prozessname/Taskname. Ein Beispiel hierfür wäre:

Material-Bestellung/Bestellung_erfassen/.

Da es mehrere Instanzen des Prozesses geben kann, ist es sinnvoll, die Prozessinstanz-ID in den Pfad aufzunehmen. Der vollständige Pfad sieht dann folgendermaßen aus: Prozessname/Instanz-ID/Taskname. Ein Beispiel hierfür wäre:

Material-Bestellung/[processInstanceId]/Bestellung_erfassen/.

Next.js erlaubt uns genau diese Art von Ordnerstruktur, die sich an der Prozessstruktur orientiert.

Datei anlegen

Wir erstellen also eine Page mit dem Namen page.tsx im Ordner Material-Bestellung/[processInstanceId]/Bestellung_erfassen:

/app/Material-Bestellung/[processInstanceId]/Bestellung_erfassen/page.tsx
import { DynamicUi, UserTaskResult } from '@5minds/processcube_app_sdk/client';
import { finishUserTask, getIdentity, waitForUserTask } from '@5minds/processcube_app_sdk/server';
 
import '@5minds/processcube_app_sdk/client/components/DynamicUi/DynamicUi.css';
import { Identity, UserTaskInstance } from '@5minds/processcube_engine_sdk';
import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';
 
async function submit(result: UserTaskResult, formData: FormData, userTask: UserTaskInstance) {
  'use server';
 
  const identity: Identity = await getIdentity();
  await finishUserTask(userTask.flowNodeInstanceId, result, identity);
  revalidatePath(`/`);
  redirect(`/`);
}
 
export default async function Page(params: {
  params: {
    processInstanceId: string;
  };
}) {
  const identity = await getIdentity();
  const userTask = await waitForUserTask(
    {
      processInstanceId: params.params.processInstanceId,
      flowNodeId: 'Bestellung_erfassen',
    },
    identity,
  );
 
  return (
    <div className="w-[600px] h-full sm:p-12 flex gap-4 flex-wrap">
      <DynamicUi task={userTask} classNames={{ base: 'rounded-none sm:rounded-lg' }} onSubmit={submit} darkMode />
    </div>
  );
}

submit

Hierbei handelt es sich erneut um eine Server Action (opens in a new tab). Sie besteht wie zuvor aus der getIdentity-Abfrage und einem Aufruf der Funktion finishUserTask. Diese Funktion stammt ebenfalls aus dem App.SDK und schließt den User Task ab, indem sie das sogenannte UserTaskResult an die Engine übermittelt.

Eine genauere Beschreibung befindet sich in der Dokumentation (opens in a new tab).

waitForUserTask

Wenn wir uns die Page-Funktion genauer ansehen, fällt auf, dass wir hier die Funktion waitForUserTask verwenden. Diese stammt ebenfalls aus dem App.SDK. Der Grundgedanke ist folgender: Es handelt sich um eine sogenannte Server-Component (opens in a new tab). Diese Komponenten werden auf dem Server gerendert und anschließend ausgeliefert. Das bedeutet, dass das JavaScript bereits auf dem Server ausgeführt wird. In diesem Fall bedeutet es, dass die Identität des Nutzers abgefragt und mit dieser auf einen User Task gewartet wird.

Eine genauere Beschreibung dazu findet sich in der Dokumentation (opens in a new tab).

Ein weiteres Detail ist, dass die Komponente die params-Prop verwendet, um die processInstanceId auszulesen. Mit dieser ID rufen wir dann die Funktion waitForUserTask auf. Das funktioniert mithilfe der Next.js-Funktionalität der Dynamic Routes (opens in a new tab).

Das gesamte Zusammenspiel sieht folgendermaßen aus:

  • Wir navigieren zu dem Pfad, der durch die processInstanceId spezifiziert wird.
  • Wir fetchen die entsprechende User-Task-Instanz.
  • Die Page wird serverseitig gerendert.
  • Die Page wird ausgeliefert, und der User sieht die entsprechende Seite zur jeweiligen User-Task-Instanz..
⚠️

Wichtig für die Funktionalität ist, dass die Flow-Node-ID im Prozessmodell entsprechend "Bestellung_erfassen" heißt. Wenn das noch nicht der Fall ist, muss sie unbenannt werden und die neue Version des Prozessmodells auf der Engine, die unter localhost:8000 läuft, deployed werden.

DynamicUI

Diese Komponente stammt aus dem App.SDK und rendert die Form Fields, die wir zuvor im Studio für den User Task modelliert haben. Ihr wird die UserTaskInstance übergeben, welche die Form Fields enthält. Zusätzlich wird eine sogenannte submit-Methode übergeben.

Im Wesentlichen dient diese Komponente dazu, schnell und effizient Formulare zu entwickeln (es handelt sich um dieselbe Komponente, die auch im Studio verwendet wird).

Eine genauere Beschreibung befindet sich in der Dokumentation (opens in a new tab).

Zur Page navigieren

Was wir nun machen wollen, ist das gezielte Navigieren zu der Seite, die wir gerade erstellt haben. Dazu passen wir die Funktion an, mit der wir die Prozesse starten.

In der Navbar-Komponente erweitern wir die Funktion startMaterialBestellungProcess um zusätzliche Funktionalität:

/app/components/Navbar.tsx
import React from 'react';
 
import { getIdentity, startProcess } from '@5minds/processcube_app_sdk/server';
import { Navbar, NavbarContent, NavbarItem, Link, Button } from '@nextui-org/react';
import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';
 
export async function startMaterialBestellungProcess() {
  'use server';
  const identity = await getIdentity();
  const response = await startProcess(
    {
      processModelId: 'Material-Bestellung_Process',
    },
    identity,
  );
 
  revalidatePath(`/Material-Bestellung/${response.processInstanceId}/Bestellung_erfassen`);
  redirect(`/Material-Bestellung/${response.processInstanceId}/Bestellung_erfassen`);
}
 
export default function Navigationbar() {
  return (
    <Navbar position="static">
      <NavbarContent className="hidden sm:flex gap-4" justify="center">
        <NavbarItem>
          <Link color="foreground" href="/">
            Home
          </Link>
        </NavbarItem>
        <NavbarItem>
          <form action={startMaterialBestellungProcess}>
            <Button type="submit">Bestellung erfassen</Button>
          </form>
        </NavbarItem>
      </NavbarContent>
    </Navbar>
  );
}

Das funktioniert folgendermaßen: Wir starten wie gewohnt den Prozess, entnehmen die Prozessinstanz-ID aus der Response und navigieren anschließend zur entsprechenden Seite. Auf dieser Seite wird mithilfe der processInstanceId die passende User-Task-Instanz abgefragt und dargestellt (wie oben beschrieben).

Nach dem Absenden (Submit) wird der User Task abgeschlossen und der Prozess setzt sich fort.