🧩 Prozessaktivitäten per REST API verwalten

🔍 Inhalt

• Voraussetzungen
• Authentifizierung
• Endpunkte im Überblick
• Aktivitäten erstellen & aktualisieren
• Beschreibung verwalten
• Planung verwalten
• Status-Historie abrufen
• Technische Hinweise
• Tipps & Best Practices
• FAQ

Voraussetzungen

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

• 📄 API-YAML-Datei zur Verwendung mit Swagger oder Code-Generatoren

• 🧪 Tool zur API-Ausführung (Swagger, Postman, Power Automate, Skript)

---

🔑 Authentifizierung

Erfolgt über HTTP Basic Auth:

Authorization: Basic <Base64-encoded-username:password>

🔗 Endpunkte im Überblick

Aktivitäten verwalten

Methode	Pfad	Beschreibung
GET	/exchange/processactivities	Liste aller Aktivitäten eines Boards abrufen
POST	/exchange/processactivities	Neue Aktivität erstellen
GET	/exchange/processactivities/{id}	Aktivität im Detail abrufen
PUT	/exchange/processactivities/{id}	Aktivität aktualisieren
DELETE	/exchange/processactivities/{id}	Aktivität löschen

📸 Screenshot: EndpunkteBeschreibung verwalten

Methode	Pfad
GET	/exchange/processactivities/{id}/description
PUT	/exchange/processactivities/{id}/description

Planung verwalten

Methode	Pfad
GET	/exchange/processactivities/{id}/planning
PUT	/exchange/processactivities/{id}/planning

Status-Historie

Methode	Pfad
GET	/exchange/processactivities/{id}/status-history

Metadaten abrufen

Methode	Pfad
GET	/exchange/processboard-categories
GET	/exchange/processboard-labels
GET	/exchange/processboards/{id}

📌 Aktivitäten erstellen (POST)

{
  "title": "Prozessschritt abschließen",
  "category": "UUID-der-Kategorie",
  "team": "UUID-des-Teams",
  "responsiblePerson": "UUID-der-Person",
  "labels": ["UUID-des-Labels"]
}

✨ Tipp: Verwenden Sie Labels zur flexiblen Filterung in Dashboards.

✏️ Aktivitäten aktualisieren (PUT)

Nur geänderte Felder im Body übergeben. Beispiel:

{
  "title": "Angepasster Titel",
  "category": "neue-Kategorie-UUID"
}

⚠️ Achtung: Wird die Phase geändert, werden automatisch neue Start- und Enddaten gesetzt.

📝 Beschreibung verwalten

Abrufen:

GET /exchange/processactivities/{id}/description

Aktualisieren:

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

<p>Neue Beschreibung als HTML</p>

🗓 Planung verwalten

Planungen geben an, welche Phasen wann geplant waren. Beispiel:

{
  "planings": [
    {
      "phase": "UUID-DER-PHASE",
      "plannedEndDate": "2025-08-30"
    }
  ]
}

📊 Status-Historie anzeigen

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

Gibt eine Liste von Statusänderungen zurück.

📌 Technische Hinweise

• Pflichtfelder: title, category, team, responsiblePerson

• Planung unterstützt mehrere Phasen pro Aktivität

• Kategorien & Labels müssen über Metadaten-Endpunkte abgerufen werden

✨ Tipps & Best Practices

• Verwenden Sie UUIDs aus /processboards/{id} für Labels, Kategorien, Phasen

• Halten Sie Planungsdaten aktuell für präzises Monitoring

• Nutzen Sie strukturierte Titel zur einfachen Wiedererkennung

• API-Aktionen werden unter "API-USER" protokolliert

❓ FAQ

Welche Felder sind beim Erstellen einer Aktivität Pflicht?
-> title, category, team, responsiblePerson

Wie erfahre ich, welche Labels oder Kategorien verfügbar sind?
-> Über die Endpunkte /processboard-labels und /processboard-categories

Kann ich Planungsdaten auch nachträglich ändern?
-> Ja, über den PUT-Endpunkt /processactivities/{id}/planning

Wie wird der Fortschritt einer Aktivität dokumentiert?
-> Über die Phasenplanung und ggf. Statusänderungen

Kann ich Aktivitäten auch wieder löschen?
-> Ja, mit DELETE /exchange/processactivities/{id}