Working with Relations

📘

Note: The Master/Slave is an outdated terminology and is being replaced by Inbound/Outbound.

Dot notation can be used with Relations to access the following fields :

Relation Type

RelationType field can be checked to filter only the type of relations needed :

Example: Returning User Story ID + only OutboundRelations where the type is 'Relation'

/api/v2/userstories?select={ID, OutboundRelations.where(RelationType.Name = 'Relation')}

Using .Count and .Where

MasterRelations + InboundRelations are Collections, so you can use '.count()' and '.where()' to check collection values

Example: Return (Name, ID) of all features that have one or more Master/Inbound Relations.

/api/v2/features?where=(InboundRelations.count > 0)&select={ID, Name}

Example: Return (Name, ID) of all features that have no Outbound Relations.

/api/v2/features?where=(OutboundRelations.count = 0)&select={ID, Name}

Example: For User Story relations of 'Relation' type, select the entity Name of the Inbound Feature

📘

Note: The Inbound entity must be a Feature to use the MasterFeature terminology.

/api/v2/userstories?select={InboundRelations.Where(RelationType.Name='Relation').Select(MasterFeature.Name)}

Using 'Inbound' and 'Outbound'

You can use Outbound.ID + Inbound.ID to check specific ID values of each individual relation

Example: Return Bug ID + only OutboundRelations where the Outbound relation ID is '12345'

/api/v2/bugs?select={ID, OutboundRelations.where(Outbound.Id = 12345)}

Example: Return User Story ID + only InboundRelations where the Inbound relation is in the project 'Actus 2.0'

/api/v2/userstories?select={Id, InboundRelations.Where(Inbound.Project.Name = 'Actus 2.0')}

Using /relations endpoint

You can use the relations endpoint to access the Inbound, Outbound, or ID fields directly.

📘

Note: The ID field is the actual ID of the relation, not the corresponding entity ID. For those values you will use Inbound. ID and/or Outbound.ID

Example: Return the relation where the Inbound entity has ID of 191261.

/api/v2/relations?where=(inbound.id = 191261)&select={inbound:{inbound.id, inbound.name}, outbound:{outbound.id, outbound.name}, RelationType.name}

Accessing Fields from Inbound/Outbound-Relations Collection

You can access ID, Outbound, Inbound, and RelationType fields directly on Relations collection.

Example : For User Stories endpoint, select the Feature ID for Inbound relations where the Relation type is 'Relation'

/api/v2/userstories?select={InboundRelations.Where(RelationType.Name = 'Relation').Select(MasterFeature.ID)}

Accessing Fields from Inbound/Outbound-Assignables Collection

Example: Return all User Stories that have at least 1 Inbound Relation and ALL inbound relations are 'In Progress' state.

/api/v2/userstories?where=((InboundAssignables.Count(EntityState.Name = 'In Progress') = InboundAssignables.Count()) 
and InboundAssignables.Count() > 0)

Example: Return all Features where there is at least 1 Inbound Assignable, at least 1 Outbound Assignable, ALL Inbound Assignables are in 'Done' state, and all Outbound Assignables are in 'Open' state.

/api/v2/features?where=((InboundAssignables.Count(EntityState.Name = 'Done') = InboundAssignables.Count()) 
and (OutboundAssignables.Count(EntityState.Name = 'Open') = OutboundAssignables.Count())  
and InboundAssignables.Count() > 0   
and OutboundAssignables.Count() > 0)

📘

Example Explained:

All Inbound Assignables in Done state -
(InboundAssignables.Count(EntityState.Name = 'Done') = InboundAssignables.Count())

All Outbound Assignables in Open state -
(OutboundAssignables.Count(EntityState.Name = 'Open') = OutboundAssignables.Count())

At least 1 Outbound Assignable -
OutboundAssignables.Count() > 0)

At least 1 Inbound Assignable -
InboundAssignables.Count() > 0

Accessing Entity-Specific Fields

You can use the following notation in order to access the relations nested fields

📘

Note: Relation of 'EntityType' must exist in order to use this notation

For MasterRelations collection: Master{EntityType} :

Example: MasterUserStory.Feature

For SlaveRelations collection: Slave{EntityType} :

Example: SlaveFeature.Release

Example: For Entity # 190977, select all Inbound Relations of 'Relation' type + select the Feature field of the 'Master' User Story

/api/v2/userstories?where=(id=190977)&select={MasterRelations.Where(RelationType.Name='Relation').Select(MasterUserStory.Feature)}

Example: For Entity # 190977, select all Outbound Relations of 'Relation' type + select the Epic field of the 'Slave' Feature

/api/v2/userstories?where=(id=190977)&select={SlaveRelations.Where(RelationType.Name='Relation').Select(SlaveFeature.Epic)}