Skip to main content
Tools

Extension Navigation Reference

A link in an extension reply names a destination, not a URL. CALM Hub maps the destination to its own routes, so a link keeps working when the routes change. Blocks, search results and chat citations use the same destination. For the blocks that hold links, see the extension blocks reference.

Destinations​

A destination has exactly one of these fields. A block link also has a label.

FieldOpensExample
hrefAn external page, in a new tab. Only http:// and https://{ "href": "https://example.org/runbook" }
hubA version of a Hub resource{ "hub": { "namespace": "demo", "type": "architectures", "id": "1", "version": "1.0.0", "element": "web-app" } }
screenA top-level extension screen{ "screen": { "extension": "release-tracker", "screen": "releases", "params": { "releases.filter": "released" } } }

The JSON Schema is $defs/destination (no label) and $defs/link (with a label) in GET /api/calm/extensions/schema/0/blocks.schema.json. The UI shows a link that is not valid as plain text.

hub​

FieldRequiredRule
namespace, type, id, versionYesThe exact resource and version. Not empty, . or ..
elementNoThe unique-id of a node or relationship. Hub selects it and opens its details. In a pattern, it is a node or relationship that the pattern declares, also as one choice of a oneOf or anyOf
extensionNoAn extension id. Hub opens the inspector on that extension

When a plain URL, such as a catalogue link, opens the latest version of an architecture with a timeline, Hub opens the current moment of the timeline. The URL of a Hub link has exact=1, so Hub opens the version that the link names. A change of tab or lens keeps exact=1 in the URL.

screen​

FieldRequiredRule
extension, screenYesThe extension id and the id of its screen contribution
contextNoThe resource that the screen is for: namespace, type, id, version and an optional element
paramsNoView parameters of the screen, such as a filter, a sort order or a page

The screen route gets context as the usual context query parameters: namespace, resource, resourceType, resourceId, version and selectedElement. The screen shows the resource above its heading, with a link to it.

params holds two kinds of name:

KindNameLimitsSent to the route
Screen parameter^[A-Za-z][A-Za-z0-9_-]{0,63}$, not a context nameAt most 8. A value has at most 256 charactersYes, in the query
Table state<table>.filter, <table>.q or <table>.page, where <table> matches ^[a-z][a-z0-9-]{0,63}$At most 12. filter has at most 100 characters, q at most 200, and page is 2 to 10000No. Hub tables read it

All of these stay in the screen URL. A change of a screen parameter loads the screen again. A change of table state does not.

The screen route gets the context and the screen parameters in its query. Together they can have at most 2048 characters when form-encoded. This is the budget for the extension's query inside Hub's limit of 4096 bytes for the whole request line, which also holds the route path. A character outside ASCII takes up to twelve encoded characters, so this budget can apply before the limit of 256 characters for each value. A namespace, type, id or version has at most 256 characters.

Each limit counts characters as Unicode code points, as JSON Schema maxLength does. An emoji is one character.

The schema bounds params only to 20 names in total. Hub checks the two counts and the query length in code, as the UI does. A search result link and a chat citation go through the same check, ExtensionDestinations, before Hub sends them on. Hub also drops a link to a namespace that the user cannot read, and an href that a browser cannot open, such as one with a port above 65535. For a host that is not a DNS name, such as one with _, Hub is stricter than a browser and drops the link.

Return to the page​

When a user follows a Hub or screen link, Hub keeps the page that they left as a return point. The next page shows Back to <page> above its content. It opens that page with its query as it was: the filters, sort and page of a list, or the tab, lens and selected node of an architecture.

  • Hub keeps the return points in the browser history, not in the URL. Back, Forward and a refresh keep them. A copied link has none.
  • Hub keeps the last 5 return points. A detailed-architecture link and a breadcrumb keep them.
  • A link to the same page, such as a filter link of a screen or a lens node that links to the version that it shows, changes only the view. It keeps the return points and adds none.
  • Back and Forward to an architecture or pattern page select the node that the user selected there again. Hub keeps that selection for each history entry in the session storage of the browser tab, not in the URL. A change of tab and Clear selection in the inspector clear it. Closing the inspector and a change of lens on the page keep it. A new visit to the same URL, such as a pasted link, is a new history entry and selects nothing. Back, Forward and a jump of more than one entry select only the node of the entry that they open, also between two entries at the same URL.
  • A Hub link and a return to an architecture or a pattern open the exact version. Their URL has exact=1, so a copied link, a new tab and a refresh also open that version.
  • The page name in Back to has at most 200 characters. Hub shortens a longer title.
  • A return point holds only the page and its query. Form input and credentials are never in a URL, so they are never in a return point.
  • The pages that make return points are extension screens, architecture and pattern pages, search results and chat.

Unavailable destinations​

A page shows what it can, and says what it cannot show.

CaseThe Hub UI shows
The resource or the version does not exist"Architecture not found", with the return link
The element is not in the versionThe architecture or pattern, and a notice that names the element
The extension is not enabled, or has no view for the resourceThe page, and a notice that names the extension
The screen is not enabled, or the extension has no such screen"Extension screen unavailable.", with the extension and screen ids
The screen link has an incomplete context, or too many parametersA message. Hub does not call the screen route

Access​

A link is not a permission. Hub checks access when each page loads: the namespace permissions for a resource, and the route scope for a screen. A user can edit any value in a URL, so a screen route must check that the user may see the data for the context that it gets (see Extension access). An extension that returns links to other namespaces must also check that the user may read them, because a link shows its label.