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 dynamische Listenansicht einschließlich eigener Felder steht /odata/DynamicTaskItem zur Verfügung.

---

Datenmodell

Eigenschaft	Typ	Beschreibung
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 (schreibgeschützt, wird automatisch gesetzt wenn IsDone geändert wird).
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. Werte: 0 = Keine Wiederholung, 1 = Täglich, 2 = Montag bis Freitag, 3 = Wöchentlich, 4 = Monatlich, 5 = Jährlich, 6 = Zweiwöchentlich, 7 = Vierteljährlich.
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

Alle Aufgaben abrufen

GET/odata/Task

Unterstützt OData-Abfrageparameter.

---

Eine einzelne Aufgabe anhand ihrer ID abrufen

GET/odata/Task({key})

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId der Aufgabe.

---

Neue Aufgabe erstellen

POST/odata/Task

Parameter	Typ	Erforderlich	Beschreibung
Body	Delta<ApiTask>	✅	JSON-Objekt mit den Aufgabeneigenschaften.

hinweis

Um eine Aufgabe in einer bestimmten Kanban-Spalte zu erstellen, geben Sie TaskItemStatusId im Request-Body an. Mit CardPositionNumber legen Sie die Position innerhalb dieser Spalte fest.

---

Aufgabe aktualisieren

PATCH/odata/Task({key})

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId der Aufgabe.
Body	Delta<ApiTask>	✅	JSON-Objekt mit den zu aktualisierenden Feldern.

---

Aufgabe löschen

DELETE/odata/Task({key})

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId der zu löschenden Aufgabe.

warnung

Das Löschen einer Aufgabe kann nicht rückgängig gemacht werden.

---

Stapelverarbeitung

Mehrere Aufgaben gleichzeitig erstellen

POST/odata/Task/BatchInsert

Parameter	Typ	Erforderlich	Beschreibung
Body	object	✅	JSON-Objekt mit einem Array von Aufgabendaten.

---

Mehrere Aufgaben gleichzeitig löschen

POST/odata/Task/BatchDelete

Parameter	Typ	Erforderlich	Beschreibung
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

Eine Aufgabe innerhalb des Kanbans verschieben

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: taskItemStatusId (Guid, erforderlich) — Die ID des Ziel-TaskItemStatus. afterTaskItemId (Guid?, optional) — Die ID der Aufgabe, nach der diese platziert werden soll. Wird der Wert weggelassen oder ist null, wird die Standardposition verwendet.

---

Ein projektdefiniertes Feld der Aufgabe aktualisieren

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: fieldName (string, erforderlich) — Der Name des projektdefinierten Felds (z. B. "pf_dt0_xxxxxxxx_SomeField"). value (string?, optional) — Der zu setzende Wert, oder null zum Löschen.

---

Eine Aufgabe duplizieren

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId der zu kopierenden Aufgabe.
Body	object	✅	JSON-Objekt mit folgenden Feldern: projectId (Guid?, optional) — Zielprojekt-ID. Wird der Wert weggelassen oder ist null, verbleibt die Kopie im selben Projekt wie die Quellaufgabe.

---

Kommentare

Die Entität TaskItemNote ist das zugrunde liegende Datenmodell für Aufgabenkommentare. Jeder Kommentar wird als TaskItemNote gespeichert und mit einer bestimmten Aufgabe verknüpft.

Eigenschaft	Typ	Beschreibung
TaskItemNoteId	guid	Eindeutige ID der Notiz.
TaskItemId	guid	ID der zugehörigen Aufgabe.
Note	string	Notiztext (Klartext).
NoteHtml	string	Notiztext (HTML-formatiert).
ShortDescription	string	Kurzbeschreibung.
CreateDateTime	DateTimeOffset	Erstellungszeitpunkt.
CreatedByContactId	guid	ID des Erstellers.

Alle Aufgabenkommentare aller Aufgaben im System abrufen

GET/odata/TaskItemNote

Unterstützt OData-Abfrageparameter.

Filtern Sie nach einer Aufgabe:

GET /odata/TaskItemNote?$filter=TaskItemId eq xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&$orderby=CreateDateTime desc

---

Einen Aufgabenkommentar nach ID abrufen

GET/odata/TaskItemNote({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die TaskItemNoteId.

---

Einen Kommentar zur Aufgabe hinzufügen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: htmlText (string, erforderlich) — HTML-formatierter Kommentarinhalt. notificationContactIds (Guid[], erforderlich) — Kontakt-IDs, die benachrichtigt werden sollen (kann leer sein []).

---

Einen Kommentar aus der Aufgabe löschen

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

Parameter	Typ	Erforderlich	Beschreibung
noteRelationId	Guid	✅	Die ID der Kommentarverknüpfung.

warnung

Das Löschen eines Kommentars kann nicht rückgängig gemacht werden.

---

Mitwirkende (Contributors)

Alle Mitwirkenden einer Aufgabe abrufen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.

---

Einen Mitwirkenden hinzufügen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: contactId (Guid, erforderlich) — Der hinzuzufügende Kontakt. workAmount (double, optional) — Arbeitsaufwand in Stunden. isDone (boolean, optional) — Abschlussstatus.

---

Einen Mitwirkenden aktualisieren

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: id (Guid, erforderlich) — Die ID des Mitwirkenden. workAmount (double, optional) — Arbeitsaufwand in Stunden. isDone (boolean, optional) — Abschlussstatus.

---

Einen Mitwirkenden entfernen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: id (Guid, erforderlich) — Die ID des zu entfernenden Mitwirkenden.

---

Stoppuhr

Den aktuellen Stoppuhr-Status einer Aufgabe abrufen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.

---

Die Stoppuhr starten

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.

---

Die Stoppuhr pausieren

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.

---

Die Stoppuhr stoppen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.

Stoppuhr-Workflow

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

---

Dokumente

Ein Dokument mit der Aufgabe verknüpfen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: documentIds (Guid[], erforderlich) — Array von Dokument-IDs, die verknüpft werden sollen.

---

Ein Dokument von der Aufgabe entfernen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: documentId (Guid, erforderlich) — Die Dokument-ID, deren Verknüpfung entfernt werden soll.

---

Verknüpfungen

Eine Verknüpfung zur Aufgabe hinzufügen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: itemId (Guid, erforderlich) — Die ID des zu verknüpfenden Elements.

---

Eine Verknüpfung aus der Aufgabe entfernen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: itemId (Guid, erforderlich) — Die ID des zu entfernenden Elements.

---

Kalendersynchronisation

Den Synchronisationsstatus der Aufgabe mit dem Kalender abrufen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.

---

Kalendersynchronisation für die Aufgabe aktivieren

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.

---

Kalendersynchronisation für die Aufgabe deaktivieren

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.

---

Benachrichtigungen / Follower

Alle Benachrichtigungsabonnenten der Aufgabe abrufen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.

---

Benachrichtigungsabonnenten zur Aufgabe hinzufügen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: contactIds (Guid[], erforderlich) — Kontakt-IDs, die als Abonnenten hinzugefügt werden sollen. projectId (Guid?, optional) — Der Projektkontext.

---

Einen Benachrichtigungsabonnenten entfernen

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

Parameter	Typ	Erforderlich	Beschreibung
key	Guid	✅	Die TaskItemId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: contactId (Guid, erforderlich) — Die Kontakt-ID des zu entfernenden Abonnenten.

---

TaskStatus

Die TaskStatus-Entität definiert den Kanban-Aufgabenstatus eines Projektes. Jeder Status kann eine Farbe und eine Sortierposition haben.

info

TaskStatus-Einträge sind projektspezifisch. Jedes Projekt kann eine eigene Menge von Aufgabenstatus definieren.

Datenmodell

Eigenschaft	Typ	Beschreibung
TaskItemStatusId	guid	Eindeutige ID des Aufgabenstatus.
Name	string	Name des Status.
ProjectId	guid	ID des zugehörigen Projekts.
OrdinalPosition	int	Sortierposition.
Color	int?	Farbwert (als Ganzzahl).

Endpunkte

Alle Aufgabenstatus abrufen

GET/odata/TaskStatus

So filtern Sie nach den Status eines Projektes in der Reihenfolge des Kanban-Boards:

GET /odata/TaskStatus?$filter=ProjectId eq xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&$orderby=OrdinalPosition

---

Einen Aufgabenstatus nach ID abrufen

GET/odata/TaskStatus({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die TaskItemStatusId.

---

Einen neuen Aufgabenstatus erstellen

POST/odata/TaskStatus

Parameter	Typ	Erforderlich	Beschreibung
Body	Delta<ApiTaskStatus>	✅	JSON-Objekt mit den Eigenschaften aus dem Datenmodell.

---

Einen Aufgabenstatus aktualisieren

PATCH/odata/TaskStatus({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die TaskItemStatusId.
Body	Delta<ApiTaskStatus>	✅	JSON-Objekt mit den zu aktualisierenden Feldern.

---

Einen Aufgabenstatus löschen

DELETE/odata/TaskStatus({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die TaskItemStatusId.

warnung

Das Löschen eines Aufgabenstatus betrifft alle Aufgaben im Projekt, die ihn verwenden. Diese Aktion kann nicht rückgängig gemacht werden.

Gibt 204 No Content bei Erfolg zurück.

---

TaskItemTemplate

Die TaskItemTemplate-Entität ermöglicht das Speichern und Laden von Aufgabenvorlagen. Vorlagen können Aufgabenstrukturen aus bestehenden Projekten erfassen und in andere Projekte laden.

Datenmodell

Eigenschaft	Typ	Beschreibung
TaskItemTemplateId	guid	Eindeutige ID der Vorlage.
Name	string	Name der Vorlage.

Endpunkte

CRUD-Operationen

Alle Aufgabenvorlagen abrufen

GET/odata/TaskItemTemplate

---

Eine Aufgabenvorlage nach ID abrufen

GET/odata/TaskItemTemplate({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die TaskItemTemplateId.

---

Eine neue Aufgabenvorlage erstellen

POST/odata/TaskItemTemplate

Parameter	Typ	Erforderlich	Beschreibung
Body	Delta<ApiTaskItemTemplate>	✅	JSON-Objekt mit den Eigenschaften aus dem Datenmodell.

---

Eine Aufgabenvorlage aktualisieren

PATCH/odata/TaskItemTemplate({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die TaskItemTemplateId.
Body	Delta<ApiTaskItemTemplate>	✅	JSON-Objekt mit den zu aktualisierenden Feldern.

---

Eine Aufgabenvorlage löschen

DELETE/odata/TaskItemTemplate({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die TaskItemTemplateId.

warnung

Das Löschen einer Aufgabenvorlage kann nicht rückgängig gemacht werden.

Gibt 204 No Content bei Erfolg zurück.

Eine Vorlage aus den Aufgaben eines Projekts speichern

POST/odata/TaskItemTemplate/SaveTemplateForProject

Parameter	Typ	Erforderlich	Beschreibung
Body	object	✅	JSON-Objekt mit folgenden Feldern: ProjectId (guid, erforderlich) — Das Projekt, dessen Aufgabenstruktur gespeichert werden soll. Name (string, erforderlich) — Name der neuen Vorlage.

Speichert die Aufgaben eines bestehenden Projekts als wiederverwendbare Vorlage.

---

Eine Vorlage in ein Projekt laden

POST/odata/TaskItemTemplate({key})/LoadTemplateForProject

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die TaskItemTemplateId.
Body	object	✅	JSON-Objekt mit folgenden Feldern: ProjectId (guid, erforderlich) — Das Zielprojekt.

Erstellt Aufgaben im angegebenen Projekt basierend auf der Vorlage.

Voraussetzung

Das Laden einer Vorlage setzt voraus, dass die Ordnerstruktur des Zielprojekts initialisiert ist. Kann der Dokumentenspeicher nicht automatisch angelegt werden, schlägt die Anfrage fehl — initialisieren Sie die Ordnerstruktur im Bereich Dokumente des Projekts und wiederholen Sie den Aufruf.

tipp

Beim Laden einer Vorlage werden die Aufgaben in das Zielprojekt übertragen.

---

Eine Vorlage herunterladen

GET/odata/TaskItemTemplate({key})/DownloadTemplate()

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die TaskItemTemplateId.

Gibt eine Datei mit dem Inhaltstyp application/xml und dem Dateinamen {Vorlagenname}.json zurück.

---

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). Eigene Felder folgen dem Muster CF_<Feldname>.

Abgeflachte Aufgabenliste mit Projekt-, Planungs- und Berechtigungsdaten abrufen

GET/odata/DynamicTaskItem

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
}

Mehrere Aufgaben gleichzeitig erstellen

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

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

tipp

Kombinieren Sie $filter mit $select, um die Nutzlastgröße zu minimieren. Bei Aufgaben ist das Filtern nach ProjectId und IsDone das gängigste Muster.