Zum Inhalt springen
Workflow Blueprint
ConnectWORKFLOW - Technische Referenz

Workflow Blueprint

Zuletzt geändert am 26.10.2026

Auf dieser Seite

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:

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.

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). 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). 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).

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) 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); 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 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

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

Hat das geholfen?