# trade-Integration

ConnectWORKFLOW liest Vorgänge aus **trade** und schreibt den Workflow-Status an den Vorgang zurück. Die Kommunikation erfolgt ausschließlich über die interne REST-Schnittstelle `/internal/transactions` von trade; der Workflow-Dienst greift nie auf die Datenbank von trade zu. microtech büro+ wird für Workflows nicht mehr benötigt.

```mermaid
graph TD
    TR[trade] -- Vorgänge und Positionen lesen --> WE[Workflow Engine]
    WE -- Status in metadata.workflow --> TR
    DMS[DMS] -- Dokument --> WE
    HR[HR] -- Gruppen und Mitglieder --> WE
    WE --- DB[(Datenbank workflow)]
```

## Datenquellen

| Quelle | Inhalt | Zugriff |
| :--- | :--- | :--- |
| **trade** | Vorgangskopf, Positionen, Vorgangsarten, Workflow-Status | REST `/internal/transactions` (interner Service-Token des Mandanten) |
| **DMS** | Belegdokument (z. B. PDF), wird beim Anzeigen durchgereicht | REST (Dokument-ID aus `documentRefId` des Vorgangs) |
| **HR** | Gruppen für die Blueprint-Prüfung und die aktiven Mitarbeiter (Empfänger von Rückfragen) | REST `/api/hr/v1/groups` und interner Verzeichnis-Abruf |

## Start eines Workflows

Die Engine fragt trade regelmäßig (Standard: jede Minute) nach Vorgängen, die zum Trigger eines Blueprints passen (`objectType: transaction`, `transactionTypes`, `statuses`). Für jeden passenden Vorgang ohne Instanz dieses Blueprints wird eine Instanz gestartet. Die Vorgangsdaten werden beim Start geladen und in der Instanz gespeichert; Details siehe [Workflowinstanz](/knowledge/docs/products/workflow/technical/workflow-instance.md) und [Workflow Blueprint](/knowledge/docs/products/workflow/technical/workflow-blueprint.md).

Pro Vorgang kann nur **ein** Workflow gleichzeitig aktiv sein.

## Statusrückschreibung

Der Workflow schreibt seinen Zustand in die Metadaten des Vorgangs (`metadata.workflow`). Die Spalte `status` des Vorgangs gehört trade und wird vom Workflow nie verändert.

| Feld in `metadata.workflow` | Inhalt |
| :--- | :--- |
| `instanceId` | ID der Workflow-Instanz |
| `blueprintId` | Blueprint der Instanz |
| `state` | Zustand der Instanz (`OPEN`, `APPROVED`, `REJECTED`, `COMPLETED`, `CANCELLED`, `RETRYING_SYNC`, …) |
| `step` | Aktueller Schritt |
| `note` | Bei regulärem Abschluss die gesammelten Kommentare der Bearbeiter, bei Abbruch der angegebene Grund (auf 1000 Zeichen gekürzt) |
| `updatedAt` | Zeitpunkt der Schreibung |

Geschrieben wird beim Start, nach jedem Schritt und beim Abschluss oder Abbruch. Die Rückfrage-Konversationen werden nicht zurückgeschrieben.

Ein Workflow, der sofort endet, ohne je gelaufen zu sein (`TRIGGER_NOT_MATCHED`, `TECHNICALLY_FAILED`), schreibt nichts an den Vorgang, damit er den Status eines anderen Workflows nicht überschreibt.

## Sperre des Vorgangs

Solange `metadata.workflow.state` den Wert `OPEN` oder `RETRYING_SYNC` hat, ist der Vorgang in trade **gesperrt**:

- Der Vorgang und seine Positionen können nicht geändert werden; Änderungsversuche werden mit HTTP 423 abgelehnt. Das gilt für alle Wege (Portal, Importe, Pipeline).
- Erlaubt bleibt allein das Schreiben des Workflow-Status selbst.
- Im Portal zeigt der Vorgang das Kennzeichen **Im Workflow**.
- Gesperrte Eingangsrechnungen werden im Extraktions-Feed übersprungen.

Mit jedem anderen Zustand (Abschluss, Ablehnung, Abbruch) ist der Vorgang wieder frei. Ein Tenant-Administrator kann einen aktiven Workflow vorzeitig beenden, um einen Vorgang sofort freizugeben (siehe [Aufgabeaktionen](/knowledge/docs/products/workflow/technical/task-actions.md)).

## Wenn trade nicht erreichbar ist

Schlägt das Schreiben des Status fehl, bleibt die Entscheidung im Workflow erhalten. Die Instanz wechselt in den Zustand `RETRYING_SYNC` und ist bis zur erfolgreichen Zustellung schreibgeschützt. Die Wiederholungen laufen mit steigendem Abstand (1, 2, 4, 8, 16 Minuten, danach alle 16 Minuten) und **ohne Obergrenze**, damit kein Vorgang dauerhaft durch einen beendeten Workflow gesperrt bleibt. Dasselbe gilt für einen Start, bei dem der Vorgang nicht geladen werden konnte. Siehe [Workflowinstanz](/knowledge/docs/products/workflow/technical/workflow-instance.md#fehlerbehandlung-und-retrying).

```mermaid
sequenceDiagram
    autonumber
    participant TR as trade
    participant WE as Workflow Engine

    Note over TR, WE: Start
    WE->>TR: Vorgänge nach Trigger abfragen
    WE->>TR: Vorgang und Positionen laden
    WE->>TR: metadata.workflow = OPEN (Vorgang gesperrt)

    Note over WE: Bearbeitung in der Cloud

    Note over TR, WE: Abschluss
    WE->>TR: metadata.workflow = APPROVED / REJECTED / COMPLETED / CANCELLED (Vorgang frei)
```
