Entity-Linking API

Verknüpfungen zwischen Tickets, Incidents, Problems, Changes, Assets, KB-Artikeln und Verträgen laufen zentral über /api/linking. Für jedes erlaubte Paar gibt es gleich aufgebaute Endpunkte zum Verknüpfen, Lösen und Auflisten — mit einheitlichen Berechtigungen, Statusregeln, Audit und Echtzeit-Updates.

Einheitliches Endpoint-Muster

Für jede registrierte Richtung eines Paares (quelle → ziel) gibt es drei Endpunkte. basePath ist die Quell-Entität (Plural), targetSlug die Ziel-Entität (Singular).

Beispiel: Ticket ↔ Problem

# Link (permission tickets.linkToProblems)
POST /api/linking/tickets/:id/link-problem
{ "problemId": "clx-problem-id" }          # → 204 No Content

# Remove
DELETE /api/linking/tickets/:id/link-problem/clx-problem-id   # → 204

# List the linked problems of a ticket (permission tickets.viewOwn)
GET /api/linking/tickets/:id/linked-problems
# → { "data": [
#     // visible: id, problemNumber, title, status, priority, createdAt,
#     //          assignedTo{name}|null  — WITHOUT a restricted flag
#     { "id": "...", "problemNumber": "PRB-0042", "title": "…", "status": "INVESTIGATING",
#       "priority": "HIGH", "createdAt": "…", "assignedTo": { "name": "Jane Smith" } },
#     // hidden: stub with only id, problemNumber, status, createdAt, restricted: true
#     { "id": "...", "problemNumber": "PRB-0043", "status": "NEW", "createdAt": "…", "restricted": true }
#   ] }

# Reverse direction (permission problems.linkToTickets / problems.viewOwn)
POST /api/linking/problems/:id/link-ticket   { "ticketId": "clx-ticket-id" }
GET  /api/linking/problems/:id/linked-tickets

Unterstützte Verknüpfungs-Paare

Pro Richtung gilt die Permission {quelle}.linkTo{Ziel}; der List-Endpunkt nutzt {quelle}.viewOwn. „↔" = beide Richtungen registriert, „→" = nur diese Richtung.

Body-Feld richtet sich nach der Ziel-Entität: problemId, ticketId, changeId, incidentId, assetId, articleId oder childTicketId (jeweils eine ID-Pflichtangabe).

Verhalten & Regeln

Sub-Tickets (Ticket ↔ Ticket)

Ein Ticket kann Sub-Tickets tragen: ein Anliegen wird in Teilaufgaben zerlegt, die getrennt bearbeitet werden. Die Beziehung ist das einzige Paar aus zwei gleichen Typen und deshalb gerichtet — die ID in der URL ist immer das ELTERNTICKET, die ID im Body immer das Kind. Es gibt genau EINE Ebene: ein Kind kann keine eigenen Kinder haben, und ein Ticket, das bereits Kind ist, nimmt keine auf.

# Subordinate an existing ticket (permission tickets.linkToTickets)
POST /api/linking/tickets/:parentId/link-child-ticket
{ "childTicketId": "clx-child-ticket-id" }                     # → 204 No Content

# Release the relationship
DELETE /api/linking/tickets/:parentId/link-child-ticket/clx-child-ticket-id   # → 204

# Sub-tickets of a parent ticket (tickets.viewOwn/viewAll + tickets.viewInternal)
GET /api/linking/tickets/:parentId/linked-child-tickets
# → { "data": [
#     { "id": "...", "ticketNumber": "TKT-2026-000043", "title": "…", "status": "IN_PROGRESS",
#       "priority": "HIGH", "source": "EMAIL", "createdAt": "…", "customer": { "name": "Max Mustermann" } },
#     { "id": "...", "ticketNumber": "TKT-2026-000044", "status": "OPEN", "createdAt": "…", "restricted": true }
#   ] }

Die Gegenrichtung hat keine eigene Listen-Route: das Elternticket steht als parentTicket (id, ticketNumber) am Kind selbst, zusammen mit childTicketCounts am Elternticket — siehe Tickets API.

Die Struktur ist eine interne Angabe: Die Kinder-Liste bleibt ohne tickets.viewInternal leer — auch für den Kunden des Elterntickets. Kind und Elternticket können verschiedenen Personen gehören; Nummer und Titel der Gegenseite gehören deshalb nicht in die Kundensicht. Leer statt 403: dieselbe Form, in der auch die Zähler am Ticket redigiert werden.

Anlegen mit parentTicketId, die Sperre gegen das Lösen eines Elterntickets mit offenen Kindern, das Verhalten beim Zusammenführen und der Listen-Filter stehen in der Tickets API. Tickets API →

Indirect-Link-Check

Prüft, ob zwischen zwei Entitäten bereits eine indirekte (transitive, 2-Hop) Verbindung besteht — z.B. um zirkuläre oder redundante Verlinkungen zu vermeiden, bevor ein direkter Link gesetzt wird.

GET /api/linking/check-indirect?sourceType=TICKET&sourceId=clx-a&targetType=PROBLEM&targetId=clx-b
# → { "data": [ { "viaType": "INCIDENT", "viaId": "clx-i", "viaNumber": "INC-2026-000042", "viaTitle": "…" } ] }

sourceType und targetType nehmen TICKET, PROBLEM und INCIDENT — genau die Typen, für die der Dienst Paare kennt; jeder andere Wert ist 400. Der Zwischen-Vorgang läuft durch dieselbe Sicht-Prüfung wie eine Liste: wer ihn nicht sehen darf, bekommt ihn auch hier nicht genannt.

Batch-Resolve

Löst mehrere verlinkte Kind-Entitäten gesammelt über ihre Eltern-Entität (Cascading Resolution Center).

# Resolve linked tickets via an incident/problem (permission tickets.editStatus)
POST /api/linking/batch-resolve?sourceType=INCIDENT&sourceId=clx
{ "ticketIds": ["clx-t1", "clx-t2"], "resolution": "Fixed via incident", "resolutionCode": "RESOLVED_BY_INCIDENT" }

# Resolve linked incidents via a problem (permission incidents.changeStatus)
POST /api/linking/batch-resolve-incidents?sourceId=clx
{ "incidentIds": ["clx-i1"], "resolution": "...", "resolutionCode": "...", "rootCauseShort": "Missing index" }

• sourceType — INCIDENT oder PROBLEM (batch-resolve-incidents kennt nur Problem-Quellen und nimmt den Parameter nicht). Eine unbekannte oder für den Aufrufer unsichtbare Quelle ist 404 bzw. 403.
• Nur Verlinktes wird aufgelöst: IDs, die nicht mit der Quelle verknüpft sind, zählen als skipped — so lässt die Antwort keine Rückschlüsse zu, ob fremde Vorgänge existieren.
• Elterntickets mit offenen Sub-Tickets werden übersprungen: Sie zählen als skipped und erscheinen in errors mit dem Code HAS_OPEN_CHILDREN — die Sammel-Auflösung bricht deswegen nicht ab, und die Oberfläche kann den Grund je Zeile benennen.
• Grenzen: höchstens 200 Zeilen je Aufruf, resolution max. 2 000 Zeichen, rootCauseShort max. 500, resolutionCode max. 50.
• Die Anzeige-Nummer der Quelle kommt vom Server — sie ist kein Eingabe-Parameter; sonst stünde ein frei gewählter Text in Ticket-Verlauf, Kunden-Benachrichtigung und Audit.

Asset ↔ Contract

Asset-Vertrags-Verknüpfungen haben eigene Endpunkte und Regeln:

// POST /api/linking/assets/:id/link-contract
{ "contractId": "clx-contract-id", "notes": "Maintenance contract" }   // → 204

• Der Body wird geprüft: contractId ist Pflicht, notes optional (max. 1 000 Zeichen, null erlaubt); ein falscher Typ ist 400.
• Eine bereits bestehende Verknüpfung antwortet 409 ASSET_CONTRACT_LINK_EXISTS (die übrigen Paare melden ALREADY_LINKED).
• Dieser Weg setzt KEINEN Hauptvertrag: isPrimary bleibt false. Das Kennzeichen lebt auf der Vertrags-Seite — POST /api/contracts/:id/assets legt die Zuordnung mit Flag an, PATCH /api/contracts/:id/assets/:assetId schaltet es um.

Impact Tree

Der Impact Tree zeigt die vollständige Auswirkung eines Vorgangs (direkte Tickets + verlinkte Incidents mit deren Tickets = 2-Hop, inkl. SLA- und Zugriffs-Info). Abrufbar über die jeweiligen Endpunkte, z.B. GET /api/problems/:id/impact-tree und GET /api/incidents/:id/impact-tree — Basis für die Close-Dialoge (Cascading Resolution).

Auch der Impact Tree ist gestaffelt: ein verknüpfter Incident, den der Aufrufer nicht sehen darf, erscheint als Knoten mit accessible: false — Nummer, Status und Priorität bleiben (sonst stimmte der Zähler nicht), Titel, Zuweisung und die fachlichen Angaben fehlen, und die Auflösung überspringt ihn. Ob ein solcher Knoten automatisch auflösbar wäre, steht nicht an der Zeile — die Mengen-Aussage trägt summary.resolvableIncidentCount, und die zählt über alle verknüpften Incidents.