Agile Central - LBAPI: Get UserStories and Features under Initiative using LookbackAPI

Products

• Rally On-Premise
• Rally SaaS

Issue/Introduction

In this scenario PortfolioItem/Initiative and PortfolioItem/Feature types are mentioned, and it is assumed that a feature's immediate parent is an initiative. But, in a given workspace those standard type names can be customized and new custom PI types may also exist. Here, Lookback API is used to efficiently get the entire work item hierarchy under a particular portfolio item.

Resolution

Generally, Lookback API is used to provide historic data. Unlike WS API that returns only the current state of the objects, LookbackAPI gives access to previous versions that it refers to as "shapshots".

However, there are scenarios when LookbackAPI is also used to get current data because it allows for efficient querying of work item and type hierarchies.

The question used in the title of this article describes a real-life scenario but it is expressed in very wide terms. There are many examples that may fall within the scope of this question that are not described here. Lookback API is powerful and nuanced, and there is no substitute for building queries gradually. Lookback API manual is available here.

Lookback API query examples shown below can be pasted directly in the browser after the placeholder workspace and project ObjectIDs are replaced with those valid in your subscription.

Example1: Get current snapshots of objects under a specific Initiative in a project hierarchy.

https://rally1.rallydev.com/analytics/v2.0/service/rally/workspace/<WORKSPACE_OID>/artifact/snapshot/query.js?&fields=["FormattedID","Name","State","ScheduleState"],&hydrate=["State","ScheduleState"]&pagesize=20000&start=0&find={"_ItemHierarchy":<OBJECT_OID>,"_ProjectHierarchy":<TOP_PROJECT_OID>,"__At": "current"}

"__At": "current" indicates that we are only interested in the current snapshots and not in historic data.
"_ProjectHierarchy":<TOP_PROJECT_OID> indicates that the scope of the query includes child projects of the project set in the _ProjectHierarchy, where <TOP_PROJECT_OID> is the ObjectID of the top project in question.
"_ItemHierarchy":<OBJECT_OID> specifies the ObjectID of a PortfolioItem/Initiative in question. All workitem types parented by this Initiative, including features, user stories and tasks will be returned by this query. The Initiative is identified by ObjectID that is available in the details URL. To find out ObjectID of any CA Agile Central artifact see the URL of the artiact's details page, e.g.
https://rally1.rallydev.com/#/<TOP_PROJECT_OID>ud/detail/portfolioitem/initiative/<OBJECT_OID>

In this example, the json returned by the query above has TotalResultCount: 63

Example 2: Get current snapshots of objects under a specific Initiative in a project hierarchy, but exclude Tasks of User Stories

https://rally1.rallydev.com/analytics/v2.0/service/rally/workspace/111/artifact/snapshot/query.js?&fields=["FormattedID","Name","State","ScheduleState"],&hydrate=["State","ScheduleState"]&pagesize=20000&start=0&find={"_ItemHierarchy":<OBJECT_OID>,"_ProjectHierarchy":<TOP_PROJECT_OID>,"__At": "current","_TypeHierarchy": { "$in":["PortfolioItem/Feature","HierarchicalRequirement"]}}

"_TypeHierarchy": { "$in":["PortfolioItem/Feature","HierarchicalRequirement"]}? limits the query to features and user stories

As expected, in this example, the json returned fewer objects, with TotalResultCount: 40

Example 3: Get current snapshots of objects under a specific Initiative in a project hierarchy, except Tasks, but return Parent or PortfolioItem attributes when they exist:

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

Here is a fragment of the returned json for illustration. UserStories have ScheduleState and Features have State, and null values are returned when an attribute that does not exist on a given type is requested:

Results: [
{
Name: "new story efd",
ScheduleState: "Defined",
PortfolioItem: <OBJECT_OID>,
FormattedID: "US337",
State: null
},
{
Parent: <TOP_PROJECT_OID>,
Name: "c-story1",
ScheduleState: "Defined",
FormattedID: "US388",
State: null
},
{
PortfolioItem: <OBJECT_OID>,
Name: "test diff user",
ScheduleState: "Defined",
FormattedID: "US387",
State: null
},
{
Parent: <TOP_PROJECT_OID>,
Name: "story 2",
ScheduleState: "Accepted",
FormattedID: "US14",
State: null
}
]

Example 4: Get current snapshots of all Features and Stories in a project hierarchy

https://rally1.rallydev.com/analytics/v2.0/service/rally/workspace/<WORKSPACE_OID>/artifact/snapshot/query.js?&fields=["FormattedID","Name","State","ScheduleState","Parent","PortfolioItem"]&hydrate=["State","ScheduleState"]&pagesize=20000&start=0&find={"_ProjectHierarchy":<TOP_PROJECT_OID>,"__At": "current","_TypeHierarchy": { "$in":["PortfolioItem/Feature","HierarchicalRequirement"]}}

"_ItemHierarchy":<OBJECT_OID> has been removed. You no longer look under a specific Initiative. Now TotalResultCount: 1617

Example 5: Get historic snapshots of all Features and Stories in a project hierarchy

https://rally1.rallydev.com/analytics/v2.0/service/rally/workspace/<WORKSPACE_OID>/artifact/snapshot/query.js?&fields=["FormattedID","Name","State","ScheduleState","Parent","PortfolioItem"]&hydrate=["State","ScheduleState"]&pagesize=20000&start=0&find={"_ProjectHierarchy":<TOP_PROJECT_OID>,_ValidFrom:{$gte:"2014-01-01",$lt:"2014-08-30"},"_TypeHierarchy": { "$in":["PortfolioItem/Feature","HierarchicalRequirement"]}}

_ValidFrom:{$gte:"2014-01-01",$lt:"2014-08-30"} specifies the date range for historic snapshots.

Now the result count is much larger: TotalResultCount: 9131