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

Document ID : KB000057601
Last Modified Date : 14/02/2018
Show Technical Document Details


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.


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.["FormattedID","Name","State","ScheduleState"],&hydrate=["State","ScheduleState"]&pagesize=20000&start=0&find={"_ItemHierarchy":777,"_ProjectHierarchy":222,"__At": "current"}

"__At": "current" indicates that we are only interested in the current snapshots and not in historic data.
"_ProjectHierarchy":222 indicates that the scope of the query includes child projects of the project set in the _ProjectHierarchy, where 222 is the ObjectID of the top project in question.
"_ItemHierarchy":777 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.

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["FormattedID","Name","State","ScheduleState"],&hydrate=["State","ScheduleState"]&pagesize=20000&start=0&find={"_ItemHierarchy":777,"_ProjectHierarchy":222,"__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:["FormattedID","Name","State","ScheduleState","Parent","PortfolioItem"]&hydrate=["State","ScheduleState"]&pagesize=20000&start=0&find={"_ItemHierarchy":777,"_ProjectHierarchy":222,"__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: 13299973053,
FormattedID: "US337",
State: null
Parent: 13951879591,
Name: "c-story1",
ScheduleState: "Defined",
FormattedID: "US388",
State: null
PortfolioItem: 13299973053,
Name: "test diff user",
ScheduleState: "Defined",
FormattedID: "US387",
State: null
Parent: 12483864553,
Name: "story 2",
ScheduleState: "Accepted",
FormattedID: "US14",
State: null

Example 4: Get current snapshots of all Features and Stories in a project hierarchy["FormattedID","Name","State","ScheduleState","Parent","PortfolioItem"]&hydrate=["State","ScheduleState"]&pagesize=20000&start=0&find={"_ProjectHierarchy":222,"__At": "current","_TypeHierarchy": { "$in":["PortfolioItem/Feature","HierarchicalRequirement"]}}

"_ItemHierarchy":777 has been removed. We no longer look under a specific Initiative. Now TotalResultCount: 1617

Example 5: Get historic snapshots of all Features and Stories in a project hierarchy["FormattedID","Name","State","ScheduleState","Parent","PortfolioItem"]&hydrate=["State","ScheduleState"]&pagesize=20000&start=0&find={"_ProjectHierarchy":222,_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
Please Update This Required Field