Resources and the resource tree

A resource is anything that provides value to a system. Resources are the building blocks of Ilograph diagrams; they define the “what” that a diagram models. While a resource is defined only once in an Ilograph diagram, it can appear in multiple perspectives.

When described in IDL (the Ilograph Diagramming Language), resources have a name, subtitle, color, and other properties. Only the name property is required. The name of a resource also serves as its identifier unless an explicit id is specified (see below).

Resources are defined in a tree-like structure called the resource tree. In IDL, the resource tree is defined under the top-level resources property. A resource can have many child resources, but a resource can have only one parent resource. In the following IDL sample, the red resources are parent resources:

# Start of IDL
resources:
- name: WonderApp Users
  subtitle: End users
  color: navy
  style: plural
- name: AWS
  subtitle: Cloud service provider
  children:
    - name: Tech Company Account
      subtitle: AWS Account
      children:
        - name: WonderApp VPC
          subtitle: Virtual Private Cloud
          children:
            - name: Alpha
              subtitle: EC2 Instance
              color: peru
            - name: Bravo
              subtitle: EC2 Instance
              color: peru
            - name: Load Balancer
              subtitle: Application Load Balancer
              color: green
        - name: WonderApp Store
          subtitle: S3 Bucket
          color: red

perspectives:
- name: Service
  color: navy
  defaultRelationLabel: Requests
  relations:
  - from: WonderApp Users
    to: Load Balancer
  - from: Load Balancer
    to: Alpha, Bravo
  - from: Alpha, Bravo
    to: WonderApp Store

When this ilograph is rendered, the parent resources appear as context resources in the perspective. Context resources convey important contextual information about the perspective to the viewer, among other benefits.

Note that the context resources (AWS, Tech Company Account, and WonderApp VPC) appear even though they aren’t directly referenced in the relation list (colored above in blue). By default, all perspectives will render context resources based on the resource hierarchy. We can override this behavior on a per-perspective basis using perspective overrides.

Resource Identification

In most cases, a resource can be referred to by its name property. However, if a resource’s name contains a restricted character (/, ^, *, [, ], or ,), the resource’s id property must be defined. The resource is then referred to by this id. The id property cannot contain restricted characters.

Two resources that share a parent cannot have the same name (or id, if defined).

Resource Inheritance

Resource inheritance is an advanced technique used to reduce repetition when creating Ilograph Diagrams.

Often, resource trees will have multiple instances of the same kind of resource, leading to lots of repetition. For example, when diagramming a computer network, you might have many identical network switches, each with the same number of ports. More specifically, if you had two identical 3-port switches, named Switch A and Switch B, it would look like the following when defined in IDL:

resources:
- name: Switch A
  subtitle: Network Switch
  color: navy
  description: A three-port switch
  abstract: true
  children:
    - name: Port 1
    - name: Port 2
    - name: Port 3

- name: Switch B
  subtitle: Network Switch
  color: navy
  description: A three-port switch
  abstract: true
  children:
    - name: Port 1
    - name: Port 2
    - name: Port 3

Being identical resources (but not the same resource), Switch A and Switch B have identical properties. We can cut down on this repetition, and formalize this “is-a” relationship, using resource inheritance. We’ll start by declaring a new resource, called Switch, and declaring it as abstract:

resources:
- name: Switch
  subtitle: Network Switch
  color: navy
  description: A three-port switch
  abstract: true
  children:
    - name: Port 1
    - name: Port 2
    - name: Port 3

Next, we’ll redefine Switch A and Switch B to be instances of Switch:

resources:
...
- name: Switch A
  instanceOf: Switch
  
- name: Switch B
  instanceOf: Switch

And with that, both Switch A and Switch B have all the properties of Switch, including its children. If desired, we can override any of the inherited properties by simply defining them on Switch A or Switch B.

Both switches and their ports can be referenced in perspectives as usual. Abstract resources, however, cannot be referenced in perspectives. We’ll round out this example by adding six Terminal resources and use them all in a simple perspective, called Network:

resources:
...
- name: Alpha
  subtitle: Terminal
- name: Bravo
  subtitle: Terminal
- name: Charlie
  subtitle: Terminal
- name: Delta
  subtitle: Terminal
- name: Echo
  subtitle: Terminal
- name: Foxtrot
  subtitle: Terminal
    
perspectives:
- name: Network
  relations:
    - from: Alpha
      to: Switch A/Port 1
    - from: Bravo
      to: Switch A/Port 2
    - from: Charlie
      to: Switch A/Port 3
    - from: Delta
      to: Switch B/Port 1
    - from: Echo
      to: Switch B/Port 2
    - from: Foxtrot
      to: Switch B/Port 3

Notice that we reference the resources as usual here; perspectives are agnostic to whether resources use inheritance or not. When rendered, this example looks like so:

You find this complete example in the ilograph app.

Detailed inheritance rules

  • You can define abstract resources at any level in your resource tree.

  • Resources can implement abstract resources it shares a parent, grand-parent, etc. with. In other words, the abstract resource must be at the same level or higher in the resource tree than the implementing resource.

  • Multiple inheritance is not supported.

  • Abstract resources can implement other abstract resources, but only from abstract resources that are higher in the resource tree.

Last updated on 2 Feb 2020
Published on 2 Feb 2020