Notes and tags
Overview
Section titled “Overview”Notes, tags, and external links attach to almost every entity in Formation through a single shared mechanism. A scheme can carry notes; so can an address, an investment event, an occupier event, a portfolio, a company. The same goes for tags and for external links. From a user perspective they behave the same wherever they appear — what’s allowed and what’s gated is the same across entity types.
What a note is
Section titled “What a note is”A free-form text entry attached to a record. The record could be a scheme, an investment event, an address, or any other entity that supports notes. There’s no fixed format — notes are typed in the Notes panel at the bottom of an entity’s edit view and saved alongside the record.
Who can manage notes
Section titled “Who can manage notes”Any user with edit access to the parent record can add, edit, or remove notes on it. There’s no separate role for note management.
What survives an edit
Section titled “What survives an edit”Notes are managed as a polymorphic collection: changes to the parent record (a scheme save, say) don’t disturb the existing notes unless you explicitly change them in the same save. The notes panel reads the current notes when the page opens, lets you add / edit / delete in place, and writes back the modified set on save.
Where notes appear
Section titled “Where notes appear”Notes show up:
- In the entity’s detail view (read-only list).
- In the entity’s edit panel (where they’re editable).
- They are not searchable from the global search bar — the
@noteoperator scopes a search to notes, but the notes themselves aren’t indexed for free-text search across entity types.
What a tag is
Section titled “What a tag is”A reusable label that can be attached to any entity. Tags are managed centrally in the Tag Manager (Settings → Tags). Once a tag exists, it can be applied to as many records as needed.
Who can manage tags
Section titled “Who can manage tags”- Adding or removing a tag from a record: any user with edit access to the record.
- Creating, editing, renaming, or deleting tags themselves: Admin only. The Tag Manager UI is rendered read-only for non-Admin users — they can see the list but not change it.
See Permissions and roles for the Admin role.
Tagging behaviour
Section titled “Tagging behaviour”- A record can carry any number of tags.
- A tag can be applied to any number of records.
- Removing a tag from a record doesn’t delete the tag — it remains in the directory for use elsewhere.
- Deleting a tag from the directory (Admin) removes it from every record it was applied to.
Search
Section titled “Search”The global search bar supports #tag syntax: typing #confidential filters list results to records carrying the confidential tag. The tag name in the search is matched case-insensitively. See Search matching for the full operator list.
External links
Section titled “External links”What an external link is
Section titled “What an external link is”A URL with an optional title, recorded on an entity to point at related material elsewhere (a planning portal link, a Companies House page, a marketing brochure). The URL is validated to be a well-formed URL on save; the title is free text.
Who can manage them
Section titled “Who can manage them”Any user with edit access to the parent record can add, edit, or remove external links. There’s no separate role for link management.
What’s preserved on edit
Section titled “What’s preserved on edit”External links are a polymorphic collection just like notes — they’re managed in their own panel and don’t get disturbed by edits elsewhere on the parent record.
How polymorphic collections work behind the scenes
Section titled “How polymorphic collections work behind the scenes”Notes, tags, and external links share a common machinery: each lives in its own table with a polymorphic foreign key that names the parent entity type and ID. The model layer loads them separately from the parent record’s main query (so they don’t blow up the JOIN), and the write controllers manage their state explicitly in each Create / Patch / Replace / Delete handler.
You’ll never see this from the UI — the load and save happen transparently — but it explains why notes and tags survive an unrelated edit cleanly, and why removing a tag from a record doesn’t touch the tag itself.
Related rules
Section titled “Related rules”- Permissions and roles — Admin gating for tag management.
- Search matching — the
#tagand@notesearch operators. - Every entity page references notes/tags in passing; the rules sit here.
Where this lives
Section titled “Where this lives”- Frontend components:
src/services/web/src/lib/components/forms/Notes.svelte,Tags.svelte,Attachments.svelte - Tag manager:
src/services/web/src/lib/components/system/TagManager.svelte - Tags controller (backend):
src/services/api/app/app.api/Controllers/TagsController.cs - Polymorphic collection load helper:
LoadPolymorphicCollectionsAsyncinsrc/services/api/app/app.api/Data/ - Per-entity wiring: each
Create*CommandHandler.cscalls the polymorphic loader after the main save (e.g.CreateSchemeCommandHandler.cs,CreateInvestmentEventCommandHandler.cs)