ea_diagram

ea_diagram creates, populates, arranges, styles, checks and exports Enterprise Architect diagrams. It has 46 operations in 16 groups.

The tool works on the diagram view: which elements appear on a diagram, where they sit, how each one is drawn, and how each connector is routed. It does not create elements or connectors. You create those with ea_model and then place them here. A diagram is a presentation of model content, so deleting a diagram, removing a placement or restyling a placement never deletes the element or connector underneath.

Every operation in this tool is Deterministic, with two exceptions noted in Vendor icon libraries and Diagram descriptions. The tidy and summary operations apply fixed rules to the geometry they are given; they do not decide what a good layout, palette or icon is. That judgment belongs to the AI that drives the tool, guided by the ea-diagram-composition and ea-diagram-advisor skills.

Examples use a Westbrook Bank scenario (the payments application landscape, built from WBABusinessApplication elements). Replace it with your own model. You do not need the Westbrook model or the WBA technology installed.

Operation groups

The calling convention and error behavior common to all tools are in How tools and operations work. An unknown diagram or package id returns a clear "not found" answer rather than a failure. The notes below cover only what is specific to diagrams.

Ideas that apply across the tool

Placement. An element has at most one placement on a diagram. A placement is the element's appearance on that one diagram: its position, size, colors and picture. Most styling is stored on the placement, not on the element, so the same element can look different on different diagrams.

Per-diagram versus model-wide appearance. Use the narrowest scope that does the job. A model-wide default changed to fix one view surprises whoever opens another.

Front and back stacking order. Every placement has a stacking number, called sequence. A lower number is nearer the front. The front-most object is number 1. A filled container, such as a system boundary, a layer band or a group, must have a higher number than the elements inside it, or it paints over them and they disappear.

Why the server re-renders before verifying. EA keeps its own cached drawing of each diagram. If the diagram changed from outside that session, such as a direct write to the model database or a change from another session or process, EA can render the old picture. It looks entirely plausible and no longer matches the model. A check that renders without reloading can certify a diagram it never saw. For that reason verify_diagram always reloads first and has no setting to skip it. Use it whenever the question is "is this right". get_diagram_png and get_diagram_svg are for when you already trust the state and want the picture; they take a refresh setting for the case where you do not. The server's render is EA's own export of the diagram. It does not show EA's window, so it cannot show the toolbox bound to a diagram or anything EA draws only on screen. With computer use the assistant can also look at the diagram open in EA. Without it, the assistant relies on the render and the returned geometry, and asks you to look at EA when the question is about the window.

Previews. Operations that create, change or open a diagram return a rendered picture of the result by default, so you see the effect in the conversation. For a model held in a local file the picture is also saved to a diagrams folder beside the model file. In a loop of many edits, turn previews off and finish with one verify_diagram; each render takes time. The appearance, connector, display, custom style and image operations have no preview. Follow them with verify_diagram.

Checking that a write landed. Diagram writes report a refusal from EA as an error, not as success. Even so, a success answer from a setting-style operation means the settings it lists as applied were accepted, not that every setting you sent was. Read the rejected list in the answer, and finish a build with verify_diagram. See Limitations and known issues for known gaps.

Colors. Colors are given as #RRGGBB or a common color name such as navy, teal or firebrick.

Creating and finding diagrams

Create a diagram in a package, then read, rename, find or delete it. A new diagram is empty; you place elements on it with the operations in Placing elements and connectors.

A diagram has an EA base type (Logical, Class, Component, Activity, Sequence, Analysis and so on). A diagram that belongs to a modeling language also records a language diagram type, such as WBA::WBAApplicationView, which is what attaches the language's toolbox to it.

Notes

• Language diagrams need create_diagram_in_language. Asking create_diagram for a language-prefixed type does not create a language diagram. It silently falls back to the base type, and you get a diagram with the generic toolbox. For example, language_id WBA with diagram type WBAApplicationView produces a Logical diagram bound to the WBA toolbox. Replace both with your own technology and diagram type.
• Check how the technology was resolved. The answer says whether the technology definition came from a loaded technology, a registered file, the model, or built-in tables. The last two are weaker than a technology EA has actually loaded. If the toolbox could not be bound, the answer says so; the diagram then has the right base type and the wrong toolbox. Fix it with update_diagram, or check the technology is loaded (see ea_mdg).
• Notes are not filled in at creation. Write the diagram's notes as the last authoring step, once you know what it contains. Leaving notes out of a later update never clears them.
• Raw settings are replaced, not merged. A diagram carries one combined settings string holding layout, display, custom style and the language binding. Writing it through update_diagram replaces the whole string. Use set_diagram_display, layout_diagram or set_custom_style for their settings; they keep every neighboring setting.
• To make a diagram an element's navigation target, use ea_model set_composite_diagram, which sets both halves of the link. Setting the parent alone does not.
• delete_diagram cannot be undone. Take a baseline first when the diagram matters (see Baselines and ea-change-management). If an element uses the diagram as its navigation target, clear that link first with set_composite_diagram, or the element is left pointing at nothing.
• get_diagram does not reload first. A diagram changed from outside the session can read stale. Its connector list includes connectors EA merely draws between two placed elements; see Connector presentation for what that means.
• Name matching follows the database. Whether find_diagrams_by_name is case-sensitive depends on the repository's database.

Opening and laying out

These operations show a diagram to the person at the keyboard, report what EA has open, force a redraw, and apply EA's own automatic layout.

Notes

• Opening is a window action. open_diagram changes what is on the user's screen. Background operations deliberately keep the EA window clean. Do not use open_diagram to read a diagram; use get_diagram or verify_diagram. Once a diagram is open, the assistant with computer use can screenshot EA's window to check it as you would see it.
• layout_diagram discards hand placement. It repositions every element, so any geometry you set by hand or computed elsewhere is lost. The composition skill avoids it for diagrams whose positions it has calculated.
• Four styles. Hierarchical is top-down layered, Orthogonal routes right-angle connectors over a general layout, Circular arranges elements around a circle, and Sequence runs left to right. If you name no style, one is chosen from the diagram type: Hierarchical for Logical, Class, Component, Deployment, Package and Requirements; Circular for State; Sequence for Activity and BPMN-style Analysis; Orthogonal otherwise.
• Style names must be spelled exactly, including capitals. An unrecognized style is refused with the list of valid ones; the server does not guess.
• Spacing is remembered per diagram. Layer spacing, column spacing and the number of layout passes can be given. Whatever you give is stored with the diagram, so the next layout reuses it. When nothing is given or stored, the defaults are 20, 20 and 4. The answer reports whether each value came from you, the diagram or the defaults. A value must be a positive whole number.
• direction does nothing. The setting is stored for EA's own interface, but EA's automation ignores it. Results were identical across the values tried. The answer says so. It does not rotate the layout.
• Layout arranges; it does not align. Follow it with neaten_diagram_objects for a tidy result. EA's layout pass can also create stored connector records for connectors between the elements it lays out; see Placing elements and connectors.

Tidying

EA's Layout ribbon offers Neaten, Box and Auto Route, but EA does not make them available to automation. The two operations below are AI Power Tools' own implementations of the same ideas. They are defined by their documented behavior, not by EA's menu. Auto Route needs no separate operation: it is set_diagram_link with the line style AutoRouting (Connector presentation).

What tidying moves

• Only the selection. Both operations take an optional list of elements and never move anything outside it, so a tidied region does not disturb the rest of the picture. Elements you list that are not on the diagram are reported and skipped. With no list, the whole diagram is the selection.
• Neaten aligns; it does not resize. Left edges within a tolerance of each other snap to one line, and so do top edges. Each group lands on its median, the move that shifts the fewest elements the least. Sizes are untouched.
• Distribute is off by default. When on, the gaps in each aligned row or column of three or more elements are evened out while the first and last stay put. It is off by default because evening a deliberately spaced row loses that information.
• Resize keeps the top-left corner, so a row stays a row. Resizing from the center would scatter an arrangement that was already aligned.

What tidying does not do

• It does not move connectors. They follow their elements.
• It cannot invent an arrangement. Elements nowhere near aligned stay put, because guessing which were meant to line up is a judgment the operation refuses to make.
• It never makes a diagram worse. An element whose move would land it exactly on another element, or create an overlap that was not there before, goes back where it was. An overlap that already existed is left for you to fix.
• It does not fix a name that no longer fits its box after resizing. EA grows a drawn element to fit a long name it cannot break, while the stored size stays the same, so the stored geometry cannot show the problem. verify_diagram with the SVG option shows the drawn size.

Read-only mode does not block these two operations. neaten_diagram_objects and resize_diagram_objects change diagram geometry but are not refused when the server runs in read-only mode (How tools and operations work).

Choosing the tolerance. The tolerance is how far apart, in EA units, two edges may be and still count as one intended line. The default is 12. Raise it for a diagram that drifted badly. Lower it if it pulls together things you meant to keep apart. A long gentle drift across a row can chain into one group, so the tolerance is your control over how much drift you call intentional.

Resizing matters because uniform size within a role is not cosmetic. A reader takes a bigger box to mean a more important thing, so peers at four different sizes make a claim nobody intended. Follow a resize with neaten_diagram_objects if the spacing is now uneven.

Placing elements and connectors

Placing elements is the step that turns model content into a diagram. The usual sequence is: place the elements, add the connectors to the diagram, then style, tidy and verify.

Notes

• Layout on placement. With the default setting, add_elements_to_diagram_bulk keeps your positions if you supplied any. If you supplied none, it runs a layout chosen from the diagram type. Naming a layout style always lays out and discards the positions you supplied. Setting layout to none never lays out. A bare list of elements with layout none leaves every element stacked at the origin, so either supply positions, let the default lay out, or run layout_diagram afterward.
• Batches are forgiving. The bulk form records each element as added, skipped (already placed) or failed, and one failure does not stop the others. add_element_to_diagram does not check whether the element is already placed, and it does not add connectors.
• A refused placement is an error. If EA refuses a placement the answer says so, rather than reporting an element as present that is not.
• What "stored" means for connectors. EA draws a relationship between any two elements placed on the same diagram, whether or not a per-diagram record of that connector exists. The record is needed to style a connector (Connector presentation), not to show it. So add_connectors_to_diagram_bulk is the right call when you are about to change a connector's presentation, and the wrong tool for restoring a line that is not visible. For a missing line, check that both ends are placed and that the connector exists in the model.
• You cannot fully prevent a connector appearing by leaving it out of placement. The option to not add connectors controls what the server stores, not what EA draws. EA's own layout pass can store connector records for elements it lays out, and the server may not be able to remove them in some EA builds. The answer then warns and names the connectors. Setting layout to none is the only way to guarantee no stored record. To hide a drawn connector, use set_diagram_link or the hide_relationships display setting.
• Check what is stored. verify_diagram reports how many connectors on a diagram are stored and how many are drawn only. Use it, rather than the placement answer alone, to confirm connector records exist before styling them.
• Elements placed by AI Power Tools cannot take a custom style. Elements placed by these operations cannot take shape, opacity or rotation changes; see Custom style.
• remove_element_from_diagram is not a model delete. To delete the element from the model, use ea_model delete_element.

Repositioning

These companions to placement change elements that are already placed. They never place a new element and never duplicate one. Positions are in EA's own units, and a position read from verify_diagram can be sent back unchanged.

Notes

• Not placed is an answer, not an add. An element not yet on the diagram is reported as not placed. These operations never add it silently. For one element the report is an error pointing you to add_element_to_diagram; in the bulk form it is recorded per element and the rest proceed.
• Raw style text is written as given. Both operations can write a placement's raw style string verbatim, so send the complete string you want stored. For one attribute, prefer the typed operations (set_diagram_object_appearance, set_custom_style, set_element_image).
• This is per-diagram. To change an element's look on every diagram, use ea_model set_element_appearance. It is a different scope, not another spelling of this one.

Element appearance

Both operations style a placement: one element on one diagram. Other diagrams showing the same element are untouched, and the element's model-wide default is unchanged.

Notes

• Check color by rendering, not by reading it back. EA hands back whatever was written, and some shapes refuse a fill outright because the shape owns it, while the value still reads back correctly. Use verify_diagram with the SVG option and read the drawn fill and stroke.
• A success answer does not mean every property landed. Read the rejected list. In the bulk form one bad entry does not stop the batch, an unknown setting name is rejected with a suggestion, and an entry where nothing could be applied counts as a failure. A name that belongs to the model-wide operation, such as backcolor, is rejected with the right name suggested.
• Text alignment is declined on purpose. EA accepts only two values and neither changed the rendered output in testing, so the request is refused with a reason that marks it as deliberate. For text alignment inside a shape use set_custom_style, subject to its limitation (Custom style).
• These work on diagrams AI Power Tools built. Unlike custom style, appearance changes work on placements created through AI Power Tools, so they are the right tool on a generated diagram.
• Stacking order lives here too. See "Front and back stacking order" above.

Connector presentation

How a connector is drawn on one diagram: its line style, color, width, labels and visibility. This is per diagram. The same connector on another diagram is unaffected, and the model is unchanged. For a connector's model-wide properties use ea_model update_connector.

All three operations need a stored link record: the per-diagram record of how that connector is drawn. EA draws a connector between two placed elements whether or not that record exists, but a drawn-only connector has nothing to read or write, and these operations return link_not_stored. Create the record first with add_connectors_to_diagram_bulk.

Line styles

The route setting takes EA's own Line Style names. Case and separators are ignored, so OrthogonalSquare, orthogonal-square and Orthogonal Square are the same.

There is no arc in EA's connector vocabulary. A radial diagram uses Direct or Bezier lines.

Notes

• A drawn-only connector cannot be styled. link_not_stored is the signal. Add the record first.
• Omitted settings are left alone. Setting the line style does not clear a color set earlier.
• A link nobody has styled reports no line style and no color rather than one nobody chose. Where EA cannot report the style directly (a Bezier curve, for example), the server derives it from the stored style settings EA draws from.
• Reading a color back proves nothing about what EA drew. Use verify_diagram with the SVG option.
• Hidden is the setting that a collapse uses. Setting hidden to false restores a connector hidden by collapse_parallel_connectors (Summary views).
• Colors. A #RRGGBB value or a color name is correct. A plain number is taken as EA's own internal color value, which is the form get_diagram_link reports, so a value read back can be written back unchanged.
• Success is not completeness. Read the rejected list. In the bulk form one bad entry does not stop the batch.

Diagram display

Whole-diagram presentation: the controls a summary or executive view needs. EA stores these in three different places, and the split is not guessable. The server hides that. Every named setting was verified by rendering, not by reading the value back, because EA stores settings it does not act on.

What you can set

For anything not covered, style_ex and extended_style accept raw settings that are merged in, so every setting you do not mention survives, including the one that binds the diagram to its modeling language. A null value removes a setting. The server does not check settings passed this way.

Notes

• Compartments cannot be removed, only reduced to their names.
• A flag cannot be shown to work on a diagram with nothing to suppress. If a flag appears to do nothing, check the diagram has content it applies to, such as connector labels, stereotypes or typed attributes.
• Use these operations rather than update_diagram for display settings. They merge; update_diagram with raw settings replaces the whole string.

Summary views

A dense model is hard to read partly because the same two elements are joined five times. Collapsing hides the duplicates so the relationship reads as one line. The rules are correctness rules, not style preferences: an executive view that hides complexity without saying so is misleading.

How collapsing decides

• Connectors are grouped by the unordered pair of elements, so A to B and B to A are one group.
• It collapses only when direction agrees. A group with both directions is left alone and reported as bidirectional, because hiding one would imply a one-way relationship.
• Where connector types differ, one representative is kept (the one with the lowest id, so repeated runs pick the same one) and the answer names every type in the group.
• Only connectors with a stored link record are considered, and groups of fewer than two are ignored.

The annotation you must place. When anything is collapsed, the answer carries the text of an annotation for each collapsed pair, for example "3 relationships (Association, InformationFlow)", and warns that collapsing without saying so is misleading. The operation returns the text; it does not draw it. Placing the note on the diagram is the caller's job. A collapse without it is a misleading diagram.

Notes

• It is a dry run by default. Without applying, it reports what would be hidden and changes nothing. Review the groups, including the bidirectional pairs it kept, then apply.
• The model is unchanged. Hiding sets the hidden flag on this diagram's link records only. The connectors still exist and still show on every other diagram.
• Read-only mode does not block either operation. collapse_parallel_connectors with apply and expand_parallel_connectors change diagram presentation but are not refused when the server runs in read-only mode (How tools and operations work). The dry run changes nothing.
• Expand cannot tell a collapse from any other hide. It un-hides every hidden connector on the diagram, including ones you hid deliberately with set_diagram_link. To restore just one, set hidden to false on that connector.

Verifying a diagram

verify_diagram is the quality-check call. It reloads the diagram, renders it, and returns the picture together with the full placed geometry.

What you get back

• the rendered picture, and optionally EA's own drawing as SVG
• a count of elements and connectors, split into stored and drawn-only connectors
• for each element: where it sits, how large it is, its stacking number, its fill, and its name, type and stereotype
• for each connector: its line style, color, width, visibility, whether a stored record backs it, and which two elements it joins
• the canvas size and the bounds of everything actually placed, so content hanging off the canvas can be detected

Notes

• The reload cannot be skipped. See "Why the server re-renders before verifying" above. It is deliberate: a verification step must not offer a faster mode that invalidates the verification.
• EA's SVG is EA's own drawing, not a reimplementation. That makes it authoritative for color and paint order, and a fill or stroke can be read from it without any image library.
• A color read back proves nothing; a render does.
• Stored size is not drawn size for long names. EA grows a drawn element to fit a name it cannot break (a 36-character name with no space was drawn 169 pixels wide against a stored 60), while the stored size stays the same. Any check that reads only the placed geometry cannot see this. The SVG does.
• Drawn-only connectors are listed. They are visible but cannot be styled.
• Verifying has a side effect. It changes nothing in the model, but it reloads the diagram in EA.
• It checks the diagram, not the window. verify_diagram returns EA's export and the stored geometry. What EA shows on screen, such as the bound toolbox, is outside it. With computer use the assistant looks at EA's window to check those. Without it, the assistant reports what the render and geometry show and asks you to look at EA for the rest.

Custom style

EA's Custom Style settings change how one placement is drawn: its shape, opacity, text alignment, text rotation, border style, and whether it is drawn as a stack of cards. They are about the drawn shape, not the palette. For fill, border and font color use set_diagram_object_appearance. For an element drawn as a picture use set_element_image or set_element_icon. Custom style is per diagram: other diagrams showing the same element are untouched.

The values. Shape: rectangle, round rectangle, ellipse, diamond, triangle. Opacity: 0, 25, 50, 75 or 100. Text alignment: the nine positions from top left to bottom right. Rotation: clockwise, counterclockwise or none. Border style: solid, dash, dot, dash-dot or none. Card stack: a count of 1 or more, with a direction (NE, SE, SW, NW). Spelling is forgiving: case, spaces and punctuation are ignored. A value EA does not recognize is refused and named rather than written, because EA silently ignores a number it does not know. Omit a setting to leave it alone; pass default to reset it.

The limitation on diagrams AI Power Tools created. Custom style works only on placements that already carry an internal identifier, which EA assigns only to placements it created itself: elements dragged onto a diagram in EA's interface, or brought in by an import. A placement added through AI Power Tools (add_element_to_diagram, add_elements_to_diagram_bulk) has none, and reloading or restyling does not create one. Such a call returns placement_has_no_duid and changes nothing. The server refuses rather than inventing an identifier, because one that EA never reads would do nothing, and copying another placement's would clone an id that must be unique in the model.

What this means for a diagram AI Power Tools generated:

• Use set_diagram_object_appearance for fill, border, font, size and stacking order. They work.
• Shape, opacity, rotation and stacked cards are reachable only on placements EA made.
• To get them on a generated diagram, apply them once through EA's own dialog (right-click the element, Appearance, Custom Style). That makes EA assign the identifier, after which set_custom_style works on that placement. The server cannot open that dialog. With computer use the assistant does it in EA's window; without computer use it gives you the steps and you apply it once. (This is a step you choose to take in EA's interface, not an error dialog; for error dialogs see Blocking dialogs in How tools and operations work.)
• In the bulk form one bad entry does not stop the batch; an element that is not placed, has no identifier or whose values were all refused is reported and skipped.

Notes

• The write is confirmed by re-reading it. A success answer means the settings are stored. Render with verify_diagram to see the shape.
• Neighbors are protected. All placements' custom styles and the diagram's link to its modeling language live in one combined settings string. The answer reports that neighboring settings survived, and the call fails if one was lost. A neighbor that merely changed is reported, not treated as damage, because EA rewrites parts of the string itself.

Custom images

Drawing an element as a picture instead of a box takes two things, not one. The artwork lives in the model's own image library, which EA calls the Image Manager. Each placement then points at an image in that library. Setting one without the other does nothing visible. add_image and list_images deal with the library. set_element_image and clear_element_image deal with the placement.

EA offers no route to its image library through its automation interface, so add_image writes to the model's database directly, and for that reason works only on a local file (.qea or .qeax). list_images and set_element_image work with a local file, a server connection and a cloud connection.

Custom images and vendor icon libraries are different things. Custom images are artwork you load into your model: a logo, a device picture, a glyph you drew. The vendor icon libraries (Vendor icon libraries) are collections that ship inside EA's own installation. Importing one of EA's cloud-icon libraries adds Artifact elements to your model, not images to the image library, so an import adds nothing to list_images. Use set_element_icon for those, which loads the picture into the image library the first time you use it.

Notes

• add_image accepts PNG, EMF and WMF only, up to 1 MiB (1,048,576 bytes). EA re-encodes raster artwork to PNG when it takes it in, so JPEG, GIF and BMP are refused with the conversion named, rather than stored under a type that would draw blank.
• add_image is idempotent on content. Adding the same artwork again, even from a renamed or re-saved file, returns the existing image id and writes nothing.
• On a server connection or a cloud connection, add_image refuses rather than risk a statement the database may not accept. The artwork then has to be loaded through EA's own Image Manager. With computer use the assistant does that in EA's window; without it, you load the artwork and the assistant then uses list_images and set_element_image.
• The image is checked before it is assigned. An image id with nothing behind it makes EA draw the element normally with no complaint, which is indistinguishable from the tool being broken, so the server checks first. A name that matches more than one library image is refused, with the candidates listed.
• A success answer does not mean EA rendered the picture. It means the setting was read back out of EA after a reload. Render with verify_diagram.
• Per diagram. Other diagrams showing the same element are untouched. clear_element_image affects only the one placement; every other placement using the same image keeps its picture. Read-only mode refuses it.
• Name placement. set_element_image can place the element's name under the picture, the layout EA's own cloud diagrams use, instead of across it.

Vendor icon libraries

EA installs about 5,200 cloud and data-platform icons as model-pattern files. The two operations below read them in place from your own EA installation. Nothing is downloaded, and no artwork ships with AI Power Tools. find_icon searches by name; set_element_icon puts a chosen icon on a placed element.

Which libraries. The server lists the libraries it finds in your EA installation, because different EA builds ship different files. The provider and vintage come from each file's name.

A library whose name matches no known family is listed under Other. A vintage the server does not recognize ranks after every known one and is treated as oldest, never as an error.

Where the libraries come from. The server reads the ModelPatterns folder of your EA installation. An administrator can point it at a different folder by setting EA_MODEL_PATTERNS, which takes precedence. If no folder holds icon libraries, both operations return icon_libraries_not_found, and a machine without the libraries cannot use them.

What is stored where.

How matches are ranked. find_icon returns matches best first, and says which kind each is.

Within each kind, the provider's newest vintage comes first, so the same glyph often appears once per vintage. A search for storage puts a literal Storage icon above Cloud Storage, which is only a normalized match. The server ranks; choosing among the candidates is the AI's judgment, and it should show you the candidates when more than one fits.

Notes

• Do not assume a caption is an icon name. A diagram caption "Amazon S3 output bucket" wants Amazon Simple Storage Service (S3) or Bucket with objects. A container labeled "Region 1" never had an icon. Search for each element's concept and prefer the newest vintage.
• Some glyphs are not in the libraries. There is no plain AWS key, for one. The right answer is to say so, not to substitute a near miss.
• Set only the icons the diagram uses. The full set is tens of megabytes.
• An icon picture is read up to 1 MB. That is the same limit add_image applies. A larger picture is not read and set_element_icon reports the icon as unreadable. In the EA build the server was checked against, the largest icon is about 158 KB.
• Same-named icons with different pictures. Several hundred icons share a name with another icon in the same library but draw differently. Those are stored with the first eight hex digits of their identifier appended in brackets, for example Azure base - Settings [1A2B3C4D], so the wrong picture is never reused. Same-named icons with the same picture share the plain name.
• Loading the artwork needs a local file (.qea or .qeax), exactly as add_image does. On a server connection or a cloud connection, the artwork is loaded through EA's Image Manager under the name this operation would use, and it is reused. The assistant does that in EA's window when it has computer use. Without it, you load the artwork, or the assistant uses set_element_image with an image you loaded.
• The element must already be on the diagram. set_element_icon does not import the library into your model and does not create elements.
• A success answer does not mean EA rendered the picture. It means the image and the placement setting were both read back. Render with verify_diagram.
• Use the icon id exactly as find_icon returns it. Treat it as opaque.

The worked scenario is Draw a cloud architecture diagram with vendor icons.

Exporting

Four ways to take a diagram out of EA. Three render through EA's own image export. The Visio export is built by the server from the diagram's geometry.

Notes on the image exports

• A render without a reload can be stale. See "Why the server re-renders before verifying" above. Ask for a refresh when the diagram may have changed from outside the session, or reload it first. For "is this right", use verify_diagram.
• get_diagram_png always returns the image bytes, so a large diagram makes a large response. Write to a file and describe it when you do not need the bytes in the conversation.
• export_diagram_image formats: PNG (default), EMF, SVG, JPEG, BMP, GIF, TIFF and TGA. An unsupported format is refused with the supported list. It reports success only if the file exists with a non-zero size, and it renders without an explicit reload, so reload first if the diagram may be out of date.
• SVG is EA's own drawing, not a reimplementation of it.

What the Visio export carries, and what it does not

The export is deliberately minimal. Visio itself is not needed to produce the file.

• Carried. One editable rectangle per element, labeled with the stereotype (in guillemets) above the name, and one connector per relationship. Page size follows the placed elements plus a margin. The scale setting, 96 EA pixels per Visio inch by default, sets the size.
• Not carried. There are no per-type shapes or stencils, no swimlanes and no BPMN shapes. Colors, fonts, custom shapes and custom images are not carried over.
• Connectors are straight lines between element centers. No waypoints, no routing, no line styles. The hidden setting is not read, so a connector hidden on the EA diagram is drawn in Visio. Only connectors with both ends placed on the diagram are emitted.
• What follows. Expect to re-skin the result in Visio. To build a Visio diagram from scratch, use AI Power Tools for Microsoft Visio, which is a separate AI Power Tools offering. For a faithful picture, use the PNG, SVG or EMF export instead.

For new work, read the manifest. export_diagram_to_visio keeps no link between a rectangle and its element, no nesting and no line routes. To redraw a diagram in another tool, or to keep a copy in step with the model, use get_diagram_manifest (Reading a diagram or a package as a manifest).

For the full import and export workflow see ea-import-export.

Diagram descriptions

A diagram's description is plain text that explains what the diagram shows, kept in the diagram's notes. It is how a screen reader, a document generator or an AI reading the model understands a diagram without seeing the picture. Every diagram can have one, whether or not the diagram ever leaves EA.

The description is generated by template from the diagram itself, with no AI judgment: the same diagram always gets the same words, so the words can be regenerated whenever the diagram changes and compared without anyone reading them. Because they are generated, they can be kept current across a whole model: one check reports which descriptions are current, out of date, missing or edited by hand, and one refresh brings them up to date while keeping what people wrote.

Each operation takes one diagram or one package. Writing covers the one package you name; add recursive to include the packages below it. The audit covers the packages below by default, so a single call reports a whole branch of the model. Diagrams a package holds include the diagrams owned by an element in it (a composite element's diagram).

What a description says. It explains what the diagram means, not how it is drawn.

There is no length limit and nothing is left out. The first sentence is at most 150 characters, so it can serve as alt text. The body follows, grouped by the diagram's groupings so that a large diagram stays readable. Everything is ordered by name, so moving a box on the diagram does not change the words.

An illustration for a Westbrook Bank application diagram. Your descriptions use the names and relationship meanings of your own technology.

Where the words come from. Business names and the meaning of each relationship come from the technology the diagram uses: a stereotype's alias is the element's kind, and a relationship stereotype's forward meaning is its verb. A stereotype EA stores under its profile name, which is not the technology's id, is matched to the technology whose definition declares that profile and the stereotype, including on a diagram that names no technology. A name that maps to no technology, or to more than one, is read from its own words with nothing removed and counted in the result as unresolved; if the technology that may own it is in the model but cannot be read, the operation reports technology_not_loaded instead. Where the technology gives a stereotype no alias, its name is split into words with the technology's prefix removed, so WBABusinessApplication reads "business application". A relationship the technology gives no meaning is described with a fixed verb for EA's own connector types (an association "is associated with", a dependency "depends on", a realization "realizes", an information flow "sends information to"). A direction rule decides which element is the subject of each sentence: the source, the target, both, or neither when the direction is not set. A relationship the technology has a meaning for reads from source to target even when its direction is not set; a plain EA connector with no direction is described as an association (or dependency, and so on) between the two, with no direction claimed.

The technology must be readable. When the diagram's technology cannot be read where the server runs, for example because it is not loaded in the model, business names are not available. The operation then writes nothing and reports technology_not_loaded, rather than replace good text with a description in base EA terms. Enable or import the technology (Specialize > Technologies > Manage Technology) and run it again.

How it is stored. The description sits in the diagram's notes between two marker lines. The closing line records the generator's version, the technology and its version, and two fingerprints: one for the words the generator last produced, one for the words as last written. Text you or anyone else wrote above or below the two lines is never altered.

Keeping descriptions current. The audit gives each diagram one status, checked in this order.

For any text that is there, generated or written by a person (the generated block and the person's text around it are read together), the audit also reports: whether text exists outside the generated block; whether the first line is longer than 150 characters or is more than one sentence; the names of elements, groupings, lanes and packages on the diagram that the text does not mention; the relationships, hidden and merged ones included, whose two ends are not named together in one sentence; whether the description is therefore incomplete (it has to explain everything the diagram holds, so there is no partial pass); and the names of elements in the diagram's package that the text mentions but the diagram does not show. These checks compare names. They find a description that leaves something out; they do not judge whether a person's text explains the diagram well.

How a refresh treats a person's edits. A refresh regenerates the text and compares it with what is stored.

A generator or technology version that differs from the one recorded counts as a change, and the result says which it was. For a needs_decision the assistant shows you the diagram's picture, the current description and the new one, and proposes a text that carries your edits into the new one. You decide. The assistant writes your text together with the two fingerprints it was shown. If the diagram changed again meanwhile the write is refused (diagram_changed), and if someone edited the description in EA meanwhile it is refused too (notes_changed), so nobody's words are lost. A bulk refresh writes what it can and lists the diagrams that wait for a decision.

replace is for a diagram that already has a description (no_generated_block if there is none) and follows the same table, so a person's edits are never discarded. The only way to overwrite a person's words is to write the text they decided. extend adds a description after a person's text (generated_block_exists if one is already there).

Notes

• Previews are the default. Create and update write nothing until you pass dry_run as false; the preview returns the text and what would happen. In read-only mode (How tools and operations work) create and update are refused, previews included; the audit is allowed.
• Only the notes and the modified date change. The write also stamps the diagram's modified date so that change reports show it. Nothing else on the diagram, and nothing in the model, is touched.
• A diagram open in EA is reloaded after the write, so its window shows the new text. Without the reload, the next save of the open diagram would write the old notes back. A diagram that is not open is not opened, and no operation here closes one.
• A diagram open in EA with unsaved changes gets nothing written. EA discards a person's unsaved changes when a diagram is reloaded or closed, and the person's next save would undo the write. The result for that diagram is open_with_unsaved_changes; save it in EA and run the operation again. A package run carries on with the other diagrams.
• An error on one diagram is that diagram's result. In a package run, a diagram with notes that are not empty (notes_not_empty, for create), broken markers or an unreadable technology is reported in its own row, and the other diagrams are still written.
• A line that holds the marker text is a marker. One that cannot be read (a changed version letter, a missing bracket) is reported as broken_markers, never as a person's text, and no second description is added next to it. Remove or repair the line in EA.
• Other results you can meet. invalid_input means the call named no diagram or package, named more than one, gave a mode that does not exist, or gave decided text without its two fingerprints (or text that looks like a marker line). write_rejected means EA refused the write and gave a reason. write_not_confirmed means EA accepted the write but the stored notes are not what was written; nothing is reloaded. read_failed is one diagram's own row when its tables could not be read in a package run or an audit; the other diagrams are still processed.
• Text for one diagram only. The decided text is written for a single diagram, not for a package.
• Names that end in a period. The checks split sentences at periods, so a name such as "Westbrook Inc. Platform" can read as two sentences.

Reading a diagram or a package as a manifest

A manifest is one complete reading of a diagram: everything another tool needs to redraw it, refresh a copy of it later, or describe it, without a request for each element. get_diagram_manifest reads one diagram. get_package_manifest reads every diagram in a package and describes each element once. Both only read. They are allowed when the repository is in read-only mode.

What you get back

• The diagram. Name, GUID, base type, the language and diagram type it belongs to, the package and its path, the last modified date, the version and the diagram's notes as stored. Every key that verify_diagram returns is there with the same meaning, so a checker that reads a verification reads a manifest unchanged.
• The repository. The identifier EA gives the model, which copies of one model share, and the connection. A password in a connection is masked.
• Every shape. The element it stands for (its GUID, name, EA type, kind, stereotype and tagged values), its stacking number, its fill, line and font, its picture if it is drawn as one, and the diagram it opens if it owns one. The kind says whether it is an element, a note, a text item, a boundary, a port or a package. The stereotype is the qualified form EA stores; this is the one place where the value differs from verify_diagram, which returns the stored column. The bare stereotype name is given beside it.
• Where it is. The rectangle exactly as EA stores it, and the same position in one declared frame: diagram units, 96 to the inch, the origin at the top left and y increasing downward. EA stores the top edge as a negative number; the frame converts it. A rectangle stored with its top below its bottom is drawn by EA from the lower edge, and the frame follows the drawing. A positive stored top, which an earlier placement call wrote, is drawn by EA at a fallback position that the stored rectangle cannot give; the frame keeps the stored value, and the shape is reported as not found in the picture.
• What is inside what. A shape's parent and how that is known. When the element's parent in the model is also on the diagram, that is the parent, and the basis is the model. Otherwise it is the smallest boundary or container whose drawn rectangle holds the shape's center, and the basis is the drawing. EA stores nothing about what a boundary encloses, so the second kind is read from the picture of the diagram, and the two bases are kept apart.
• Every line. The connector's GUID, type, stereotype, name and direction, the two elements and the two shapes it joins, its style, color and thickness, whether it is hidden, the labels with their offsets and, where EA stored the route, the points of the line in the same frame, both ends included (the route EA stores holds the bends only). About one line in six is routed by EA when it draws and has no stored route; the manifest marks such a line as drawn only, with no points, and leaves the routing to the tool that redraws it. Lines hidden by a collapse are listed as hidden.
• Swimlanes and note links. Each lane with its name, order and the elements in it. A note link is a line of its own kind.
• Display settings. Whether connector labels, element and connector stereotypes, attribute types, operation return types and brackets are hidden, and whether element notes are shown, and which presentation profile (detail, review or executive) those settings amount to, if exactly one.
• A description. The generated description stored in the diagram's notes when there is one, so a person's edits to it travel with the manifest, and otherwise the text Diagram descriptions would write. The manifest says which. When the diagram's language cannot be read on the machine running the server, the description is left out and the manifest says why; the rest of the read is unaffected.

Stored size is not drawn size

EA grows a box to fit a name it cannot break, and only its picture shows it. With the picture, each shape also carries the box EA drew for it, given only where it differs from the stored rectangle by more than two units, and whether the shape was found in the picture. A shape that is not found is reported as such and never guessed at. The picture has no identifiers, so shapes are matched by geometry: the picture's origin is taken from the shapes that are drawn at their stored size, and a shape belongs to the placement whose top-left corner it starts at. Two kinds of shape are not found: a figure drawn inside a larger rectangle, such as an actor, and a text item, which draws text and no shape. Where a box is drawn at another size, nesting and the end points of its lines are worked out from the drawn box.

The picture, and EA's window

• The picture is on by default for one diagram and off for a package. A package read with no picture is database queries only. It opens nothing in EA and reports nothing about a window. Ask for the picture when the drawn sizes or the pictures are needed.
• With the picture, the diagram is reloaded, rendered and closed. EA renders from a cache, so the reload comes first; if it fails no picture is taken. A diagram that was already open in EA stays open. A diagram that was not open is not left open, whatever the render does.
• A diagram open in EA with unsaved changes is neither reloaded, rendered nor closed. EA throws away unsaved changes on reload and on close, with no warning, and a picture taken without a reload can show a stale or unsaved state. The manifest is still read from the stored diagram, no picture is taken, no drawn sizes are reported, and the result says the diagram is open with unsaved changes. In a package read the other diagrams carry on.
• EA shortens a long tab name. The check for an open diagram allows for that. When it cannot tell whether a diagram is open, it treats the diagram as having unsaved changes, which is the reading under which nothing is touched.

Notes

• The package rule. A package holds every diagram that belongs to it, including a diagram that an element in it owns (a composite diagram). Such a diagram names its owner.
• One entry per element. In a package read, each element appears once in a section keyed by GUID, with its name, kind, stereotype, text and tagged values. Each shape in a diagram then carries the element's GUID and its placement only.
• An error on one diagram is that diagram's result. A diagram that cannot be read is listed with the reason, and the rest of the package is still returned.
• It differs from the Visio operations in its coordinates. The manifest uses diagram units from the top left. The Visio operations use inches from the bottom left.
• It does not replace export_diagram_to_visio for a quick file, but it is the route for anything that must keep each shape tied to its element or be refreshed later (Exporting).
• What it cannot see. It does not trace lines that EA routes itself, and it does not decode hyperlink or legend objects.

For taking a diagram into another tool see ea-import-export.