# Workflow Komponente im Portal konfigurieren

> **Zielgruppe & Rolle**
>
> **Rolle**: Mandanten-Administrator / Prozessverantwortlicher / Einrichter | **Voraussetzung**: [Voraussetzungen für ConnectWORKFLOW](/knowledge/docs/products/workflow/system-config/prerequisites.md) erfüllt


# Workflow Komponente im Portal konfigurieren

> **Unterstützung durch MBCOM**
>
> Auf Wunsch kann die vollständige Einrichtung von ConnectWORKFLOW durch MBCOM übernommen werden.


Die Workflow-Konfiguration im ConnectCLOUD Portal ermöglicht die mandantenspezifische Bereitstellung automatisierter Genehmigungs- und Prüfpfade für Vorgänge aus trade. In diesem Bereich verwalten Sie Ihre Workflow-Blueprints, überprüfen die technischen Voraussetzungen über den Konfigurationstest und schalten die Workflow-Engine für den Mandanten aktiv.

> **Richtigen Mandanten auswählen**
>
> Die Workflow-Konfiguration gilt für den aktuell ausgewählten Mandanten. Prüfen Sie vor jeder Änderung die Mandantenauswahl oben in der linken Leiste des Portals.


### Vorgehen bei der Ersteinrichtung im Überblick

Die Einrichtung der Workflow-Komponente im ConnectCLOUD Portal erfolgt in folgenden Schritten:

1. [**Voraussetzungen & Vorbereitung prüfen**](#1-voraussetzungen--vorbereitung-pruefen)
2. [**Workflow-Bereich im Portal aufrufen & Grundeinstellungen festlegen**](#2-workflow-bereich-im-portal-aufrufen--grundeinstellungen-festlegen)
3. [**Workflow-Blueprints verwalten**](#3-workflow-blueprints-verwalten)
4. [**Blueprint im Editor konfigurieren**](#4-blueprint-im-editor-konfigurieren)
5. [**Benachrichtigungen & Rückfragen einrichten**](#5-benachrichtigungen--rueckfragen-einrichten-optional)
6. [**Konfigurationstest durchführen**](#6-konfigurationstest-durchfuehren)
7. [**Workflow-Automatisierung aktivieren & testen**](#7-workflow-automatisierung-aktivieren--testen)

## 1. Voraussetzungen & Vorbereitung prüfen

Bevor Sie mit der Konfiguration im Portal beginnen, müssen die folgenden Systemvoraussetzungen erfüllt sein:

1. **Voraussetzungen erfüllt**: trade, HR und DMS stehen dem Workflow-Dienst zur Verfügung (siehe [**Voraussetzungen für ConnectWORKFLOW**](/knowledge/docs/products/workflow/system-config/prerequisites.md)). Eine microtech-Anbindung ist für Workflows nicht nötig.
2. **HR-Gruppen angelegt**: Die Gruppen, die Aufgaben bearbeiten sollen, existieren in HR und haben Mitglieder.
3. **Benachrichtigungskanäle bereitgestellt (optional)**: [**Einrichtung von Teams**](/knowledge/docs/products/workflow/system-config/teams-configuration.md) bzw. [**Einrichtung vom Postfach**](/knowledge/docs/products/workflow/system-config/mail-configuration.md)

## 2. Workflow-Bereich im Portal aufrufen & Grundeinstellungen festlegen

1. Öffnen Sie das ConnectCLOUD Portal und wählen Sie in der Mandantenauswahl den gewünschten Zielmandanten aus.
2. Navigieren Sie über das Menü zu **Administration** und öffnen Sie das Register bzw. die Kachel **Workflow**.
3. Auf der Seite sehen Sie die Status-Karte **Workflow Automatisierung**.

> **Workflow-Automatisierung zunächst deaktiviert lassen**
>
> Lassen Sie den Schalter **Workflow Automatisierung** während der gesamten Ersteinrichtung auf **Deaktiviert**. Aktivieren Sie die Engine erst, nachdem Sie Ihre Blueprints hinterlegt und den Konfigurationstest fehlerfrei bestanden haben.


## 3. Workflow-Blueprints verwalten

Im Bereich **Workflow Blueprints** werden alle für den aktuellen Mandanten hinterlegten Geschäftsprozess-Definitionen aufgelistet.

### Blueprint-Übersicht

Die Tabelle gibt Ihnen einen schnellen Überblick über die konfigurierten Prozesse:

| Spalte | Bedeutung |
| :--- | :--- |
| **ID & Version** | Eindeutige Kennung des Blueprints (z. B. `incoming-invoice`) sowie die aktuelle Versionsnummer (z. B. `v3`). |
| **Schritte** | Anzahl der im Workflow hinterlegten Prozessschritte (`UserSteps` und `SystemSteps`). |
| **Status** | Zeigt an, ob der jeweilige Blueprint aktiv geschaltet ist (`aktiv` oder `inaktiv`). |
| **Aktionen** | Schaltflächen zum Betrachten, Bearbeiten oder Löschen des Blueprints. |

### Verfügbare Aktionen

- **Neuer Blueprint (`+`)**: Öffnet den Editor mit einer leeren Vorlage zur Neuanlage eines Workflows.
- **Anzeigen (Auge)**: Öffnet eine schreibgeschützte Detailansicht des Blueprints inklusive der interaktiven grafischen Vorschau.
- **Bearbeiten (Stift)**: Öffnet den Blueprint im zweigeteilten Bearbeitungs-Editor.
- **Löschen (Papierkorb)**: Entfernt den Blueprint. Bitte beachten Sie die Bestätigungsabfrage im Dialog.


## 4. Blueprint im Editor konfigurieren

Klicken Sie auf **Neuer Blueprint** oder bearbeiten Sie einen bestehenden Eintrag, um den Blueprint-Editor zu öffnen.

### Die Arbeitsumgebung im Editor

Der Editor ist in zwei synchronisierte Bereiche aufgeteilt:

1. **Linke Seite – YAML-Editor**:
   - Hier bearbeiten Sie die Definition des Blueprints in strukturierter YAML-Form.
   - Ein integrierter Validator überprüft Ihre Eingaben. Er prüft zusätzlich serverseitig (während der Bearbeitung und beim Speichern) Vorgangsarten, Feldnamen, Bedingungen und HR-Gruppen und zeigt alle Probleme mit Pfad und Hinweis an. Speichern ist nur ohne Probleme möglich.
   - Eine **Feldauswahl** liefert die Feldnamen des Vorgangs (und der Positionen), eine **Gruppenauswahl** fügt die ID einer HR-Gruppe an der Cursorposition ein.
   - Der Status wird oben über Badges signalisiert:
  
| Status | Bedeutung |
| :--- | :--- |
| **Gültig** | Die Syntax und das Schema sind fehlerfrei.|
| **Warnung** | Nicht-kritische Hinweise zur Definition.|
| **Fehlerhaft** | Syntax- oder Strukturfehler mit detaillierter Zeilen- und Fehlerbeschreibung.|
2. **Rechte Seite – Designer-Vorschau (`WorkflowCanvas`)**:
   - Stellt die im YAML-Code definierte Prozessstruktur als interaktives Ablaufdiagramm dar.
   - Jeder hinzugefügte Schritt, jede Verzweigung und jeder Übergang wird unmittelbar grafisch visualisiert.

```mermaid
flowchart LR
    Y[YAML-Editor] -->|Echtzeit-Validierung| V[Syntax & Schema Status]
    Y -->|Live-Rendering| D[Designer-Vorschau / Canvas]
    D -->|Visuelle Kontrolle| A[Administrator / Einrichter]
```

### Schrittweiser Aufbau der Blueprint-Definition

Bauen Sie Ihren Workflow im YAML-Editor nach folgendem Muster auf:

1. **Kopfdaten & Trigger festlegen**:
   - `id`: Vergeben Sie eine eindeutige Kennung (z. B. `incoming-invoice`).
   - `version`: Setzen Sie die Startversion (z. B. `1`). Bei wesentlichen Änderungen erhöhen Sie die Version.
   - `trigger`: Setzen Sie `objectType: transaction`, die Vorgangsart(en) (`transactionTypes`, z. B. `[INBOUND_INVOICE]`), den Status (`statuses`, z. B. `[IN_REVIEW]`), optional eine Startbedingung (`condition`, z. B. `grossTotal > 5000`) und den Start-Schritt (`nextStep.step`). Für jeden passenden Vorgang startet automatisch ein Workflow.
2. **Übersichtsfelder definieren (`overviewField1`, `overviewField2`)**:
   - Definieren Sie bis zu zwei Vorgangsfelder (z. B. `partnerCompany` und `documentDate`).
   - Diese Felder werden im Portal schrittübergreifend in der Aufgabenliste als separate Spalten angezeigt und erleichtern Anwendern die schnelle Orientierung.
3. **Bearbeitungsschritte (`steps`) anlegen**:
   - **UserStep (Fachliche Bearbeitung)**:
     - Vergeben Sie einen eindeutigen Schrittnamen (`name`, z. B. `abteilungsleiter_freigabe`).
     - Weisen Sie die Bearbeiter über `group` (die **ID einer HR-Gruppe**, per Gruppenauswahl einfügbar) oder `user` zu.
     - Legen Sie in `fields` fest, welche Vorgangsfelder der Bearbeiter im Portal sehen soll (z. B. `transactionNumber`, `netTotal`, `typeData.validUntil`) mit `editable: false`. Das Beleg-PDF wird aus dem DMS automatisch angezeigt.
     - Setzen Sie `allowInquiry: true`, wenn Bearbeiter Rückfragen an Kollegen stellen dürfen.
     - Konfigurieren Sie bei Bedarf Benachrichtigungen über `notificationEmail` (z. B. `einkauf@firma.de`) oder `teamsWebhookUrl`.
   - **SystemStep (Automatisierter Abschluss)**:
     - Definieren Sie Schritte ohne Benutzerinteraktion am Ende des Pfads.
     - Über `action: approve` wird der Beleg als freigegeben markiert, über `action: reject` als abgelehnt.
4. **Übergänge & Entscheidungsbuttons (`nextSteps`) definieren**:
   - Legen Sie für jeden `UserStep` die Schaltflächen fest, die dem Anwender zur Auswahl stehen.
   - Vergeben Sie eine Beschriftung (`label`, z. B. *Freigabe*), eine Farbe (`color`, z. B. `success` oder `error`) und ein Icon (`icon`, z. B. `check-circle` oder `x-circle`).
   - Definieren Sie den Zielschritt (`step`) und bei Bedarf Verzweigungsbedingungen (`condition`).
5. **Blueprint speichern**:
   - Klicken Sie oben rechts auf **Speichern**. Der Blueprint wird persistent für den Mandanten gesichert.

> **Technische Spezifikation in der Technischen Referenz**
>
> Die vollständige Spezifikation aller Blueprint-Eigenschaften, Expr-Bedingungsoperatoren, Typkonvertierungen für RTF-Texte `(as:TEXT)`, 2-Ebenen-Feldgrenzen und ein direkt kopierbares YAML-Praxisbeispiel finden Sie in der Technischen Referenz:
> [**Technische Referenz: Workflow Blueprint**](/knowledge/docs/products/workflow/technical/workflow-blueprint.md)




## 5. Benachrichtigungen & Rückfragen einrichten (optional)

> **Optionale Benachrichtigungskanäle**
>
> Die Einrichtung von Benachrichtigungen und Webhooks ist **optional**. Sämtliche Workflows und Genehmigungsprozesse funktionieren auch ohne Notifikationskanäle. Wir empfehlen jedoch die Aktivierung mindestens eines Kanals, damit Bearbeiter zeitnah über neue Aufgaben oder Rückfragen informiert werden, ohne das Portal permanent überwachen zu müssen.


ConnectWORKFLOW unterstützt zwei parallele Benachrichtigungskanäle, die direkt in den Workflow-Blueprints im YAML-Editor konfiguriert werden: **E-Mail-Benachrichtigungen** und **Microsoft Teams (Webhooks)**.

---

### E-Mail-Benachrichtigungen im Blueprint

ConnectWORKFLOW kann automatisierte E-Mails versenden, um Bearbeiter über anstehende Aufgaben zu informieren oder den Austausch bei Rückfragen zu unterstützen.

#### Wofür wird eine E-Mail im Blueprint hinterlegt?

1. **Aufgaben-Benachrichtigung bei Schritteintritt (`UserStep`)**:
   Sobald ein Beleg in einen bestimmten Bearbeitungsschritt eintritt (z. B. *Freigabe Einkauf* oder *Freigabe Geschäftsleitung*), versendet ConnectWORKFLOW automatisch eine formatierte E-Mail an die im Blueprint hinterlegte Adresse.
   - Die E-Mail enthält alle wesentlichen Vorgangsdaten (Belegnummer, Status, Schrittbezeichnung) sowie einen direkten Link zur Aufgabe in der Aufgabenübersicht (`taskURL`).
   - Die zuständigen Personen müssen das Portal somit nicht manuell im Blick behalten, sondern werden proaktiv benachrichtigt, sobald eine Handlung erforderlich ist.

2. **Rückfragen zu Belegen**:
   Stellt ein Bearbeiter im Portal eine Rückfrage zu einem Beleg, wählt er den gewünschten Kollegen aus. ConnectWORKFLOW bietet die aktiven Mitglieder der im Blueprint genannten HR-Gruppen an und verwendet deren E-Mail-Adresse aus HR. Die Benachrichtigung inklusive Rückfragetext und Beleglink wird direkt per E-Mail zugestellt. Bei einer Antwort erhält der ursprüngliche Bearbeiter auf demselben Weg eine Benachrichtigung.

> **Voraussetzung: Mail-Komponente im Portal**
>
> Für den E-Mail-Versand muss die Mail-Komponente in dem Administrationsbereich eingerichtet und aktiv sein. Die technische Anbindung erfolgt über Microsoft Graph (`Mail.Send`).
> [**Mail-Komponente im Portal konfigurieren**](/knowledge/docs/products/workflow/tenant-config/mail-portal-config.md) | [**Einrichtung vom Postfach (Systemkonfiguration)**](/knowledge/docs/products/workflow/system-config/mail-configuration.md)


#### Wie wird die E-Mail im Blueprint hinterlegt?

Die E-Mail-Adresse wird im YAML-Editor direkt auf der Ebene des jeweiligen Bearbeitungsschritts (`UserStep`) über die Eigenschaft **`notificationEmail`** eingetragen:

```yaml
steps:
  - name: freigabe_einkauf
    stepType: UserStep
    group: 3f2b8c1e-5d7a-4b9e-8a61-2c4d9e7f1a30 # ID der HR-Gruppe
    
    # E-Mail-Adresse für proaktive Aufgaben-Benachrichtigung:
    notificationEmail: "einkauf@firma.de"
    
    allowInquiry: true
    fields:
      - name: transactionNumber
        visible: true
        editable: false
      - name: netTotal
        visible: true
        editable: false
    nextSteps:
      - label: Freigeben
        color: success
        step: genehmigung_abteilungsleiter
```

> **Einzelperson vs. Gruppen-/Funktionspostfach**
>
> Als `notificationEmail` kann sowohl die persönliche E-Mail-Adresse einer Einzelperson (z. B. `max.mustermann@firma.de`) als auch eine Gruppen- bzw. Sammeladresse (z. B. `einkauf@firma.de` oder `rechnungseingang@firma.de`) angegeben werden. Für Teams und Abteilungen empfehlen wir Sammelpostfächer oder Verteilerlisten, damit alle zuständigen Bearbeiter gleichzeitig informiert werden.


---

### Microsoft Teams (Webhooks) im Blueprint

Über Microsoft Teams können Bearbeiter in Echtzeit benachrichtigt werden. Die Zustellung erfolgt über einen Power-Automate-Flow, der Nachrichten über den Teams **Flow-Bot** direkt im persönlichen 1:1 Chat des Empfängers veröffentlicht.

#### Wofür wird ein Webhook im Blueprint hinterlegt?

1. **Rückfragen per Flow-Bot (Persönlicher 1:1 Chat)**:
   Wird zu einer Aufgabe eine Rückfrage gestellt oder beantwortet, sendet ConnectWORKFLOW eine strukturierte Benachrichtigung an den zentralen Webhook. Der Power-Automate-Flow stellt die Nachricht mit Vorgangsdetails und direktem Portal-Link als Flow-Bot-Nachricht in den persönlichen 1:1 Teams-Chat des Kollegen zu.

2. **Kanal-Benachrichtigung für neue Aufgaben (`teamsWebhookUrl`)**:
   Optional kann an einzelnen Schritten ein Teams-Kanal-Webhook hinterlegt werden, um ein ganzes Team über neue Aufgaben in einem öffentlichen oder privaten Teams-Kanal zu informieren.

> **Voraussetzung: Power-Automate-Flow in Teams**
>
> Für die Teams-Anbindung muss vorab ein automatisierter Cloud-Flow mit HTTP-Trigger in Microsoft Power Automate eingerichtet worden sein.
> [**Einrichtung von Teams (Systemkonfiguration)**](/knowledge/docs/products/workflow/system-config/teams-configuration.md)


#### Wie wird der Webhook im Blueprint hinterlegt?

Die Einbindung des Teams-Webhooks erfolgt im YAML-Editor des Blueprints in zwei bzw. drei Schritten:

1. **Zentrale Webhook-URL für Rückfragen hinterlegen (`inquiryWebhookUrl`)**:
   Tragen Sie die aus Power Automate kopierte HTTP-POST-URL auf der **obersten Ebene (Root-Ebene)** des Blueprints unter der Eigenschaft `inquiryWebhookUrl` ein. Diese URL gilt für alle Rückfragen und Antworten innerhalb dieses Workflows:

   ```yaml
   id: ER-MBCOM
   version: 4

   # Zentraler Teams-Webhook für alle Rückfragen dieses Workflows:
   inquiryWebhookUrl: "https://prod-12.westeurope.logic.azure.com/workflows/..."
   ```

2. **Rückfragen auf Bearbeitungsschritten aktivieren (`allowInquiry: true`)**:
   Damit Bearbeiter bei einer anstehenden Aufgabe die Schaltfläche **Rückfrage** sehen und nutzen können, aktivieren Sie auf den gewünschten Bearbeitungsschritten (`UserStep`) die Eigenschaft `allowInquiry: true`:

   ```yaml
   steps:
     - name: freigabe_einkauf
       stepType: UserStep
       group: Einkauf
       allowInquiry: true # Aktiviert die Rückfrage-Option im Portal
   ```

3. **Optional: Teams-Kanal-Webhook pro Schritt (`teamsWebhookUrl`)**:
   Möchten Sie zusätzlich beim Eintritt in einen bestimmten Schritt ein gesamtes Team in einem Teams-Kanal informieren, tragen Sie die Webhook-URL des Kanals unter `teamsWebhookUrl` direkt am Schritt ein:

   ```yaml
   steps:
     - name: freigabe_einkauf
       stepType: UserStep
       group: Einkauf
       # Optional: E-Mail und Teams-Kanal parallel benachrichtigen
       notificationEmail: "einkauf@firma.de"
       teamsWebhookUrl: "https://outlook.office.com/webhook/..."
       allowInquiry: true
   ```

> **Technische Details & Schemas**
>
> Detaillierte Spezifikationen zu den JSON-Payloads für HTTP-Trigger und Adaptive Cards in Teams finden Sie in der Technischen Referenz:
> [**Technische Referenz: Notifikationen & Teams-Webhooks**](/knowledge/docs/products/workflow/technical/notifications.md)


## 6. Konfigurationstest durchführen

Bevor die Workflow-Komponente aktiviert wird, sollte die Konfiguration über den integrierten Konfigurationstest überprüft werden.

1. Wechseln Sie im Portal zur Workflow-Übersicht (**Administration > Workflow**).
2. Klappen Sie die Karte **Konfigurationstest** auf.
3. Klicken Sie auf **Test starten**.

### Was wird geprüft?

Der Konfigurationstest führt eine grundlegende Validierung der Systemumgebung durch und prüft, ob alle beteiligten Komponenten und Dienste ordnungsgemäß miteinander kommunizieren können. Die Karte listet folgende Prüfungen einzeln mit Ergebnis und Hinweis:

| Prüfung | Was geprüft wird |
| :--- | :--- |
| **Datenbank** | Die Workflow-Datenbank ist erreichbar. |
| **Konfiguration** | Die gespeicherte Workflow-Konfiguration des Mandanten ist lesbar. |
| **trade-Verbindung** | Der Workflow-Dienst kann trade (Vorgänge) erreichen. |
| **HR-Verbindung** | Der Workflow-Dienst kann HR (Gruppen) erreichen. |
| **Blueprints** | Alle Blueprints bestehen die Prüfung (Vorgangsarten, Feldnamen, Bedingungen, Gruppen). Sind keine Blueprints angelegt, erscheint eine Warnung. |
| **Benachrichtigungsdienst** | Der Benachrichtigungsdienst (comms) ist erreichbar. |

### Testergebnis auswerten

- **Konfiguration ist gültig (grün)**: Alle Prüfungen sind erfolgreich. Die Komponente kann aktiviert werden.
- **Die Konfiguration enthält Fehler (rot)**: Mindestens ein Dienst ist nicht erreichbar oder ein Blueprint ist fehlerhaft. Prüfen Sie in diesem Fall die angezeigten Detailhinweise (bei Blueprints stehen die Einzelheiten im Workflow-Editor) sowie die [Voraussetzungen](/knowledge/docs/products/workflow/system-config/prerequisites.md).


## 7. Workflow-Automatisierung aktivieren & testen

Nachdem alle Blueprints konfiguriert und der Konfigurationstest erfolgreich bestanden wurde, schalten Sie die Komponente aktiv.

### Aktivierung im Portal

1. Scrollen Sie nach oben zur Karte **Workflow Automatisierung**.
2. Stellen Sie den Schalter von **Deaktiviert** auf **Aktiviert**.
3. Klicken Sie in der Kopfzeile auf **Speichern**. Die Workflow-Engine ist nun für diesen Mandanten aktiv.

### End-to-End-Funktionstest durchführen

Führen Sie zur Freigabe einen realen Testdurchlauf durch:

1. **Vorgang bereitstellen**:
   - Legen Sie in trade einen Testvorgang an (z. B. eine Eingangsrechnung) oder wählen Sie einen vorhandenen, der Vorgangsart, Status und Trigger-Bedingung des Blueprints erfüllt.
2. **Start abwarten**:
   - Der Workflow startet automatisch durch Hintergrund-Polling (ca. 60 Sekunden). Der Vorgang ist danach in trade gesperrt und zeigt **Im Workflow**.
3. **Aufgabe im Portal prüfen**:
   - Öffnen Sie im ConnectCLOUD Portal die **Aufgabenübersicht**.
   - Die Aufgabe muss unter **Aufgaben der Gruppe** für die berechtigte Gruppe sichtbar sein.
   - Übernehmen Sie die Aufgabe und prüfen Sie, ob alle Vorgangsdaten und das PDF korrekt angezeigt werden.
   - Betätigen Sie eine Entscheidungs-Schaltfläche (z. B. *Freigabe*).
4. **Rückschreibung in trade kontrollieren**:
   - Kontrollieren Sie den Vorgang in trade:
   - `metadata.workflow.state` wechselt auf `APPROVED` (bzw. `REJECTED`), der Vorgang ist wieder bearbeitbar und das Kennzeichen **Im Workflow** verschwindet.
   - Die Entscheidung steht im Verlauf der Aufgabe im Portal.


## Weiterführende Referenzen & Nächste Schritte

> **Weiterführende Dokumentation**
>
> -  [**Anwenderhandbuch: ConnectWORKFLOW im Arbeitsalltag**](/knowledge/docs/products/workflow/user-docs.md): Anleitung für Anwender zur täglichen Aufgabenübernahme, Freigabe, Rückfragen und Bearbeitungshistorie.
> -  [**Technische Referenz: Workflow Blueprint**](/knowledge/docs/products/workflow/technical/workflow-blueprint.md): Vollständige Spezifikation, JSON/YAML-Eigenschaften, Expr-Bedingungen und Praxisbeispiel.
> -  [**Technische Referenz: Notifikationen & Teams-Webhooks**](/knowledge/docs/products/workflow/technical/notifications.md): Einrichtung von Microsoft Power Automate Flows und Teams Adaptive Cards.
> -  [**Technische Referenz: Workflowinstanz & Lebenszyklus**](/knowledge/docs/products/workflow/technical/workflow-instance.md): Polling-Mechanismen, Timeouts (Auto-Release nach 24h), Sperrungen und Fehlerbehandlung.
> -  [**Technische Referenz: trade-Integration**](/knowledge/docs/products/workflow/technical/erp-integration.md): Vorgangsabfrage, Statusrückschreibung und Sperre des Vorgangs.
