Rally - Lookback API: How to analyze the result of LBAPI queries

Document ID : KB000129468
Last Modified Date : 14/03/2019
Show Technical Document Details
When issuing Lookback API queries we are getting a JSON text. How do we analyze it? What should we look for in that JSON structure?
The Lookback API queries the Analytics platform which is external to Rally/ALM. This platform holds a large series of snapshots. A snapshot is created every time any artifact is created, updated or deleted. Snapshots are only created on such events of artifacts including User Story, Defect, Task, Portoflio Items, but not for non-artifact objects such as User, Project, Workspace, Permissions .

Any Lookback API query will necessarily return snapshots that match it in a JSON format structure. The 'TotalResultCount' will hold the number of snapshots included in this returned JSON. Note, the total number of results returned may be smaller than that TotalResultCount depending on how you used paging (the 'start' and 'pagesize' arguments) in your query in conjunction with the total number of actual results.

The key factor in each result within this JSON structure is the _PreviousValues property. This is a property that holds the fields of that artifact which actually changed in this snapshot. So, for example, if a user story changed its name, which created a snapshot, and then this snapshot is returned by a LBAPI query (for example, a query that requests all snapshots of user stories that had their names changed) - then the _PreviousValues property will include the 'Name' field. The _PreviousValues property will hold all fields that changed in this snapshot, so if multiple changes were made at once then all these changes will be part of this property of that snapshot. Another example could be: If a portfolio item was added 2 new user stories, removed 4 other user stories, changed its State, changed its Project and updated its Description - all in a single change that was saved as such then the generated snapshot will have all these changes stored in the _PreviousValues of that snapshot.

So, essentially if a snapshot is returned by a LBAPI query then it means it matches what was requested by this query. To best explore and fully analyze and realize this change you shall explore the _PreviousValues property, this will tell you all that was different for this artifact prior to this single change, then you can compare the fields under the _PreviousValues with the same fields in the actual snapshot. This can lead you to a full understanding of all that was changed in the snapshot as well as what it changed from and what it changed to.