References

When defining relations is perspectives, resources are identified by name (except in rare cases when a resource has the id property specified). If a resource name (or id) is unique in an Ilograph diagram, then it can be referenced by name without any qualifiers. If it is not unique, then references to it will need to be qualified in terms of its ancestor resources.

If two or more resources have the same name, they can be distinguished by specifying their parent(s) using xpath-like expressions. To demonstrate this, consider two AWS regions and their availability zones in a resource list:

resources:
- name: AWS
  subtitle: Cloud service provider
  children:
  - name: us-east-1
    subtitle: Region
    color: green
    children:
    - name: AZ1
      subtitle: Availability Zone
      color: darkgreen
      
    - name: AZ2
      subtitle: Availability Zone
      color: darkgreen
      
  - name: us-east-2
    subtitle: Region
    color: green
    children:
    - name: AZ1
      subtitle: Availability Zone
      color: darkgreen
      
    - name: AZ2
      subtitle: Availability Zone
      color: darkgreen

  - name: Alpha
      subtitle: EC2 Instance
    - name: Bravo
      subtitle: EC2 Instance
    - name: Charlie
      subtitle: EC2 Instance
    - name: Delta
      subtitle: EC2 Instance

Notice that the AZ1 and AZ2 resources appear twice each; they are identical except for their parent resources (us-east-1 and us-east-2). We’ll create a new perspective (called Availability Zone) and reference these resources:

perspectives:
- name: Availability Zone
  color: green
  defaultArrowLabel: Runs in
  relations:
  - from: Alpha
    to: us-east-1/AZ1
    
  - from: Bravo
    to: us-east-1/AZ2
    
  - from: Charlie
    to: us-east-2/AZ1
    
  - from: Delta
    to: us-east-2/AZ2

We’ve distinguished the different availability zones by pre-pending the parent resource, followed by a forward slash. This can be done using as many hierarchy levels as needed. When rendered, this perspective looks like so:

To reference any descendant resource of a parent resource, use two forward slashes in succession. Consider the following example:

relations:
    ...
    to: us-east-1//Load Balancer
...

In this reference will match a Load Balancer resource that is any descendant resource of a us-east-1 resource. The Load Balancer need not be a direct child of us-east-1.

Resource references that are ambiguous (that is, they refer to more than one resource of the same name or id) are allowed in Ilograph source. Ambiguous references will resolve to one of the referenced resources. Which specific resource is resolved in these cases is not defined. See the next section on how to reference multiple resources at once.

Aliases allow you to give a convenient name to resource reference(s). Typically, the alias is for a comma-seperated list of references. Aliases are defined and used in perspectives like so:

# ...
perspectives:
- name: My Perspective
  # ...
  aliases: 
  - alias: RACK_A_SERVERS
    for: NY-WEB01, NY-WEB03, NY-WEB05, NY-WEB07, NY-WEB09, NY-WEB11
  # ...
  relations:
    - from: Main Server
    - to: RACK_A_SERVERS

Alias IDs are declared in all-caps by convention, but this is technically not required. These IDs can be used in the perspective anywhere resource references are used. The Physical Datacenter Architecture demo shows alias in action.