Zum Hauptinhalt springen

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​

TypSchreibzugriff akzeptiertLesezugriff liefertGraphQL-Ausgabe
tagsArray aus IDs, Labels oder Tag-ReferenzobjektenAufgelöste Objekte {id, label, color}Liste von Tag-Objekten
required_skillsArray aus IDs, Labels oder Skill-ReferenzobjektenAufgelöste Objekte {id, label}Liste von Skill-Objekten
provided_skillsArray aus IDs, Labels oder Skill-ReferenzobjektenAufgelöste Objekte {id, label}Liste von Skill-Objekten
relationshipEinzelne Ziel-UUID/Referenz für To-one; Arrays für To-manyEinzelne kompakte Referenz oder null für To-one; {items, page} für To-manyZielobjekt oder Connection
locationAdresse, Koordinaten, Tracking-Referenz oder KombinationTypisierter gespeicherter und aufgelöster StandortRecordLocation

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 PUT auf 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.