Object Context and LinkPath
Learn how to access the current, parent, and main objects in an expression and how to use the LinkPath to access other linked objects.
Object Context
When working with linked instances, TIVITY provides several expressions for accessing objects from the current context:
CurrentObjectParentObjectMainObjectLinkPath
Which objects these expressions refer to depends on the LinkPath through which the current instance was opened.
For example, consider the following structure:
Project
└── Story
└── TaskIf a Task is opened through this structure, the context is:
CurrentObject
Task
ParentObject
Story
MainObject
Project
This makes it possible to access fields from different levels of the current context without manually navigating through links.
CurrentObject
CurrentObject refers to the object that is currently being evaluated or displayed.
For example, when working on a Task:
returns the ID of the current Task.
The existing Condition Values documentation also supports accessing fields of the current object using this expression. # Expressions in Condition Valu…
Example
For:
while viewing the Task:
ParentObject
ParentObject refers to the object directly before the CurrentObject in the active LinkPath.
For example:
returns the ID of the direct parent object.
The existing documentation describes ParentObject as the parent of an object created or accessed through another linked object. # Expressions in Expressions
Example
For:
while viewing the Task:
When viewing the Story through the same path:
In this case, ParentObject and MainObject refer to the same object.
MainObject
MainObject refers to the highest object of the current LinkPath context.
For example:
returns the ID of the main instance from which the current context originates.
Example
For:
while viewing the Task:
When viewing the Project itself:
There is no separate parent within this LinkPath.
Understanding LinkPath
The LinkPath represents the chain of linked instances through which the current object was reached.
The LinkPath is therefore context-dependent. The same instance can have a different CurrentObject, ParentObject, and MainObject context depending on how it was opened.
For example, a Task opened through:
has the Project as its MainObject and the Story as its ParentObject.
If the same Task is opened directly, the context can instead begin with the Task itself. In that case, the Task is both the current and main object.
This is important when creating expressions that are used in different layouts or navigation contexts.
Accessing Objects with LinkPath
Instead of relying only on ParentObject or MainObject, a specific class within the active LinkPath can be addressed directly:
The current Expressions documentation describes LinkPath as a way to access fields of indirectly linked objects by their class name. # Expressions in Expressions docs.tivity.one
Using a class name makes the expression less dependent on where that class is positioned within the LinkPath.
Example
Consider a more complex structure:
When the Task is opened through this path:
However, all other objects in the LinkPath can also be addressed directly.
To access the Feature:
To access the Epic:
To access a field of the Project:
This is particularly useful for indirectly linked objects because it is not necessary to know whether the desired object is the immediate parent or the main object.
ParentObject and MainObject vs. LinkPath
ParentObject and MainObject are convenient when the required object's position in the context is known.
For example:
always refers to the direct parent in the current LinkPath, while:
refers to the highest object in that context.
A LinkPath expression instead identifies the object by its class:
For an app where the hierarchy may contain several levels, using LinkPath can therefore make the expression independent of the exact depth of the desired class.
For example, both of these hierarchies may contain a Feature:
and
An expression such as:
addresses the Feature by class rather than depending on it being the ParentObject or MainObject.
Example Overview
For the following LinkPath:
and a Task as the current object:
{CurrentObject.Id}
ID of the Task
{ParentObject.Id}
ID of the Story
{MainObject.Id}
ID of the Project
{LinkPath["Story"].Id}
ID of the Story
{LinkPath["Feature"].Id}
ID of the Feature
{LinkPath["Epic"].Id}
ID of the Epic
{LinkPath["Project"].Id}
ID of the Project
Key Difference
The important distinction is:
CurrentObject is the object currently being worked with.
ParentObject is the object directly above it in the current LinkPath.
MainObject is the highest object in the current LinkPath.
LinkPath allows a specific class anywhere in that context to be addressed directly.
Because the LinkPath depends on how an instance was opened, app creators should take the expected navigation context into account when using CurrentObject, ParentObject, and MainObject. When the required class is known, LinkPath["<ClassName>"] can be used to address that class directly.
Last updated