Zum Hauptinhalt springen

Definitionsmetadaten

Objekte, Fahrzeuge und Aufgaben verwenden eine gemeinsame effektive Definitionsdarstellung. Für denselben Aufrufer und dieselbe Revision liefern Detail-, Listen-, Erstellungs- und Änderungsantworten sowie die gemeinsame Abfrage dieselbe Definition einschließlich ihrer ressourcenspezifischen Felder.

Endpunkte und Sichtbarkeit​

  • GET /api/v2/definitions/all listet sichtbare konkrete Definitionen und unterstützte native Projektionen.
  • GET /api/v2/definitions/all/{definition_ref} akzeptiert eine UUID oder einen Slug des Workspace.
  • Die Bearbeitung erfolgt weiterhin unter /api/v2/definitions/objects, /vehicles und /tasks.

Konkrete Fahrzeug- und Aufgabendefinitionen sind standardmäßig enthalten, auch geschützte integrierte Aufgabendefinitionen. Die internen Familienwurzeln vehicle und system_task sind von beiden Abfrageendpunkten ausgeschlossen. Die Liste akzeptiert das nullbasierte page und size (1–100). Die Sichtbarkeitsprüfung erfolgt vor Zählung und Seitenauswahl; sortiert wird nach Slug und UUID. Verborgene, nicht unterstützte oder unbekannte Definitionen liefern 404.

Sichtbare Metadaten gewähren keinen Datensatzzugriff. Datensatzregeln, Zugriff über Elternobjekte und Feldberechtigungen werden beim Lesen und Schreiben weiterhin geprüft. Die Eignung als Beziehungsziel ist unabhängig von der Sichtbarkeit.

Alle Leseendpunkte für Definitionen (/api/v2/definitions/all, /api/v2/definitions/objects, /api/v2/definitions/vehicles und /api/v2/definitions/tasks) liefern ein schwaches ETag sowie Cache-Control: private, no-cache und unterstützen bedingte Revalidierung über If-None-Match (304 Not Modified).

Gemeinsame Felder​

FeldBedeutung
id, slug, nameStabile Definitions-UUID, im Workspace eindeutiger Selektor und übersetzte Namen im Singular/Plural.
resource_typeErweiterbare Zeichenfolge: object, vehicle, task oder ein registrierter nativer Schlüssel wie tag oder plugin:bw:tour. Ein nativer Schlüssel macht die Ressource nicht zu einem Objekt.
attributesVollständige effektive Feldbeschreibungen einschließlich Systemfeldern und geerbten Feldern der Ressource.
created_at, updated_at, lock_versionZeitstempel und optimistische Revision der Definition; Metadatenabfragen verändern sie nicht.
managed_by, managed_by_plugin, schema_policyEigentümerschaft durch tenant, system oder plugin, optionale Plugin-ID und Bearbeitungsregel editable oder locked.
is_readonlySchreibbarkeit der Datensätze auf Definitionsebene, unabhängig von der Schemaeigentümerschaft.
is_relationship_targetOb diese Definition als Beziehungsziel unterstützt wird.
natural_id_key, display_templateOptionale Identitäts- und Anzeigeeinstellungen, soweit von der Ressource unterstützt und konfiguriert.
icon, color, map_marker_fieldsOptionales Symbol, Palettenfarbe und geordnete Feldauswahl für Kartenmarkierungen; die Auswahl ist immer ein Array.

Aufgabenantworten enthalten zusätzlich execution_type und is_extendable. Fahrzeuge und Objekte benötigen keinen weiteren Familiendiskriminator. Öffentliche Definitionen enthalten kein base_definition_id; definition_id eines Datensatzes bleibt unverändert. Beim Erstellen einer Aufgabendefinition wählt execution_type das Verhalten aus.

Felder erscheinen in der Reihenfolge System → Plugin → Benutzerdefiniert; innerhalb jeder Gruppe bleibt die Definitionsreihenfolge erhalten. is_system_managed schützt das Attributschema, is_readonly steuert davon unabhängig Wertänderungen. Schreibbare native Aufgabenfelder verwenden weiterhin die typisierten Aufgabenfelder auf oberster Ebene. Strukturierte Beschreibungen wie visit und interaction haben den ausschließlich für Antworten vorgesehenen Typ json. Sie sind keine frei anlegbaren JSON-Attribute. Effektive Metadaten dürfen nicht ungeprüft als Schema zurückgeschrieben werden.

Darstellung bearbeiten​

Alle drei Ressourcen-APIs akzeptieren icon, color und map_marker_fields beim Erstellen, vollständigen Ersetzen und Metadaten-PATCH. Eine nicht gesetzte Farbe ergibt einen transparenten Hintergrund. Antworten lassen nicht gesetzte Symbole/Farben weg; eine leere Markerauswahl ist [].

{"icon":"truck","color":null,"map_marker_fields":["name","reference"]}

Dieses Beispiel setzt geeignete Felder name und reference in der effektiven Definition voraus. Die Auswahl darf nur unterstützte Felder ohne Duplikate enthalten. Ungültige Felder oder Werttypen führen zu feldbezogenen 422-Fehlern. Umbenennung und Löschung eines Attributs passen die Auswahl innerhalb derselben Transaktion an.

Bei PATCH erhält ein weggelassenes Feld den bestehenden Wert. Explizites null löscht Symbol/Farbe und setzt die Markerauswahl auf []; ein Array ersetzt die gesamte geordnete Auswahl. POST und PUT setzen weggelassene optionale Symbole/Farben auf ungesetzt und Markerfelder auf []. Eine veraltete mitgesendete lock_version führt zu 409. Verwaltete Definitionen erlauben ihre bestehenden Ausnahmen für Darstellungsänderungen, während das Schema geschützt bleibt. Eine Konfiguration schafft keine zusätzliche Karte, Seitenleiste oder Datensatzberechtigung.