add_note_to_view
Add a visual note (sticky annotation) to a diagram view for comments that do not belong in the model tree, such as caveats or ownership details. Notes are not ArchiMate elements, so they do not affect validation or reports.
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. Must be unique across the
*entire* active model — not just within this call, this
batch, or this concept type. An id already used by any
element, relationship, view, node or connection is
rejected. When generating ids across several batches,
namespace them (`bp-`, `ac-`, `tech-`) so batches cannot
collide.
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 | |||