Rally - User Stories and Portfolio Items relationship [under the hood] - Validation error: HierarchicalRequirement.parentArtifact should not be set if HierarchicalRequirement.Parent is set and vice versa

Products

• Rally On-Premise
• Rally SaaS

Issue/Introduction

Error:  Validation error: HierarchicalRequirement.parentArtifact should not be set if HierarchicalRequirement.Parent is set and vice versa

There seems to be confusion, perhaps inconsistency in how user stories and portfolio items are linked. 
In the UI we associate a feature to the user story using the Parent field, yet, it is not showing as a parent, but it's showing in a Feature field. This is unlike when we use the Parent field to assign a user story, then it is showing in the parent field.

This is also evident in the Custom List app, and possibly other apps or pages, see below:

Furthermore:
When we examine the WSAPI endpoint for HierarchicalRequirement (the user story object), then we see field for:

Parent
Feature
PortfolioItem

They, too, seem to be part of these associations.


It is unclear what is happening here and how it all works.

Environment

Release:
Component: ACSAAS

Resolution

There are a number of things to explain here.

Parent
User stories may live in hierarchies. You can have user stories be parent of other stories or children of other stories. The Parent field only allows you to associate a story with another story. You can see this in the WSAPI defintion:

PortfolioItem and Feature fields
A user story can be associated with one portfolio item. That portfolio item must be of your lowest portfolio hierarchy type. Each workspace allows you to create and manage a different portfolio hierarchy. The lowest-level portfolio item type of that hierarchy can be associated with user stories. So, for example, if our hierarchy is: Theme -> Initiative -> Feature, then only the Feature object can be associated with user stories.

Upon defining your portfolio hierarchy, two new fields will be created for your user story in the hierarchicalrequirement endpoint:
1. PortfolioItem
2. A field by the name of your lowest-level portfolio item type.

For a workspace where the lowest level is a Feature, these will be these two fieds:

Similarly, for a workspace where Theme is the lowest-level portfolio item type, these two fields will look like that:

Notice a few things here:
a. The PortfolioItem field links to the specific endpoint of your lowest-level portfolio item type. So, in the first example, we see the PortfolioItem field links the user story to a Feature. In the second example we see this same field links the user story to a Theme. This design makes certain that only the lowest-level portfolio can be linked to a user story. As explained, this field is dynamically created in your workspace and is dynamically set to link to your lowest-level portfolio.

b. The Feature/Theme fields (which are the dynamically created field in the name of your lowest-level portfolio item type) are Read Only.



Here is how all this works:
- When associating a user story to a portfolio item then you can only use the PortfolioItem field to effectuate this link. If done with WSAPI then you'll use a POST method and set this field with the reference to the portfolio item you are linking to the user story. So, if your lowest-level is a Feature, then you'll provide a reference to a feature. If it's Theme, you'll provide a reference to a Theme. If you attempt to provide a reference to a portfolio item which is higher up in the portfolio hierarchy then you'll get an error since the PortfolioItem field only allows the lowest-level and is generated with that constraint (as explained above).

- You can use the Feature/Theme fields to only read/view the associated portfolio item, not to set or reset or make any changes. That is because this field is a read-only field. If you open up a user story in the user interface, then you'll see the Feature/Theme field (a field in the name of your lowest-level portfolio item type). You can see that it's a read-only field.


There is more to this when we combine this with the fact that stories are organized in hierarchies:
- Essentially we need to understand that it is only allowed for all stories in a story-hierarchy to belong to the same portfolio item. Let's say Feature is the lowest level, then it would be a Feature. So, all stories in the story-hierarchy will be linked/owned by the same feature. 

- What the above means is that if you set a different feature to some story in a hierarchy then that will cut its chain from the hierarchy. Let's provide an example:
We have Story 1 (parent of) -> Story 2 (parent of) -> Story 3 (parent of) -> Story 4. Let's say all these stories (entire hierarchy) is associated with Feature1.

If we now set "Story 3" to be linked with Feature2 (using the PortfolioItem field, as mentioned above) then that will cut "Story 3" and its chain out of the original hierarchy and form a new hierarchy. Here is what will be the result:

Story 1 (parent of) -> Story 2   - both associated with Feature1.
Story 3 (parent of) -> Story 4   - both associated with Feature2.

So, setting a portfolio item to a story will cause this story to become the source (root level) of its new story-hierarchy. Any story that is underneath will be automatically associated with that same feature.

Doing that from WSAPI is straight-forward cause we're using the PortfolioItem field to make this change, as explained.

However, from the user-interface, we use the Parent field to make this association. Since the Feature field (or other lowest-level field) is a Read-Only, then you can't use it in the UI to set a feature. Hence, we use the Parent field to allow associating a story either with a story or with a portfolio item. If a portfolio item is selected, it will then result in an outcome as explained in above example. This practice with the UI may cause a confusion where it makes it seems as if the Feature is supposed to be a true Parent for the story, but it is not. 

To conclude:
- Parent - can only be a user story. It will be 'null' for the top stories of hierarchies, as they have no parent.

- Feature - This field is not necessarily Feature. It is by the name of your workspace's lowest-level portfolio hierarchy. This is a read-only field can can not be set (either from WSAPI or from UI). It is optional to associate user stories with portfolio items. However, if associated then the entire hierarchy will be associated to the same portfolio item object. This field is used to GET the information of if/which portfolio item is linked with the story.

- PortfolioItem - This field is used to actually associate a user story with a portfolio item. It is constructed to allow associating only with that lowest-level type and will not allow other portfolio types which are higher up. Upon associating a portfolio item to a story, it will clear/unset it's Parent field, hence making this story a root of a new story-hierarchy. It will also trickle down the portfolio item and associate it with all stories in this new hierarchy.