Customizing Referenz

Aktuell wird Version 7 von Camunda BPMN unterstützt.

Zur Info: Camunda Version 8 ist kein direkter Nachfolger von Version 7, die in Version 7 genutzten Features sind teilweise in Version 8 nicht mehr open source vorhanden. Daher ist die Unterstützung der Version 8 nicht geplant.

Voraussetzungen

Umgebung

• be Portal, beas

• Package @workflow/workflow-adapter

Tools

• Für die Modellierung des Workflows als BPMN-Diagramm → https://camunda.com/download/modeler/

• Zur Bearbeitung von JSON-Definitionen für Pages und/oder HTTP-Requests → VS Code Extension

Prozess-Variablen

In Camunda werden Prozess-Variablen dazu verwendet, Informationen zwischen Prozess-Schritten zu übertragen.

So kann zum Beispiel die erste Aufgabe in einem Prozess darin bestehen, eine Rechnung per OCR auszulesen. Ausgelesene Informationen werden in Prozess-Variablen gespeichert, die in weiteren Schritten verwendet werden, um diese Daten einem Benutzer zur Rechnungskontrolle anzuzeigen.

In User Tasks sind Variablen mit Formular-Controls verknüpft, um User Inputs zu speichern und anzuzeigen.

Prozess-Variablen bestehen aus den beiden Informationen type und value.

Gültige Typen sind:

• String

• Boolean

• Short

• Integer

• Long

• Double

• Date

• Bytes

Namenskonvention

Damit Prozess-Variablen als solche gut zu erkennen sind, müssen sie einem bestimmten Namensschema folgen:

• Variablen, die Teil des Standardumfangs eines Prozesses sind, beginnen mit std_. Des Weiteren sollte erkennbar sein, ob diese Variablen in einer Datenbank persistiert werden oder ob sie nur zur Laufzeit des Prozesses existieren.

  • Beispiele

    • std_db_eingangsrechnung_betrag ist eine Variable im Prozess Eingangsrechnung. Der Betrag wird in der Tabelle eingangsrechnung gespeichert, daher beginnt der Name mit std_db_eingangsrechnung

    • std_proc_kreditor_identifiziert aus demselben Prozess enthält die Information, ob der Kreditor automatisch identifiziert werden konnte. Der Wert wird nicht persistiert und beginnt daher mit std_proc_

• Variablen in Custom Prozessen oder Variablen, welche einen Standard-Prozess erweitern, beginnen mit custom_,  folgen sonst aber den gleichen Richtlinien wie Standard-Variablen.

Die Liste aller Variablen, die während eines Prozesses erstellt werden, können in der Camunda WebApp Cockpit angesehen werden.

Workflow

Ein "Workflow-Package" besteht aus verschiedenen - teils optionalen - Bestandteilen. Dabei muss folgende Ordner-Struktur eingehalten werden:

• .bpmn

  • Prozess-Diagram (*.bpmn Datei)

  • HTTP Definitionen (*.json, *.yml)

• .globals

  • Globals des Codeblock-Package

• .pages

  • Page Definitionen der User-Tasks

• .workflow-tasks

  • beas Skripte der beas Tasks

Camunda Modeler - Workflow modellieren

Sowohl der Prozess selbst als auch einzelne Tasks oder Schritte sollten immer einen Namen sowie eine einzigartige ID bekommen.

Falls der Prozess manuell gestartet werden soll, muss er als Startable markiert werden. Für Prozesse, die automatisch gestartet werden, z.B. durch den Import einer E-Mail oder aus dem Codeblock heraus, sollte diese Einstellung deaktiviert werden.

Color Coding

Verschiedene Arten von Tasks sollten anhand der Farbe erkennbar sein. Die unterschiedlichen Typen haben folgende Farben:

• User Tasks: keine Farbe

• beas Tasks: blau

• HTTP Tasks: orange

Zum Einfärben eines Tasks muss dieser ausgewählt werden, danach kann per Edit → Set Color die Farbe gewählt werden.

User Task

Dies sind Aufgaben, die von einem User übernommen und bearbeitet werden. Die GUI dafür wird in einer externen YAML-Datei gepflegt um muss im Modeler dem User Task zugewiesen werden.

Die Definitions-Datei muss die Endung <name>.page.yaml haben, z.B.: user-task.page.yaml

Der User Task muss als Input den Variablen Namen pageId bekommen, der Value muss der voll qualifizierte Name der Page sein (Package Key + Page Id). z.B. WF.schritt1

Ein detaillierte Dokumentation für das designen einer Page ist hier zu finden: Anwendungsframework

Damit der Task in der Taskliste sichtbar ist, muss der Benutzer über die Berechtigung der Page verfügen.

beas Task

Bei einem beas Task kann ein Codeblock-beas-Skript angegeben werden, das im Prozess ausgeführt wird. Im Codeblock-Skript können Prozess-Variablen gelesen, geändert und angelegt werden.

| 
  m_oVarsIn, // TbeCbAnything
  m_oVarsOut // TbeCbAnything
|

// Prozess Variable lesen
m_oVarsIn.getExtended('std_db_eingangsrechnung_betrag'),

// Prozess Variable schreiben
m_oVarsOut.appendBoolean('std_proc_kreditor_identifiziert', True),

Die Implementation muss folgendermaßen gepflegt werden:

• Type: External

• Topic: beas

Der Input muss folgendermaßen gepflegt werden:

• Local Variable Name: implementation

• Value: Programmname des Codeblock Skripts

  • Beispiel: eingangsrechnungen/.workflow-tasks/kreditor-automatisch-identifizieren

HTTP Task

Mit HTTP Tasks können HTTP(S)-Requests an externe APIs abgesetzt werden. Die Definition dieser Requests erfolgt in einer externen Datei <name>.http.json

Die Implementaion muss folgendermaßen gepflegt werden:

• Type: External

• Topic: http

Der Input muss folgendermaßen gepflegt werden:

• Local Variable Name: definition_file

• Value: <name>.http.json

Workflow veröffentlichen

Sobald der Workflow fertig definiert wurde, muss dieser veröffentlicht werden. Alle neuen Prozesse verwenden ab diesem Zeitpunkt die aktualisierte Prozess-Definition. 

Beim Veröffentlichen muss zum einen ein Name für den Workflow vergeben werden. Zum anderen müssen alle externen User-Task- und HTTP-Task-Dateien mit veröffentlicht werden.

Der REST Endpoint ist: <be Portal URL>/api/workflow/engine-rest, z.B. https://acme-port.de/api/workflow/engine-rest

Definition der Oberfläche (GUI) für User Tasks

Überblick

Der Oberflächen-Aufbau für User Tasks kann komplett über YAML Konfigurations-Dateien beschrieben werden werden. Es gibt drei Hauptbereiche, die unterschiedliche Teile der Aufgaben-Listen-Oberfläche beeinflussen:

(1) controls

Bereich 1 sind die controls. Diese sind ein Array von Control-Definitionen, die an der GUI angezeigt werden. Es gibt viele verschiedene Controls für Text oder numerische Eingaben, Datepicker, Dropdowns und tabellarische Darstellungen.

(2) taskPreview

Im Bereich 2 taskPreviewItems können Prozess-Variablen verwendet werden, um die Liste der ausstehenden Aufgaben mit mehr Kontext anzureichern. Hier können Prozess-Variablen der Aufgabe in der Liste dargestellt werden.

(3) customElements

customElements beeinflussen viele verschiedene Bereiche der Oberfläche. Es können unter anderem Buttons zum Beenden oder Eskalieren der Aufgabe definiert werden, die PDF- und Kommentar-Komponente kann gesteuert werden und Info-Panels können definiert werden.

Diese folgende Anleitung beschreibt die Möglichkeiten aus High Level Perspektive. Alle Details erhält man direkt beim Schreiben einer Oberflächen-Definition in VS Code über die JSON Schema-Unterstützung.

contributes.workflow

Unter contributes.workflow werden Elemente des Aufgaben-Bereichs definiert, die rund um die Eingabe-Felder zur Verfügung stehen. Dazu gehören verschiedene Buttons zum Auslösen weiterer Prozessschritte, die Anzeige von Kommentaren und ein Dokumenten-Viewer für PDF-Dateien.

objectType: pagecontainer
id: ERU.buchen
type: mainPage
title: Buchen
contributes:
  workflow:
    assignTaskModal: ...
    taskPreviewItems: ...
    completeButtons: ...
    errorButtons: ...
    escalationButtons: ...
    documentViewer: ...
    comments: ...
data:
  variables:
    ... 
controls: ...

assignTaskModal

Mit dem assignTaskModal kann definiert werden, ob die Aufgabe einem bestimmten User oder einer Gruppe zugeordnet werden kann. Zudem kann sowohl bei den Usern als auch bei den Gruppen die Auswahlmöglichkeit auf konkrete Werte begrenzt werden.

taskPreviewItems

Hier können Prozess-Variablen benutzt werden, um die Liste der Aufgaben mit Informationen anzureichern.

completeButtons, errorButtons, escalationButtons

Es gibt drei verschiedene Arten von Buttons (completeButtons, escalationButtons und errorButtons), um im Prozess Folgeschritte auszulösen bzw. abzubrechen.

comments

Der Kommentarbereich ist während aller Aufgaben in einem Prozess gültig und kann für Hinweise, Notizen, etc. verwendet werden. Es ist möglich den Kommentar-Bereich bei bestimmten Prozessschritten auf readonly zu setzen.

documentViewer

Mit dem documentViewer kann ein zugehöriges Dokument, das im DMS gespeichert ist, angezeigt werden.

Prozess starten

Prozesse können manuell oder automatisch gestartet werden, zum Beispiel per Abruf einer E-Mail mit Rechnung im Anhang oder aus dem Codeblock.

Prozess manuell starten

In der Aufgabenliste kann ein neuer Prozess gestartet werden, sofern es Prozesse gibt, die im Camunda Modeler als Startable markiert sind.

Es können optionale Prozess-Variablen definiert werden sowie Dateien ins DMS hochgeladen werden. Die UUID des hochgeladenen Dokumentes steht als Prozess-Variable zur Verfügung.

Für Prozesse kann außerdem ein "Start Formular" angegeben werden. Dieses muss ausgefüllt werden, bevor der Prozess gestartet werden kann.

Die Definition eines Start-Formulars erfolgt analog zur Definition eines User-Task-Formulars.

Prozess automatisch starten

Nach E-Mail Import

In der Administration-Oberfläche im be Portal kann ein E-Mail-Profil und ein E-Mail-Ordner definiert werden. Aus diesem Ordner werden E-Mails periodisch abgerufen. Wenn diese einen PDF Anhang haben, wird für jeden PDF-Anhang automatisch eine Instanz des angegebenen Prozesses gestartet.

Per Codeblock

Mit der Funktion WoFl_StartProcess aus dem Package @workflow/workflow-adapter kann ein Prozess auch aus dem Codeblock heraus gestartet werden.

| cKey, aProcessVariables |

cKey              := 'std_eingangsrechnung_pruefen',
aProcessVariables := {},
AAdd(aProcessVariables, {'std_db_dms_document_versions_uuid', '65055084-d315-4716-95ad-08be00a6e743'}),
AAdd(aProcessVariables, {'std_db_email_imports_sender', 'bestellungen@alu-gmbh.de'}),

WoFl_StartProcess(cKey, aProcessVariables),

Aufgaben zuweisen

Aufgaben in einem Prozess können sowohl Benutzern als auch Gruppen zugewiesen werden. Auf der Oberfläche können die Aufgaben nach dem eigenen Benutzer oder nach Gruppen gefiltert werden.

Manuelle Zuweisung

Die Zuweisung kann manuell für eine bestehende Aufgabe erfolgen.

Übernehmen weist die Aufgabe dem eigenen Benutzer zu.

Mit dem Gruppen-Icon wird ein Dialog geöffnet, bei dem eine Liste an definierten Benutzern/Gruppen zur Verfügung steht, aus denen die Zuweisung ausgewählt werden kann.

Die Liste der zur Verfügung stehenden Benutzer und Gruppen kann in den customElements bestimmt werden. Dort kann auch definiert werden, dass dieser Dialog automatisch erscheint, wenn einer der Buttons gedrückt wird. Der Benutzer wird dann als Bearbeiter für den nächsten Task gesetzt.

Zuweisung per Codeblock-Event

Immer wenn eine Aufgabe in den nächsten Schritt geht, kann per Codeblock-Event der nächste Benutzer oder die nächste(n) Gruppen gesetzt werden.

Administrative Aufgaben

Für administrative Aufgaben, wie z.B. um einen Prozess-Schritt bei einem Fehler neu zu starten oder eine alte Version eines Prozesses zu löschen, müssen die Camunda WebApps verwendet werden. Diese können aus dem be Portal Dashboard heraus geöffnet werden.

Eine Dokumentation mit alle Funktionalitäten der Camunda WebApps ist hier zu finden: https://docs.camunda.org/manual/7.18/webapps/

Prozess-Definition löschen

Prozess-Definitionen können im Camunda Cockpit unter Mehr → Deployments gelöscht werden.

Dabei ist es in der Entwicklungs-Phase oft sinnvoll, die Cascade-Option anzuwählen, um auch alle zugehörigen Ressourcen zu löschen.

Diese Option sollte für eine Prozess-Instanz im Produktiv-Betrieb nicht ausgewählt werden.

Unterstützte BPMN Komponenten im be Portal

Aktuell werden folgende Bestandteile von BPMN unterstützt:

Archivierung von Prozess-Instanzen

Standardmäßig werden abgelaufene Prozesse 90 Tage lang archiviert, bevor sie automatisch gelöscht werden. Dieser Wert kann im Camunda Modeler überschrieben werden.

Die Angabe der Zeitspanne muss ISO 8601 konform erfolgen: https://de.wikipedia.org/wiki/ISO_8601#Zeitspannen