Agile Central - WSAPI: Get Tags of a Portfolio Item - Feature.

Document ID : KB000076824
Last Modified Date : 09/04/2018
Show Technical Document Details
Introduction:
Dear Rally team, I would like to ask for your assistance with our Rally at Amdocs. We have an API in which we bring all portfolio item features field from Rally to the Beat On Cloud system. But, since we bring the DB names of the field it creates an issue for us to know what is the assigned column in the DB is. For example, for the field “Tags” (as it appears in the Front End) in the WS “TEF Workspace”, project “TEF GLX”, I have no idea what’s the backend name of this column? Is this something you can help with?
Instructions:
In this example we'll use WSAPI to retrieve the Tags of a Feature.

Our Features are displayed in Screen No: 1. We will retrieve the Tags of the Feature with FormattedID = 'F4' . You can see this Tags have one tag with a value of 'S2'.

Screen No: 1
User-added image
 
The first thing to understand about how to retrieve the Tags field is why we don't find it in list of fields of the PortfolioItem/Feature. 
When going to the WSAPI documentation at: https://rally1.rallydev.com/slm/doc/webservice/ and locating the PortfolioItem/Feature in the left pane under the Object Model, then we can see the list of fields as Child Elements. But the Tags field is not in this list.

This is because Tags is inherited from one of the Parent Classes of our object (Feature). We need to locate which is the parent that has the Tags field. The Parent Type of 'PortfolioItem/Feature' is "PortfolioItem", but when clicking there and browsing the Child Elements then we still won't find 'Tags'. So , we'll continue to the next parent. The next parent up the chain is 'Rankable Artificat' but also there we will not find Tags. So, we'll keep on going. The next parent is 'Artifcat'. When examining the “Artifact” definition then we find the Tags field. Being defined on the 'Artifact' level means that 'Tags' is a field is automatically available by inheritance to all sub-classes of 'Artifact' (including Rankable Artifact, PortfolioItem and PortfolioItem/Feature). 
Similarly, we see other Child Elements listed under the Artifact (such as: Name). These fields too are automatically available by inheritance to all sub-classes.

Screen No: 2 shows the Tags field definition as found on the 'Artifact' class. Note the 'Collection URL' parameter which we'll use to actually retrieve the Tags collection later on.

Screen No: 2 
User-added image
 
Let’s now get it via WSAPI.
 
The first thing we notice in the Collection URL is that we need the ObjectID. That ObjectID is of the PortfolioItem/Feature. We need to get it. 
 
The query below will fetch the ObjectID (also fetch Name and Description) for a Feature with FormattedID = ‘F4’.

https://rally1.rallydev.com/slm/webservice/v2.0/portfolioitem/feature?query=(FomattedID = "F4")&fetch=ObjectID,Name,Description&start=1&pagesize=20
 
Screen No: 3 has the JSON response highlighting the received ObjectID:
User-added image
 
Now with the ObjectID, we can get the Tags based on the above-mentioned URL. We will plant our ObjectID to the Collecstion URL to form the GET request. Here is the request (notice it is on ‘Artifact’ because the Tags are on Artifact, as explained above):
https://rally1.rallydev.com/slm/webservice/v2.0/artifact/203131554400/Tags
 
Screen No: 4 displays the JSON response includes the Tags array/collection :
 
User-added image
 
We basically already see the Name of our requested Tag but it's encapsulated under the _tagsNameArray. We can extract from there, or we will need to use the URL in the "_ref" element to form our final get request:

https://rally1.rallydev.com/slm/webservice/v2.0/PortfolioItem/Feature/203131554400/Tags?fetch=Name

Screen No: 5 is highlighting the Name field of the Tag which we asked for:
User-added image