icon
menu

Creating Your First Ilograph Diagram

In this step-by-step tutorial, we will create, edit, and save a simple Ilograph diagram.

Creating a diagram

Click here to create a new Ilograph diagram if you have not already done so. Your new diagram is pre-populated with a handful of resources and a sample perspective. The diagram’s source code, which we will be editing, appears in the black panel on the left:

A new Ilograph diagram

Making some simple changes

Let’s get started by making some very simple edits to the code and observing how they change the diagram. At the highest level, the source code has two sections: resources and perspectives. The resources section defines what the resources (blocks) are in your diagrams, while perspectives defines how they are related to each other.

At the very top of the source, the very first resource that is defined is called Users. It corresponds to the Users block that appears in the diagram:

An Ilograph diagram with a resource highlighted

Changing a resource’s color

Userscolor attribute is currently defined as “Gray”. Change that to “Green”. The text and icon color of Users should now be green:

An Ilograph diagram with a green resource

Changing a resource’s subtitle

Users also has the subtitle attribute, which defines the smaller text that appears below the resource name:

An Ilograph diagram with an unedited subtitle

We can change this to anything we wish. Change the value to “Our awesome users”; the subtitle in the diagram should immediately reflect this change.

An Ilograph diagram with an edited subtitle

We will cover changing a resource’s name later.

Changing a resource’s icon

Resources can optionally have icons. For instance, Service A has its icon defined on line 14:

The resource's icon definition

Ilograph comes with built-in icons for AWS, Azure, GCP, and generic networking. Let’s change Service A’s icon to something else. First delete the current icon value, then type Ctrl+space to start the autocomplete. From there, you can browse the icons to select one:

The autocomplete can also be used to search. If you know the name of the icon you’d like, just start typing it:

Creating a new resource

Next, let’s define a new resource that can be used in our diagram. We define this new resource alongside the others in the resources section of our source code.

Find again the service named Service A in the resources section. Copy the three lines that make up its definition like so:

Selecting text in code part 1 Selecting text in code part 2

Paste these three lines immediately below (make sure the indentation matches) and change the name of this new resource to “New Service”. Also, give this attribute a color. Choose any color you like (below I’ve picked “DarkCyan”). The result should look like so:

Pasting code

Our resource now exists, but we cannot yet see it in our diagram because it has not been added to any perspectives. We’ll do this in the next section.

Adding the new resource to the perspective

Our sample diagram has a single perspective called Dependency. It is the perspective we are currently viewing, and it is defined in the perspectives section of our source code. This section appears after all of our resource definitions:

Persepctives highlighted

This perspective is a relational perspective, meaning it defines a set of relations that are then rendered in the diagram. The very first relation defined is from Users and to Service A and Service B. This relation results in the highlighted part of the diagram:

Relations highlighted

Adding our new resource to this perspective is as easy as including it in this existing relation. Do so by adding New Service to the to field of this relation like below. Notice that New Service now appears in the diagram.

Adding a new service

We can also define an entirely new relation if we wish. Create a new relation from New Service and to Data Store X. Also, give this relation a label of your choice (below I picked “Write”):

Defining a new relation

Renaming a resource

Resources are defined in the resources section and are referenced by name in perspectives. Manually renaming a resource will not update those references, which can cause problems. For example, if you manually rename the Data Store X resource to New Data Store in the resources section, you’ll see three warnings in the perspective section:

Warnings after manually renaming a resource

These warnings happen because these relations are referencing a resource (Data Store X) that no longer exists. You can manually update those references, however, there is a better way.

Instead of manually renaming Data Store X, select the name: Data Store X line in the editor, and a blue “Rename resource” button will appear:

The blue rename button

Click it to bring up the “Rename resource” dialog:

The rename resource dialog

Rename this resource to New Data Store in this dialog. All references in your perspective(s) will be automatically updated!

Diagram with updated resource names

Saving your diagram

When you’re ready to save your changes, click the “Save changes” link at the top of the source panel. The first time you save, you will be prompted to choose a name for your diagram. If you have not already done so, you first will be asked to create an account and choose a user name.

Sharing your diagram

Once saved, diagrams can be shared with others. To do so, click the “Share diagram” button in the top-right of the app. In this dialog you can add viewers or create a team workspace.

The share dialog

Next steps

From here you can continue to create resources and add them to this perspective. You can also add additional perspectives to show different ways your resources relate and interact with each other. Learn more about the resource tree and perspectives. For a complete breakdown of Ilograph source, see the Ilograph spec.