Rally - WSAPI: Collection Summaries

Products

• Rally On-Premise
• Rally SaaS

Issue/Introduction

When I use a deprecated version of WS API (anything prior to v2.0) I can get elements of collections from the same request, but now I only get a reference object of the collection, and have to make a separate request to load the collection elements.

Resolution

In v2.0 of Web Services API collections are not hydrated automatically. Tasks on a User Story, Defects on a User Story, UserStories on a Feature, Iterations on a Project, etc. are examples of collections. For performance reasons v2.0 (unlike its predecessors - please see the API deprecation schedule here) does not allow getting the elements of the collection from the same request you made to get the parent object. You need a second request to load (hydrate) the collection. 

However v2.0 has a concept of collection's summary. 

EXAMPLE 1: Iterations collection on Project

Here is an example of an endpoint that fetches Iterations collection on Project without summarizing it:

https://rally1.rallydev.com/slm/webservice/v2.0/projects?fetch=Name,Iterations

Notice that even if fetch includes StartDate and EndDate, as in ?fetch=Name,Iterations,StarDate,EndDate those Iteration fields will not be included in the result. The iteration object returned by this endpoint is only a reference to the full object:
 

• {
  
  • _rallyAPIMajor: "2",
  • _rallyAPIMinor: "0",
  • _ref: "https://rally1.rallydev.com/slm/webservice/v2.0/project/<Project_OID>",
  • _refObjectUUID: "<Object_UUID>",
  • _objectVersion: "10",
  • _refObjectName: "Mars",
  • Iterations: 
     
    {
    
    • _rallyAPIMajor: "2",
    • _rallyAPIMinor: "0",
    • _ref: "https://rally1.rallydev.com/slm/webservice/v2.0/Project/<Project_OID>/Iterations",
    • _type: "Iteration",
    • Count: 12
    
    },
  • Name: "Mars",
  • _type: "Project"
  
  },

To summarize the collection by a desired fields, follow this syntax:

https://rally1.rallydev.com/slm/webservice/v2.0/projects?fetch=Name,Iterations:summary[StartDate;EndDate]

Notice Iterations:summary format: ?fetch=Name,Iterations:summary[StartDate;EndDate]

The iteration object returned by this endpoint includes StartDate and EndDate fields.
 

• {
  
  • _rallyAPIMajor: "2",
  • _rallyAPIMinor: "0",
  • _ref: "https://rally1.rallydev.com/slm/webservice/v2.0/project/<Project_OID>",
  • _refObjectUUID: "<Object_UUID>",
  • _objectVersion: "10",
  • _refObjectName: "Mars",
  • Name: "Mars",
  • Summary:
    {
    
    • Iterations: 
       
      {
      
      • StartDate: 
         
        {
        
        • Mon Jul 27 18:00:00 MDT 2015: 1,
        • Fri Sep 25 18:00:00 MDT 2015: 1,
        • Fri Jun 12 18:00:00 MDT 2015: 1,
        • Sun Oct 25 18:00:00 MDT 2015: 1,
        • Wed Aug 26 18:00:00 MDT 2015: 1,
        • Sun Jul 12 18:00:00 MDT 2015: 1,
        • Thu May 28 18:00:00 MDT 2015: 1,
        • Sat Oct 10 18:00:00 MDT 2015: 1,
        • Tue Aug 11 18:00:00 MDT 2015: 1,
        • Sat Jun 27 18:00:00 MDT 2015: 1,
        • Wed May 13 18:00:00 MDT 2015: 1,
        • Thu Sep 10 18:00:00 MDT 2015: 1
        
        },
      • EndDate: 
         
        {
        
        • Mon Jul 27 17:59:59 MDT 2015: 1,
        • Fri Sep 25 17:59:59 MDT 2015: 1,
        • Sat Oct 10 17:59:59 MDT 2015: 1,
        • Sun Jul 12 17:59:59 MDT 2015: 1,
        • Wed Aug 26 17:59:59 MDT 2015: 1,
        • Tue Aug 11 17:59:59 MDT 2015: 1,
        • Sun Oct 25 17:59:59 MDT 2015: 1,
        • Thu May 28 17:59:59 MDT 2015: 1,
        • Mon Nov 09 16:59:59 MST 2015: 1,
        • Thu Sep 10 17:59:59 MDT 2015: 1,
        • Fri Jun 12 17:59:59 MDT 2015: 1,
        • Sat Jun 27 17:59:59 MDT 2015: 1
        
        },
      • Count: 12
      
      }
    
    },
  • _type: "Project"
  
  },

EXAMPLE 2: TestCases collection on HierarchicalRequirement

Here is an example of an endpoint that fetches TestCases collection on User Stories without summarizing it. User Stories are filtered by iteration:

https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<Workspace_OID>&query=(Iteration = /iteration/<Iteration_OID>)&fetch=TestCases&pagesize=200

The same endpoint where TestCases are summarized by LastVerdict attribute of TestCase object:

https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<Workspace_OID>&query=(Iteration = /iteration/<Iteration_OID>)&fetch=TestCases:summary[LastVerdict]&pagesize=200

Here one of the stories scheduled for this iteration, a story "abc" has 3 test cases in its TestCases collection. Two of them have LastVerdict "Pass". The third test case does not have a verdict, hence "No Entry".

• {
  
  • _rallyAPIMajor: "2",
  • _rallyAPIMinor: "0",
  • _ref: "https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/<Story_OID>",
  • _refObjectUUID: "<Object_OID>",
  • _objectVersion: "9",
  • _refObjectName: "abc",
  • Summary:
     
    {
    
    • TestCases:
       
      {
      
      • LastVerdict:
         
        {
        
        • -- No Entry --: 1,
        • Pass: 2
        
        },
      • Count: 3
      
      }
    
    },
  • _type: "HierarchicalRequirement"
  
  }

The query above can be modified to include a summary of TestCases by FormattedID in addition to LastVerdict

https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<Workspace_OID>&query=(Iteration = /iteration/<Iteration_OID>)&fetch=TestCases:summary[FormattedID;LastVerdict]&pagesize=200
 

• Summary:
   
  {
  
  • TestCases:
     
    {
    
    • LastVerdict:
       
      {
      
      • -- No Entry --: 1,
      • Pass: 2
      
      },
    • FormattedID:
       
      {
      
      • TC1160: 1,
      • TC1158: 1,
      • TC1159: 1
      
      },
    • Count: 3
    
    }
  
  },