add_note_to_view
Add a visual annotation to an ArchiMate view for comments or notes without creating model elements. Place sticky notes at any position and optionally connect them to diagram nodes.
Instructions
Add a diagram-only note (sticky annotation) to a view.
Use this to comment on a diagram — a caveat, an owner, a "retire in
FY27". Do NOT create a `Grouping` element just to write a comment:
that pollutes the model tree and participates in validation, while a
note does not.
Notes are visual only. A note has no ArchiMate element, no folder
and no model-tree entry, so it never shows up in `query_elements`,
`count_by_type`, `list_orphan_elements` or the coverage section of
`build_quality_report`. `connect_to_node_ids` draws annotation-only
connector lines that create NO ArchiMate relationship.
`x`/`y` are kept exactly as given, including across
`auto_layout_view` (both layout engines), because a note annotates
one specific spot. Layout will not move element nodes out from under
a note, so place notes in free space — off to the side of the
diagram, or below it. Routed connections are drawn around notes.
Args:
view_id: ID of the target view.
text: Note text. Must be non-empty; kept verbatim, so multi-line
text keeps its line breaks and indentation. Verbatim also
means escape sequences are NOT interpreted: pass real line
breaks for a multi-line note, because a literal backslash-n
is stored and rendered as those two characters.
x: X coordinate (top-left, integer pixels). Used exactly.
y: Y coordinate (top-left, integer pixels). Used exactly.
width: Note width in pixels. Defaults to 185 (Archi's default).
height: Note height in pixels. Defaults to 80.
connect_to_node_ids: Optional list of things to point at. Each
entry may be a visual node ID or an element ID that is
already visible in this view.
note_id: Optional stable visual node ID. When omitted a UUID is
generated.
Returns:
Success envelope with `data.node_id`, `data.connection_ids`,
`data.connected_node_ids` (resolved visual node IDs),
`data.text`, and the geometry `data.x`, `data.y`,
`data.width`, `data.height`.
Errors:
`INVALID_NOTE_TEXT` when `text` is missing or blank.
`ViewNotFoundError` when `view_id` is unknown.
`ModelOperationError` for a duplicate `note_id`, or for connect
targets that are not visible in the view — the unresolved
IDs are listed in `error.details.unknown_ids` and nothing is
created.
Notes are not updatable or deletable yet: recreate the view (or the
note) if the text or placement needs to change.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| text | Yes | ||
| width | No | ||
| height | No | ||
| note_id | No | ||
| view_id | Yes | ||
| connect_to_node_ids | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||