Skip to main content

Model elements

Introduction​

Model elements are the basic building blocks used to represent various parts of the software architecture. Relationships, in turn, play a central role in modeling the interaction between these model elements. Following the principles of C4 methodology, they can be categorized into actors, systems, containers, and components. By organizing the architecture into different model elements and their relationships, architects can create a shared understanding of the system structure and dependencies.

Model elements are represented as cards in diagrams.

Overview​

This page provides you with an overview of all model elements within the project:

  • Actors
  • Systems, can contain one or more...
  • Containers, can contain one or more...
  • Components
  • Groups (used to thematically group model elements in diagrams)

The table can be viewed as a tree table, visualizing the dependencies between containers and their respective system, as well as between components and their respective containers; or as a plain data table. You can find the button to switch between these views on the right side of the table toolbar, next to the Create model element button.

You can view the details of a model element by clicking on the respective row within the table or using the table row action Show details. This opens a second column to the right of the table where the following information can be accessed:

  • 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 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. In a diagram, these relationships are visualized as arrows between model element cards.
  • Loop: Here, you can find links and connections to other parts of the project.

Additionally, you can find the following actions in the overflow menu of the details:

  • Share model element: This open a dialog where you can copy the model element's URL or share it directly via email.
  • Create new project: Directly create a new service project based on the information that has been given. Only available for containers.
  • Open spotlight: Opens the Spotlight view of this model element where you can see all incoming and outgoing relationships of the element, regardless of diagrams.
  • Delete model element (see Delete a model element below)

Create a model element​

Model elements that have been created within the diagram modeling tool (see Diagrams) are automatically displayed within the model elements overview. Additionally, it is possible to create new model elements from the Model elements overview page. These model elements are then also available in the diagram modeling tool.

To create a new model element, use the Create capability to the right of the table tool bar.

Model elements are defined using the following master data:

  • Type: Choose the type of the model element (Actor, System, Container, or Component; required)
  • Label: The name of the model element (required)
  • File name: Unique identifier for the model element that is used in the repository to where it is saved. If not specified by the user, the Label is used as a base for the File name (required)
  • Domain: Business domain to which the model element belongs (optional)
  • Scope: A model element can be marked as Internal or External for further differentiation. Only available for Actors and Systems (required)
  • Container type: A Container can be classified as Application or Datastore. This option is not available for other model element types (required)
  • Summary: A short summary of the element that will also be displayed in the cards within a diagram (optional)
  • Description: This is a longer description of the model element and its role within the diagram (optional)
  • Tags: To tag the model element (optional)
  • Icon: Name of the icon used on the model element card in the diagram(s). If not specified, the standard icon for the respective model element type will be used (optional)
❗️info

Groups can only be created within the modeling tool, since they thematically group elements independently from systems or containers.

Browse Git projects to create new model elements​

Model elements can also be created by referencing existing Git projects. To visualize existing Git projects as System, Container or Component on diagrams click the Browse Git option of the Create model element button.

In the action you will first have to select the Git provider and repository group before the projects of the selected repository group are displayed. For one or more projects you now can decide to create a model element. Available model elements for a project are System, Container or Component.

The model elements created this way will use the chosen projects name and description. A link to the project itself is also created automatically and shown in the section Implementation of the Loop tab.

Edit a model element​

All editable fields can be directly edited within the details view of a model element. You can view the details of a model element by clicking on the respective row within the table or using the table row action Open details. This opens a second column to the right of the table where all information can be accessed and changed.

Delete a model element​

The capability to delete a model element can be found in overflow menu at the end of each table row, as well as in the overflow menu of the details section of each model element.

⚠warning

When you delete a model element, it is also removed from all diagrams in which it is used. You will need to confirm the action before the selected model element is permanently deleted.

Loop​

Connect model element to architectural decision​

In the Loop tab of the details, you can link a model element to a specific decision within your project. Just click on the Add decision capability and select the decisions you want to connect to the model element.

Connect model element to implementation project​

You can also add implementation projects and/or Git projects to your Loop to document the implementation of your System, Container, or Component. Just click on the Add project button in the Implementation section. You can then choose between the following options:

  • Add project: Select one or several implementation project(s) within your IBM DevOps Solution Workbench to be connected to your model element. This will create one link to the internal implementation project (service project) as well as one link to the corresponding Git repository.
  • Add Git repository: Select one or several Git repositories after specifying a Git provider and repository group.

Allows users to add, view, and remove external URLs in the "Links" section of the Loop panel for model elements. Users can easily associate relevant resources by adding links through a simple interface, and can access these resources by clicking on the link