Skip to main content

Modeling tool

Modeling tool​

A click on the Label of a diagram will open it in the Modeling tool. This tool is designed to help software architects create, manage and refine architectural diagrams with ease.

In the top right corner of the page, there is an overflow menu. Here, you have the following options concerning the diagram as a whole:

  • Show details: Display the diagram details in the modeling tool
  • Share diagram: This opens a dialog where you can copy the diagram's URL or share it directly via email.
  • Clone diagram: Creates an exact copy of your diagram (see Clone a diagram)
  • Export as PNG: Export your diagram as an image in the PNG file format
  • Clean up diagram: Clean up corrupted and unused data from the diagram (such as one-sided connections, non-existent parents or unused relationships). Such inconsistencies can for example occur due to changes on file level when altering or deleting model elements directly in their Git repository and not updating the diagrams accordingly.
  • Delete diagram: Delete the whole diagram. You will need to confirm the action before the diagram is permanently deleted.

The modeling canvas​

The canvas is the central workspace of the modeling tool. It provides an interactive, drag-and-drop environment to easily add, position, and connect model elements such as systems, containers, components and actors.

You can click anywhere and drag the canvas in order to navigate through the diagram.

In the top left corner, you find capabilities to

  • Toggle selection mode
    • When selection mode is on, you can select several cards at once to reposition them on the canvas. Expanded systems/containers can be moved as a whole by clicking and dragging the icon appearing in the top right corner of their frame. The selected group of elements as a whole can also be copied , inserted and deleted via common keyboard shortcuts.
    • In normal mode, you can move freely around on the canvas by click and drag.
  • Toggle the interactivity of the diagram, e.g. for presentation or overview purposes
  • Auto layout with further options to adjust your view
  • Undo and Redo
  • Configure cards: Customize the title, text, additional values and tags of the model elements in this diagram. Custom fields are available as well.

In the bottom left corner, a mini map visualizes which part of the diagram is being displayed on the canvas at the moment. You can also use this mini map to move around the canvas and adjust the zoom level. The Fit view functionality sets the zoom level and canvas to the optimal settings to view as much of your diagram as possible. You can also Hide the mini map here.

Adding model elements​

In the top right corner of the canvas, you can find a (+) button with which new elements can be added to the canvas.

  • New elements can be found at the top of the menu. You can directly enter a label for the element and add it to the canvas; alternatively it is also possible to just drag-and-drop an element from the list into the canvas and name it afterwards.
  • Available elements lists all model elements that already exist in the project (see Model elements) and are available to be used in the diagram. They are sorted by type (Actors, Systems, Containers, Components).

Editing model elements​

With one click on a model element card, you can open its details; here you can view and edit the same information that is also provided in the Model elements overview:

  • Details: Master data of the model element (see also Create a model element); all writable fields are editable here as well.
  • Usages: Displays where the model element is already in use. This can be Diagrams and/or Groups within diagrams to which the element has been added, as well as Systems (for Containers) or Containers (for Components), if the element is already part of a system/container.
  • Relationships: This tab comprises all Incoming and Outgoing relationships to other model elements of the project (from all diagrams). In a diagram, these relationships are visualized as arrows between model element cards. You can also easily add available relationships already established in other diagrams to the canvas at hand by clicking on the + icon of the card.
  • Loop: Here, you can find links and connections to other parts of the project.

All changes that are done here are automatically reflected in the Model elements overview, and vice versa.

Managing model elements​

When clicking on a model element, a menu with different options is displayed above the element, depending on its type. Alternatively, you can also right-click on a model element to access the same actions.

  • Copy: Copy a model element, also via CRTL+C
  • Cut: Cut a model element, also via CRTL+X
  • Paste: Paste a model element, also via CRTL+V
  • Clone: Clone a model element. This creates a new model element with the same data but a new identifier.
  • Select color: Change the color of the model element card in the diagram(s). If not specified, the default colors (grey + specific accent color) for the respective model element type will be used.
  • Drill up or Drill down: If there are diagrams for levels above or below this model element, you can directly drill up/down from here.
  • Normal view mode and Expanded view mode: Changes the view of a system or container between normal view and expanded view to add elements inside (read more about this here). Please be aware that only one card can be displayed in expanded view at the same time if you put the same system or container into one diagram several times.
  • Open spotlight: Opens the spotlight of this model element in an overlay over the canvas (close via the X icon or ESC)
  • Add available relationships: Adds all available relationships of the model element that are not set on the diagram.
  • Create diagram: Create a new diagram of the next level for this model element.
  • Create new project: For containers, a new implementation project can directly be created from the model element
  • Detach from group/system/container: Detaches this model element from the parent or group it is currently placed in, so that it can be moved out of the parent model element or group.
  • Update Children: Synchronizes the group or the expanded system/container with the child elements of the model element. Non-existent child elements are added and elements that should no longer exist are deleted. In addition, the available relationships that are not set in the diagram are added to the child elements.
  • Bring to front: Brings the model element to the very front so that it is displayed above all other elements in the diagram.
  • Bring forward: Moves the model element one level forward in the overlay order.
  • Send to backward: Moves the model element one level backward in the overlay order.
  • Send to back: Moves the model element to the very back so that it is displayed below all other elements in the diagram.
  • Remove from diagram: Removes the model element from this particular diagram. You can still find it in the available model elements. Can also be achieved by using DEL.
  • Delete from project: Deletes the model element from the project. You will need to confirm the action before the selected model element is permanently deleted.

Removing and deleting model elements​

In the model element details, you can also access the capabilities to Remove the model element from the diagram and Delete the model element from the project altogether in the overflow menu of the details header.

⚠warning

If you delete a model element, child model elements inside are not going to be affected. You will need to confirm the action before the selected model element is permanently deleted.

All changes that are done here are automatically reflected in the Model elements overview, and vice versa.

Connecting model elements (Relationships)​

Each model element card has two nodes for adding relationships. Just click on the bottom node and drag the cursor to the top node of the model element you want to connect it to. The Incoming and Outcoming endpoints are immediately reflected within the Relationships tab of the model elements details as well. You can specify the type of relationship between the two elements by clicking on the relationship and entering a label in the sidebar.

Relationships can easily be removed by selecting them and using the DEL key on your keyboard. As long as a relationship between two elements is used at least once in the project, it will always be displayed in the Relationships tab of the corresponding elements.

❗️info

If you remove a relationship between two model elements, it does not get deleted as a whole, but will be re-added automatically if you connect the two elements again.

Relationships that have already been established in other diagrams can also be added to the canvas. There are several ways to do this:

  • Add one specific relationship by selecting the Relationships tab of a model element and clicking on the + icon of the desired relationship.
  • Add all available relationships of a model element by selecting Add available relationships in a model element's context menu (by selecting a model element or right-clicking on it).
  • Add all available relationships for the current diagram by right-clicking on the canvas and selecting Add available relationships.

Creating additional levels of a diagram​

A system model element can comprise one or several containers, and a container can comprise one or several components. In order to correctly reflect these connections, a new corresponding diagram must be created.

If you want to further model a system, right-click on the system card and select Create diagram in order to create a new Container diagram (Level 2) for this system. The new diagram level will automatically be displayed. The system card will become larger and can be adjusted in size; containers can then just be dragged an dropped into the system. The same procedure applies to containers and their components (Level 3 - Component diagram).

If there already are one or several corresponding diagrams (indicated by an arrow in the bottom right corner of the model element card), you can drill down into the next level by right-clicking on the card and selecting Drill down. You can then select the diagram to which you want to drill down. To drill back up to the former diagram click on the arrow icon in the top left corner of the canvas header, next to the title.

❗️info

It is possible to have several systems in a container diagram (and several containers in a component diagram) and to expand each of them them to add further model elements inside. It is, however, recommended to work according to C4 Modeling principles and use several diagrams to model specific aspects of your system architecture.

Managing model elements within other model elements​

If you add a system to a container diagram, or a container to a component diagram, and want to add elements into these parts, you first have to expand the system/container. To do this, right-click on the element you want to expand and select Expanded view mode. The card then becomes bigger and items can be moved inside. You can go back to the simple card view of a system/container by right-clicking again and selecting Normal view mode in the menu.

As soon as a model element is inside a parent model element (system, container, or group), it cannot be moved outside of the parent element anymore. If you want to move an element out of a parent element, you first need to detach it. Right-click on the element you want to move and select Detach from group/system/container. The element can then be moved outside again.

Groups​

Groups are a way to visually organize and categorize model elements within a diagram, e.g. for domains or infrastructure. In the modeling tool, you can create groups to group systems and actors (level 1 diagrams), as well as containers (level 2 diagrams), and components (level 3 diagrams). They can also be placed inside systems or containers.

It is not possible to connect groups to other model elements via relationships.

Notes​

You can use notes to add more context to your diagram, add preliminary information, or model more generic parts of your diagram.

With one click on a note, you can open its details. Here, it is also possible to give a title, a description and tags to the note (optional). Additionally, you have the following options both in the details and in the context menu of a note on the canvas:

  • Copy: Copy a note, also via CRTL+C
  • Cut: Cut a note, also via CRTL+X
  • Paste: Paste a note, also via CRTL+V
  • Convert to model element: Convert your note into a model element. The note content can be moved to the new element's label, summary, or description field.
  • Select color: Change the color of the note. If not specified, the default color (Yellow) will be used.
  • Bring to front: Brings the note to the very front so that it is displayed above all other elements in the diagram.
  • Bring forward: Moves the note one level forward in the overlay order.
  • Send to backward: Moves the note one level backward in the overlay order.
  • Send to back: Moves the note to the very back so that it is displayed below all other elements in the diagram.
  • Delete: The note is deleted from the diagram.
❗️info

Notes are specific to a diagram and cannot be reused in other diagrams. To reuse it in another diagram, convert the note into a model element first.

Notes can be connected to other notes, shapes as well as to model elements on the canvas. Just click on one of its nodes and drag the cursor to a node of the note, shape or model element you want to connect it to. These connections can be defined using the following master data:

  • Label: The label to indicate the purpose or reference (optional)
  • Description: This is a description of the connection (optional)
  • Tags: To tag the connection (optional)

Shapes​

You can use shapes to display complex data, information or relationships in your diagram in a clear and easy-to-understand manner.

With one click on a shape, you can open its details. Here, it is also possible to give a title, a description and tags to the shape (optional). Additionally, you have the following options both in the details and in the context menu of a shape on the canvas:

  • Copy: Copy a shape, also via CRTL+C
  • Cut: Cut a shape, also via CRTL+X
  • Paste: Paste a shape, also via CRTL+V
  • Clone: Clone a shape
  • Convert to model element: Convert your shape into a model element. The shape content can be moved to the new element's label, summary, or description field.
  • Select shape: Change the shape type of the shape.
  • Select color: Change the color of the shape. If not specified, the default color (Cyan) will be used.
  • Bring to front: Brings the shape to the very front so that it is displayed above all other elements in the diagram.
  • Bring forward: Moves the shape one level forward in the overlay order.
  • Send to backward: Moves the shape one level backward in the overlay order.
  • Send to back: Moves the shape to the very back so that it is displayed below all other elements in the diagram.
  • Delete: The shape is deleted from the diagram.
❗️info

Shapes are specific to a diagram and cannot be reused in other diagrams. To reuse it in another diagram, convert the note into a model element first.

Shapes can be connected to other shapes, notes, as well as to model elements on the canvas. Just click on one of its nodes and drag the cursor to a node of the shape, note or model element you want to connect it to. If a shape is connected to another shape or model element, the direction of the arrow can be changed using the "Change direction" action in the context menu. These connections can be defined using the following master data:

  • Label: The label to indicate the purpose or reference (optional)
  • Description: This is a description of the connection (optional)
  • Tags: To tag the connection (optional)

Creating a service project for a container​

For container model elements, you can also directly create a service project for subsequent implementation. Create new project can be accessed via right click on the container in the canvas, as well as from the overflow menu of a container's details view.

Diagram Assistant (beta)​

When using the Modeling tool to create diagrams, the Diagram Assistant helps to get insights about the diagrams and create the diagrams faster. It offers various useful capabilities to understand the existing canvas content and complement it.

The Diagram Assistant is available via the purple AI button on the canvas or the context menu. If nothing has been selected, the whole diagram is considered as input for the action. To only focus on a specific part of your diagram, please switch to the selection mode and select the desired items.

The following capabilities are available:

  • Explain diagram - Describe the architectural scenario on the diagram.
  • Describe as solution option for ADR - Describe the diagram as solution option for a decision.
  • Propose changes - Explain proposed changes to realize the scenario.
  • Suggest stories - Suggest Jira stories to implement the scenario.
  • Suggest improvements - Find and list ideas to improve the described approach.
  • List advantages - Find and list advantages of the described approach.
  • List downsides - Find and list downsides of the described approach.

After triggering the capability, the result is displayed in a sidebar, from where you can:

  • add it as a note on the diagram
  • copy it to the clipboard
  • go back to trigger another action

If you want to perform a different action on the diagram data you can also choose the button for custom actions. You can use it to e.g. phrase your own questions or ask the system to generate text for you, specifically for your custom needs.

❗️info

To make use of the Diagram Assistant, it is required that you have an OpenAI API key set up for your user. To do that, please follow the steps described here.

The AI-based capabilities are based on gpt4o, provided by OpenAI. Read more about AI infused capabilities in the IBM DevOps Solution Workbench here.