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 parent overrides.
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 (Advanced)
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, but distinct, resources, 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 (except children, see note below) 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.
Resources that implement abstract resource can define their own children in addition to children defined by the inherited resource. A defined child resource will replace an inherited child resource if they have the same id/name.
Abstract resources can implement other abstract resources, but only from abstract resources that are higher in the resource tree.