How to use collections in WSAPI

Products

• Rally SaaS
• Rally On-Premise

Issue/Introduction

For many attribute types in Rally's API, there can be a one-to-many relationship.  Examples of one-to-many relationships would be Tasks to a User Story or Tags on a Defect.

When inspecting attributes in the API, these one-to-many attributes are often expressed in a plural format.  An example of this would be if you see an attribute named "Projects", it is very likely that this would be a one-to-many capable attribute.

Creating or updating these attribute types in Rally requires special consideration.

Resolution

In order to make associations with these one-to-many attributes it is necessary to supply the value as an array of objects, even if you are only associating a single relationship.

For example, associating a Milestone with Projects, the following will fail:

{
  "Milestone": {
    "Projects": "/project/<PROJECT_OID>"
  }
}

 

The following is an example of how to associate a Milestone with a single Project:

{
  "Milestone": {
    "Projects": [
      {"_ref":"/project/<PROJECT_OID>"}
    ]
  }
}

 

If it is necessary to associate a Milestone with multiple Projects, then the following format is used:

{
  "Milestone": {
    "Projects": [
      {"_ref":"/project/<PROJECT_OID>"},
      {"_ref":"/project/<PROJECT_OID>"}
    ]
  }
}