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 :

Field Name

Description

'Inbound'

The main entity in the relation

'Outbound'

The secondary entity in the relation

'RelationType'

Type of the relation('Link', 'Blocker', 'Relation', or 'Duplicate')

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)}