ea_model

ea_model builds and edits the structure of the model: packages, elements, connectors, the attributes and operations of class-like elements, tagged values, and the link between an element and a child diagram. It is the tool a modeling session calls most. Diagrams themselves (creating one, placing elements, layout, styling) belong to ea_diagram, and read-only analysis across the model belongs to ea_analyze.

It has 50 operations in six groups.

Group	Operations	What it covers
Packages	9	Create, read, update, delete, list, search and copy packages
Elements	15	Create elements (plain, technology-bound, bulk, external reference), read, update, restyle, move, delete, search, find orphans, UI selection, neighborhood walk
Composite and navigation diagrams	2	Link an element to a child diagram; audit the link
Connectors	7	Create, read, update, delete, list and filter connectors
Class members	9	Attributes, operations and operation parameters
Tagged values	8	Tagged values on elements and on connectors

Every operation is Deterministic. Where one reports a finding (orphans, mismatches), deciding what to do about it is left to the assistant or to you. Examples use the fictitious Westbrook Bank, with technology id WBA and stereotypes such as WBABusinessApplication. They are illustrations: replace them with your own modeling language. Nothing here requires your model to contain Westbrook content.

Conventions that apply to every operation in this tool:

Properties. The create and update operations take a set of EA properties to apply (name, alias, notes, status and similar). EA's property names are case-sensitive, and the server accepts common spellings of them, so notes resolves to Notes. A name the server does not recognize is rejected, not guessed. The reply lists the properties that were applied and those that were rejected, and a successful reply does not mean every property landed. A tag name passed as a property is always rejected, with a pointer to the tagged-value route.
Writes EA can refuse. Some write paths check EA's acceptance and report a named rejection (for example create_connector, update_connector, set_element_appearance, set_composite_diagram, set_connector_tagged_value). Several others do not, and report success regardless. After a write that matters, have the assistant re-read the object, or check anything drawn with verify_diagram.
Not-found. An unknown package, element, connector or diagram identifier returns a named not-found result and changes nothing. The exceptions are called out in the notes: attributes and operations updated by an unknown GUID, a member that is not on the element named, and the query-based readers that answer empty.
Colors. EA stores a color as a number in blue-green-red order, where 255 is red and 16711680 is blue. Give colors as #RRGGBB, the ordinary web form, and the server converts them. A number is used as given, and default clears an override. An unrecognized color is rejected. The reply reads the stored values back and shows each one as #RRGGBB, so you can confirm what EA stored.
Sequential writes. EA runs one automation call at a time. Writes are issued one at a time; parallel creates have been reported to cause intermittent EA errors. Use the bulk operations to cut the number of calls.
Read-only mode refuses all 28 operations in this tool that write. Only select_element_in_browser among the 50 changes EA's state without being blocked, and it changes only the selection.
Deletes are permanent. Seven operations delete: delete_package, delete_element, delete_connector, delete_attribute, delete_operation, delete_tagged_value and delete_connector_tagged_value. Baseline first (Baselines); see How tools and operations work.

Packages

Packages hold every element, connector and diagram, so they are created first and parent first: a package needs its parent to exist. To find the parent for a top-level package, list_root_packages reports the number of each model root.

Operation	What it does	When you would use it	Changes the model	Logic
`create_package`	Creates a package under a parent and optionally sets its properties	Building the package hierarchy before any element	Yes	Deterministic
`get_package`	Reads one package by number or GUID, optionally with the identifiers of its child packages, elements and diagrams	Confirming a package exists; reading its notes and stereotype	No	Deterministic
`update_package`	Changes a package's name, alias, notes, stereotype or version	Renaming; repairing a name EA stored encoded	Yes	Deterministic
`delete_package`	Deletes a package and everything inside it	Removing a scratch package or a retired version	Yes: destructive	Deterministic
`list_root_packages`	Lists the top-level packages (model roots)	Orienting at the start of a build; choosing a parent	No	Deterministic
`list_child_packages`	Lists a package's immediate children	Stepping down the hierarchy one level at a time	No	Deterministic
`list_package_tree`	Walks the hierarchy beneath a package in a few queries, optionally with each package's diagrams and element count	Reading or reasoning over a whole subtree	No	Deterministic
`find_packages_by_name`	Finds packages whose name contains the text, or equals it	Locating a package by name; checking before creating a duplicate	No	Deterministic
`duplicate_package`	Copies a package subtree, like EA's "Paste as New", giving every copied object a fresh GUID	Cutting a new version before editing; copying a tested structure as the start of a variant	Yes	Deterministic

Notes: package operations

Create packages one at a time, parent first. Parallel creation is reported to hit race conditions in EA's package tree. An unknown parent number is reported as not found.
Names containing &, <, > or a quotation mark have been reported to come back encoded on some paths (for example Operations & Support). Read the package back and repair it with update_package.
Moving a package. A package's parent is changed by copying the package with duplicate_package into the new parent and deleting the original with delete_package, by a direct query, or in EA's user interface, after a baseline.
delete_package removes everything beneath it. Before deleting a package, check what its elements connect to outside it with traverse_element_subgraph (Elements); the ea-model-hygiene skill follows that sequence.
list_package_tree has its own depth limit, ten levels by default, and reports whether it stopped at the limit without checking whether anything lies deeper. It counts the elements directly in each package, not those in descendants.
The name searches treat % and _ as wildcards in a substring search, and the limit (100 by default) caps matches before they are loaded, so a very common name returns the first matches in repository order, not the best.
duplicate_package rebuilds the subtree object by object, because EA's programming interface has no package copy. By default the copy is a sibling with the same name as the source, as in EA, so rename one afterward. Rules for what the copy carries:
- every package, element, attribute, operation, connector and diagram gets a fresh GUID;
- a connector with both ends inside the copied subtree is duplicated with both ends remapped to the copies;
- a connector with one end outside (for example a profile's link to a metaclass outside the profile package) keeps pointing at the original outside element, which is never copied;
- diagrams are copied with their layout and links, and their placed elements are remapped when the element was copied, or left pointing at the original when it was not;
- a setting can skip connectors or diagrams.
What the copy does not carry. A type reference (an attribute typed as another class) is not remapped, even when the target is inside the copy. The ends of a connector (role, cardinality, navigability), tagged values on attributes, operations, connectors and packages, and element-to-element parentage are not in the copied lists. Treat the copy as structurally faithful, compare it with the source before relying on it, and take a baseline before copying into a package that already holds content you care about. The reply lists what was deliberately not copied.
Check navigation links on the copy. After duplicating a package that contains navigation diagrams, run find_composite_diagram_mismatches on the copy (Composite and navigation diagrams) and repair any it reports.
Large subtrees take proportionally long, because the work is one call per object.

Elements

Fifteen operations create, read, change, move, delete and search elements, and read an element's neighborhood in the connector graph. Create elements after their package exists and before the connectors that reference them.

Two ways to create an element. They differ in who chooses the EA base type.

Way to create	Operations	You supply	The server supplies
Plain	`create_element`, and a bulk item that gives a type	The EA base type, optionally a stereotype	Nothing. Choosing a base type that fits the stereotype is up to the caller. The reply warns when the server knows the stereotype's expected type and it differs
Technology-bound	`create_element_in_language`, and a bulk item that gives a technology id and stereotype	A technology id and a stereotype name from that technology	The base type, read from the technology definition

Prefer creating with a technology id for any stereotype defined by an MDG Technology, because it cannot choose the wrong base type. The technology is resolved in this order: the technology EA has loaded, then one parsed earlier in the session, then the server's built-in tables for ArchiMate 3, BPMN 2.0, BPMN and UML. The reply says which source answered. A technology that is not loaded, and not built in, is reported as unknown. The Westbrook technology is the AI Power Tools team's own test language and is not available to customers; use your own technology id.

Operation	What it does	When you would use it	Changes the model	Logic
`create_element`	Creates one element from an EA base type, optionally with stereotype, properties and tagged values in one call	One-off elements; an element with its governance tags in one step	Yes	Deterministic
`create_element_in_language`	Creates one element from a technology id and a stereotype name; the base type is looked up	Creating MDG-stereotyped elements, for example a Westbrook business application	Yes	Deterministic
`create_elements_bulk`	Creates many elements in one call, skipping any that already exist	Catalog loads of applications, services or data assets	Yes	Deterministic
`create_external_reference_element`	Creates a placeholder for an object held in another system, with four identifying tags	Representing a CMDB item or a ticket in the model without copying it	Yes	Deterministic
`get_element`	Reads one element by number or GUID, optionally with its attributes, operations, tags and connector numbers	Confirming an element and reading its current state	No	Deterministic
`update_element`	Changes properties, tagged values and default appearance in one call	Renaming, re-noting, re-stereotyping and tagging after creation	Yes	Deterministic
`set_element_appearance`	Sets an element's model-wide default colors and border	Giving elements of a stereotype a consistent default look	Yes	Deterministic
`delete_element`	Deletes an element with its connectors, members and diagram placements	Removing duplicates and decayed elements after the pre-delete checks	Yes: destructive	Deterministic
`list_elements_in_package`	Lists the elements in a package, optionally including child packages	Enumerating a package before bulk work; confirming a load	No	Deterministic
`find_elements_by_name`	Finds elements anywhere in the model by name, each with its package path	Resolving a name to an identifier; checking before creating	No	Deterministic
`find_orphan_elements`	Finds elements with no connector at either end, optionally for one stereotype and one package subtree	First step of a hygiene review	No	Deterministic (a query; whether an orphan is decay is a judgment left to the AI and you)
`move_element`	Moves an element to a different package	Placing an element in the right package after the fact	Yes	Deterministic
`get_current_selection`	Reads which elements are selected on the diagram open in EA	Letting you say "this one" in the EA window	No	Deterministic (reads the current selection in EA's window)
`select_element_in_browser`	Highlights an element in EA's Browser tree	Showing you where an element lives	No (changes EA's highlight only)	Deterministic
`traverse_element_subgraph`	Reads the neighborhood a few hops out from an element: the elements reached and the connectors between them	The neighborhood check before a delete or a change; feeding diagram advice	No	Deterministic

Notes: element operations

Types are matched exactly, as EA spells them (Class, Component, Artifact and so on). The server does not validate the type; EA decides. For an MDG stereotype, the type should be its base metaclass.
create_element base-type warning is advisory. It appears only when the server has a table entry for the stereotype. A stereotype with no entry gets no warning even when the type is wrong, which is another reason to create elements with a technology id for your own MDG Technology. Set colors afterward with set_element_appearance, not as a property at creation.
create_element_in_language creates nothing on an unknown technology or stereotype. It does not fall back silently. It has no input for tagged values (supplying one is reported as an unknown input), so create the element, then apply tags with update_element or set_tagged_value.
Applying a stereotype after the fact can be refused by EA. If update_element sets a stereotype whose base metaclass does not match the element's type, EA can refuse silently, and the reply carries a warning when the value does not read back. This operation cannot change an element's base type; recreate an element that was made with the wrong type.
Bulk element creation is idempotent. The duplicate test is name plus package plus stereotype; the element type is not part of it, and for a technology item the stereotype compared is the technology's. A skipped item does not update the existing element's properties or tags. Properties and tags that fail to apply are not itemized per element, so after a load that depends on tags, verify with get_element_tags (Tagged values). Run bulk operations one at a time. For very large loads (dozens of elements or more), EA's own in-process scripting is reported to be faster than any route through this server.
create_external_reference_element is idempotent on name plus the stored external identifier within one package; the same external object under a different name in the same package is not detected. The four tags written are the external system, identifier, link and a synced-at timestamp. The timestamp is set at creation only; refresh it with set_tagged_value. The stereotype is written as supplied, and the operation does not install a profile that defines it.
get_element returns the extended stereotype when one is set. Loading features loads everything, so for a class with many attributes prefer the specific list operations.
update_element routes colors correctly. Give appearance values (BackColor, FontColor, BorderColor, BorderWidth) with the other properties; they set the element's default look on every diagram that does not override it. To restyle one placement on one diagram, use the per-diagram appearance operations in Element appearance. When appearance is all that changes, set_element_appearance has its own validation and is the better choice. Colors written through EA's own dialog are reported to be invisible to color rules; colors written here can be read back.
delete_element is permanent. An orphan reported by find_orphan_elements is not necessarily safe to delete: it can still be drawn on a diagram, own a composite diagram, or be a container.
list_elements_in_package with child packages has no depth limit. The minimal shape carries no type or stereotype; ask for the full shape or use get_element. For stereotype or type distributions across a model, the summaries in Summaries are cheaper than listing.
find_elements_by_name matches % and _ as wildcards in a substring search, and the limit caps matches before loading. It reads every kind of object without filtering by element type.
"Orphan" means "no connectors", nothing more. It does not mean unused or safe to delete. The scan also reports containers whose only relationship is containment, package mirror rows, elements that appear only on diagrams, and elements that anchor a composite diagram. On a capability model most orphans are of these kinds. The real candidates for decay are elements with a real stereotype, no connectors and no diagram placement; check the last two with traverse_element_subgraph and the diagram queries. The type filter, despite its name, filters on stereotype. Package scope covers the package and its full subtree. The reply gives the number of orphans, the number of objects in scope and the percentage. An unknown package number returns an empty result. Scope the scan to the smallest package that answers the question.
move_element changes only the package. The element's connectors, diagram placements and composite link survive. A moved element can end up drawn on a diagram that lives in another package; that is expected. The destination package is not checked for existence, so re-read the element to confirm the new location.
get_current_selection reads the open diagram only, not the Browser selection, and reports elements, not selected connectors. It reads what is selected in EA's window at that moment, so the same call can answer differently after you click elsewhere.
traverse_element_subgraph details. Depth defaults to 2, and values outside 1 to 5 are clamped silently. Direction is upstream, downstream or both. Stereotypes are replaced by display aliases unless turned off. When depth is above 2 and more than 50 elements are reached, the element list is cut to the root plus the first 50, but the connector list is not, so a connector can name an element no longer listed. A connector reached by two paths can be listed twice, so treat both lists as sets, not counts. The walk reads each element through EA one at a time and is slow on large neighborhoods; for larger graph questions, trace_connectors, find_paths and get_traceability_tree in Graph and traceability work from one bulk query. An invalid direction is reported with a named error.

EA lets an element own a child diagram: double-click the element on any diagram and EA opens that child diagram. Chains of these links make a drill-down set, a parent diagram whose boxes open the diagrams one level down. The ea-navigation-diagrams skill builds a whole set on two operations.

The link is two separately stored facts that must agree. The diagram must be recorded as a child of the element, and the element must be flagged as composite. With only the first, the diagram sits under the element in the Browser but the element shows no marker and does not navigate. With only the second, the marker is there and there is nothing to open. A set built by hand with one half set looks navigable and is not.

Operation	What it does	When you would use it	Changes the model	Logic
`set_composite_diagram`	Sets or clears an element's child diagram, writing both halves in one call and reading them back	Making a hierarchy navigable; fixing a reported mismatch; removing a link	Yes	Deterministic
`find_composite_diagram_mismatches`	Audits a package, optionally with its whole subtree, for elements where the two halves disagree	Acceptance check on a navigation build, or before offering to build one	No	Deterministic

Look at the consistency result. set_composite_diagram reports whether, after the write, both halves agree. A successful reply with an inconsistent result means the write did not fully land; investigate and do not assume it worked. The operation changes both halves together.
Clearing is explicit. To clear the link you must state that no diagram is wanted; omitting the diagram does nothing. Clearing resets every diagram currently recorded as the element's child, and clears the flag. Setting does not touch other diagrams already under the element. The operation is idempotent. An unknown element or diagram is reported as not found, and EA can refuse the diagram link with a named rejection.
The mismatch audit reports two problems. diagram_without_flag means a child diagram exists but the element is not flagged: it looks navigable in the Browser but does not drill down. flag_without_diagram means the flag is set but no diagram is recorded: the marker opens nothing. An element with neither half set is an ordinary leaf and not a mismatch. Package-type objects are excluded. The subtree is walked to full depth. An unknown package returns zero elements checked.
A clean audit does not prove double-click works. In some EA builds, double-clicking an element whose two halves agree may open its properties instead of the child diagram, even though the marker is drawn. If it happens, report it to support (help@novocircle.com) with the EA build.
Reload before checking visually. The flag is written directly to the model, so EA's open session can show stale state until a diagram is reloaded (reload_diagram in ea_diagram, or the refresh option on the render operations). Do not set the flag with a hand-written direct database write.

Connectors

A connector runs from a client (its source) to a supplier (its target). Create connectors after both elements exist: creation checks that both do and reports which one is missing.

Operation	What it does	When you would use it	Changes the model	Logic
`create_connector`	Creates one connector between two elements, after checking both exist	Linking elements one at a time	Yes	Deterministic
`create_connectors_bulk`	Creates many connectors in one call, skipping duplicates	Loading the relationships of a catalog after its elements	Yes	Deterministic
`get_connector`	Reads one connector by number or GUID, including role, cardinality and navigability of each end	Confirming a connector and reading its ends	No	Deterministic
`update_connector`	Changes a connector's name, notes, stereotype, direction or type	Correcting a name, stereotype or direction	Yes	Deterministic
`delete_connector`	Deletes a connector	Removing a wrong or obsolete relationship	Yes: destructive	Deterministic
`list_connectors_for_element`	Lists every connector attached to an element, both directions	Seeing what an element is connected to	No	Deterministic
`get_connectors_for_element_filtered`	Lists an element's connectors filtered by direction, connector type and stereotype	Checking a stereotype's use around an element; verifying a bulk load	No	Deterministic

Notes: connector operations

Connector types use EA's own spelling, for example Association, Dependency, Generalization, Realisation (with an s, which is the stored value) and InformationFlow. The server does not validate the type. A technology can declare its own connector types and stereotypes, or none, so check what yours declares; plain UML types without a stereotype are the safe fallback.
A refused stereotype or direction is not an error. create_connector reports it as a rejected property, and the connector exists without it. EA can also refuse the connector itself, with a named rejection.
Connector tags are separate. A connector tagged value cannot be set through create_connector or update_connector; use set_connector_tagged_value (Tagged values).
Bulk creation skips by direction. A connector is a duplicate when source, target, type, stereotype and name all match, and a blank name or stereotype matches only a blank one. The reverse pair is not a duplicate, and two connectors between the same pair that differ in name or type are both created. An item cannot carry a direction or other properties, so use update_connector afterward. A stereotype EA refuses is not itemized in the bulk result, so verify with get_connectors_for_element_filtered after a load that depends on stereotypes.
update_connector on a diagram-heavy model. After bulk connector edits, check the affected diagrams with verify_diagram. Per-diagram presentation (route, color, width) is set in Connector presentation, not here.
delete_connector removes the connector everywhere, including from every diagram that showed it. Baseline first.
get_connectors_for_element_filtered returns raw repository-style rows, not the tidy records of get_connector. The limit shrinks the reply and does not make the query cheaper. The element is not checked, so an unknown number returns an empty result. The stereotype filter compares only the first stereotype of a connector that carries several.
For more than one element or more than one hop, use the graph operations in Graph and traceability.

Class members

Nine operations manage the features of a class-like element: attributes, operations (methods), and the parameters of an operation. They work on any element that can carry features and key off the owning element, not off how it was created. Create the element first.

Operation	What it does	When you would use it	Changes the model	Logic
`create_attribute`	Adds an attribute to an element, optionally with type, default and properties	Building the data structure of a class or data asset	Yes	Deterministic
`list_attributes`	Lists an element's attributes	Reading the identifiers that update and delete need; verifying a build	No	Deterministic
`update_attribute`	Changes an attribute, identified by its GUID	Changing type, default, notes or visibility after creation	Yes	Deterministic
`delete_attribute`	Deletes an attribute, identified by element number plus attribute number	Removing an attribute	Yes: destructive	Deterministic
`create_operation`	Adds an operation (method) to an element	Adding behavior to a class	Yes	Deterministic
`list_operations`	Lists an element's operations with their parameters	Reading the identifiers that update, delete and add-parameter need	No	Deterministic
`update_operation`	Changes an operation, identified by its GUID	Changing return type, notes or visibility	Yes	Deterministic
`delete_operation`	Deletes an operation, identified by element number plus operation number	Removing an operation	Yes: destructive	Deterministic
`add_parameter`	Adds a parameter to an operation and confirms it by reading it back	Completing an operation's signature	Yes	Deterministic

Notes: class member operations

Identifiers are not uniform, and the assistant must use the right one. Each attribute and operation has a number and a GUID. Updating takes the GUID; deleting takes the owning element's number plus the member's own number. A parameter has no number, and add_parameter returns a GUID. Create operations already return both identifiers; at any other time the assistant lists the members and reads the identifiers off the row, matching by name. There is no find-by-name operation for members.
A parameter is changed or removed by recreating the operation. Adding a parameter is not an upsert. Adding a second parameter with a name that already exists on the same operation is reported to fail: EA ignores the write and the read-back cannot find it. A failure of that kind is reported to mean nothing was written.
Defaults read back differently. An unset default reads as empty in the creation reply but, reportedly, as EA's placeholder text <none> when read later. Do not write a check that assumes one or the other.
Not-found handling is partial here. An unknown owning element returns a not-found result, but update_attribute and update_operation have no guard for an unknown GUID, and a member that is not on the named element is reported as a plain tool error. These operations do not check EA's acceptance of the write; re-read with the list operations when it matters.
Deletes cannot be undone. Baseline first.

Tagged values

Eight operations read and write tagged values, the name-and-value pairs a technology uses to carry governance data such as criticality or ownership, on elements and on connectors. Tags on an element can also be set at creation through create_element, update_element and the bulk creation; the operations here are for after-the-fact changes, reads and deletes.

	Element	Connector
Create or update (idempotent by name)	`set_tagged_value`	`set_connector_tagged_value`
Read through EA's own list	`list_tagged_values`	`list_connector_tagged_values`
Read across every place tags are kept	`get_element_tags`	`get_connector_tags`
Delete by name	`delete_tagged_value`	`delete_connector_tagged_value`

Operation	What it does	When you would use it	Changes the model	Logic
`set_tagged_value`	Creates or updates one tag on an element; an existing tag of that name has its value replaced	Tagging after creation, or changing one tag	Yes	Deterministic
`get_element_tags`	Returns every tag on an element, merged from all the places EA keeps them	The authoritative read of an element's tags; verifying a tagged load	No	Deterministic
`list_tagged_values`	Lists an element's tags through EA's own list	Reading the tags EA itself reports	No	Deterministic
`delete_tagged_value`	Deletes one tag from an element by name	Removing a tag that no longer applies	Yes: destructive	Deterministic
`set_connector_tagged_value`	Creates or updates one tag on a connector	Tagging relationships; authoring or building a modeling language's relationship constraints	Yes	Deterministic
`get_connector_tags`	Returns every tag on a connector, merged from all the places EA keeps them	The authoritative read of a connector's tags	No	Deterministic
`list_connector_tagged_values`	Lists a connector's tags through EA's own list	Reading the connector tags EA itself reports	No	Deterministic
`delete_connector_tagged_value`	Deletes one tag from a connector by name	Removing a connector tag that no longer applies	Yes: destructive	Deterministic

Notes: tagged value operations

Two ways to read, and the wrong one can return nothing. The list_ operations read EA's own tag list. The get_ operations query the model directly and merge every place EA keeps tags, including, when asked, the records where a technology applies stereotype properties. When a tag you expect is missing from a list_ result, use the get_ operation with the cross-reference option on.
The multi-store readers answer empty for an unknown number. An unknown element or connector number returns success with no tags; only an unknown GUID returns not-found. Confirm the object exists when an empty result surprises you. The same tag can appear in more than one place, and the tag count counts entries, not distinct names. Where a tag comes from a technology's own store, its name field may carry that store's internal property identifier and not the readable tag name.
Values are text. A true-or-false tag takes true or false; an enumeration tag takes an exact permitted value (Mission-Critical, not Mission Critical). The server does not check values against the technology. Conformance is checked by ea_validate (ea_validate).
To set several tags at once, use update_element with tagged values; it refreshes EA's list once instead of once per tag.
Deleting removes the first tag with that name. A tag that is not there is reported as not found by name. Deletes cannot be undone.
Element and connector tags are stored separately. An element operation cannot read or write a connector's tags. set_connector_tagged_value checks that EA accepted the write and reports a named rejection if not; set_tagged_value does not, so re-read with list_tagged_values when it matters.