Verknüpfungen und Standorte
Verknüpfungsattribute verbinden einen Datensatz mit einer anderen verwalteten Tourfold-Ressource. Standorte speichern einen typisierten Ort oder folgen der Position eines anderen Datensatzes. Ihre Schreibformen sind ausdrücklich definiert, weil sie an Validierung, Zugriffskontrolle, Traversierung, Bereinigung und Webhook-Verhalten beteiligt sind.
Typmatrix
| Typ | Schreibzugriff akzeptiert | Lesezugriff liefert | GraphQL-Ausgabe |
|---|---|---|---|
tags | Array aus IDs, Labels oder Tag-Referenzobjekten | Aufgelöste Objekte {id, label, color} | Liste von Tag-Objekten |
required_skills | Array aus IDs, Labels oder Skill-Referenzobjekten | Aufgelöste Objekte {id, label} | Liste von Skill-Objekten |
provided_skills | Array aus IDs, Labels oder Skill-Referenzobjekten | Aufgelöste Objekte {id, label} | Liste von Skill-Objekten |
relationship | Einzelne Ziel-UUID/Referenz für To-one; Arrays für To-many | Einzelne kompakte Referenz oder null für To-one; {items, page} für To-many | Zielobjekt oder Connection |
location | Adresse, Koordinaten, Tracking-Referenz oder Kombination | Typisierter gespeicherter und aufgelöster Standort | RecordLocation |
Diese Typen akzeptieren weder config.default noch config.is_unique. is_required: true bedeutet bei
Tags, Fähigkeiten und Beziehungen, dass die Menge mindestens eine Verknüpfung enthalten muss.
Tags
Verwenden Sie tags für im Workspace verwaltete Labels, die über unterschiedliche Datensatztypen
hinweg geteilt werden können.
{
"slug": "tags",
"type": "tags",
"name": {"en": "Tags", "de": "Tags"}
}
Alle folgenden Elemente sind gültige Schreibwerte:
{
"data": {
"tags": [
"00000000-0000-4000-8000-000000000801",
"urgent",
{"id": "00000000-0000-4000-8000-000000000802"},
{"label": "safety-relevant"}
]
}
}
Ein String in UUID-Form wird immer als ID behandelt. Enthält ein Referenzobjekt sowohl id als auch
label, gewinnt die ID. Lesezugriffe lösen die Verknüpfungen zu Objekten mit id, label und color
auf; diese Form kann unverändert zurückgeschrieben werden.
Die Tags selbst werden über die Tags API verwaltet. Das Löschen eines Datensatzes entfernt seine Verknüpfungen, aber nicht das gemeinsam verwendete Tag.
Erforderliche und bereitgestellte Fähigkeiten
Verwenden Sie required_skills für Fähigkeiten, die zur Arbeit mit einem Datensatz nötig sind, und
provided_skills für Fähigkeiten, die der Datensatz bereitstellt. Beide verweisen auf den
Fähigkeitenkatalog des Workspaces.
{
"slug": "required_skills",
"type": "required_skills",
"name": {"en": "Required skills", "de": "Erforderliche Fähigkeiten"},
"config": {"is_required": true}
}
Schreibzugriffe akzeptieren Skill-UUIDs, Labels, {"id":"..."} oder {"label":"..."}.
Lesezugriffe liefern aufgelöste Objekte {"id","label"}. Verwenden Sie stattdessen eine Beziehung zu
einem eigenen Objekt, wenn das Ziel eigene Datensatzfelder, einen Lebenszyklus oder objektspezifische
Berechtigungen benötigt.
Beziehungen
Ein relationship verknüpft Datensätze mit genau einem Zielobjekt. Es ist nie polymorph: Ein einzelnes
config.target identifiziert das Ziel über Slug oder UUID.
{
"slug": "equipment",
"type": "relationship",
"name": {"en": "Equipment", "de": "Anlage"},
"config": {
"target": "equipment",
"is_multiselect": false,
"is_required": true,
"reverse": {
"slug": "maintenance_requests",
"name": {
"en": "Maintenance requests",
"de": "Wartungsanfragen"
},
"is_multiselect": true
}
}
}
Für is_multiselect: false schreiben Sie eine einzelne UUID oder Referenz. Für true verwenden Sie ein Array:
{
"data": {
"equipment": {"record_id": "6f3d2a10-0000-4000-8000-000000000117"}
}
}
Die Antwort ergänzt Objekt-Slug und Anzeigewert. Wenn Sie dieses aufgelöste Objekt zurücksenden,
verwendet der Server record_id, validiert es gegen das deklarierte Ziel und behandelt Anzeigedaten als
nicht verbindliche Eingabe.
Eigentum gehört zum Typ
Ist reverse vorhanden, materialisiert Tourfold ein schreibgeschütztes Attribut auf dem Zielobjekt. Das
deklarierende Attribut bleibt alleiniger Eigentümer von Schema und Verknüpfungsänderungen. Daraus folgt:
- Merge Patch auf der Eigentümerseite ersetzt oder leert deren vollständige Verknüpfungsmenge.
- Das Schreiben der Rückbeziehung liefert
422 relationship-reverse-managed. - Ein deklaratives
PUTauf dem Ziel löscht eine ausgelassene verwaltete Rückbeziehung nicht. - Umbenennung, Kardinalitätsänderung und Löschen beginnen am deklarierenden Attribut.
Diese Asymmetrie verhindert, dass eine gewöhnliche Ersetzung des Zielobjekts Verknüpfungen eines anderen Objekts löscht. Beziehungen beschreibt Kardinalität, Lesen der Rückseite, Paginierung verknüpfter Datensätze, Filterung und Löschverhalten vollständig.
Innerhalb einer atomaren Batch-Erstellung kann {"ref":"request-local-key"} auf ein anderes Element
desselben Requests verweisen, bevor einer der Datensätze eine persistente UUID hat.
Workspace-Benutzer
Um Personen zu erfassen, etwa eine verantwortliche Person oder Teammitglieder, verwenden Sie das
System-Objekt user als Ziel:
{"slug": "owner", "type": "relationship", "name": {"en": "Owner", "de": "Verantwortlich"}, "config": {"target": "user"}}
Für ein Team verwenden Sie is_multiselect: true. Bevorzugen Sie dies gegenüber Text- oder E-Mail-Attributen: Namen
bleiben aktuell, deaktivierte und gelöschte Personen sind über status gekennzeichnet, und
{"owner": {"id": {"eq": "me"}}} filtert „meine Datensätze“ für die jeweils anfragende Person. Wer den
Datensatz lesen darf, sieht die Namen auch ohne users:read. reverse ist für Benutzerziele nicht
verfügbar. Siehe Workspace-Benutzer als Ziele.
Standort
Ein Standort kann Adresse, Koordinaten, Beobachtungszeitpunkt oder eine Kombination enthalten:
{
"data": {
"position": {
"street": "Karlsplatz 1",
"city": "Wien",
"postal_code": "1010",
"country_code": "AT",
"lat": 48.2004,
"lon": 16.3696,
"located_at": "2026-08-27T13:45:00Z"
}
}
}
Geocoding erfolgt im Client: Tourfold speichert die akzeptierten Werte und ersetzt weder eine Adresse stillschweigend durch Koordinaten noch umgekehrt.
Einem anderen Datensatz folgen
Ein Standort kann einem Standortattribut eines anderen Datensatzes folgen:
{
"data": {
"position": {
"tracking": {
"record_id": "6f3d2a10-0000-4000-8000-000000000201",
"object": "device",
"attribute": "gps"
}
}
}
}
Lesezugriffe können neben tracking die aktuell aufgelöste Adresse und Koordinaten enthalten. Wird in
einem Merge Patch nur das Tracking entfernt, friert Tourfold die zuletzt bekannte Position als
gewöhnlichen Standort ein. Das Löschen des vollständigen Standortattributs entfernt ihn.
GraphQL stellt ein RecordLocation-Objekt mit Adress-, Koordinaten-, Zeitstempel- und optionalen
Tracking-Feldern bereit. Standortwerte können ausgewählt, aber nicht direkt gefiltert oder sortiert
werden.
Ersetzung, Zugriff und Löschen
Arrays auf beschreibbaren Verknüpfungsattributen sind vollständige Ersatzmengen: auslassen zum Erhalten,
das gewünschte vollständige Array zum Ersetzen senden und mit [] oder null leeren, soweit optional.
Der Aufrufer benötigt Zugriff auf die betroffenen Objektdatensätze; eine syntaktisch gültige UUID umgeht
weder Mandanten- noch objektspezifische ACLs.
Das Löschen eines verknüpften Datensatzes entfernt Beziehungskanten. Das Löschen eines Datensatzes mit Tags oder Fähigkeiten entfernt seine Verknüpfungen, aber keine gemeinsam verwendeten Katalogeinträge. Das Löschen eines besitzenden Beziehungsattributs entfernt seine verwaltete Rückbeziehung und sämtliche von dieser Beziehung verwalteten Kanten.
Strategien für die Synchronisierung mit diesen Ersatzregeln finden Sie unter Datensätze synchronisieren.