Advanced References
This page documents the following advanced techniques for referencing resources in perspectives:
Multi-reference matching is used to match multiple resources using a single reference. It is useful for cutting down on repetition in relation perspectives.
As explained in the previous section, references normally resolve to a single resource, even if multiple resources have the same identifier in the resource tree. For example, the following perspective code:
resources: - name: Main Server icon: Networking/laptop.svg - name: Switch A children: - name: Port 1 - name: Port 2 - name: Port 3 - name: Switch B children: - name: Port 1 - name: Port 2 - name: Port 3 - name: Switch C children: - name: Port 1 - name: Port 2 - name: Port 3 perspectives: - name: Connections relations: - from: Main Server - to: Port 1 # Matches only one instance of Port 1
will produce the following diagram:
As shown, only one instance of Port 1 appears connected to Main Server.
To have this relation instead go to all Port 1s, surround the resource ID in square brackets like so:
relations:
- from: Main Server
- to: [Port 1] # Matches ALL instances of Port 1
This will produce the following diagram:
Note that square brackets can used when referencing parents, children, and descendants:
relations:
- from: Main Server
- to: Data Center 1//[Port 1] # Will match ALL instances of Port 1 that are descendants of Data Center 1
Wildcards (*s) can be used with multi-reference matching like so:
relations:
- from: Main Server
- to: [Port *] # Matches ALL Ports
Wildcard matching can be combined with parent/children/descendant references:
relations:
- from: Main Server
- to: Switch A/[Port *] # Matches ALL Ports that are direct descendants of Switch A
Wildcards can begin at the beginning, middle, and end of the query. Multiple wildcards in one query are allowed.
For examples of multi-reference matching, see the Physical Datacenter Architecture demo diagram.
Relative references is another advanced method to reduce repetition in relational perspectives.
Consider a model of three identical systems (System 1, System 2, and System 3), each with a firewall, a load balancer, and two “instances” (Instance A and Instance B):
resources:
- name: System
icon: Networking/computer-network.svg
color: RoyalBlue
abstract: true
children:
- name: Firewall
color: Firebrick
icon: Networking/firewall.svg
- name: Load Balancer
color: DarkCyan
icon: Networking/network-hub.svg
- name: Instance A
color: DeepPink
icon: Networking/server.svg
- name: Instance B
color: DarkBlue
icon: Networking/server.svg
- name: System 1
instanceOf: System
- name: System 2
instanceOf: System
- name: System 3
instanceOf: System
Using this model, we can create a perspective showing that each firewall sends traffic to its corresponding load balancer:
...
perspectives:
- name: Routing
relations:
- from: System 1/Firewall
to: System 1/Load Balancer
- from: System 2/Firewall
to: System 2/Load Balancer
- from: System 3/Firewall
to: System 3/Load Balancer
When rendered, the perspective looks like so:
While this works, there is quite a bit of repetition here. This repetiton would continue as the number of Systems increase.
We could try to cut down on this repetion using multi-reference matching (see above), replacing three relations with just one:
...
perspectives:
- name: Routing
relations:
- from: [Firewall]
to: [Load Balancer]
label: Traffic
While this is cetainly shorter, it is not equivalent to what it replaced. Since [Firewall] matches all firewalls, and [Load Balancer] matches all load balancers, the result is every firewall sending traffic to every load balancer:
This is clearly not what we intended. Instead, we want to specify that every firewall sends traffic to the load blancer in the same system. This is where relative references can be used:
...
perspectives:
- name: Routing
relations:
- from: [Firewall]
to: ../Load Balancer
label: Traffic
By prefacing the to reference with ../ we indicate that it is relative to the from reference(s) in the same relation. This is now equivalent to the first perspective, only without the repetition:
Relative references can be combined with multi-reference-matching. Below, we add another relation specifying that every load balancer routes to every instance it shares a parent with:
...
perspectives:
- name: Routing
relations:
- from: [Firewall]
to: ../Load Balancer
label: Traffic
- from: [Load Balancer]
to: ../[Instance *]
label: Routes to
With this addition, the perspective now looks like so:
Note: to reduce visual repetition, the diagram renderer may start stacking the Systems on top of each other if “Stack Similar Resources” is enabled. This can be disabled in the “more” menu (web version), or under the “View” menu (Ilograph Desktop).
Relative references are not limited to resources with shared parents. Multiple ../’s can be combined to go “up” multiple ancestors in the resource tree, like in this example:
...
to: ../../../Resource
Note that relative references can also be combined with references to any descendant resource (using the double forward-slash):
...
to: ../..//Resource
Relative references can be used in the from or to propery in a relation, but not both at once. As demonstrated in the above example, relative references are very useful when combined with resource inheritance and multi-reference-matching.
Cloning is a very advanced, and very rare, technique that allows the same resource to appear in more than one place in a perspective. It should not be confused with resource inheritance, which allows you to define similar or identical, but still distinct, resources.
Normally, a resource appears in only one place in a perspective. This is desireable because otherwise viewers might see the same resource in two places and conclude (wrongly) that they are distinct entities. There are some rare circumstances, however, where it is desireable to override this behavior. This is accomplished by resource cloning.
Resource clones are created when referencing resources in perspectives. To create a clone, simply reference a resource as normal (such as in the to field of a relation), and append a * and an identifier. Each unique identifier results in a unique clone. Below is a simple example of cloning in a perspective:
resources:
- name: Resource A
- name: Resource B
perspectives:
- name: Dependency
relations:
- from: Resource A
to: Resource B
- from: Resource B
to: Resource A *2
The resulting perspective looks like so:
The identifier can be any string; it is not restricted to numbers.
Resource clones can be used anywhere regular resources are referenced, namely in relations, sequences, and slides. Cloned resources can also be referenced in aliases, and given new parents using parent overrides.