Benutzerdefinierte Felder

Benutzerdefinierte Felder ermöglichen es Ihnen, die InLoox-Datenmodelle um eigene Attribute zu erweitern. Über die API können Sie Felddefinitionen verwalten, Werte lesen und aktualisieren sowie Zugriffsberechtigungen steuern.

Dynamic-Endpunkte

Um benutzerdefinierte Felder zusammen mit den Standardeigenschaften einer Entität abzurufen, verwenden Sie die Dynamic*-Endpunkte (z. B. DynamicProject, DynamicTaskItem, DynamicContact). Diese geben alle konfigurierten benutzerdefinierten Felder als zusätzliche Spalten zurück.

Für den Zugriff auf benutzerdefinierte Felder verwenden Sie die Dynamic-Varianten der Entitäten:

Standard-Entität	Dynamic-Variante	Beschreibung
Project	DynamicProject	Projekte mit benutzerdefinierten Feldern
Task	DynamicTaskItem	Aufgaben mit benutzerdefinierten Feldern
TimeEntry	DynamicTimeEntry	Zeiteinträge mit benutzerdefinierten Feldern
Budget	DynamicBudget	Budgets mit benutzerdefinierten Feldern
LineItem	DynamicLineItem	Positionen mit benutzerdefinierten Feldern
n/a	DynamicContact	Kontakte mit benutzerdefinierten Feldern

---

CustomField

Die CustomField-Entität erlaubt den direkten Zugriff auf einzelne benutzerdefinierte Feldwerte. Jeder Wert wird durch den Feldnamen (Name) und die Objekt-ID (ObjectId) identifiziert.

Zusammengesetzter Schlüssel

CustomField verwendet einen zusammengesetzten Schlüssel aus Name und ObjectId. Für den Zugriff auf einzelne Werte werden zwei URL-Notationen unterstützt: Klammer-Notation und Schrägstrich-Notation. Beide verhalten sich identisch.

Datenmodell

Eigenschaft	Typ	Beschreibung
ObjectId	guid	ID des Objekts, dem das Feld zugeordnet ist (z. B. ProjectId, TaskItemId).
Name	string	Interner Spaltenname des benutzerdefinierten Felds, z. B. "cf_f52d9d79_Standort". Siehe in InLoox unter Account-Einstellungen > Eigene Felder.
Value	string	Der Wert des benutzerdefinierten Felds.
Type	string	Der Datentyp des Felds: String, DateTime, Integer, Decimal, Boolean, List, Currency.

Endpunkte

Wert abrufen (Klammer-Notation)

Einen benutzerdefinierten Feldwert abrufen

GET/odata/CustomField(Name={keyName},ObjectId={keyObjectId})

Parameter	Typ	Erforderlich	Beschreibung
keyName	string	✅	Der interne Spaltenname des Felds.
keyObjectId	guid	✅	Die ID des zugehörigen Objekts.

---

Wert aktualisieren (Klammer-Notation)

Einen benutzerdefinierten Feldwert aktualisieren

PATCH/odata/CustomField(Name={keyName},ObjectId={keyObjectId})

Parameter	Typ	Erforderlich	Beschreibung
keyName	string	✅	Der interne Spaltenname des Felds.
keyObjectId	guid	✅	Die ID des zugehörigen Objekts.
Body	object	✅	JSON-Objekt mit den folgenden Feldern: Value (string, erforderlich) — Der neue Wert des benutzerdefinierten Felds.

---

Wert abrufen (Schrägstrich-Notation)

Einen benutzerdefinierten Feldwert mit Schrägstrich-Notation abrufen

GET/odata/CustomField/Name={keyName},ObjectId={keyObjectId}

Parameter	Typ	Erforderlich	Beschreibung
keyName	string	✅	Der interne Spaltenname des Felds.
keyObjectId	guid	✅	Die ID des zugehörigen Objekts.

---

Wert aktualisieren (Schrägstrich-Notation)

Einen benutzerdefinierten Feldwert mit Schrägstrich-Notation aktualisieren

PATCH/odata/CustomField/Name={keyName},ObjectId={keyObjectId}

Parameter	Typ	Erforderlich	Beschreibung
keyName	string	✅	Der interne Spaltenname des Felds.
keyObjectId	guid	✅	Die ID des zugehörigen Objekts.
Body	object	✅	JSON-Objekt mit den folgenden Feldern: Value (string, erforderlich) — Der neue Wert des benutzerdefinierten Felds.

---

Stapelaktualisierung

Mehrere benutzerdefinierte Feldwerte gleichzeitig aktualisieren

POSTodata/CustomField/BatchUpdate

Parameter	Typ	Erforderlich	Beschreibung
Body	array	✅	JSON-Array von Objekten mit den folgenden Feldern pro Eintrag: ObjectId (guid, erforderlich) — Die ID der Entität (z. B. Projekt- oder Aufgaben-ID). Name (string, erforderlich) — Der interne Spaltenname des benutzerdefinierten Felds. Value (string?, optional) — Der zu setzende Wert. Übergeben Sie null, um das Feld zu leeren.

Ermöglicht das gleichzeitige Aktualisieren mehrerer benutzerdefinierter Felder in einem einzigen Aufruf.

Stapelaktualisierung

Verwenden Sie BatchUpdate, wenn Sie mehrere benutzerdefinierte Felder für ein Objekt gleichzeitig setzen möchten. Dies ist effizienter als mehrere einzelne PATCH-Aufrufe.

---

CustomFieldDefinition

Die CustomFieldDefinition-Entität beschreibt die Metadaten eines benutzerdefinierten Felds, einschließlich Datentyp, Anzeigename und Validierungsregeln.

Datenmodell

Eigenschaft	Typ	Beschreibung
CustomFieldDefinitionId	guid	Eindeutige ID der Felddefinition.
ColumnName	string	Interner Spaltenname (eindeutiger Bezeichner).
DisplayName	string	Anzeigename des Felds in der Benutzeroberfläche.
TableName	string	Tabelle, der das Feld zugeordnet ist. Werte: TimeEntry (0), LineItem (1), Budget (2), Document (3), MindMapNode (4), MindMap (5), Planning (6), TaskItem (7), Project (8), CheckList (9), FiscalPeriodFunding (10), Risk (11), Contact (12), PresetLineItem (101), Preset (102).
OrdinalPosition	int?	Sortierposition des Felds.
StringValue	string	Standardwert (Zeichenkette).
IntValue	int?	Standardwert (Ganzzahl).
BoolValue	bool	Standardwert (Wahrheitswert).
WriteProtectionEnabled	bool	Ob Schreibschutz aktiviert ist.
DecimalValue	decimal?	Standardwert (Dezimalzahl).
DateTimeValue	DateTimeOffset?	Standardwert (Datum/Uhrzeit).
ColumnType	int	Datentyp der Spalte. Werte: 0 = String (Text), 1 = DateTime (Datum und Uhrzeit), 2 = Integer (Ganzzahl), 3 = Decimal (Kommazahl), 4 = Boolean (Ja-Nein)-Wert, 5 = Liste, 6 = Currency (Währung).
DisplayRuleField	string	Feldname für bedingte Anzeige.
DisplayRuleExpression	string	Ausdruck für bedingte Anzeige.
CurrencySymbol	string	Währungssymbol (bei Währungsfeldern).
WarningIfEmpty	bool	Warnung anzeigen, wenn das Feld leer ist.
AllowAddNewItem	bool	Ob Benutzer neue Werte zur Auswahlliste hinzufügen dürfen.
DefaultCustomFieldDefinitionListId	guid?	ID der Standard-Auswahlliste.
DefaultCustomFieldDefinitionListValue	string	Standardwert aus der Auswahlliste.
CustomFieldSectionId	guid	ID des Abschnitts, dem dieses Feld zugeordnet ist. Siehe CustomFieldSection.

Endpunkte

Alle Felddefinitionen des gesamten Accounts abrufen

GET/odata/CustomFieldDefinition

Unterstützt OData-Abfrageoptionen.

---

Eine Felddefinition nach ID abrufen

GET/odata/CustomFieldDefinition({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die CustomFieldDefinitionId.

---

Eine neue Felddefinition erstellen

POST/odata/CustomFieldDefinition

Parameter	Typ	Erforderlich	Beschreibung
Body	Delta<ApiCustomFieldDefinition>	✅	JSON-Objekt mit den Objekteigenschaften.

info

Der ColumnName muss eindeutig pro Tabelle sein. Verwenden Sie ein Präfix wie cf_, um benutzerdefinierte Felder leicht von Systemfeldern zu unterscheiden.

---

Eine Felddefinition aktualisieren

PATCH/odata/CustomFieldDefinition({key})

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

---

Eine Felddefinition löschen

DELETE/odata/CustomFieldDefinition({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die CustomFieldDefinitionId.

Warnung

Das Löschen einer Felddefinition entfernt auch alle zugehörigen Werte bei allen Objekten. Diese Aktion kann nicht rückgängig gemacht werden.

Gibt 204 No Content bei Erfolg zurück.

---

CustomFieldPermission

Die CustomFieldPermission-Entität steuert den Zugriff auf benutzerdefinierte Felder. Sie können festlegen, welche Benutzer oder Rollen welche Felder bearbeiten dürfen.

Datenmodell

Eigenschaft	Typ	Beschreibung
CustomFieldPermissionId	guid	Eindeutige ID der Berechtigung.
CustomFieldDefinitionId	guid	ID der zugehörigen Felddefinition.
SubjectType	int	Art der Berechtigung. Werte: 1 = Benutzer, 2 = Rolle.
SubjectId	guid	ID des Subjekts (Benutzer-ID oder Rollen-ID).
RoleType	int?	Rolle (optional, für rollenbasierte Berechtigungen). Werte: 2 = Projektleitung, 4 = Team, 8 = Partner, 16 = Kunde, 32 = Weitere, 64 = Projektantragsprüfer, 128 = Weitere 1, 256 = Weitere 2, 512 = Weitere 3, 1024 = Weitere 4, 2048 = Weitere 5.

Endpunkte

Alle Feldberechtigungen aller Felder abrufen

GET/odata/CustomFieldPermission

Unterstützt OData-Abfrageoptionen.

---

Eine Feldberechtigung nach ID abrufen

GET/odata/CustomFieldPermission({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die CustomFieldPermissionId.

---

Eine neue Feldberechtigung erstellen

POST/odata/CustomFieldPermission

Parameter	Typ	Erforderlich	Beschreibung
Body	Delta<ApiCustomFieldPermission>	✅	JSON-Objekt mit den Berechtigungseigenschaften.

---

Eine Feldberechtigung aktualisieren

PATCH/odata/CustomFieldPermission({key})

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

---

Eine Feldberechtigung löschen

DELETE/odata/CustomFieldPermission({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die CustomFieldPermissionId.

warnung

Das Löschen einer Berechtigung macht das benutzerdefinierte Feld für alle Benutzer beschreibbar, die Schreibzugriff auf die entsprechende Entität haben.

Gibt 204 No Content bei Erfolg zurück.

---

Gesperrte Felder einer Entität für den aktuellen Benutzer abrufen

GET/odata/CustomFieldPermission/GetBlockedFieldsForEntity(entityType={entityType},entityId={entityId})

Parameter	Typ	Erforderlich	Beschreibung
entityType	string	✅	Der Entitätstyp. Werte: TimeEntry (0), LineItem (1), Budget (2), Document (3), MindMapNode (4), MindMap (5), Planning (6), TaskItem (7), Project (8), CheckList (9), FiscalPeriodFunding (10), Risk (11), Contact (12), PresetLineItem (101), Preset (102).
entityId	guid	✅	Die ID der spezifischen Entität.

Gibt eine Liste der benutzerdefinierten Felder zurück, die der aktuelle Benutzer nicht bearbeiten darf.

---

CustomFieldSection

Die CustomFieldSection-Entität ermöglicht es Ihnen, benutzerdefinierte Felddefinitionen in benannte Gruppen innerhalb eines Entitätstyps zu organisieren. Jeder Abschnitt hat einen Anzeigenamen und eine Sortierposition.

Datenmodell

Eigenschaft	Typ	Beschreibung
CustomFieldSectionId	guid	Eindeutige ID des Abschnitts.
TableName	string	Entitätstyp, dem der Abschnitt zugeordnet ist. Werte: TimeEntry (0), LineItem (1), Budget (2), Document (3), MindMapNode (4), MindMap (5), Planning (6), TaskItem (7), Project (8), CheckList (9), FiscalPeriodFunding (10), Risk (11), Contact (12), PresetLineItem (101), Preset (102).
DisplayName	string	Anzeigename des Abschnitts in der Benutzeroberfläche.
OrdinalPosition	int	Sortierposition des Abschnitts innerhalb seines Entitätstyps.

Endpunkte

Alle Abschnitte für benutzerdefinierte Felder abrufen

GET/odata/CustomFieldSection

Unterstützt OData-Abfrageoptionen.

---

Einen Abschnitt nach ID abrufen

GET/odata/CustomFieldSection({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die CustomFieldSectionId.

---

Einen neuen Abschnitt erstellen

POST/odata/CustomFieldSection

Parameter	Typ	Erforderlich	Beschreibung
Body	object	✅	JSON-Objekt mit den folgenden Feldern: TableName (string, erforderlich) — Der Entitätstyp für den Abschnitt. DisplayName (string, erforderlich) — Der Anzeigename des Abschnitts.

---

Einen Abschnitt aktualisieren

PATCH/odata/CustomFieldSection({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die CustomFieldSectionId.
Body	object	✅	JSON-Objekt mit den zu aktualisierenden Feldern: DisplayName (string, optional) — Der neue Anzeigename. OrdinalPosition (int, optional) — Die neue Sortierposition.

---

Einen Abschnitt löschen

DELETE/odata/CustomFieldSection({key})

Parameter	Typ	Erforderlich	Beschreibung
key	guid	✅	Die CustomFieldSectionId.
targetSectionId	guid	✅	Die ID des Abschnitts, in den vorhandene Felder vor dem Löschen verschoben werden sollen.

warnung

Das Löschen eines Abschnitts verschiebt alle seine benutzerdefinierten Felder in den Zielabschnitt. Es muss mindestens ein weiterer Abschnitt für denselben Entitätstyp vorhanden sein.

Gibt 204 No Content bei Erfolg zurück.

---

Dynamische Endpunkte

Dynamische Endpunkte stellen benutzerdefinierte Feldwerte gemeinsam mit den Standardeigenschaften der Entität in einem einzelnen flachen Ergebnissatz bereit. Anstatt CustomField separat abzufragen und über ObjectId zu verknüpfen, können Sie benutzerdefinierte Felddaten direkt auf der Entität lesen und filtern.

Verfügbare dynamische Entitätsmengen

Dynamischer Endpunkt	Basisentität
/odata/DynamicProject	Project
/odata/DynamicTaskItem	TaskItem
/odata/DynamicBudget	Budget
/odata/DynamicLineItem	LineItem
/odata/DynamicTimeEntry	TimeEntry
/odata/DynamicContact	Contact (siehe Kontakte)

Projekte mit enthaltenen benutzerdefinierten Feldspalten abrufen

GET/odata/DynamicProject

Aufgabenelemente mit enthaltenen benutzerdefinierten Feldspalten abrufen

GET/odata/DynamicTaskItem

Budgets mit enthaltenen benutzerdefinierten Feldspalten abrufen

GET/odata/DynamicBudget

Positionen mit enthaltenen benutzerdefinierten Feldspalten abrufen

GET/odata/DynamicLineItem

Zeiteinträge mit enthaltenen benutzerdefinierten Feldspalten abrufen

GET/odata/DynamicTimeEntry

Benennung der benutzerdefinierten Feldspalten

Benutzerdefinierte Feldspalten erscheinen mit dem Präfix CustomField_, gefolgt vom ColumnName der entsprechenden CustomFieldDefinition. Ein Feld mit ColumnName = Priority erscheint beispielsweise als CustomField_Priority in der dynamischen Antwort.

Diese Spalten mit Präfix können in allen Standard-OData-Abfrageoptionen verwendet werden:

Abfrageoption	Beispiel
$select	$select=Name,CustomField_Priority
$filter	$filter=CustomField_Priority eq 'High'
$orderby	$orderby=CustomField_Priority asc

tipp

Dynamische Endpunkte sind schreibgeschützte Ansichten. Um benutzerdefinierte Feldwerte zu aktualisieren, verwenden Sie die oben beschriebenen CustomField-PATCH- oder BatchUpdate-Endpunkte.

---

OData-Abfragebeispiele

Einen benutzerdefinierten Feldwert abrufen

GET /odata/CustomField(Name='cf_Priority',ObjectId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Einen benutzerdefinierten Feldwert aktualisieren

PATCH /odata/CustomField(Name='cf_Priority',ObjectId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
Content-Type: application/json

{
  "Value": "Hoch"
}

Mehrere benutzerdefinierte Feldwerte gleichzeitig aktualisieren

POST /CustomField/BatchUpdate
Content-Type: application/json

[
  { "Name": "cf_Priority", "ObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "Value": "High" },
  { "Name": "cf_Region", "ObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "Value": "EMEA" }
]

Definitionen für eine bestimmte Tabelle abrufen

GET /odata/CustomFieldDefinition?$filter=TableName eq 'Project'&$orderby=OrdinalPosition

Eine Felddefinition erstellen

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

{
  "ColumnName": "cf_Risikostufe",
  "DisplayName": "Risikostufe",
  "TableName": "Project",
  "ColumnType": 0,
  "OrdinalPosition": 5,
  "WarningIfEmpty": false,
  "WriteProtectionEnabled": false
}

Eine Felddefinition aktualisieren

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

{
  "DisplayName": "Risikobewertung",
  "WarningIfEmpty": true
}

Berechtigungen nach Felddefinition filtern

GET /odata/CustomFieldPermission?$filter=CustomFieldDefinitionId eq xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Eine Feldberechtigung erstellen

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

{
  "CustomFieldDefinitionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "SubjectType": 0,
  "SubjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Eine Feldberechtigung aktualisieren

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

{
  "RoleType": 1
}

Gesperrte Felder für eine Entität abrufen

GET /odata/CustomFieldPermission/GetBlockedFieldsForEntity(entityType='Project',entityId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Projekte nach benutzerdefiniertem Feld filtern

GET /odata/DynamicProject?$filter=CustomField_Priority eq 'High'

Projekte mit benutzerdefinierten Feldern auswählen und filtern

GET /odata/DynamicProject?$select=ProjectId,Name,CustomField_Priority,CustomField_Region&$filter=CustomField_Region eq 'EMEA'&$orderby=CustomField_Priority asc

tipp

Kombinieren Sie $filter mit $select, um die Antwortgröße zu minimieren. Verwenden Sie $top und $skip, um große Ergebnismengen zu paginieren.