# Workflow Blueprint

Ein **Workflow Blueprint** ist das "Gehirn" jedes Geschäftsprozesses in ConnectWorkflow. Er definiert nicht nur die Abfolge von Schritten, sondern legt fest, wer wann welche Informationen sieht und welche Entscheidungen an welchen Stellen getroffen werden müssen.

> **Blueprint als Prozess-Definition**
>
> Man kann sich den Blueprint wie einen Bauplan vorstellen: Er beschreibt die statische Struktur des Prozesses, während eine **Workflow-Instanz** die konkrete Ausführung für einen bestimmten Beleg darstellt.


## Die hierarchische Struktur

Ein Blueprint ist modular aufgebaut. Die folgende Grafik verdeutlicht die Abhängigkeiten zwischen den einzelnen Elementen:

```mermaid
graph TD
    BP[Blueprint] --> TR[Trigger]
    BP --> OF[OverviewFields]
    BP --> INQ[InquiryWebhookUrl]
    BP --> ST[Steps]
    ST --> FI[Fields]
    ST --> NS[NextSteps]
    NS --> CO[Conditions]
    ST --> NO[Notifications]
```

## Identität und Trigger 

Jeder Blueprint benötigt eine eindeutige Identität und ein Kriterium, wann er "anspringen" soll.

### Kopfdaten
Neben einer eindeutigen `id` verfügt jeder Blueprint über eine `version`. Diese Versionierung ist entscheidend für die Stabilität: Laufende Instanzen verbleiben in der Version, in der sie gestartet wurden, während neue Instanzen immer die aktuellste Version nutzen.

**Syntax & Beispiel:**
```json
{
  "id": "rechnungspruefung_v1",
  "version": 1
}
```

### Übersichtssfelder (`overviewField1` & `overviewField2`)

Über die optionalen Kopf-Eigenschaften `overviewField1` und `overviewField2` können bis zu zwei Belegfelder zentral im Blueprint definiert werden, die schrittübergreifend in der Benutzeroberfläche hervorgehoben werden.

Jedes Übersichtssfeld besteht aus folgenden Eigenschaften:

| Eigenschaft | Beschreibung |
| :--- | :--- |
| **Name** (`name`) | Feldname des Vorgangs (z. B. `partnerCompany`, `grossTotal` oder `typeData.<schlüssel>`), siehe Abschnitt Feldnamen der Vorgangsdaten. Der Wert stammt aus dem beim Start gespeicherten Vorgang. |
| **Label** (`label`) | Anzeigename für die Feldbezeichnung in Tabellen und Formularen (z. B. `Lieferant` oder `Gesamtbetrag`). |

**Verwendungszweck & Verhalten in der Benutzeroberfläche:**
- **Aufgabenübersicht (`TasksPage`):** In der Aufgabenliste werden `overviewField1` und `overviewField2` in eigenen Tabellenspalten dargestellt (z. B. inline als `Label: Wert`).
- **Aufgabendetailansicht (`TaskDetailPage`):** Übersichtssfelder dienen ausschließlich der Hervorhebung in der Aufgabenübersicht und werden nicht automatisch in der Aufgabendetailansicht angezeigt. Wenn ein Feld in der Detailansicht sichtbar sein soll, muss es explizit in den `fields` des jeweiligen Bearbeitungsschritts konfiguriert werden.

**Syntax & Beispiel:**
```json
{
  "overviewField1": {
    "name": "partnerCompany",
    "label": "Lieferant"
  },
  "overviewField2": {
    "name": "documentDate",
    "label": "Belegdatum"
  }
}
```

### Webhook für Rückfragen (`inquiryWebhookUrl`)

Über die optionale Kopf-Eigenschaft `inquiryWebhookUrl` kann eine zentrale Webhook-URL (z. B. Power Automate Flow) für alle Rückfragen und Rückfrage-Antworten innerhalb dieses Workflows definiert werden. 

Wird eine Rückfrage gestellt oder beantwortet, sendet ConnectWorkflow eine HTTP-POST-Payload mit den Details (Titel, Fragetext, Empfänger-E-Mail/UPN und Portal-Link) an diesen Endpunkt.

Detaillierte Informationen zum Payload-Aufbau und zur Einrichtung via Power Automate finden Sie im Kapitel [Workflow-Notifikationen & Teams-Webhooks](/knowledge/docs/products/workflow/technical/notifications.md).

### Webhook-URLs im Blueprint-Editor

Webhook-URLs (`inquiryWebhookUrl`, `teamsWebhookUrl` eines Schritts) enthalten einen Zugangsschlüssel (z. B. `sig=…` bei Power Automate). ConnectWorkflow speichert sie, gibt sie aber über keine Schnittstelle heraus – weder im Blueprint-Editor noch in Aufgaben- oder Instanzansichten. Statt der URL steht dort `"********"`.

- **Unverändert lassen:** Bleibt `"********"` beim Speichern stehen, behält ConnectWorkflow die gespeicherte URL (bei `teamsWebhookUrl` die des gleichnamigen Schritts).
- **Ändern:** Eine neue URL eintragen.
- **Entfernen:** Den Wert leeren (`""`).
- Wird ein Schritt umbenannt oder kopiert, steht für ihn keine URL zum Behalten bereit; das Speichern wird dann abgelehnt und die URL muss neu eingetragen werden.

**Syntax & Beispiel:**
```json
{
  "id": "rechnungspruefung_v1",
  "version": 1,
  "inquiryWebhookUrl": "https://prod-12.westeurope.logic.azure.com/workflows/..."
}
```

### Der Trigger-Mechanismus
Der Trigger legt fest, welche trade-Vorgänge den Workflow starten. Die Engine fragt trade regelmäßig ab und startet für jeden passenden Vorgang, der noch keine Instanz dieses Blueprints hat, genau eine Instanz (siehe [Workflowinstanz](/knowledge/docs/products/workflow/technical/workflow-instance.md)). Pro Vorgang kann nur ein Workflow aktiv sein.
- **ObjectType (`objectType`):** Immer `transaction` (trade-Vorgang).
- **Vorgangsarten (`transactionTypes`):** Liste der Vorgangsarten-Codes aus trade (z. B. `INBOUND_INVOICE`). Die Vorgangsarten müssen in trade aktiv sein.
- **Status (`statuses`):** Liste der trade-Status, in denen ein Vorgang den Workflow auslöst (z. B. `IN_REVIEW`). Vorgangsarten **und** Status sind Pflicht; fehlt eines von beiden, wird der Blueprint nicht abgefragt.
- **Condition (`condition`, optional):** Ein logischer Ausdruck (Expr-Syntax) über die Vorgangsdaten, der prüft, ob der Vorgang für diesen Workflow relevant ist (z. B. `grossTotal > 5000` oder `typeData.validUntil != ""`). Bleibt die Bedingung leer oder wird `true` angegeben, startet der Workflow für alle Vorgänge, die Vorgangsart und Status erfüllen (`default` ist auf Trigger-Ebene nicht vorgesehen). Wird die Bedingung nicht erfüllt, endet die Instanz mit `TRIGGER_NOT_MATCHED`.
- **Erster Schritt (`nextStep.step`):** Sobald der Trigger zündet, wird die Instanz erzeugt und in den ersten definierten Schritt (Start-Step) versetzt.

**Syntax & Beispiel:**
```json
"trigger": {
  "objectType": "transaction",
  "transactionTypes": ["INBOUND_INVOICE"],
  "statuses": ["IN_REVIEW"],
  "condition": "grossTotal > 5000",
  "nextStep": {
    "step": "department_approval"
  }
}
```

> **Vorgang gesperrt**
>
> Sobald die Instanz läuft, ist der Vorgang in trade gesperrt (siehe [trade-Integration](/knowledge/docs/products/workflow/technical/erp-integration.md)). Die Vorgangsfelder sind im Workflow daher schreibgeschützt.


### Blueprint ein- und ausschalten (`active`)

Nur ein **aktiver** Blueprint startet Workflows – weder das regelmäßige Abholen der Vorgänge noch ein manueller Start (`POST /trigger`) beginnen einen Workflow mit einem ausgeschalteten Blueprint. Laufende Workflows sind davon nicht betroffen und laufen weiter.

- In *Einstellungen › Workflows* hat jeder Blueprint einen Schalter „aktiv/inaktiv“ (`PUT /blueprints/<id>/active` mit `{"active": true|false}`). Einschalten prüft den Blueprint wie beim Speichern; mit Problemen bleibt er aus. Ausschalten geht immer, auch wenn trade oder HR nicht erreichbar sind.
- **Importierte Blueprints sind zunächst ausgeschaltet**, außer die Datei setzt `active: true`. So lässt sich ein Blueprint vorbereiten und prüfen, bevor er live geht.
- Blueprints ohne das Feld (gespeichert vor der Einführung des Schalters) gelten als aktiv.
- Pro Vorgang kann nur ein Workflow aktiv sein. Reagieren zwei Blueprints auf dieselbe Vorgangsart und denselben Status, gewinnt der zuerst gestartete; den anderen schaltet man aus.

```yaml
id: test-kontierung-eingangsrechnung
active: false
```

## Feldnamen der Vorgangsdaten

Bedingungen, Schritt-Felder und Übersichtsfelder verwenden die **trade-Feldnamen** (camelCase) des Vorgangs. Der Blueprint-Editor bietet eine Feldauswahl dafür (`GET /blueprints/fields`).

| Gruppe | Felder |
| :--- | :--- |
| **Kopf** | `transactionType`, `transactionNumber`, `version`, `status`, `partnerCompany`, `partnerName`, `partnerEmail`, `netTotal`, `taxTotal`, `grossTotal`, `currency`, `documentDate`, `dueDate`, `documentRefId`, `headerText`, `footerText` |
| **Typdaten** | `typeData.<schlüssel>` (freie, vorgangsartabhängige Daten, z. B. `typeData.validUntil`) |
| **Positionen** | `lines` (Liste) und `lineCount`. In Bedingungen hat jede Position die Felder `positionNumber`, `positionType`, `articleNumber`, `mpn`, `ean`, `name`, `description`, `quantity`, `unit`, `unitPriceNet`, `discountPercent`, `taxRate`, `totalPriceNet`, `totalPriceGross`, `isOptional`, `isSelected`, `lineData`, `sortOrder` |

Die Vorgangsdaten werden beim Start einmalig geladen und in der Instanz gespeichert. microtech-Feldnamen (`fld…`) werden vom Editor abgelehnt; er nennt, wo bekannt, das passende trade-Feld (z. B. `fldBelegNr` → `transactionNumber`, `fldGesBrutto` → `grossTotal`).

## Gruppen

Das Feld `group` eines Bearbeitungsschritts enthält die **ID einer HR-Gruppe** (UUID). Der Editor bietet eine Gruppenauswahl, die die ID an der Cursorposition einfügt. Gruppennamen werden nicht akzeptiert; die Prüfung nennt bei einem bekannten Namen die passende ID.

## Prüfung beim Speichern

Der Editor prüft einen Blueprint serverseitig (`POST /blueprints/validate`) und beim Speichern: Aufbau, Objekttyp, aktive Vorgangsarten in trade, Feldnamen, Bedingungen (Syntax und Felder) und HR-Gruppen. Alle Probleme werden mit Pfad und Hinweis gemeinsam angezeigt. Sind trade oder HR nicht erreichbar, wird der Blueprint nicht ungeprüft gespeichert.

## Die Bearbeitungsschritte 

Die Schritte sind die Bausteine des Workflows. In ConnectWorkflow wird zwischen zwei grundlegenden Arten unterschieden:

### UserStep (Fachliche Bearbeitung)
Dies ist der Standard-Schritt für menschliche Interaktionen. Hier wird festgelegt, wer die Aufgabe bearbeiten darf:
- **Zuständigkeit:** Über das Feld `group` (bevorzugt; ID einer HR-Gruppe) oder `user` wird die Aufgabe einer Bearbeitergruppe oder einer Einzelperson zugewiesen.
- **Rückfragen:** Durch `allowInquiry = true` kann der Bearbeiter diesen Schritt temporär pausieren, um Informationen von anderen Nutzern einzuholen.
- **Benachrichtigungen:** Pro Schritt können eine `notificationEmail` und ein `teamsChannel` hinterlegt werden. `teamsChannel` ist die ID eines Webhook-Kanals aus *Einstellungen › Benachrichtigungen › Kanäle* (im Editor über „Teams-Kanal wählen“ einfügen); eine ältere `teamsWebhookUrl` wird beim Speichern in einen solchen Kanal überführt.
- **Bearbeiter benachrichtigen:** `notifyAssigneesByEmail: true` und/oder `notifyAssigneesByTeams: true` informieren die zugewiesenen Personen (`user`, sonst die Mitglieder der Gruppe) per E-Mail bzw. in ihrem persönlichen Teams-Chat, sobald die Aufgabe wartet (Details: [Notifikationen](/knowledge/docs/products/workflow/technical/notifications.md#bearbeiter-benachrichtigen)).

**Syntax & Beispiel:**
```json
{
  "name": "department_approval",
  "stepType": "UserStep",
  "group": "3f2b8c1e-5d7a-4b9e-8a61-2c4d9e7f1a30",
  "allowInquiry": true,
  "notificationEmail": "einkauf@firma.de",
  "teamsChannel": "8d1c2f0a-3b4e-4c5d-9e6f-7a8b9c0d1e2f",
  "notifyAssigneesByEmail": true,
  "notifyAssigneesByTeams": true
}
```

### SystemStep (Automatisierung)
Ein SystemStep erfordert keine manuelle Interaktion. Er führt eine vordefinierte `action` aus (z. B. eine automatische Statusänderung oder den Abschluss eines Teilprozesses) und leitet basierend auf dem Ergebnis direkt zum nächsten Schritt weiter.

**Syntax & Beispiel:**
```json
{
  "name": "auto_archive",
  "stepType": "SystemStep",
  "action": "archive_document"
}
```
## Feldsichtbarkeit und UI-Steuerung 

Innerhalb eines `UserSteps` steuert die Liste der `fields`, was der Bearbeiter in der Workflow-Oberfläche sieht und tun kann. Jedes Feld referenziert dabei einen Feldnamen der Vorgangsdaten (z. B. `grossTotal`, `typeData.validUntil`; siehe [Feldnamen der Vorgangsdaten](#feldnamen-der-vorgangsdaten)) oder ein Workflow-eigenes Eingabefeld.

> **Datenquelle**
>
> Die Werte stammen aus dem beim Start gespeicherten Vorgang. Das Belegdokument (z. B. PDF) wird an der Aufgabe aus dem DMS angezeigt; eine Angabe im Blueprint ist dafür nicht nötig.


| Eigenschaft | Wirkung |
| :--- | :--- |
| **Visible** (`visible`) | Steuert, ob das Feld überhaupt angezeigt wird. Hilfreich, um nur prozessrelevante Daten einzublenden. |
| **Editable** (`editable`) | Macht das Feld im Schritt bearbeitbar (Eingabefeld). Bei Vorgangs- und Positionsfeldern wird die Änderung beim Abschluss des Schritts in den Vorgang in trade geschrieben (siehe [Vorgangsdaten im Schritt ändern](#vorgangsdaten-im-schritt-aendern)); bei Workflow-eigenen Eingabefeldern gehört der Wert zur Instanz. |
| **Required** (`required`) | Markiert das Feld in der Oberfläche als Pflichtfeld. Der Server prüft das beim Abschluss des Schritts noch nicht. |

**Syntax & Beispiel:**
```json
"fields": [
  {
    "name": "grossTotal",
    "label": "Brutto-Gesamtbetrag",
    "visible": true,
    "editable": false,
    "required": true
  },
  {
    "name": "headerText",
    "label": "Kopftext",
    "visible": true,
    "editable": false
  }
]
```

## Vorgangsdaten im Schritt ändern

Ein `UserStep` kann den Bearbeiter Daten des Vorgangs korrigieren lassen, z. B. die Fälligkeit oder die Kostenstelle je Position. Der Vorgang bleibt während des Workflows in trade gesperrt; nur der Workflow, der ihn sperrt, darf ihn ändern.

- **Kopffelder:** `editable: true` ist erlaubt für `partnerCompany`, `partnerName`, `partnerEmail`, `documentDate`, `dueDate`, `headerText`, `footerText` und `typeData.<schlüssel>`. Nummer, Art, Status, Version, Währung und Summen vergibt oder berechnet trade; der Editor lehnt `editable: true` dort ab.
- **Positionsfelder:** Felder mit dem Präfix `lines.` werden als Spalten der Positionstabelle gezeigt (z. B. `lines.name`, `lines.totalPriceNet`). Bearbeitbar sind `articleNumber`, `mpn`, `ean`, `name`, `description`, `quantity`, `unit`, `unitPriceNet`, `discountPercent`, `taxRate`, `isOptional`, `isSelected` und `lineData.<schlüssel>` (z. B. `lines.lineData.costCenter`).
- **Positionen kopieren und löschen:** `lines: { allowDuplicate: true, allowDelete: true }` am Schritt. Eine Kopie übernimmt alle Werte ihrer Position und steht direkt dahinter; danach sind nur die bearbeitbaren Felder änderbar. Leere Positionen anlegen ist nicht vorgesehen.
- **Neuberechnung:** Ändert der Bearbeiter Menge, Preis, Rabatt oder Steuersatz, kopiert oder löscht er Positionen, berechnet trade Positions- und Vorgangssummen neu und zeigt sie sofort als Vorschau (alt → neu). Gespeichert wird erst beim Abschluss des Schritts. Ändert ein Schritt nur Felder ohne Betragsbezug (z. B. die Kostenstelle), bleiben die gespeicherten Summen unverändert.
- **Speichern:** Beim Abschluss schreibt der Workflow die Änderungen in trade, bevor der Schritt weitergeht. Lehnt trade sie ab, bleibt der Schritt mit den Eingaben offen; ein erneuter Versuch wendet dieselben Änderungen nur einmal an. Folgeschritte und Bedingungen sehen die neuen Werte.
- **Protokoll:** Der Eintrag des Schritts enthält, was geändert wurde: je Feld alter und neuer Wert (mit der Feldbezeichnung des Schritts), kopierte und gelöschte Positionen mit allen Werten sowie die Summen vorher und nachher. Die Oberfläche zeigt eine Zusammenfassung („Kopftext geändert · 2 Positionen geändert · 1 kopiert · Brutto 1.200,00 € → 1.350,00 €“), die sich zur Tabelle der Änderungen aufklappen lässt. trade speichert dieselbe Änderung zusätzlich als Ereignis `WORKFLOW_CHANGES` am Vorgang.

```yaml
- name: kontierung
  stepType: UserStep
  group: 3f2b8c1e-5d7a-4b9e-8a61-2c4d9e7f1a30
  lines: { allowDuplicate: true, allowDelete: true }
  fields:
    - { name: dueDate, label: Fällig am, editable: true }
    - { name: lines.name, label: Bezeichnung }
    - { name: lines.quantity, label: Menge, editable: true }
    - { name: lines.lineData.costCenter, label: Kostenstelle, editable: true }
    - { name: lines.totalPriceNet, label: Gesamt netto }
  nextSteps:
    - { label: Weiter, step: freigabe }
```

## Übergänge und Entscheidungslogik

Die `nextSteps` definieren die Ausgänge eines Schritts. Sie erscheinen in der Oberfläche als Interaktions-Buttons für den Benutzer.

### Bedingungen (Conditions)
Jeder Übergang kann an eine `condition` geknüpft sein. Dabei handelt es sich um Ausdrücke, die gegen die aktuellen Daten des Belegs geprüft werden. 
- Ist eine Bedingung erfüllt, wird der definierte Ziel-`step` angesteuert. 
- Ist das Feld `step` leer, bedeutet dies den **Abschluss des gesamten Workflows**.

### Visuelle Gestaltung (Farben und Icons)
Über `color` und `icon` kann die Wirkung der Buttons gesteuert werden (z. B. ein grüner Button mit Haken für "Freigeben", ein roter für "Ablehnen"). Dies sorgt für eine intuitive Bedienung und eine klare Darstellung in der Prozess-Historie.

#### Icon-Konfiguration (`icon`)
- **Lucide Icon Name**: Es können kurze Lucide Icon-Namen (z. B. `check-circle`, `x-circle`, `thumbs-up`, `trash`) oder Namen mit dem Präfix `i-lucide-` (z. B. `i-lucide-check-circle`) angegeben werden.
- **Fallback**: Wird `icon` weggelassen oder ist leer, verwendet die Oberfläche automatisch den Standard-Icon `i-lucide-arrow-right`.
- **Icon-Übersicht**: Eine Übersicht aller verfügbaren Icons ist auf [lucide.dev](https://lucide.dev/) zu finden.

#### Farb-Konfiguration (`color`)
- **Semantische Farben**: Direkt unterstützt werden `primary`, `error`, `success`, `warning` und `neutral`.
- **Farb-Aliase**: Für einfache Konfiguration werden auch grundlegende Farbnamen automatisch zugeordnet:
  - `red` oder `danger` → `error`
  - `green` → `success`
  - `yellow` oder `amber` → `warning`
  - `blue` → `primary`
  - `gray` oder `grey` → `neutral`
- **Fallback**: Wird `color` weggelassen, gilt standardmäßig `primary`.

**Syntax & Beispiel:**
```json
"nextSteps": [
  {
    "label": "Freigeben",
    "color": "success",
    "icon": "check-circle",
    "condition": "grossTotal < 10000",
    "step": "zahlung_veranlassen"
  },
  {
    "label": "Ablehnen",
    "color": "red",
    "icon": "x-circle",
    "condition": "default",
    "step": "ende_abgelehnt"
  }
]
```

## Vollständiges Praxisbeispiel

Das folgende Beispiel zeigt einen Blueprint für eine Eingangsrechnungsprüfung (ER). Es verdeutlicht das Zusammenspiel von Triggern, Vorgangsfeldern (inkl. Punkt-Notation für `typeData`) und System-Abschlüssen.

```yaml
# Identität des Blueprints
id: ER-MBCOM
version: 4

# Webhook für alle Rückfragen in diesem Workflow
inquiryWebhookUrl: 'https://prod-12.westeurope.logic.azure.com/workflows/...'

# Übersichtssfelder für die Aufgabenliste
overviewField1:
  name: partnerCompany
  label: Lieferant
overviewField2:
  name: documentDate
  label: Belegdatum

# Einstiegspunkt: Wann soll dieser Workflow starten?
trigger:
  objectType: transaction
  transactionTypes: [INBOUND_INVOICE] # Vorgangsarten aus trade
  statuses: [IN_REVIEW] # Status, in dem der Workflow startet
  condition: grossTotal > 500 # optionaler Filter
  nextStep:
    step: freigabe_er # Leitet zum ersten Bearbeitungsschritt weiter

# Definition der einzelnen Prozessphasen
steps:
  - name: freigabe_er
    stepType: UserStep
    group: 3f2b8c1e-5d7a-4b9e-8a61-2c4d9e7f1a30 # ID der HR-Gruppe ER Controlling
    allowInquiry: true # Erlaubt Rückfragen in diesem Schritt
    fields:
      # Felder des Vorgangs
      - name: transactionNumber
        label: Beleg-Nr
        visible: true
        editable: false
      - name: netTotal
        label: Gesamtpreis netto
        visible: true
        editable: false
      # Freie Typdaten der Vorgangsart mittels Punkt-Notation
      - name: typeData.validUntil
        label: Gültig bis
        visible: true
        editable: false
    nextSteps:
      # Schaltflächen für die Benutzerentscheidung
      - label: Freigabe
        color: success
        icon: i-lucide-check-circle
        step: approve # Verweist auf den SystemStep 'approve'
      - label: Ablehnung
        color: error
        icon: i-lucide-x-circle
        step: reject  # Verweist auf den SystemStep 'reject'
    # Benachrichtigungen (Values für Dokumentationszwecke entfernt)
    teamsWebhookUrl: ''
    notificationEmail: ''

  # Automatischer Abschluss bei Erfolg
  - name: approve
    stepType: SystemStep
    action: approve

  # Automatischer Abschluss bei Ablehnung
  - name: reject
    stepType: SystemStep
    action: reject
```

![Beispiel-Workflow als Übersicht](/knowledge/docs/assets/example-workflow.png)

*Abbildung: Grafische Prozessdarstellung der Schritte und Entscheidungsübergänge im Workflow.*
