Entity Linking API

Links between tickets, incidents, problems, changes, assets, KB articles and contracts run centrally via /api/linking. Every allowed pair has uniformly structured endpoints to link, unlink and list — with consistent permissions, status rules, audit and real-time updates.

Uniform Endpoint Pattern

For each registered direction of a pair (source → target) there are three endpoints. basePath is the source entity (plural), targetSlug the target entity (singular).

Example: 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

Supported Link Pairs

Per direction the permission is {source}.linkTo{Target}; the list endpoint uses {source}.viewOwn. "↔" = both directions registered, "→" = this direction only.

The body field matches the target entity: problemId, ticketId, changeId, incidentId, assetId, articleId or childTicketId (each a single required ID).

Behaviour & Rules

Sub-Tickets (Ticket ↔ Ticket)

A ticket can carry sub-tickets: one request is split into partial tasks that are worked separately. This is the only pair of two identical types and therefore directed — the ID in the URL is always the PARENT ticket, the ID in the body always the child. There is exactly ONE level: a child cannot have children of its own, and a ticket that is already a child accepts none.

# 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 }
#   ] }

The reverse direction has no list route of its own: the parent ticket appears as parentTicket (id, ticketNumber) on the child itself, together with childTicketCounts on the parent — see the Tickets API.

The structure is internal information: The children list stays empty without tickets.viewInternal — including for the customer of the parent ticket. Child and parent can belong to different people; number and title of the other side therefore do not belong in the customer view. Empty instead of 403: the same shape in which the counters on the ticket are redacted.

Creating with parentTicketId, the lock against resolving a parent with open children, merge behaviour and the list filter are documented in the Tickets API. Tickets API →

Indirect-Link-Check

Checks whether two entities are already connected indirectly (transitive, 2-hop) — e.g. to avoid circular or redundant links before creating a direct one.

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 and targetType accept TICKET, PROBLEM and INCIDENT — exactly the types the service knows pairs for; any other value is 400. The intermediate item passes the same visibility check as a list: whoever may not see it is not told about it here either.

Batch-Resolve

Resolves multiple linked child entities in bulk via their parent entity (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 or PROBLEM (batch-resolve-incidents only knows problem sources and does not take the parameter). An unknown source, or one invisible to the caller, is 404 or 403.
• Only linked rows are resolved: IDs not linked to the source count as skipped — so the response reveals nothing about whether other records exist.
• Parent tickets with open sub-tickets are skipped: They count as skipped and appear in errors with the code HAS_OPEN_CHILDREN — the bulk resolution does not abort because of it, and the UI can name the reason per row.
• Limits: at most 200 rows per call, resolution max 2,000 characters, rootCauseShort max 500, resolutionCode max 50.
• The display number of the source comes from the server — it is not an input parameter; otherwise freely chosen text would end up in the ticket history, the customer notification and the audit trail.

Asset ↔ Contract

Asset-contract links have their own endpoints and rules:

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

• The body is validated: contractId is required, notes optional (max 1,000 characters, null allowed); a wrong type is 400.
• An existing link answers 409 ASSET_CONTRACT_LINK_EXISTS (the other pairs report ALREADY_LINKED).
• This path never sets a primary contract: isPrimary stays false. The flag lives on the contract side — POST /api/contracts/:id/assets creates the assignment with the flag, PATCH /api/contracts/:id/assets/:assetId toggles it.

Impact Tree

The impact tree shows the full downstream impact of a record (direct tickets + linked incidents with their tickets = 2-hop, incl. SLA and access info). Available via the respective endpoints, e.g. GET /api/problems/:id/impact-tree and GET /api/incidents/:id/impact-tree — the basis for the close dialogs (cascading resolution).

The impact tree is tiered as well: a linked incident the caller may not see appears as a node with accessible: false — number, status and priority remain (otherwise the counter would be wrong), while title, assignment and the business fields are missing, and the resolution skips it. Whether such a node would be auto-resolvable is not stated on the row — summary.resolvableIncidentCount carries that quantity, and it counts across all linked incidents.