WS API and Lookback API endpoints for Children collections and Item Hierarchies

search cancel

WS API and Lookback API endpoints for Children collections and Item Hierarchies

book

Article ID: 57628

calendar_today

Updated On:

Products

Rally On-Premise Rally SaaS

Issue/Introduction

WS API and Lookback API have endpoints for Children collections and Item Hierarchies respectively. Sometimes when query results seem inconclusive, particularly when troubleshooting a custom app that is using SnaphotStore to retrieve historic data from Lookback API? it is helpful to compare results of Lookback API query with results returned by a similar WS API query.

Resolution

The test below was conducted in a workspace where a hierarchy of work item types is as follows:

PortfolioItem/Initiative
|__ PortfolioItem/Feature
|__ Parent UserStory
|__ UserStory

Since PortfolioItem types can be customized, your PI Types names can be different. Some terms used casually may mean different things in the context of different workspaces.
For example, the word "epic" is often used to refer to a parent User Story, which is a User Story that has children user stories. The work item type of the parent story is the same as the work item type of its children. In WS API and in Lookback API this type is called HierarchicalRequirement.
However, in a customized workspace where one of the PortfolioItem types is called Epic, the word "epic" will refer to PortfolioItem/Epic.
When contacting support please indicate what "epic" means in your workspace.

If your worksapce PI types are customized, you may still follow the example below, but will have to modify the PI type endpoints to reflect your PIs custom names. FormattedIDs and ObjectIDs will also have to be replaced with valid IDs in your workspace.
For each WS API example two endpoints (one with a query by FormattedID and the other with a query by ObjectID) will be shown. They both return same results, and you may choose to use either one. The only reason for including WS API queries by ObjectID is to make WS API queries look more similar to LBAPI queries so that it is easier to spot the corresponding LBAPI query.
WS API endpoints below will summarize Children collections.

We will compare query results from the 3 pairs of similar endpoints:

1. HierarchicalRequirement endpoint

WS API: Collection of User Stories on a parent User Story (HierarchicalRequirement) object.
LB API: _ItemHierarchy that starts with a parent User Story

2. PortfolioItem/Feature endpoint

WS API: Collection of User Stories on a parent User Story (HierarchicalRequirement) object.
LB API: _ItemHierarchy that starts with a parent User Story

3. PortfolioItem/Initiative endpoint

WS API: Collection of User Stories on a parent User Story (HierarchicalRequirement) object.
LB API: _ItemHierarchy that starts with a parent User Story

1. HierarchicalRequirement endpoint

a) WS API

Two variations of the same endpoint:
https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=(FormattedID = US13215)&fetch=Children:summary[FormattedID]
https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=(ObjectID = <OBJECT_OID>)&fetch=Children:summary[FormattedID]

return this result. UserStory US13215 has two child stories:

Results:

[
- ?
  {
  - _rallyAPIMajor: "2",
  - _rallyAPIMinor: "0",
  - _ref: "https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/<STORY_OID>",
  - _refObjectUUID: "<OBJECT_UUID>",
  - _objectVersion: "14",
  - _refObjectName: "Epic 2:4 of feature 16",
  - Summary:
    ?
    {
    
    Children:
    ?
    {
    
    FormattedID:
    ?
    {
    
    US16533: 1,
    
    US16527: 1
    
    },
    
    Count: 2
    
    }
    
    },
  - _type: "HierarchicalRequirement"
  }
]

b) LBAPI

This query returns 3 items. Compare them to the results from the corresponding WS API query above. LBAPI query returns the entire hierarchy: two child stories and the parent story

https://rally1.rallydev.com/analytics/v2.0/service/rally/workspace/<WORKSPACE_OID>/artifact/snapshot/query.js?find={"_ItemHierarchy":<OBJECT_OID>,"_TypeHierarchy":"HierarchicalRequirement","__At":"current"}&fields=["FormattedID"]

[

?
{
- FormattedID: "US16533"
},
?
{
- FormattedID: "US13215"
},
?
{
- FormattedID: "US16527"
}

],

2. PortfolioItem/Feature endpoint

a) WS API

Two variations of the same endpoint:

https://rally1.rallydev.com/slm/webservice/v2.0/portfolioitem/feature?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=(FormattedID = F2285)&fetch=UserStories:summary[FormattedID]
https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=(ObjectID = <OBJECT_OID>)&fetch=Children:summary[FormattedID]

return this result. PortfolioItem/Feature F2285 has four stories under it:

Results:

[
- ?
  {
  - _rallyAPIMajor: "2",
  - _rallyAPIMinor: "0",
  - _ref: "https://rally1.rallydev.com/slm/webservice/v2.0/portfolioitem/feature/<OBJECT_OID>",
  - _refObjectUUID: "<OBJECT_UUID>",
  - _objectVersion: "9",
  - _refObjectName: "Feature 166",
  - Summary:
    ?
    {
    
    UserStories:
    ?
    {
    
    FormattedID:
    ?
    {
    
    US13773: 1,
    
    US13777: 1,
    
    US13780: 1,
    
    US13784: 1
    
    },
    
    Count: 4
    
    }
    
    },
  - _type: "PortfolioItem/Feature"
  }
]

b) LBAPI

This query returns four items. Compare them to the results from the corresponding WS API query above. LBAPI query returns the the same four items. It excludes the PI/Feature itself because we limit the _TypeHierarchy to HierarchicalRequirement:

https://rally1.rallydev.com/analytics/v2.0/service/rally/workspace/<WORKSPACE_OID>/artifact/snapshot/query.js?find={"_ItemHierarchy":<OBJECT_OID>,"_TypeHierarchy":"HierarchicalRequirement","__At":"current"}&fields=["FormattedID"]

Results:
?
[
- ?
  {
  - FormattedID: "US13773"
  },
- ?
  {
  - FormattedID: "US13777"
  },
- ?
  {
  - FormattedID: "US13780"
  },
- ?
  {
  - FormattedID: "US13784"
  }
],

3. PortfolioItem/Initiative endpoint

a) WS API

Two variations of the same endpoint:

https://rally1.rallydev.com/slm/webservice/v2.0/portfolioitem/initiative?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=(FormattedID = I26)&fetch=Children:summary[FormattedID]
https://rally1.rallydev.com/slm/webservice/v2.0/portfolioitem/initiative?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=(ObjectID = <OBJECT_OID>)&fetch=Children:summary[FormattedID]

return this result. PortfolioItem/Iteration I26 has eight PortfolioItem/Fatures under it:

Results:

[

?
{
- _rallyAPIMajor: "2",
- _rallyAPIMinor: "0",
- _ref: "https://rally1.rallydev.com/slm/webservice/v2.0/portfolioitem/initiative/<OBJECT_OID>",
- _refObjectUUID: "<OBJECT_UUID>",
- _objectVersion: "140",
- _refObjectName: "Initiative 0",
- Summary:
  ?
  {
  - Children:
    ?
    {
    
    FormattedID:
    ?
    {
    
    F2177: 1,
    
    F2180: 1,
    
    F2152: 1,
    
    F2150: 1,
    
    F2178: 1,
    
    F2179: 1,
    
    F2154: 1,
    
    F2149: 1
    
    },
    
    Count: 8
    
    }
  },
- _type: "PortfolioItem/Initiative"
}

b) LBAPI

This query returns eight items. Compare them to the results from the corresponding WS API query above. LBAPI query returns the the same eight items. It excludes the PI/Initiative itself because we limit the _TypeHierarchy to PortfolioItem/Feature:

https://rally1.rallydev.com/analytics/v2.0/service/rally/workspace/<WORKSPACE_OID>/artifact/snapshot/query.js?find={"_ItemHierarchy":<OBJECT_OID>,"_TypeHierarchy":"PortfolioItem/Feature","__At":"current"}&fields=["FormattedID"]

[

?
{
- FormattedID: "F2152"
},
?
{
- FormattedID: "F2154"
},
?
{
- FormattedID: "F2149"
},
?
{
- FormattedID: "F2150"
},
?
{
- FormattedID: "F2180"
},
?
{
- FormattedID: "F2178"
},
?
{
- FormattedID: "F2177"
},
?
{
- FormattedID: "F2179"
}

],

We will modify the query above in order to include UserStories (HierarchicalRequirement objects) in the result. This demonstrates the power of _TypeHierarchy construct in LBAPI. In WS API Children collection on PortfolioItem/Initiative will only return objects of the PortfolioItem type that is directly under Initiative (in a standard configuration it is PortolioItem/Feature). In LBAPI we can include UserStories that exist under respective PortolioItem/Features in the results of PortfolioItem/Initiative endpoint using this syntax:
"_TypeHierarchy":{ "$in" : ["PortfolioItem/Feature","HierarchicalRequirement"]}

https://rally1.rallydev.com/analytics/v2.0/service/rally/workspace/<WORKSPACE_OID>/artifact/snapshot/query.js?find={"_ItemHierarchy":<OBJECT_OID>,"_TypeHierarchy":{ "$in" : ["PortfolioItem/Feature","HierarchicalRequirement"]},"__At":"current"}&fields=["FormattedID"]

This is just a fragment of the result that has TotalResltCount of 81. The result includes 8 PI/Features and their stories.

TotalResultCount: 81,
StartIndex: 0,
PageSize: 100,
ETLDate: "2015-08-07T22:35:48.906Z",
Results:
?
[
- ?
  {
  - FormattedID: "US13235"
  },
- ?
  {
  - FormattedID: "US13236"
  },
- ?
  {
  - FormattedID: "US13241"
  },
- ?
  {
  - FormattedID: "US13338"
  },
- ?
  {
  - FormattedID: "US13351"
  },

Feedback

thumb_up Yes

thumb_down No