✅ Aufgaben per REST API verwalten

🔍 Inhalt

Voraussetzungen
Authentifizierung
Endpunkte im Überblick
Aufgaben verwalten (CRUD)
Beschreibung & Statusverlauf abrufen/bearbeiten
Technische Hinweise
Tipps & Best Practices
FAQ

Voraussetzungen

🔐 API-Zugangsdaten (Username + Passwort für HTTP Basic Auth)
⚙️ Eine Umgebung zur Ausführung von REST-Requests
(z. B. Power Automate, Postman, Python, Swagger UI)

ℹ️ Hinweis: Zum Erstellen einer Aufgabe benötigen Sie gültige UUIDs für:

Team (responsibleTeam)
Kategorie (category)
Optional: Label, verantwortliche Person, T-Card

🔑 Authentifizierung

Die Authentifizierung erfolgt per HTTP Basic Auth.
Header-Beispiel:

Authorization: Basic <Base64-kodierter Benutzername:Passwort>

🔧 Änderungen über die API werden im System mit dem Nutzer „API-USER“ dokumentiert.

🔗 Endpunkte im Überblick (Tasks)

Methode	Endpunkt	Beschreibung
GET	`/exchange/tasks`	Alle Aufgaben abrufen
GET	`/exchange/tasks/{id}`	Einzelne Aufgabe abrufen
POST	`/exchange/tasks`	Neue Aufgabe erstellen
PUT	`/exchange/tasks/{id}`	Aufgabe aktualisieren
DELETE	`/exchange/tasks/{id}`	Aufgabe löschen

📸 Screenshot: Endpunkte

Zusätzliche Endpunkte:

📄 Beschreibung abrufen/bearbeiten:
- GET /tasks/{id}/description
- PUT /tasks/{id}/description
📈 Statusverlauf abrufen:
- GET /tasks/{id}/status-history
🧾 Metadaten (Kategorien, Labels, Teams):
- GET /taskboard-categories, GET /taskboard-labels, GET /teams/{id}/taskboard

➕ Neue Aufgabe erstellen (POST)

POST /exchange/tasks

📄 Beispiel-Request:

{
  "title": "Neue Aufgabe",
  "category": "263c2d97-762f-4ef3-a350-b88225d00882",
  "priority": true,
  "responsibleTeam": "49af7f6c-c1e5-49c7-99ed-c27b29067eec",
  "status": 2,
  "targetEndDate": "2025-08-31",
  "targetEffort": 6.0
}

✨ Tipp:
Für T-Card-Aufgaben zusätzlich "tCard": true und passende Label-ID angeben.

🛠 Aufgabe aktualisieren (PUT)

PUT /exchange/tasks/{task-id}

📄 Beispiel-Request:

{
  "title": "Titel geändert",
  "category": "263c2d97-762f-4ef3-a350-b88225d00882",
  "priority": false,
  "status": 3,
  "statusMessage": "Blockiert durch fehlende Ressourcen",
  "responsibleTeam": "c2c1483f-7b29-4ed5-9d46-c290f8cb50a5",
  "targetEffort": 4.0,
  "targetEndDate": "2025-09-10"
}

⚠️ Achtung: Beim Ändern des Status (z. B. grün → rot) muss statusMessage mitgegeben werden!

🗑️ Aufgabe löschen (DELETE)

DELETE /exchange/tasks/{task-id}

⚠️ Achtung: Beim Löschen einer Aufgabe werden auch verknüpfte Inhalte (Deviation, Feedback etc.) entfernt.

📄 Beschreibung bearbeiten (PUT)

PUT /exchange/tasks/{task-id}/description
Content-Type: text/html

<p>Neue Beschreibung mit HTML-Markup</p>

🕓 Status-Historie abrufen

GET /exchange/tasks/{task-id}/status-history

Beispiel-Antwort:

[
  {
    "comment": "Status geändert",
    "modifiedByUser": "API-USER",
    "modifiedDate": "2025-08-01",
    "status": 3
  }
]

📌 Technische Hinweise

Pflichtfelder beim Erstellen: title, category, responsibleTeam, status, targetEffort, targetEndDate
Status-Codes: 1 = grün, 2 = blau, 3 = rot
Archivieren ist nur über die UI möglich
T-Card-Aufgaben können nicht automatisiert abgeschlossen oder replanned werden
HTML für description muss gültig sein

✨ Tipps & Best Practices

🔄 Verwenden Sie eindeutige Labels & Kategorien pro Team (über GET /teams/{id}/taskboard)
🧪 Testen Sie API-Requests zuerst in Swagger oder Postman
👥 Aufgaben mit verantwortlicher Person müssen aus Team-Members stammen (GET /teams/{id})

❓ FAQ

Welche Felder sind beim Erstellen einer Aufgabe erforderlich?
-> Mindestens: title, category, responsibleTeam, status, targetEndDate, targetEffort.

Kann ich Aufgaben über die API archivieren?
-> Nein – das ist nur über die UI möglich.

Was passiert, wenn ich ein Feld mit null sende?
-> Es wird gelöscht bzw. auf null gesetzt.