🛠️  Maßnahmen (Countermeasures) per REST API verwalten

🔍 Inhalt

• Voraussetzungen
• Authentifizierung
• Endpunkte im Überblick
• Maßnahme erstellen (POST)
• Maßnahme aktualisieren (PUT)
• Maßnahme abrufen & löschen
• Beschreibung verwalten
• Technische Hinweise
• Tipps & Best Practices
• FAQ

Voraussetzungen

• 🔐 API-Zugangsdaten (Username + Passwort für HTTP Basic Auth)

• 🌐 Tool zur Request-Ausführung (z. B. Postman, Swagger, Python, ...)

• 🧾 ID der zugehörigen Abweichung (deviationId)

• 👥 Verantwortliche Person (UUID eines Team-Members)

• 📅 Geplantes Enddatum (Format: YYYY-MM-DD)

---

🔑 Authentifizierung

Die Authentifizierung erfolgt per HTTP Basic Auth. API-Aktivitäten werden im Änderungsprotokoll unter dem Benutzer "API-USER" dokumentiert.

---

🔗 Endpunkte im Überblick (PDCA)

Aktion	Methode	Endpoint
Maßnahmen abrufen	GET	/exchange/countermeasures?team={id}
Einzelne Maßnahme abrufen	GET	/exchange/countermeasures/{id}
Statusverlauf anzeigen	GET	/exchange/countermeasures/{id}/status-history
Neue Maßnahme erstellen	POST	/exchange/countermeasures/pdca
Maßnahme aktualisieren	PUT	/exchange/countermeasures/pdca/{id}
Maßnahme löschen	DELETE	/exchange/countermeasures/pdca/{id}
Beschreibung abrufen	GET	/exchange/countermeasures/pdca/{id}/description
Beschreibung aktualisieren	PUT	/exchange/countermeasures/pdca/{id}/description

📸 Screenshot: Endpunkte

✍️ Maßnahme erstellen (POST)

POST /exchange/countermeasures/pdca
Content-Type: application/json

Beispiel-Body:

{
  "deviationId": "9770be21-ba1a-4b45-a21c-92fcdb62a4e3",
  "endDatePlan": "2025-08-30",
  "priority": true,
  "progress": "PLAN",
  "closeDeviation": false,
  "responsiblePerson": "ffa6fda3-e10f-4e86-bd3a-6314e7e28ee6",
  "responsibleTeam": "e70ebfdd-760b-4f50-b69f-6564acb4a367",
  "status": 1,
  "statusMessage": "In Planung",
  "title": "Maßnahme umsetzen"
}

✨ Tipp: Der Parameter closeDeviation: true kann genutzt werden, um die zugehörige Abweichung automatisch zu schließen – aber nur, wenn keine offenen Maßnahmen mehr existieren.

✏️ Maßnahme aktualisieren (PUT)

PUT /exchange/countermeasures/pdca/{id}

Beispiel-Body:

{
  "progress": "DO",
  "status": 2,
  "statusMessage": "Maßnahme in Umsetzung",
  "endDatePlan": "2025-09-10"
}

⚠️ Achtung: Änderungen an progress, status oder statusMessage sollten konsistent erfolgen. Andernfalls kann es zu Validierungsfehlern kommen.

📄 Maßnahme abrufen & löschen

Einzelne Maßnahme abrufen

GET /exchange/countermeasures/{id}

Statusverlauf anzeigen

GET /exchange/countermeasures/{id}/status-history

Maßnahme löschen

DELETE /exchange/countermeasures/pdca/{id}

⚠️ Achtung: Beim Löschen werden verknüpfte Inhalte (z. B. Feedback, Top Issue) entfernt. Aufgaben (Tasks) bleiben bestehen, verlieren jedoch ihre Verbindung zur Maßnahme.

📝 Beschreibung verwalten

Beschreibung abrufen

GET /exchange/countermeasures/pdca/{id}/description
Accept: text/html


Beschreibung aktualisieren

PUT /exchange/countermeasures/pdca/{id}/description
Content-Type: text/html

<p>Beschreibung der Maßnahme in HTML</p>

📌 Technische Hinweise

• Unterstützte Maßnahmentypen: Nur PDCA

• Pflichtfelder: title, responsibleTeam, responsiblePerson, deviationId, progress, status

• Status-Codes: 1 = offen, 2 = in Arbeit, 3 = erledigt

• Fortschritt (progress): PLAN → DO → CHECK → ACT

• Beschreibung muss im gültigen HTML-Format übermittelt werden

✨ Tipps & Best Practices

• Starte API-Tests im Swagger Editor oder Postman

• Nutze strukturierte Titel und Statusmeldungen für bessere Übersicht

• Vermeide Mehrfachzuweisungen zu geschlossenen Abweichungen

• Dokumentiere alle Maßnahmen mit Beschreibung und Fortschritt

❓ FAQ

Kann ich auch A3-Maßnahmen per API verwalten?
-> Nein – A3-Maßnahmen können nur gelesen, aber nicht erstellt oder bearbeitet werden.

Welche Werte sind für progress erlaubt?
-> PLAN, DO, CHECK, ACT

Wie kann ich eine Maßnahme mit einer Abweichung verknüpfen?
-> Über das Feld deviationId im POST-/PUT-Body.

Was passiert beim Löschen einer Maßnahme?
-> Die Maßnahme wird vollständig entfernt. Verknüpfte Aufgaben bleiben erhalten, verlieren jedoch ihre Verbindung zur Maßnahme.