Fetch user stories by iteration using Rally API

Question

I can't figure out how to fetch all the fields of one User story in Rally. Right now, I need to fetch last 5 iterations, and calculate done points for every iteration. I managed to fetch iterations, by specifying `type: iteration`, but don't know how to fetch user stories for those iterations, and how to specify only done. Should I go with `TaskStatus` of tasks associated with User story? I guess that User story has reference on Iteration, but I'm not sure how it looks like. I don't find this manual very concise, is there any other docs that I should use? EDIT: I see that within HierarchicalRequirement, I have Iteration object with following fields: ``` _rallyAPIMajor: 2 _rallyAPIMinor: 0 _ref: https://rally1.rallydev.com/slm/webservice/v2.0/iteration/18831411089 _refObjectUUID: 8053fbd0-867c-4126-805c-18ccbc958a93 _refObjectName: Iteration 1 _type: Iteration ``` Question: How I should use this? I was thinking to fetch 5 iterations (ordered by EndDate), and then to fetch all tasks for…

Accepted Answer

Rally object model is available in Web Services API documentation.

There is Iteration attribute on HierarchicalRequirement (user story) object, which is a reference to Iteration object, so it is possible to query stories by iteration.

The manual you referenced is specific to LookbackAPI, and requires familiarity with the object model in WS API documentation.

Here is a LookbackAPI endpoint that queries user stories that scheduled for one of three iterations, where 222,333,444 are ObjectIDs of iterations:

```
"Iteration" : {$in: [222,333,444]} 
```

and fetches `'FormattedID','ScheduleState','PlanEstimate'` user story fields.

```
https://rally1.rallydev.com/analytics/v2.0/service/rally/workspace/111/artifact/snapshot/query.js?find={"Iteration" : {$in: [222,333,444]},"_TypeHierarchy":"HierarchicalRequirement","__At" : "current"}&fields=['FormattedID','ScheduleState','PlanEstimate'],hydrate=['ScheduleState']
```

Here is a similar WS API endpoint:

```
https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/1119&query=(((Iteration.ObjectID = 222) OR (Iteration.ObjectID = 333)) OR (Iteration.ObjectID = 444))&fetch=FormattedID,ScheduleState,PlanEstimate&pagesize=200
```

Two queries return the same results.

You may use Lookback API queries instead of WS API queries even if you want to get current state of objects, as in the example above using `"__At" : "current"`, but Lookback API is designed to give historic data. WS API returns only current state of objects, while Lookback API can return snapshots of those objects in time.

rally-node does not have a built-in support for Lookback API.

Here is a rally-node example that queries for stories by 3 iterations:

```
var rally = require('rally'),
    queryUtils = rally.util.query;
    mySettings = {
        apiKey: '_XYZ...',
        server: 'https://rally1.rallydev.com',  //this is the default 
        requestOptions: {
            headers: {
                'X-RallyIntegrationName': 'stories by iteration node.js program',  
                'X-RallyIntegrationVendor': 'My company'
                'X-RallyIntegrationVersion': '1.0'                    
            },    
        }
    },
    restApi = rally(mySettings);

var q = queryUtils.where('Iteration.ObjectID', '=', 222).or('Iteration.ObjectID', '=', 333).or('Iteration.ObjectID', '=', 444);

restApi.query({
    type: 'hierarchicalrequirement'
    fetch: ['FormattedID', 'Name', 'ScheduleState', 'PlanEstimate', 'Iteration'], 
    query: q, 
    scope: {
        workspace: '/workspace/111', 
    },
}, function(error, result) {
    if(error) {
        console.log(error);
    } else {
        console.log(result.Results);
    }
});
```

Fetch user stories by iteration using Rally API

Solution

Problem