Rally Software

When searching for user stories, I want to be able to query keywords or item IDs referenced in the revision history.

For example, I have a user story with a reference to a portfolio item ID in its revision history, but when I query for that portfolio item ID, all that is returned is the portfolio item itself, not the user story with a reference to it.

Hi John,

A separate request has to be made using the reference to the revision history returned by the first request provided RevisionHistory attribute was fetched during the first request. Fetching RevisionHistory returns a reference to it, and in order to "hydrate" this object, a separate request will be needed. In the previous versions of WS API it was possible to hyrate collections in the same request, but that caused a lot of recusive calls. v2.0 of WS API does not allow that.

This javascript code fragment based on the old version of WS API and legacy AppSDK illustrates the object model's complexity well:

for ( i=0 ; i<results.s.length ; i++ ) {
   for ( j=0 ; j<results.s[i].RevisionHistory.Revisions.length ; j++ ) {
                 if(results.s[i].RevisionHistory.Revisions[j].Description.indexOf("FEATURE added")>=0){
                        results.s[i].CreationDate = results.s[i].RevisionHistory.Revisions[j].CreationDate
                        results.s[i].RevisionDescription=results.s[i].RevisionHistory.Revisions[j].Description;
                        table.addRow(results.s[i]);

                }
   }
}

Here results.s is the array of results of a query on user stories (the query string could be anything, e.g. stories in the current iteration). Notice how we travese from individual story to individual revision.

In v2.0 the object model did not change. The only change that is relevant in the context of this conversation is that a separate requst is needed to hydrate the collection, but the traversal path is the same.

Also, regardless of the version of WS API used, it is not possible and was never possible to query a story by a content of a Revision since along the traversal path there are collections and only in code we can iterate over collections. This will return an error:

"Could not parse: Attribute "RevisionHistory" on type HierarchicalRequirement is not allowed in query expressions.



Per WS API object model, it is possible to traverse from an artifact (e.g. user story or defect) to a RevisionHistory and further to Revisions collection and individual revisions, but it is not possible to traverse the same path in the opposite direction. Artifact object in the WS API (from which stories and defects inherit) has an attribute RevisionHistory, but RevisionHistory or it's collection of revisions does not have a reference pointing back at the artifact they belong to. This has implications when writing custom code where Artifact data and attributes on revisions have to be stitched together.
Revision history in WS API has four attributes: Description, RevisionHistory(which is a reference to the parent RevisionHistory object), RevisionNumber and User(which is the author of the revision).
Neither Revision object, nor the RevisionHistory object that contains it has an attribute that points to the actual artifact (e.g. user story or defect) the revision belongs too.

Unfortunately the size of data when getting revision history can be very large and it is generally suggested to make more narrow calls when querying RevisionHistory - particularly when you want to parse it for specific string. You may limit the revisions indirectly by filtering artifacts for which RevisionHistory is fetched, or you may limit Revisions by CreationDate.

Here is an example of a Revision endpoint that returns revisions where state was changed. Parsing is accomplished by using the exact string that appears in revision history when state is changed:
 

https://rally1.rallydev.com/slm/webservice/v2.0/revision?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/12345&query=(Description contains "STATE changed from [Open] to [Fixed]")&fetch=true&pagesize=200

A similar query below looks for ocurrences of FEATURE added string that appears in a user story's revision history when a story is parented by a feature
 

https://rally1.rallydev.com/slm/webservice/v2.0/revision?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/12345&query=(Description contains "FEATURE added")&fetch=true&pagesize=200

If you interested in code samples that work with RevisionHistory, I have four C# examples here (https://github.com/nmusaelian-rally/rally-dot-net-rest-apps/blob/master/RevisionExamples/getRevisionsOfStoriesLastUpdatedInTwoDays.cs). They are written with Rally REST toolkit for .NET (https://github.com/RallyTools/RallyRestToolkitFor.NET). Even if your choice of language is different, your code will have to do something similar since it will be working within the context of the same WS API object model. In case you have not seen this, there is a KnowledgeBase article (https://rallydev.force.com/answers?id=kA014000000PKKq) on how to query on RevisionHistory.