Diagram content
Introduction
The Design Assistant can read what is drawn on a diagram and change it from the chat. A node is an element placed on the diagram. An edge is a relationship drawn between two nodes.
You can ask what a diagram shows, and you can ask the assistant to put elements on it, draw relationships, move them, change how the cards are shown, or take them off again. The assistant follows the diagram type's description in the OML profile — its purpose, which element types belong on it, and any layout conventions — and any design-recipe skill that applies to the request.
Changes are proposed in one confirmation, together with any model changes from the same request. Confirm applies them. Reject discards them. See Confirm or reject actions.
Coding assistants outside the workbench can read and change the same diagram content through the Modelling Support MCP server.
What you can do
| You want to | What to ask for |
|---|---|
| Understand a diagram | Summarize it, explain how the elements relate, or check it against its purpose. |
| Place elements | Put existing elements on the diagram as nodes, or create them and show them in the same request. |
| Draw relationships | Show relationships as edges. Placing elements also draws relationships that are not on the diagram yet. |
| Update the drawing | Move or rearrange nodes, nest them, change how a card is shown, or change which side a line attaches to. |
| Take something off | Remove nodes or edges from this diagram. Model elements and relationships stay in the project. |
| Start a diagram | Create a diagram of any configured type and fill it in the same request. |
Questions and changes apply to diagrams in the project and branch you have open.
Point the assistant at a diagram
The assistant needs to know which diagram you mean.
- The diagram you have open. Open it in the modeling tool, then say this diagram, the diagram, or here.
- A mention. Type
@and pick the diagram. See Mentions. - Its name. Use the diagram label in quotes when you cannot use a mention.
When more than one diagram matches, the assistant asks with a clarification card.
Asking to create a diagram creates a new diagram element. It does not reuse the diagram you have open.
Ask about a diagram
Use this when you want an explanation or a check, and the diagram should stay as it is. The assistant describes the purpose, the kinds of elements and how many, the main groups or nesting, and the important relationships by name.
Summarize this diagram for someone who has not seen the project.
What is on diagram "Order APIs", and which relationships between those elements are not drawn yet?
Does this system context diagram include the people and external systems its diagram type expects? List what is missing.
A check compares the diagram with the diagram type's description, any applicable design-recipe skill, and the goal you stated. It reports relationships between shown elements that are not drawn, element types the diagram type expects and does not have, and elements that do not fit. The assistant offers fixes and waits for you to ask for them.
An empty diagram is reported as empty. The assistant does not fill it until you name what to add.
Place elements as nodes
Ask the assistant to show elements that already exist, or to create them and show them in one step. Prefer @ mentions or labels in quotes so the right elements are chosen.
Add all REST APIs to this diagram, and draw their relationships to elements already shown.
Create 10 entities for travel expense management and show them on this diagram, including the relationships between them.
Create a note on this diagram titled "Open question" with the text "Confirm who approves a cancelled order."
An element that is already shown is left as it is. Ask for another copy when the same element should appear twice — for example once in an overview and once next to a specific flow.
Notes, shapes, and text belong to one diagram. The assistant creates them on that diagram and places them there.
New nodes are placed in free space next to what is already there, or next to a node you name.
Draw relationships as edges
An edge draws a relationship that exists in the model. When you place elements, the assistant also draws each relationship between a newly placed element and another element on the diagram, when that line is not there yet. Relationships you ask to create in the same request are included.
Draw the relationship from "Order Service" to "Orders API" on this diagram.
Place the entities, and do not draw their relationships yet.
Add the relationships that exist between the elements on this diagram but are not drawn.
You can name the sides the line should use: top, bottom, left, or right.
Connect "Order Service" from the right to "Orders API" on the left.
Two lines between the same two nodes use different sides. The assistant picks a free side when you do not name one.
To show the same relationship on a different pair of nodes, ask to take the line off and draw it again between the nodes you want. An existing line stays attached to its nodes until then.
Update nodes and edges
An update changes how something is drawn. The element or relationship in the model stays as it is. To rename an element, or to edit a relationship's label, description, or tags, ask for that model change. The line on the diagram keeps showing that relationship.
Move and arrange
Move "Payment Service" next to "Order Service".
Tidy this diagram. Group by domain, and read it from left to right.
Arrange this diagram from top to bottom: people, then the system, then external systems.
Describe the groups and the reading direction (top to bottom, or left to right). The assistant places the nodes so they do not overlap, and moves the connection sides of lines whose nodes moved. For the canvas layout variants, use Auto layout on the modeling canvas.
You can also ask for an exact spot or a size. A nested node's position is inside its parent.
Nest elements
Show nodes inside an expanded parent when you ask for it, or when the diagram type or a skill says that one element contains another. Nesting needs an aggregation or composition relationship between the parent and the child. The parent's type must allow that kind of relationship. Otherwise the assistant places the nodes side by side and connects them.
Show the line items inside "Order" as an expanded card.
The parent is shown as an expanded card and sized to fit its children. The aggregation or composition line between them is taken off the diagram, because the nesting already shows that relationship. The relationship stays in the model.
Notes, shapes, and text cannot sit inside another node or contain other nodes.
How a card is shown
Ask for a visualization when the default card is not what you want. The assistant keeps card until you ask for another one. A nesting parent becomes an expanded card on its own.
| You ask for | What you get |
|---|---|
| Card | Card with element type, label, and summary. |
| Mini card | Smaller card with element type and label. |
| Expanded card | Large card that can contain other nodes. |
| Text | Large card that shows the description on the card. |
Show the APIs on this diagram as mini cards.
Remove nodes and edges
Taking something off a diagram changes that diagram. Say delete or remove from the project when the element or relationship should leave the model. While you are working on a diagram, remove takes the item off the diagram.
| You ask | Result |
|---|---|
| Remove an element from the diagram, take it off, or hide it | Its node leaves this diagram. The element stays in the project and on any other diagram that shows it. |
| Remove a relationship line from the diagram | The edge leaves this diagram. The relationship stays in the model. The nodes stay. |
| Delete an element or relationship, or remove it from the project | It is deleted from the model and disappears from every diagram. |
| Remove a note, shape, or text | It is deleted. It exists only on that diagram. |
Remove all elements with tag "deprecated" from this diagram.
Remove the relationship line from "Order Service" to "Orders API" on this diagram.
Delete "Order Service" from the project.
Taking a parent node off the diagram also takes off the nodes nested inside it and the lines connected to them. Those elements stay in the project. Ask to move a nested element out first when it should remain on the diagram.
Create a diagram and fill it
Name the diagram type and what should appear on it. Diagram types come from the OML profiles of the project, including the blank canvas. See Diagrams.
Create a canvas "Order APIs" with every REST API whose label contains "order", and the relationships between them.
Create a system context diagram for travel management and show the system, its users, and the external systems it depends on.
Limitations
- Colors, line styles, arrow markers, opacity, rotation, shape title position, and stacking order (which node is in front) are changed on the modeling canvas.
- Images and freehand drawings cannot be added or changed from the chat.
- The OML shape visualization is set on the canvas. From the chat you can ask for card, mini card, expanded card, or text.
- Relationship type cannot be changed on an existing relationship. Delete it and create one of the type you want, then draw that relationship on the diagram.
- On a protected branch the assistant can explain and check a diagram. Switch to a branch you can edit before it can change the diagram.
- Responses depend on how the request is phrased. Name the diagram, the elements, and the change you want. @ Mentions keep those references precise.