Aufgaben

Die Task-Entität (intern ApiTask / TaskItem) repräsentiert Aufgaben innerhalb eines Projekts. Über die OData-API können Sie Aufgaben erstellen, aktualisieren, löschen sowie Stapelverarbeitung, Mitwirkende, Stoppuhr-Funktionen und Kalendersynchronisation nutzen.

OData-Endpunktbasis

Alle Endpunkte verwenden den Basispfad /odata/Task. Für die abgeflachte Listenansicht steht /odata/DynamicTaskItem zur Verfügung.

---

Datenmodell

Property	Type	Description
TaskItemId	Guid (UUID)	Eindeutiger Bezeichner der Aufgabe (Primärschlüssel).
Name	string?	Name der Aufgabe.
TaskItemStatusId	Guid?	Status der Aufgabe (Fremdschlüssel zur Statusdefinition).
ContactId	Guid?	Zugewiesener Kontakt (Verantwortlicher).
ProjectId	Guid?	Zugehöriges Projekt.
PlanningId	Guid?	Verknüpftes Planungselement.
GroupId	Guid	Aufgabengruppe.
StartDateTime	DateTimeOffset?	Startdatum und -uhrzeit.
EndDateTime	DateTimeOffset?	Enddatum und -uhrzeit.
IsDone	boolean	Gibt an, ob die Aufgabe abgeschlossen ist.
DoneDate	DateTimeOffset?	Datum des Abschlusses.
WorkAmount	double	Arbeitsaufwand (Stunden).
CustomColor	int32?	Benutzerdefinierte Farbe (als Integer-Wert).
CardPositionNumber	int32	Position auf dem Kanban-Board.
DescriptionHTML	string?	Beschreibung der Aufgabe als HTML.
IsBillable	boolean	Gibt an, ob die Aufgabe abrechenbar ist.
Recurrence	int32	Wiederholungsmuster (0 = keine Wiederholung).
AssignedByContactId	Guid?	Kontakt, der die Aufgabe zugewiesen hat.
CreatedByContactId	Guid	Kontakt, der die Aufgabe erstellt hat.
ContactDisplayName	string?	Anzeigename des zugewiesenen Kontakts (schreibgeschützt).
ContactImageId	Guid?	Bild-ID des zugewiesenen Kontakts (schreibgeschützt).
RiskId	Guid?	Verknüpftes Risiko.
RiskName	string?	Name des verknüpften Risikos (schreibgeschützt).
ChecklistItemsCount	int32	Gesamtanzahl der Checklisten-Elemente.
CheckListItemsDoneCount	int32	Anzahl der abgeschlossenen Checklisten-Elemente.
CheckListItemsOpenCount	int32	Anzahl der offenen Checklisten-Elemente.
ContributorsCount	int32	Anzahl der Mitwirkenden.
ContributorsWorkAmount	double	Arbeitsaufwand aller Mitwirkenden.
WorkAmountOwner	double	Arbeitsaufwand des Verantwortlichen.

---

Endpunkte

CRUD-Operationen

GET/odata/Task

Alle Aufgaben abrufen. Unterstützt OData-Abfrageparameter.

POST/odata/Task

Neue Aufgabe erstellen.

Parameter	Type	Required	Description
Body	Delta<ApiTask>	✅	JSON-Objekt mit den Aufgabeneigenschaften.

GET/odata/Task({key})

Eine einzelne Aufgabe anhand ihrer ID abrufen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId der Aufgabe.

PATCH/odata/Task({key})

Aufgabe teilweise aktualisieren.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId der Aufgabe.
Body	Delta<ApiTask>	✅	JSON-Objekt mit den zu aktualisierenden Feldern.

DELETE/odata/Task({key})

Aufgabe löschen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId der zu löschenden Aufgabe.

GET/odata/Task/$count

Gesamtanzahl aller Aufgaben abrufen.

---

Stapelverarbeitung

POST/odata/Task/BatchInsert

Mehrere Aufgaben gleichzeitig erstellen.

Parameter	Type	Required	Description
Body	object	✅	JSON-Objekt mit einem Array von Aufgabendaten.

POST/odata/Task/BatchDelete

Mehrere Aufgaben gleichzeitig löschen.

Parameter	Type	Required	Description
Body	object	✅	JSON-Objekt mit einem Array von TaskItemIds.

warnung

Die Stapellöschung entfernt alle angegebenen Aufgaben dauerhaft. Diese Aktion kann nicht rückgängig gemacht werden.

Leistung

Die Stapelverarbeitung ist deutlich effizienter als das einzelne Erstellen oder Löschen von Aufgaben. Verwenden Sie BatchInsert und BatchDelete, wenn Sie mit großen Mengen arbeiten.

---

Aufgabenverwaltung

POST/odata/Task({key})/MoveTaskItem

Eine Aufgabe verschieben (z. B. in eine andere Gruppe oder ein anderes Planungselement).

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit dem Zielort.

POST/odata/Task({key})/UpdateProjectDefinedField

Ein projektdefiniertes Feld der Aufgabe aktualisieren.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit Feldname und Wert.

POST/odata/Task({key})/Copy

Eine Aufgabe duplizieren.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId der zu kopierenden Aufgabe.
Body	object	✅	JSON-Objekt mit Kopieroptionen.

---

Notizen

POST/odata/Task({key})/AddNote

Eine Notiz zur Aufgabe hinzufügen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit dem Notizinhalt.

GET/odata/Task/DeleteNote(noteRelationId={noteRelationId})

Eine Notiz von der Aufgabe löschen.

Parameter	Type	Required	Description
noteRelationId	Guid	✅	Die ID der Notizverknüpfung.

---

Mitwirkende (Contributors)

GET/odata/Task({key})/GetContributors()

Alle Mitwirkenden einer Aufgabe abrufen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.

POST/odata/Task({key})/AddContributor

Einen Mitwirkenden hinzufügen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit Kontakt-ID und Aufwand.

POST/odata/Task({key})/UpdateContributor

Einen Mitwirkenden aktualisieren.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit aktualisierten Mitwirkendendaten.

POST/odata/Task({key})/RemoveContributor

Einen Mitwirkenden entfernen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit der Kontakt-ID des zu entfernenden Mitwirkenden.

---

Stoppuhr

GET/odata/Task({key})/GetStopwatch()

Den aktuellen Stoppuhr-Status einer Aufgabe abrufen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.

POST/odata/Task({key})/StartStopwatch

Die Stoppuhr starten.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.

POST/odata/Task({key})/PauseStopwatch

Die Stoppuhr pausieren.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.

POST/odata/Task({key})/StopStopwatch

Die Stoppuhr stoppen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.

Stoppuhr-Workflow

Der typische Workflow ist: StartStopwatch → PauseStopwatch (optional) → StopStopwatch. Beim Stoppen wird automatisch ein Zeiteintrag erstellt.

---

Dokumente

POST/odata/Task({key})/AddDocumentToTaskItem

Ein Dokument mit der Aufgabe verknüpfen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit der Dokument-ID.

POST/odata/Task({key})/RemoveDocumentFromTaskItem

Ein Dokument von der Aufgabe entfernen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit der Dokument-ID.

---

Verknüpfungen

POST/odata/Task({key})/AddRelation

Eine Verknüpfung zur Aufgabe hinzufügen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit den Verknüpfungsdetails.

POST/odata/Task({key})/RemoveRelation

Eine Verknüpfung von der Aufgabe entfernen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit der Verknüpfungs-ID.

---

Kalendersynchronisation

GET/odata/Task({key})/GetCalendarSyncStatus()

Den Synchronisationsstatus der Aufgabe mit dem Kalender abrufen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.

POST/odata/Task({key})/EnableCalendarSync

Kalendersynchronisation für die Aufgabe aktivieren.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.

POST/odata/Task({key})/DisableCalendarSync

Kalendersynchronisation für die Aufgabe deaktivieren.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.

---

Benachrichtigungen

POST/odata/Task({key})/AddNotificationFollowers

Benachrichtigungsabonnenten zur Aufgabe hinzufügen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit den Kontakt-IDs der Abonnenten.

POST/odata/Task({key})/RemoveNotificationFollower

Einen Benachrichtigungsabonnenten entfernen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit der Kontakt-ID.

GET/odata/Task({key})/GetNotificationFollowerContacts()

Alle Benachrichtigungsabonnenten der Aufgabe abrufen.

Parameter	Type	Required	Description
key	Guid	✅	Die TaskItemId.

---

DynamicTaskItem

Der Endpunkt /odata/DynamicTaskItem bietet eine schreibgeschützte, abgeflachte Ansicht, die Daten aus Aufgabe, Projekt, Planung, Portfolio und Berechtigungen zusammenführt. Alle Eigenschaften sind mit einem Präfix versehen (z. B. TaskItem_Name, Project_Name, Planning_DisplayName).

GET/odata/DynamicTaskItem

Abgeflachte Aufgabenliste mit Projekt-, Planungs- und Berechtigungsdaten abrufen.

GET/odata/DynamicTaskItem/$count

Gesamtanzahl der DynamicTaskItem-Einträge abrufen.

Nur lesender Zugriff

DynamicTaskItem unterstützt ausschließlich GET-Anfragen. Zum Erstellen oder Bearbeiten verwenden Sie die regulären /odata/Task-Endpunkte.

---

OData-Abfragebeispiele

Offene Aufgaben eines Projekts abrufen

GET /odata/Task?$filter=ProjectId eq 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' and IsDone eq false

Aufgaben eines bestimmten Kontakts

GET /odata/Task?$filter=ContactId eq 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Überfällige Aufgaben

GET /odata/Task?$filter=EndDateTime lt 2025-01-01T00:00:00Z and IsDone eq false

Aufgabe erstellen

POST /odata/Task
Content-Type: application/json

{
  "Name": "API-Integration testen",
  "ProjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "ContactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "StartDateTime": "2025-02-01T09:00:00Z",
  "EndDateTime": "2025-02-15T17:00:00Z",
  "WorkAmount": 16.0
}

Aufgabe als erledigt markieren

PATCH /odata/Task('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
Content-Type: application/json

{
  "IsDone": true,
  "DoneDate": "2025-01-20T14:30:00Z"
}

Mehrere Aufgaben gleichzeitig erstellen

POST /odata/Task/BatchInsert
Content-Type: application/json

{
  "items": [
    { "Name": "Aufgabe 1", "ProjectId": "..." },
    { "Name": "Aufgabe 2", "ProjectId": "..." }
  ]
}