# Rückfragen-Notifikationen & Teams-Webhooks

ConnectWorkflow informiert Bearbeiter automatisch über anstehende Aufgaben, Rückfragen und Antworten. Benachrichtigungen werden per **E-Mail** sowie über **Webhooks** (Microsoft Teams, Power Automate) zugestellt. Den Versand übernimmt für alle Kanäle das Kommunikationsmodul **comms**: ConnectWorkflow übergibt nur eine Vorlage mit Parametern, comms erzeugt daraus die Nachricht, stellt sie zu und protokolliert sie.

```mermaid
flowchart TD
    WE[ConnectWorkflow Engine] -->|Vorlage + Parameter| CO[comms]
    CO -->|Standard-Postfach des Mandanten| UserMail[E-Mail Postfach des Empfängers]
    CO -->|signierter HTTP POST, Adaptive Card| Teams[Teams-Webhook eines Schritts]
    CO -->|signierter HTTP POST, JSON| PA[Power Automate Webhook]
    PA -->|Microsoft Teams Connector| TeamsBot[Teams Flow-Bot 1:1 Chat]
```

## Zustellung über comms

- **E-Mails** werden über den **Standard-E-Mail-Kanal des Mandanten** (sein eigenes Postfach, siehe [Einrichtung vom Postfach](/knowledge/docs/products/workflow/system-config/mail-configuration.md)) versendet. Ist kein Postfach eingerichtet, lehnt comms die Nachricht ab; der Fehler wird protokolliert.
- **Teams-Kanal eines Schritts:** Ein Schritt nennt seinen Teams-Kanal als **comms-Kanal** (`teamsChannel`, die ID eines Webhook-Kanals unter *Einstellungen › E-Mail & Kanäle › Kanäle*); im Blueprint steht damit keine URL mehr. Ältere Blueprints mit `teamsWebhookUrl` funktionieren weiter: Beim nächsten Speichern legt ConnectWorkflow die URL als comms-Kanal „Workflow: Teams“ an und speichert nur noch dessen ID.
- **Webhook-URLs** aus dem Blueprint (`inquiryWebhookUrl` des Workflows, `teamsWebhookUrl` noch nicht gespeicherter Blueprints) legt comms beim ersten Versand automatisch als **Webhook-Kanal des Mandanten** an („Workflow: Teams“ bzw. „Workflow: Rückfragen“). Die URL enthält einen Zugangsschlüssel und wird deshalb **verschlüsselt** gespeichert und nie protokolliert. Auch ConnectWorkflow gibt sie über keine Schnittstelle heraus (siehe [Webhook-URLs im Blueprint-Editor](/knowledge/docs/products/workflow/technical/workflow-blueprint.md#webhook-urls-im-blueprint-editor)).
- Webhook-Aufrufe sind nach der Spezifikation **Standard Webhooks** signiert (Header `webhook-id`, `webhook-timestamp`, `webhook-signature`). Empfänger, die die Signatur nicht prüfen (z. B. Power Automate), ignorieren die Header einfach.
- comms stellt **asynchron mit Wiederholungen** zu; nur öffentlich erreichbare Ziele werden aufgerufen. Jede Zustellung (Status, Versuche, letzter Fehler) ist im Portal im **Zustellprotokoll** von comms nachvollziehbar.
- **Schritt-Benachrichtigungen werden mit dem Schritt gespeichert:** ConnectWorkflow legt sie in derselben Datenbank-Transaktion ab, die den Schrittwechsel speichert, und übergibt sie danach an comms (mit Wiederholungen, falls comms kurz nicht erreichbar ist). Ein Schrittwechsel, der nicht gespeichert wird, verschickt nichts; wird derselbe Wechsel erneut gespeichert, verwirft comms die doppelte Nachricht (fester Schlüssel je Vorgang, Schritt und Empfänger).
- Benachrichtigungen sind **Best Effort**: Ist comms nicht erreichbar oder lehnt eine Nachricht ab, wird das protokolliert, der Workflow läuft unverändert weiter. Rückfragen-Benachrichtigungen werden (noch) direkt beim Stellen bzw. Beantworten versendet.
- Alle Links zeigen auf das Portal (`FRONTEND_URL`). Ist keine Portal-Adresse konfiguriert, werden Benachrichtigungen mit Aufgabenlink nicht versendet.
- Texte aus Rückfragen und Antworten werden als reine Parameter übergeben und von comms beim Erzeugen der Nachricht maskiert (kein HTML aus Benutzereingaben).

| Anlass | Vorlage | Empfänger |
| :--- | :--- | :--- |
| Bearbeitungsschritt erreicht | `workflow.task_notification` (Status „offen“) | `teamsChannel` und `notificationEmail` des Schritts; mit `notifyAssigneesByEmail` / `notifyAssigneesByTeams` zusätzlich die Bearbeiter (siehe unten) |
| Systemschritt ausgeführt | `workflow.task_notification` | `teamsChannel` und `notificationEmail` des Systemschritts |
| Workflow durch Entscheidung im Bearbeitungsschritt beendet | `workflow.task_notification` (freigegeben / abgelehnt / abgeschlossen) | `teamsChannel` und `notificationEmail` des entscheidenden Schritts |
| Rückfrage gestellt | `workflow.inquiry` | Zielperson der Rückfrage, `inquiryWebhookUrl` |
| Rückfrage beantwortet (auch nach Zeitüberschreitung) | `workflow.inquiry_answered` | Bearbeiter des Vorgangs (übernehmende Person, sonst Fragesteller, sonst `notificationEmail` bzw. `user` des Schritts), `inquiryWebhookUrl` |
| Rückfrage zurückgeholt | `workflow.inquiry_withdrawn` | Zielperson der Rückfrage (nur E-Mail) |
| Rückfrage nach 24 Stunden abgelaufen | `workflow.inquiry_timeout` | Zielperson der Rückfrage (nur E-Mail) |

### Bearbeiter benachrichtigen

Zwei Schalter eines Bearbeitungsschritts informieren die Personen, denen die Aufgabe zugewiesen ist (der `user` des Schritts, sonst die aktiven Mitglieder seiner HR-Gruppe), sobald die Aufgabe wartet:

| Schalter | Zustellung |
| :--- | :--- |
| `notifyAssigneesByEmail: true` | per E-Mail an jede Person |
| `notifyAssigneesByTeams: true` | in den **persönlichen Teams-Chat** jeder Person |
| beide | an alle Ziele, die die Person in ihren persönlichen Einstellungen hinterlegt hat |

- Den persönlichen Teams-Chat richtet jede Person selbst unter *Einstellungen › Meine Benachrichtigungen* ein (eigener Webhook, z. B. ein Teams-Workflow „Nachricht an mich senden“). Wer keinen hinterlegt hat, erhält bei `notifyAssigneesByTeams` nichts – auch keine E-Mail als Ersatz; das Zustellprotokoll von comms zeigt „Kein Ziel in den persönlichen Einstellungen“.
- Persönliche Einstellungen gelten auch sonst: Hat jemand Workflow-Benachrichtigungen abbestellt, als Zusammenfassung gewählt oder ist abwesend, beachtet comms das.
- Auch nur für Teams braucht comms das **Standard-Postfach des Mandanten** (Benachrichtigungen an Personen laufen darüber).

Der Teams-Webhook eines Schritts erhält eine **Adaptive Card** mit Status, den Fakten Mandant, Objektnummer, Schritt und Workflow sowie den Schaltflächen „Sichtbeleg anzeigen“ (falls ein Sichtbeleg-Link vorliegt) und „In ConnectCloud öffnen“.

## Ablauf und Funktionsweise

1. **Rückfrage stellen:** Ein Bearbeiter öffnet einen Vorgang im Portal und wählt die Aktion *Rückfrage* (`action = INQUIRY`), wählt die gewünschte Zielperson aus und formuliert die Frage.
2. **Automatische Empfängerermittlung:** ConnectWorkflow ermittelt die E-Mail-Adresse / den User Principal Name (UPN) der Zielperson aus HR (aktive Mitarbeiter des Mandanten).
3. **Parallele Zustellung über comms:**
   - **E-Mail:** An die Zielperson über das Postfach des Mandanten.
   - **Webhook:** Sofern im Workflow-Blueprint auf Root-Ebene `inquiryWebhookUrl` hinterlegt ist, sendet comms einen signierten HTTP-POST-Request mit einer strukturierten JSON-Payload an diesen Webhook.
4. **Rückfrage beantworten:** Bei Beantwortung der Rückfrage (`action = ANSWER_INQUIRY`) wird der ursprüngliche Bearbeiter auf demselben Weg über die Antwort benachrichtigt.

### JSON-Payload des Rückfragen-Webhooks

Die Felder `eventId`, `recipient`, `title`, `message` und `url` sind stabil und werden von bestehenden Power-Automate-Flows verwendet:

| Feld | Inhalt |
| :--- | :--- |
| `eventId` | ID der Workflow-Instanz (Vorgang) |
| `recipient` | E-Mail-Adresse / UPN der zu benachrichtigenden Person |
| `title` | Überschrift, z. B. „Neue Rückfrage in ConnectCloud“ oder „Rückfrage beantwortet“ |
| `message` | Rückfragetext mit Absender bzw. Antwort mit antwortender Person |
| `url` | Link auf die Aufgabe im Portal |

Zusätzlich enthält die Payload `id` (ID der Nachricht in comms), `type` (Vorlage), `occurredAt`, `facts` (Mandant, Objektnummer), `actions` und `data` (die Vorlagenparameter). Flows, die nur die fünf oben genannten Felder auswerten, funktionieren unverändert.


## Einrichtung in Microsoft Power Automate

Diese Anleitung beschreibt die Erstellung eines Power-Automate-Flows, der die HTTP-Anforderung von ConnectWorkflow (zugestellt über comms) entgegennimmt und eine persönliche Microsoft-Teams-Nachricht als **Flow-Bot** an den im Feld `recipient` angegebenen Benutzer sendet.

```mermaid
flowchart TD
    A[ConnectWorkflow über comms] -->|signierter HTTP POST + JSON| B[Power-Automate-Webhook]
    B --> C[Microsoft-Teams-Connector]
    C -->|Flow-Bot| D[Persönlicher Teams-Chat]
```

### Voraussetzungen

- Zugriff auf [Microsoft Power Automate](https://make.powerautomate.com/) und Microsoft Teams
- Eine gültige Teams-Verbindung für den Flow-Besitzer
- Die Teams-App **Workflows** muss im Microsoft Teams Admin Center für Benutzer freigegeben sein
- Für den HTTP-Request-Trigger in Power Automate wird in der Regel eine **Power Automate Premium**-Lizenz (oder ein entsprechender Flow-Plan) für den Flow-Besitzer benötigt
- Der Empfänger muss über seine E-Mail-Adresse bzw. seinen User Principal Name (UPN) in Microsoft 365 erreichbar sein



### Schritt 1: Flow anlegen

1. Öffnen Sie [Microsoft Power Automate](https://make.powerautomate.com/).
2. Wählen Sie links **Meine Flows** aus.
3. Klicken Sie auf **Neuer Flow > Automatisierter Cloud-Flow**.
4. Vergeben Sie einen Namen (z. B. `ConnectWorkflow Rückfragen Teams-Benachrichtigung`).
5. Suchen Sie nach dem Trigger **Beim Empfang einer HTTP-Anforderung** (Request Connector) und wählen Sie diesen aus.

### Schritt 2: HTTP-Trigger konfigurieren

1. Wählen Sie bei **Wer kann den Flow auslösen?** den Wert **Jeder** (oder konfigurieren Sie bei Bedarf OAuth-Authentifizierung).

> **Sicherheitshinweis zur Webhook-URL**
>
> Bei der Einstellung *Jeder* kann jeder, der die vollständige Webhook-URL kennt, den Flow auslösen. Die generierte URL muss daher vertraulich wie ein Kennwort behandelt und ausschließlich sicher im Blueprint hinterlegt werden.


2. Klicken Sie auf **Beispielpayload zum Generieren eines Schemas verwenden** und fügen Sie folgende Beispiel-Payload ein:

```json
{
  "eventId": "e1c278f6-8242-4982-82c6-36856bd8eb27",
  "recipient": "max.mustermann@firma.de",
  "title": "Neue Rückfrage in ConnectCloud",
  "message": "Rückfrage von anna.meier@firma.de:\n\nBitte die Kostenstelle für Position 2 prüfen.",
  "url": "https://portal.connectcloud.de/tasks/e1c278f6-8242-4982-82c6-36856bd8eb27?tenant=MANDANT1"
}
```

Power Automate generiert daraus automatisch folgendes JSON-Schema:

```json
{
  "type": "object",
  "properties": {
    "eventId": {
      "type": "string"
    },
    "recipient": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "url": {
      "type": "string"
    }
  }
}
```

#### Kontrollansicht des Triggers (Codeansicht)

In der schreibgeschützten Codeansicht des Triggers sollte folgende Definition vorliegen:

```json
{
  "type": "Request",
  "kind": "Http",
  "inputs": {
    "triggerAuthenticationType": "All",
    "schema": {
      "type": "object",
      "properties": {
        "eventId": { "type": "string" },
        "recipient": { "type": "string" },
        "title": { "type": "string" },
        "message": { "type": "string" },
        "url": { "type": "string" }
      }
    }
  },
  "metadata": {}
}
```

### Schritt 3: Teams-Aktion hinzufügen

1. Klicken Sie unterhalb des HTTP-Triggers auf **+** (Neuer Schritt).
2. Suchen Sie nach der Aktion **Nachricht in einem Chat oder Kanal veröffentlichen** des Connectors **Microsoft Teams**.
3. Stellen Sie bei Bedarf die Microsoft-Teams-Verbindung für den Flow-Besitzer her.
4. Konfigurieren Sie die Aktion mit folgenden Parametern:

| Einstellung | Wert |
| :--- | :--- |
| **Veröffentlichen als** | `Flow-Bot` |
| **Veröffentlichen in** | `Mit einem Flow-Bot chatten` |
| **Recipient** | Dynamischer Inhalt: `recipient` (aus dem HTTP-Trigger) |

> **Dynamischer Empfänger**
>
> Der Empfänger muss als dynamischer Baustein (`recipient`) aus dem vorherigen HTTP-Trigger ausgewählt werden. Tragen Sie hier keinen festen statischen Text ein, damit die Nachricht dynamisch an die jeweilige Zielperson der Rückfrage zugestellt wird.


### Schritt 4: Nachricht formatieren

Klicken Sie im Feld **Meldung** auf das Formelsymbol (**fx / Ausdruck**) und fügen Sie folgenden Ausdruck ein:

```text
concat(
  '<b>',
  triggerBody()?['title'],
  '</b><br><br>',
  triggerBody()?['message'],
  '<br><br><a href="',
  triggerBody()?['url'],
  '">Vorgang im Portal öffnen</a>'
)
```

Dieser Ausdruck generiert eine übersichtliche Teams-Nachricht:

> **Neue Rückfrage in ConnectCloud**
>
> Rückfrage von anna.meier@firma.de:
>
> Bitte die Kostenstelle für Position 2 prüfen.
>
> [Vorgang im Portal öffnen](https://portal.connectcloud.de/tasks/...)

#### Kontrollansicht der Teams-Aktion (Codeansicht)

Die Codeansicht der Teams-Aktion stellt sich wie folgt dar:

```json
{
  "type": "OpenApiConnection",
  "inputs": {
    "parameters": {
      "poster": "Flow bot",
      "location": "Chat with Flow bot",
      "body/recipient": "@triggerBody()?['recipient']",
      "body/messageBody": "<p class=\"editor-paragraph\">@{concat('<b>', triggerBody()?['title'], '</b><br><br>', triggerBody()?['message'], '<br><br><a href=\"', triggerBody()?['url'], '\">Vorgang im Portal öffnen</a>')}</p>"
    },
    "host": {
      "apiId": "/providers/Microsoft.PowerApps/apis/shared_teams",
      "connection": "shared_teams",
      "operationId": "PostMessageToConversation"
    }
  },
  "runAfter": {}
}
```

### Schritt 5: Speichern und Webhook-URL kopieren

1. Speichern Sie den Flow oben rechts über **Speichern**.
2. Öffnen Sie den ersten Schritt (*Beim Empfang einer HTTP-Anforderung*) erneut.
3. Kopieren Sie die nun generierte **HTTP-POST-URL**.

> **SAS-Key erneuern**
>
> Sollte eine Webhook-URL versehentlich öffentlich geworden sein, kann der SAS-Key in Power Automate in den Triggereinstellungen regeneriert oder der Flow dupliziert und neu angelegt werden.



## Anpassung im Workflow-Blueprint

Damit ConnectWorkflow die Webhook-Benachrichtigungen für Rückfragen versendet, wird der Blueprint angepasst.

### 1. `inquiryWebhookUrl` auf Root-Ebene hinterlegen

Die Webhook-URL wird als Eigenschaft **`inquiryWebhookUrl`** auf der obersten Ebene (Kopfebene) des Blueprints definiert. Sie gilt für alle Rückfragen und Rückfrage-Antworten innerhalb dieses Workflows.

### 2. `allowInquiry: true` auf Schritt-Ebene aktivieren

Damit Bearbeiter bei einem Schritt eine Rückfrage auslösen können, muss auf den jeweiligen Benutzer-Schritten (`UserStep`) die Option `allowInquiry: true` gesetzt sein.


### Blueprint-Beispiel (YAML)

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

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

overviewField1:
  name: partnerCompany
  label: Lieferant
overviewField2:
  name: documentDate
  label: Datum

trigger:
  objectType: transaction
  transactionTypes: [INBOUND_INVOICE]
  statuses: [IN_REVIEW]
  nextStep:
    step: freigabe_einkauf

steps:
  - name: freigabe_einkauf
    stepType: UserStep
    group: 3f2b8c1e-5d7a-4b9e-8a61-2c4d9e7f1a30 # HR-Gruppen-ID (Einkauf)
    allowInquiry: true # Aktiviert Rückfragen für diesen Schritt

    fields:
      - name: transactionNumber
        label: Beleg-Nr
        visible: true
        editable: false

    nextSteps:
      - label: Freigabe
        color: success
        icon: i-lucide-check-circle
        step: approve
      - label: Ablehnung
        color: error
        icon: i-lucide-x-circle
        step: reject

  - name: approve
    stepType: SystemStep
    action: approve

  - name: reject
    stepType: SystemStep
    action: reject
```

## Weiterführende Links

- [Einrichtung von Teams (Systemkonfiguration)](/knowledge/docs/products/workflow/system-config/teams-configuration.md)
- [Einrichtung vom Postfach (Systemkonfiguration)](/knowledge/docs/products/workflow/system-config/mail-configuration.md)
- [Workflow Komponente im Portal konfigurieren](/knowledge/docs/products/workflow/tenant-config/workflow-portal-config.md)
- [Workflow Blueprint Spezifikation](/knowledge/docs/products/workflow/technical/workflow-blueprint.md)
- [Aufgabeaktionen & Rückfragen](/knowledge/docs/products/workflow/technical/task-actions.md)
- [Microsoft Dokumentation: Teams-Nachrichten mit Power Automate senden](https://learn.microsoft.com/en-us/power-automate/teams/send-a-message-in-teams)
- [Microsoft Dokumentation: OAuth-Authentifizierung für HTTP-Trigger](https://learn.microsoft.com/en-us/power-automate/oauth-authentication)
- [Microsoft Dokumentation: SAS-Key eines HTTP-Triggers regenerieren](https://learn.microsoft.com/en-us/power-automate/regenerate-sas-key)
