# 2.14 Fehlersuche und Dokumentation von Schnittstellen

APIs und automatisierte Workflows verbinden mehrere technische Systeme miteinander.

Tritt ein Fehler auf, muss geprüft werden:

- welches System betroffen ist
- an welcher Stelle der Fehler sichtbar wird
- wo die eigentliche Ursache liegt
- welche Daten übertragen wurden
- welcher Statuscode zurückgegeben wurde
- ob Authentifizierung und Berechtigungen stimmen
- welche Änderungen zuletzt durchgeführt wurden
- ob mehrere Teilsysteme gemeinsam den Fehler erzeugen

> Eine Fehlermeldung zeigt häufig nur, wo ein Problem sichtbar wird – nicht zwingend, wo seine Ursache liegt.

---

**Lernziele**

Nach dieser Seite solltest du erklären können:

- wie Schnittstellenfehler systematisch untersucht werden
- warum Fehler häufig erst im Zusammenspiel entstehen
- wie Anforderungen, Datenformate und Abhängigkeiten Fehler verursachen
- wie Komponenten-, Integrations- und Systemtests unterschieden werden
- wie Logs und Statuscodes ausgewertet werden
- was eine Schnittstellendokumentation enthalten sollte
- wie Störungen nachvollziehbar dokumentiert und übergeben werden

---

**Fehler zuerst eingrenzen**

Vor der technischen Analyse sollte geklärt werden:

- Was funktioniert nicht?
- Was sollte stattdessen passieren?
- Seit wann besteht der Fehler?
- Wer oder was ist betroffen?
- Tritt der Fehler immer oder nur gelegentlich auf?
- Funktionieren die einzelnen Teilsysteme?
- Wurde vorher etwas verändert?
- Welche Fehlermeldung wird angezeigt?

Genaue Beschreibung:

> Der Workflow startet, aber die Gruppenzuweisung schlägt nach der erfolgreichen Benutzeranlage fehl.

Ungenaue Beschreibung:

> Die API funktioniert nicht.

---

**Fehlerkategorien**

| Fehlerbereich | Beispiel |
|---|---|
| Anforderung | gewünschtes Verhalten wurde unterschiedlich verstanden |
| Trigger | Webhook startet den Workflow nicht |
| Software | fehlerhafte Logik oder Konfiguration |
| Elektronik | Sensor-, Signal- oder Spannungsproblem |
| Mechanik | Verschleiß, Blockierung oder falsche Ausrichtung |
| Netzwerk | DNS-Fehler, geschlossener Port oder Paketverlust |
| TLS | Zertifikat wird nicht akzeptiert |
| Authentifizierung | Token fehlt oder ist abgelaufen |
| Autorisierung | Rolle oder Scope fehlt |
| Request | Methode, Endpoint oder Body ist falsch |
| Daten | Pflichtfeld oder Datentyp ist falsch |
| Timing | Folgeschritt wird zu früh ausgeführt |
| Zielsystem | API antwortet mit einem Serverfehler |
| Workflow-Logik | Bedingung oder Datenmapping ist falsch |
| Rate Limit | zu viele Anfragen wurden gesendet |
| Abhängigkeit | nachgelagerter Dienst ist ausgefallen |

---

**Fehler entstehen häufig im Zusammenspiel**

Theoretisch kann die Ursache eines technischen Problems in einem einzelnen Bereich liegen:

- Software
- Elektronik
- Mechanik
- Netzwerk
- Konfiguration
- Bedienung

In der Praxis entstehen viele Fehler jedoch erst durch das Zusammenspiel mehrerer Komponenten.

Einzelne Teilsysteme können für sich betrachtet korrekt funktionieren. Sobald sie miteinander verbunden werden, können dennoch unerwartete Probleme auftreten.

> Ein funktionierendes Einzelteil garantiert noch kein funktionierendes Gesamtsystem.

Häufige Ursachen:

- unterschiedliche Interpretation von Anforderungen
- fehlerhafte Schnittstellen
- unterschiedliche Datenformate
- falsche Einheiten
- zeitliche Abhängigkeiten
- falsche Reihenfolge
- versteckte Systemabhängigkeiten
- gegenseitige Beeinflussung mehrerer Workflows
- nicht berücksichtigte Systemzustände

---

**Fehlerstelle und Fehlerursache**

Die sichtbare Fehlermeldung muss nicht aus dem Bereich stammen, in dem die eigentliche Ursache liegt.

Beispiel aus einem technischen System:

1. Ein mechanisches Bauteil bewegt sich schwergängig.
2. Der Motor benötigt dadurch mehr Strom.
3. Die Elektronik erkennt eine Überlastung.
4. Die Steuerungssoftware schaltet das System ab.
5. Die Software zeigt eine Fehlermeldung an.

Die Meldung erscheint in der Software. Die eigentliche Ursache liegt jedoch in der Mechanik.

Beispiel aus der IT:

1. Eine Datenbank ist nicht erreichbar.
2. Die Anwendung kann keine Benutzerdaten laden.
3. Die API antwortet mit `500 Internal Server Error`.
4. Der n8n-Workflow meldet einen fehlgeschlagenen API-Aufruf.

Der Fehler wird in n8n sichtbar. Die Ursache liegt jedoch bei der Datenbank.

> Die Stelle, an der ein Fehler sichtbar wird, ist nicht zwingend die Stelle seiner Ursache.

---

**Unterschiedliche Interpretation von Anforderungen**

Anforderungen müssen eindeutig und überprüfbar formuliert sein.

Unklare Anforderung:

> Ein Benutzer soll beim Austritt automatisch deaktiviert werden.

Mögliche Interpretationen:

- sofort nach der Mitteilung
- am letzten Arbeitstag
- am Ende des letzten Arbeitstags
- erst nach der Datenübertragung
- nur im Hauptsystem
- gleichzeitig in allen verbundenen Systemen

Alle beteiligten Systeme könnten technisch korrekt funktionieren. Der Gesamtprozess wäre trotzdem falsch, wenn die Anforderung unterschiedlich verstanden wurde.

Mögliche Folgen:

- Konto wird zu früh gesperrt
- Konto bleibt zu lange aktiv
- Daten können nicht mehr übertragen werden
- einzelne Zugänge bleiben bestehen
- Lizenzen werden nicht freigegeben

> Unklare Anforderungen führen häufig zu technisch korrekten, aber fachlich falschen Lösungen.

---

**Fehler an Schnittstellen**

Eine Schnittstelle verbindet zwei Systeme oder Komponenten miteinander.

An einer Schnittstelle müssen beide Seiten dieselben Vereinbarungen verwenden.

Dazu gehören:

- Datenformat
- Feldnamen
- Datentypen
- Einheiten
- Protokoll
- Zeichencodierung
- Zeitformat
- Zeitzone
- Reihenfolge
- Authentifizierung
- erwartete Response
- Fehlerbehandlung

---

**Beispiel: Unterschiedliche Datentypen**

Quellsystem:

    {
      "active": "true"
    }

Zielsystem erwartet:

    {
      "active": true
    }

Unterschied:

- `"true"` ist ein String
- `true` ist ein Boolean

Beide Systeme können einzeln korrekt arbeiten. Der Fehler entsteht durch unterschiedliche Erwartungen an der Schnittstelle.

---

**Beispiel: Unterschiedliche Feldnamen**

Quellsystem:

    {
      "mail": "max.mustermann@example.com"
    }

Zielsystem erwartet:

    {
      "primaryEmail": "max.mustermann@example.com"
    }

Ohne korrektes Datenmapping kann das Zielsystem die E-Mail-Adresse nicht zuordnen.

---

**Beispiel: Unterschiedliche Einheiten**

Ein Sensor überträgt:

    1500 Millivolt

Die Software interpretiert den Wert als:

    1500 Volt

Der Messwert wurde korrekt übertragen, aber falsch interpretiert.

Weitere mögliche Verwechslungen:

- Millimeter und Zentimeter
- Byte und Bit
- Kilobyte und Kibibyte
- Sekunden und Millisekunden
- Celsius und Fahrenheit
- UTC und lokale Zeit

---

**Fehler durch Reihenfolge und Timing**

Manche Fehler entstehen nur, weil Schritte zu früh, zu spät oder in der falschen Reihenfolge ausgeführt werden.

Beispiel:

1. Ein Benutzerkonto wird angelegt.
2. Das Zielsystem benötigt einige Sekunden für die Bereitstellung.
3. Der Workflow versucht sofort, den Benutzer einer Gruppe hinzuzufügen.
4. Das Zielsystem kennt den neuen Benutzer noch nicht vollständig.
5. Die Gruppenzuweisung schlägt fehl.

Die einzelnen Funktionen arbeiten korrekt.

Das Problem entsteht durch das Timing zwischen den Schritten.

Mögliche Lösungen:

- Verfügbarkeit abfragen
- Status des Vorgangs prüfen
- auf ein Folgeereignis warten
- begrenzten Retry verwenden
- Backoff einsetzen
- notwendige Wartezeit einbauen

> Ein erfolgreicher API-Request bedeutet nicht immer, dass das Ergebnis sofort in allen Teilsystemen verfügbar ist.

---

**Abhängigkeiten zwischen Systemen**

Ein System kann von mehreren weiteren Diensten abhängig sein.

Beispiel:

    n8n
      |
      v
    API
      |
      v
    Benutzerverwaltung
      |
      v
    Datenbank

Fällt die Datenbank aus, meldet möglicherweise die API einen Fehler.

n8n zeigt dann einen fehlgeschlagenen API-Aufruf an, obwohl die Ursache in der Datenbank liegt.

Mögliche Abhängigkeiten:

- DNS
- Datenbank
- Authentifizierungsdienst
- Reverse Proxy
- Firewall
- TLS-Zertifikat
- Cloud-Dienst
- Speicher
- Warteschlange
- externer Anbieter

---

**Verkettete Fehler**

Ein einzelner Fehler kann mehrere Folgefehler auslösen.

Beispiel:

1. DNS-Auflösung schlägt fehl.
2. API ist nicht erreichbar.
3. Benutzerkonto wird nicht angelegt.
4. Gruppenzuweisung kann nicht stattfinden.
5. Hardware-Aufgabe wird nicht erstellt.
6. Mehrere Workflow-Schritte melden Fehler.

Die gemeinsame Ursache ist der DNS-Fehler.

> Mehrere Fehlermeldungen können dieselbe gemeinsame Ursache besitzen.

Deshalb sollte zuerst der früheste fehlgeschlagene Schritt untersucht werden.

---

**Emergentes Verhalten**

Emergentes Verhalten bedeutet:

> Das Gesamtsystem zeigt ein Verhalten, das bei der getrennten Betrachtung der Einzelteile nicht erkennbar war.

Beispiele:

- zwei funktionierende Dienste erzeugen gemeinsam eine Endlosschleife
- mehrere automatische Retries überlasten das Zielsystem
- zwei Synchronisierungen überschreiben gegenseitig Änderungen
- mehrere Zeitpläne starten denselben Prozess gleichzeitig
- einzeln korrekte Regeln erzeugen gemeinsam falsche Berechtigungen

Emergentes Verhalten entsteht nicht zwingend durch eine defekte Komponente.

Es kann durch die Verbindung, Reihenfolge oder gegenseitige Beeinflussung entstehen.

---

**Beispiel: Gegenseitige Synchronisierung**

System A synchronisiert Daten zu System B.

System B synchronisiert dieselben Daten zurück zu System A.

    System A ändert Datensatz
              |
              v
    System B übernimmt Änderung
              |
              v
    System B meldet Änderung zurück
              |
              v
    System A verarbeitet sie erneut

Mögliche Folgen:

- Endlosschleife
- unnötige API-Anfragen
- Rate Limit
- doppelte Benachrichtigungen
- widersprüchliche Daten

Mögliche Schutzmaßnahmen:

- führendes Quellsystem festlegen
- eindeutige Änderungs-ID verwenden
- Herkunft der Änderung speichern
- eigene Änderungen nicht erneut verarbeiten
- Zeitstempel oder Versionen vergleichen

---

**Komponententest**

Ein Komponententest prüft eine einzelne Funktion oder Komponente.

Beispiele:

- API-Endpoint einzeln testen
- JSON-Validierung prüfen
- einzelne n8n-Node ausführen
- Datenbankverbindung testen
- Sensor einzeln prüfen

Ziel:

> Funktioniert die einzelne Komponente für sich?

---

**Integrationstest**

Ein Integrationstest prüft das Zusammenspiel mehrerer Komponenten.

Beispiele:

- n8n überträgt Daten an eine API
- ein Personalsystem sendet einen Webhook
- die Benutzerverwaltung weist eine Gruppe zu
- eine Anwendung speichert Daten in einer Datenbank

Ziel:

> Funktionieren die Schnittstellen zwischen den Komponenten?

---

**Systemtest**

Ein Systemtest prüft den vollständigen Ablauf unter realistischen Bedingungen.

Beispiel:

    Mitarbeiter wird freigegeben
              |
              v
    Webhook wird gesendet
              |
              v
    Benutzerkonto wird angelegt
              |
              v
    Gruppen werden zugewiesen
              |
              v
    Hardware-Aufgabe wird erstellt
              |
              v
    Ergebnis wird protokolliert

Ziel:

> Funktioniert das vollständige Gesamtsystem?

---

**Abnahmetest**

Ein Abnahmetest prüft, ob die tatsächlichen fachlichen Anforderungen erfüllt werden.

Beispiele:

- Konto wird zum richtigen Zeitpunkt aktiviert
- notwendige Rechte werden vergeben
- unnötige Rechte werden nicht vergeben
- Fehler werden korrekt gemeldet
- Datenschutzanforderungen werden eingehalten
- zuständige Personen erhalten die benötigten Informationen

Ziel:

> Erfüllt die Lösung den vorgesehenen Zweck?

---

**Testebenen im Überblick**

| Testart | Geprüfter Bereich |
|---|---|
| Komponententest | einzelne Funktion oder Komponente |
| Integrationstest | Verbindung zwischen Komponenten |
| Systemtest | vollständiges Gesamtsystem |
| Abnahmetest | fachliche Anforderungen |

> Ein erfolgreicher Komponententest ersetzt keinen Integrationstest.

---

**Grundregel der Fehlersuche**

Empfohlene Reihenfolge:

1. fachliche Erwartung klären
2. Fehlerbild genau beschreiben
3. Trigger prüfen
4. Eingangsdaten prüfen
5. Netzwerk und Erreichbarkeit prüfen
6. Endpoint und HTTP-Methode prüfen
7. Authentifizierung prüfen
8. Berechtigungen prüfen
9. Header und Request-Body prüfen
10. Statuscode und Response auswerten
11. Reihenfolge und Timing prüfen
12. Systemabhängigkeiten untersuchen
13. letzte Änderungen kontrollieren
14. Integration und Gesamtsystem testen

> Von außen nach innen prüfen: Erwartung, Auslösung, Verbindung, Zugang, Daten und Verarbeitung.

---

**Trigger prüfen**

Zu prüfen sind:

- Ist der Workflow aktiv?
- Wurde das Ereignis ausgelöst?
- Ist die Webhook-URL korrekt?
- Wird die richtige HTTP-Methode verwendet?
- Ist der Zeitplan korrekt?
- Ist die richtige Zeitzone eingestellt?
- Wurde das Ereignis als Duplikat abgelehnt?
- Wurde die Test- oder Produktiv-URL verwendet?

---

**Eingangsdaten prüfen**

Zu prüfen sind:

- Sind alle Pflichtfelder vorhanden?
- Sind Felder leer oder `null`?
- Stimmen die Datentypen?
- Ist die JSON-Struktur korrekt?
- Stimmen die Feldnamen?
- Enthalten Werte unerwartete Leerzeichen?
- Entsprechen die Daten der Dokumentation?

Beispiel:

Erwartet:

    {
      "active": true
    }

Empfangen:

    {
      "active": "true"
    }

---

**Erreichbarkeit prüfen**

Mögliche Probleme:

- DNS-Auflösung fehlerhaft
- Port geschlossen
- Firewall blockiert
- Proxy falsch konfiguriert
- Container oder Dienst gestoppt
- Zielsystem in Wartung
- TLS-Zertifikat ungültig
- Netzwerkroute fehlerhaft

Wichtig:

> Wird keine HTTP-Response empfangen, existiert auch kein HTTP-Statuscode.

Dann liegt möglicherweise ein Netzwerk-, DNS-, TLS- oder Verbindungsfehler vor.

---

**Endpoint und HTTP-Methode prüfen**

Beispiele:

    GET /users/15

ruft einen Benutzer ab.

    POST /users

legt einen neuen Benutzer an.

Typische Fehler:

- falsche API-Version
- falscher Ressourcenname
- Schreibfehler in der URL
- falsche Benutzer-ID
- GET statt POST
- PUT statt PATCH
- nicht unterstützte HTTP-Methode

---

**Authentifizierung prüfen**

Zu prüfen sind:

- Ist das Credential vorhanden?
- Ist das richtige Credential ausgewählt?
- Ist das Token gültig?
- Ist das Token abgelaufen?
- Wurde es widerrufen?
- Ist der Authorization-Header korrekt?
- Stimmen Client ID und Client Secret?

Falsch:

    Authorization: abc123

Möglicherweise erforderlich:

    Authorization: Bearer abc123

Typischer Statuscode:

    401 Unauthorized

---

**Autorisierung prüfen**

Die Identität kann gültig sein, obwohl eine Aktion nicht erlaubt ist.

Zu prüfen sind:

- Benutzerrolle
- Gruppenmitgliedschaft
- API-Scopes
- Administratorfreigabe
- Zugriff auf die konkrete Ressource
- Least-Privilege-Konfiguration

Typischer Statuscode:

    403 Forbidden

Merksatz:

> 401 bedeutet: Identität nicht bestätigt.  
> 403 bedeutet: Identität bestätigt, aber Zugriff nicht erlaubt.

---

**Header und Request-Body prüfen**

Typische Header:

    Authorization: Bearer ***
    Content-Type: application/json
    Accept: application/json

Typische Fehler:

- `Content-Type` fehlt
- falsches Datenformat
- JSON syntaktisch ungültig
- Pflichtfeld fehlt
- Feldname ist falsch
- falscher Datentyp
- Body besitzt falsche Verschachtelung

Beispiel:

Gesendet:

    {
      "name": "Max Mustermann",
      "department": "IT"
    }

Erwartet:

    {
      "user": {
        "name": "Max Mustermann",
        "department": "IT"
      }
    }

---

**Statuscode auswerten**

| Code | Typische Prüfung |
|---:|---|
| 200 | erwartete Daten vorhanden? |
| 201 | Ressource tatsächlich erstellt? |
| 400 | Request und Pflichtfelder prüfen |
| 401 | Token und Authentifizierung prüfen |
| 403 | Rolle und Scopes prüfen |
| 404 | Endpoint und ID prüfen |
| 409 | vorhandene Ressource prüfen |
| 415 | `Content-Type` prüfen |
| 422 | fachliche Daten prüfen |
| 429 | Rate Limit und Wartezeit prüfen |
| 500 | Zielsystem und Logs prüfen |
| 502 | Proxy oder nachgelagerten Dienst prüfen |
| 503 | Verfügbarkeit des Dienstes prüfen |
| 504 | Timeout und Antwortzeit prüfen |

Der Statuscode sollte immer gemeinsam mit dem Response-Body ausgewertet werden.

---

**Response-Body prüfen**

Beispiel:

    Status: 400 Bad Request

    {
      "error": "Missing required field",
      "field": "email"
    }

Der Statuscode zeigt die allgemeine Fehlerklasse.

Der Response-Body nennt häufig:

- genaue Ursache
- betroffenes Feld
- interne Fehlerkennung
- Request-ID
- empfohlene Maßnahme

---

**Logs verwenden**

Logs können zeigen:

- Zeitpunkt
- Workflow-Ausführung
- betroffene Node
- Eingangsdaten
- Ausgangsdaten
- Statuscode
- Fehlermeldung
- Anzahl der Versuche
- Ausführungsdauer

Nicht vollständig protokollieren:

- Passwörter
- API-Keys
- Bearer-Tokens
- Refresh Tokens
- Client Secrets
- vertrauliche personenbezogene Daten

---

**Fehler reproduzieren**

Ein reproduzierbarer Fehler kann gezielt untersucht werden.

Festgehalten werden sollten:

- genaue Eingabedaten
- verwendeter Endpoint
- HTTP-Methode
- relevante Header
- Zeitpunkt
- Statuscode
- Response
- betroffene API-Version
- vorherige Änderungen
- Reihenfolge der Schritte

Ein Test sollte möglichst erfolgen mit:

- Testkonto
- Testdaten
- Test-Endpoint
- ungefährlicher Ressource
- deaktivierten Löschaktionen

---

**Einzelne Schritte testen**

Ein komplexer Workflow sollte in kleinere Teile zerlegt werden.

Empfohlene Vorgehensweise:

1. Trigger allein testen
2. Eingangsdaten prüfen
3. JSON validieren
4. Authentifizierung testen
5. GET-Anfrage ausführen
6. POST oder PATCH mit Testdaten ausführen
7. Response auswerten
8. Folgeschritte einzeln ergänzen
9. vollständigen Integrationstest durchführen
10. Gesamtsystem testen

> Erst den kleinsten fehlerhaften Schritt finden, danach den vollständigen Ablauf prüfen.

---

**Letzte Änderungen prüfen**

Viele Fehler entstehen nach einer Änderung.

Mögliche Änderungen:

- neues Token
- neue API-Version
- geänderter Endpoint
- neue Benutzerrolle
- verändertes Datenmapping
- aktualisierte n8n-Node
- geänderte Firewall-Regel
- neuer Proxy
- neue Umgebungsvariable
- Softwareupdate

Zu dokumentieren sind:

- Was wurde geändert?
- Wann wurde es geändert?
- Wer hat es geändert?
- Warum wurde es geändert?
- Wie wurde es getestet?
- Wie kann die Änderung zurückgenommen werden?

---

**Änderungen ganzheitlich prüfen**

Eine kleine Änderung kann mehrere Systeme beeinflussen.

Beispiel:

Ein Feld wird von:

    department

zu:

    departmentName

umbenannt.

Möglicherweise betroffen:

- Webhook
- Datenmapping
- If-Node
- Switch-Node
- API-Request
- Logging
- Dokumentation
- weitere Workflows

Vor einer Änderung sollte deshalb geprüft werden:

- Welche Systeme verwenden das Feld?
- Welche Workflows sind abhängig?
- Gibt es Testdaten?
- Ist ein Rollback möglich?
- Muss die Dokumentation angepasst werden?

---

**Schnittstellendokumentation**

Eine Schnittstellendokumentation beschreibt, wie zwei Systeme miteinander kommunizieren.

Sie sollte enthalten:

- Zweck der Schnittstelle
- Quell- und Zielsystem
- verantwortliche Personen
- Trigger
- Endpoints
- HTTP-Methoden
- Authentifizierungsverfahren
- benötigte Scopes
- Datenformat
- Feldnamen
- Datentypen
- Einheiten
- Zeitformat und Zeitzone
- Datenmapping
- Statuscodes
- Fehlerbehandlung
- Retry-Verhalten
- Rate Limits
- Logging
- Datenschutz
- Testverfahren
- Wiederherstellungsverfahren

---

**Beispiel einer Kurzdokumentation**

| Bereich | Inhalt |
|---|---|
| Name | Mitarbeiter-Onboarding |
| Zweck | Benutzerkonto automatisiert vorbereiten |
| Quellsystem | Personalsystem |
| Zielsystem | Benutzerverwaltung |
| Automatisierung | n8n |
| Trigger | Webhook |
| Methode | POST |
| Ressource | `/users` |
| Datenformat | JSON |
| Zeitformat | ISO 8601 |
| Zeitzone | Europe/Berlin |
| Authentifizierung | OAuth 2.0 |
| Fehleralarm | Kanal `#it-support` |
| Verantwortlich | interne IT |
| Testsystem | separates Testkonto |

---

**Datenmapping dokumentieren**

| Quellfeld | Zielfeld | Datentyp | Pflicht | Beispiel |
|---|---|---|---:|---|
| `firstName` | `givenName` | String | ja | Max |
| `lastName` | `familyName` | String | ja | Mustermann |
| `mail` | `primaryEmail` | String | ja | max.mustermann@example.com |
| `department` | `organization.department` | String | ja | IT |
| `active` | `isActive` | Boolean | ja | `true` |
| `startDate` | `custom.startDate` | Datum | nein | 2026-08-03 |

---

**Workflow dokumentieren**

Ein Workflow sollte folgende Angaben besitzen:

- eindeutiger Name
- kurze Beschreibung
- verantwortliche Person
- verwendete Credentials
- Trigger
- Eingaben
- Verarbeitung
- Ausgaben
- Bedingungen
- Fehlerpfad
- Abhängigkeiten
- letzte Änderung

Guter Name:

    Mitarbeiter-Onboarding – Benutzerverwaltung

Ungünstiger Name:

    Workflow Kopie Neu Final 3

---

**Node-Namen**

Nodes sollten nach ihrer Funktion benannt werden.

Gut:

- `Webhook – Mitarbeiter empfangen`
- `Pflichtfelder prüfen`
- `Benutzer nach E-Mail suchen`
- `Benutzerkonto anlegen`
- `Gruppenzuweisung prüfen`
- `Fehler an IT melden`

Ungünstig:

- `HTTP Request 4`
- `If 2`
- `Node Neu`
- `Test Final`

---

**Änderungsprotokoll**

| Datum | Änderung | Verantwortlich | Ergebnis |
|---|---|---|---|
| 18.07.2026 | API-Endpoint aktualisiert | interne IT | erfolgreich getestet |
| 19.07.2026 | neues Scope ergänzt | Administration | Freigabe dokumentiert |
| 20.07.2026 | Fehlerpfad erweitert | interne IT | Test erfolgreich |

Ein Änderungsprotokoll erleichtert die Fehlersuche nach Anpassungen.

---

**Störungsdokumentation**

Eine gute Störungsmeldung enthält:

- kurze Fehlerbeschreibung
- betroffene Systeme
- Beginn der Störung
- Auswirkung
- Statuscode oder Fehlermeldung
- bereits geprüfte Schritte
- vorläufige Ursache
- aktuelle Gegenmaßnahme
- zuständige Person
- nächster Schritt

Beispiel:

    Fehler:
    Benutzer-Onboarding schlägt bei der Gruppenzuweisung fehl.

    Auswirkung:
    Benutzerkonto wird erstellt, Gruppe jedoch nicht zugewiesen.

    Statuscode:
    403 Forbidden

    Bereits geprüft:
    Token gültig, Endpoint erreichbar, Benutzer vorhanden.

    Vermutete Ursache:
    benötigter Scope für Gruppenverwaltung fehlt.

---

**Priorisierung von Störungen**

| Priorität | Beispiel |
|---|---|
| niedrig | einzelner unkritischer Datensatz |
| mittel | mehrere Benutzer betroffen |
| hoch | wichtiger Geschäftsprozess ausgefallen |
| kritisch | Sicherheitsvorfall oder Datenverlust |

Zu berücksichtigen sind:

- Anzahl betroffener Benutzer
- betriebliche Auswirkung
- Sicherheitsrisiko
- möglicher Datenverlust
- vorhandener Workaround
- zeitliche Dringlichkeit

---

**Übergabe an andere Mitarbeiter**

Eine Übergabe sollte enthalten:

- aktueller Stand
- Fehlerursache, falls bekannt
- bereits getestete Maßnahmen
- offene Fragen
- relevante Logs
- betroffene Systeme
- sichere Wiederholungsmöglichkeit
- nächster empfohlener Schritt

Schlechte Übergabe:

> Funktioniert nicht. Bitte prüfen.

Bessere Übergabe:

> Der POST-Request an `/users` ist erfolgreich. Die anschließende Gruppenzuweisung antwortet mit 403. Token, Benutzer-ID und Endpoint wurden geprüft. Vermutlich fehlt der Scope für Gruppenänderungen.

---

**Wiederherstellung**

Vor größeren Änderungen sollte bekannt sein:

- Gibt es ein Backup?
- Kann der Workflow exportiert werden?
- Kann eine alte Version wiederhergestellt werden?
- Können Credentials zurückgesetzt werden?
- Können Änderungen rückgängig gemacht werden?
- Welche manuellen Schritte sind notwendig?

Mögliche Maßnahmen:

- Workflow-Version sichern
- Konfiguration exportieren
- Testlauf durchführen
- Rollback dokumentieren
- Änderungen schrittweise veröffentlichen

---

**Praxisbeispiel: Fehlerhafte Benutzeranlage**

Fehler:

    POST /users

    Status: 409 Conflict

    {
      "error": "Email already exists"
    }

Systematische Prüfung:

1. Response wurde empfangen.
2. Endpoint und Methode sind korrekt.
3. Authentifizierung ist gültig.
4. E-Mail-Adresse existiert bereits.
5. vorhandenes Konto wird mit GET gesucht.
6. Datensatz wird nicht erneut angelegt.
7. Workflow erstellt eine manuelle Prüfaufgabe.
8. Ergebnis wird protokolliert.

---

**Praxisbeispiel: Workflow startet nicht**

Prüfung:

1. Workflow aktiv?
2. Webhook-URL korrekt?
3. Test- oder Produktiv-URL verwendet?
4. Quellsystem hat tatsächlich gesendet?
5. Firewall oder Proxy blockiert?
6. richtige HTTP-Methode?
7. Authentifizierung gültig?
8. Trigger-Log vorhanden?

Mögliche Ursache:

> Im Quellsystem wurde noch die Test-Webhook-URL verwendet.

---

**Praxisbeispiel: Zusammenspiel mehrerer Workflows**

Folgende Regeln gelten:

- Workflow A deaktiviert Benutzer ohne Abteilung.
- Workflow B entfernt beim Offboarding die Abteilung.
- Workflow C reaktiviert Benutzer mit offenen Aufgaben.

Möglicher Ablauf:

1. Workflow B entfernt die Abteilung.
2. Workflow A deaktiviert den Benutzer.
3. Workflow C erkennt offene Aufgaben.
4. Workflow C aktiviert den Benutzer erneut.

Jeder Workflow arbeitet nach seiner eigenen Regel korrekt.

Das Gesamtergebnis ist dennoch falsch.

Mögliche Lösung:

- gemeinsame Prozesslogik definieren
- eindeutigen Mitarbeiterstatus verwenden
- Prioritäten festlegen
- gegenseitige Abhängigkeiten dokumentieren
- vollständigen Systemtest durchführen

---

**Systematische Fehlersuche**

Bei einer gestörten Schnittstelle:

1. fachliche Anforderung klären
2. Problem genau beschreiben
3. betroffene Systeme bestimmen
4. Trigger prüfen
5. Eingangsdaten prüfen
6. Erreichbarkeit prüfen
7. Endpoint und Methode kontrollieren
8. Authentifizierung prüfen
9. Autorisierung prüfen
10. Header und Body prüfen
11. Statuscode auswerten
12. Response-Body lesen
13. Reihenfolge und Timing untersuchen
14. Abhängigkeiten prüfen
15. Logs kontrollieren
16. letzte Änderungen prüfen
17. Komponenten einzeln testen
18. Integrationstest durchführen
19. Gesamtsystem testen
20. Ursache und Lösung dokumentieren

---

**Wichtige Begriffe**

| Begriff | Bedeutung |
|---|---|
| Fehlerursache | tatsächlicher Auslöser eines Problems |
| Fehlerstelle | Stelle, an der ein Problem sichtbar wird |
| Fehlereingrenzung | Problem Schritt für Schritt lokalisieren |
| Schnittstellenfehler | Fehler bei Übergabe oder Interpretation |
| Abhängigkeit | ein System benötigt ein anderes System |
| emergentes Verhalten | unerwartetes Verhalten des Gesamtsystems |
| Komponententest | einzelne Komponente prüfen |
| Integrationstest | Zusammenspiel mehrerer Komponenten prüfen |
| Systemtest | vollständiges Gesamtsystem prüfen |
| Abnahmetest | fachliche Anforderungen prüfen |
| Reproduktion | Fehler unter gleichen Bedingungen erneut auslösen |
| Änderungsprotokoll | technische Änderungen dokumentieren |
| Rollback | Änderung auf vorherigen Stand zurücksetzen |
| Workaround | vorläufige Umgehung eines Fehlers |

---

**Gesamtmerksatz**

> Technische Fehler liegen nicht immer eindeutig in Software, Elektronik oder Mechanik. Viele Probleme entstehen erst durch unklare Anforderungen, fehlerhafte Schnittstellen, falsche Datentypen, unterschiedliches Timing, versteckte Abhängigkeiten oder das Zusammenspiel mehrerer Teilsysteme. Deshalb müssen neben den einzelnen Komponenten auch ihre Integrationen und das vollständige Gesamtsystem geprüft werden.

---

**Kontrollfragen**

**Warum zeigt eine Fehlermeldung nicht immer die eigentliche Ursache?**

Weil ein Fehler in einem anderen Teilsystem entstehen und erst später sichtbar werden kann.

**Warum können funktionierende Komponenten gemeinsam einen Fehler erzeugen?**

Weil Schnittstellen, Datenformate, Reihenfolge, Timing oder Abhängigkeiten nicht zusammenpassen.

**Was ist ein Schnittstellenfehler?**

Ein Fehler bei der Übergabe oder Interpretation von Daten, Signalen oder Befehlen zwischen Systemen.

**Was bedeutet emergentes Verhalten?**

Das Gesamtsystem zeigt ein Verhalten, das bei der getrennten Betrachtung der Einzelteile nicht erkennbar war.

**Was prüft ein Komponententest?**

Eine einzelne Funktion oder Komponente.

**Was prüft ein Integrationstest?**

Das Zusammenspiel und die Schnittstellen zwischen mehreren Komponenten.

**Was prüft ein Systemtest?**

Den vollständigen Ablauf des Gesamtsystems.

**Was prüft ein Abnahmetest?**

Ob das System die tatsächlichen fachlichen Anforderungen erfüllt.

**Warum müssen Statuscode und Response-Body gemeinsam geprüft werden?**

Der Statuscode zeigt die allgemeine Fehlerklasse. Der Response-Body enthält häufig die genaue Ursache.

**Warum ist ein Änderungsprotokoll wichtig?**

Damit Fehler mit vorherigen technischen Änderungen in Verbindung gebracht werden können.

**Warum sollte der früheste Fehler eines Ablaufs zuerst untersucht werden?**

Weil spätere Fehlermeldungen häufig nur Folgefehler derselben Ursache sind.

---

**Quellen**

- [IETF – HTTP Semantics](https://datatracker.ietf.org/doc/html/rfc9110)
- [MDN Web Docs – HTTP-Statuscodes](https://developer.mozilla.org/de/docs/Web/HTTP/Status)
- [n8n-Dokumentation – Executions](https://docs.n8n.io/workflows/executions/)
- [n8n-Dokumentation – Error Handling](https://docs.n8n.io/flow-logic/error-handling/)
- [OWASP – Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)
- [BSI – IT-Grundschutz](https://www.bsi.bund.de/grundschutz)
```