Record Links

Record Links Overview

A record link joins two records — in any two datastores — and records what kind of relationship it is, who made it and when.

Where to find it

Architect Panel → Data:

• Record Links — every link in the system, with its type and author
• Datastores — where a fixed one-to-many relationship belongs instead

What a link holds

• From — a datastore and a record.
• To — a datastore and a record.
• Link type — what the relationship means.
• Created by and created at.

Because both ends name their own datastore, one mechanism covers every combination. A case can link to an asset, an asset to a document, a document to another document, without any of those datastores knowing about the others.

Why not just add a field

Add a field when the relationship is part of what the record is: an invoice line belongs to an invoice, and that is structural.

Use a link when the relationship is something that happened: this order was converted from that quotation, this case is a duplicate of that one, this asset was involved in that incident. Those are facts about events, they are not known when the datastore is designed, and modelling them as fields would mean a column for every relationship anybody might ever record.

Links carry provenance

The author and timestamp are the reason a link is more than a pointer. "These two cases are related" is an assertion; "J. Okafor linked these on 14 March as duplicates" is a record of a decision, and it is what lets somebody later judge whether the link is still right.

Link types

The type is what makes a link readable. converted, duplicate-of, supersedes, relates-to each mean something specific, and each supports a different question.

Keep the vocabulary small and agreed. A dozen near-synonymous types produce links nobody can query usefully, because half the "related" links are recorded as "relates-to" and half as "associated".

Document conversion uses links

When a quotation is converted into an order, a converted link is written between them. That is what lets you trace an order back to what it came from — and it is worth knowing that this is the same general mechanism, not a special case buried in the conversion code.

Direction means something

From and to are not interchangeable. "This order was converted from that quote" and "this quote was converted into that order" describe the same link read in opposite directions, and a type like supersedes is meaningless without knowing which end supersedes which. Decide the convention when you define the type.

Worked example

A housing team links a repair case to the property asset, to the two previous repair cases at the same address, and to the contractor's quotation. None of those relationships existed when the case datastore was designed, and none required a schema change to record.

Recommendations

• Fields for structure, links for events.
• Agree a small vocabulary of link types and write it down.
• Fix the direction convention per type.
• Do not duplicate a link as a field as well — two sources of the same truth will diverge.

Working with Record Links

Links are created as people work — from a record, from a conversion, or in bulk during a migration.

Where to find it

Architect Panel → Data:

• Record Links — browse, filter and audit every link
• Merges — where duplicate records are combined
• Trash — deleted records, whose links remain

Creating them

Most links are created in context: somebody looking at a record connects it to another. Some are created automatically — a document conversion writes one without being asked.

Bulk creation during a migration is legitimate, but pick the link type carefully: a migration that writes ten thousand links of type relates-to has recorded that things are connected without recording how, and nobody will go back and refine it.

Finding what is linked

Because links are stored centrally, they can be queried in either direction — what does this record point at, and what points at it. The second question is the one people forget to ask, and it is usually the more interesting: not "what did this case reference" but "what has been raised against this asset".

Removing a link

Remove a link when the relationship was recorded in error. Do not remove one because the relationship ended — a quotation that was converted was still converted, even if the order was later cancelled.

The distinction matters because links are provenance. Deleting historical connections to make a current view look tidy destroys the trail that explains how the current state arose.

Deleted records

Deletion is soft, so a link to a deleted record is not broken — it points at something recoverable. Expect to see links to records that no longer appear in normal browsing, and treat that as correct rather than as orphaned data.

Merges

When duplicate records are merged, review the links. Two records merged into one may leave two links to the same target where one is now sufficient, or a duplicate-of link that has served its purpose. This is worth a pass after any significant deduplication exercise.

Audit them occasionally

Links accumulate quietly. A periodic look at the link types actually in use will usually find one created for a single project three years ago, and one that people are using for something other than its original meaning. The first can go; the second needs a conversation before it spreads.

Worked example

A quotation is converted to an order, writing a converted link. The order is later cancelled and a replacement raised, linked supersedes to the cancelled one. Asked why the customer has two order references, the sales manager reads the chain — quote, order, cancellation, replacement — without opening a single email thread.

Recommendations

• Query links in both directions; the inbound view is usually the useful one.
• Remove links only when they were wrong, never because they are historical.
• Review links after a merge.
• Audit the type vocabulary annually.