We can reference attributes anywhere in our model, either in relative or absolute fashion, using FQN's (fully qualified names).
Recap: FQN's
Each element in our model tree has a displayName and an internalName attribute. Display names allow capitalizations, spaces, some special characters. Internal names, on the other hand, are all lowercase, typically auto-generated, and follow rules that include some encoding of special characters and the use of the underscore sign instead of spaces. We can string together the complete path to an attribute, from the organization, along spaces and equipments by concatenating the individual nodes' internal names and using a dot as a separator. This is refered to as FQN, or fully qualified name.
Technical Hint:
If you use the GraphQL API, the FQN is available for all things as "fqnList" - an array of strings. Also, internalName is refered to as relativeName.
Example of an attribute:
- Display Name: Tank Fill Level
- Internal Name: tank_fill_level
- FQN: acme.north_america.plant_123.batch_line.tank_room.tank_15.tank_fill_level
Absolute References
Absolute references follow the syntax of a fully qualified name (fqn) $root_name.name.name.name.attribute where root_name is a top level name in the system, name.name.name is any combination of names in the fqn, attribute is the attribute that we are referring to.
We can reference any attribute by its location in the model using a "$" and its FQN. Very simple. If you wanted to calculate twice the Tank Fill Level for the attribute example above, you'd write:
2 * $acme.north_america.plant_123.batch_line.tank_room.tank_15.tank_fill_level
Absolute references should only be used when they are absolutely needed, examples can be that the Acme Corporation has a set of business targets that are managed at the business unit level. These targets can be used in any equipment attribute, an example of such an attribute reference would be $acme_corp.chemicals_bu.yield_target
Relative References
Relative references are more common than absolute references. A relative reference is related to the attribute that the expression is attached to. The syntax is referring to part of the fully qualified name that is below the selected attribute parent equipment.
We can traverse from the attribute that contains an expression by moving upwards in the path of the FQN, one level at a time, using the "." character. The syntax supports any number of levels, so that $……. will refer to 7 levels up in the fqn.
Parent Attributes (Siblings):
Up one dot gets you to the node that hosts the attribute, Tank 15. Followed by the internal name of the target attribute would get us a sibling attribute, i.e. an attribute that resides in the same host.
For example, to calculate the utilization in percent of the above mentioned Tank 15 one would divide the level (in inch) by the maximum height (in inch) and multiply with 100. This would be the corresponding expression:
$.tank_fill_level / $.tank_max_fill_level * 100
Grandparent Attributes:
In the example above, up two dots get you to the Tank Room. If we wanted the absolute value of the difference between the temperatures of our tank content and the tank room, we would write an expression as follows:
Abs($..room_temperature - $.temp)
Greek Connection: Cousins and other Distant Relatives:
Finally, we can traverse up the tree and down into other branches. To calculate the average temperature of the content of tanks 15, 17, and 19, we would write an expression as follows:
( $.temp + $..tank_17.temp + $..tank_19.temp ) / 3