It's all about the answers!

Ask a question

Is it possible to retrieve a specific history entry from the work item through the REST API?

Andre Gusmao (801937) | asked May 29 '14, 4:19 p.m.
Here is the scenario:

There is a tool built client using RTC REST API. This tool retrieves the work items from a given time frame and records them in an external database. It is required to retrieve the work item history along with some other attributes.
Whenever a work item is retrieved, history is comprised of all entries.
The question is: is it possible to retrieve a specific history entry? What we want to achieve is a delta update in the work item history in the external database. So let's say a work item has 10 history entries. Through the tool, the work item gets recorded in the external database. After that, the work item was changed, and a 11th history entry was created in RTC. We are able to update the work item in the external database, but instead of recording all history entries over again, we want to record only the 11th history entry. Is this possible to achieve through the REST API?

Accepted answer

permanent link
Brian Fleming (1.6k11928) | answered May 29 '14, 5:12 p.m.
According to the REST API:
"itemHistory (type:, maxOccurs: unbounded). A collection of zero or more WorkItem elements, representing the entire history of the work item. Each state the work item has ever been in is reflected in this history list. "
This means you should be able to perform the same filtering mechanisms on the historic versions of the workitem as you can on the current version.  Sure enough a query such as the one below will only return the itemHistory records modified since 2014-05-01.  You can use this mechanism to create a "delta" pull for your external repository, only pulling itemHistory records that have been created since your last pull.

https://<server:port>/ccm/rpt/repository/workitem?fields=workitem/workItem/itemHistory[modified > 2014-05-01T01:00:00.000-0500]/*/*/*
Andre Gusmao selected this answer as the correct answer

Andre Gusmao commented Jun 02 '14, 4:25 p.m.

Thanks Brian. I will share the information with the rest of the team so they can run a couple of tests.

Best regards,

Andre Gusmao commented Jun 04 '14, 9:04 a.m.

Works fine. Thanks again!

One other answer

permanent link
Henry Armburg Jennings (13076) | answered Sep 12 '14, 5:36 a.m.
 Hi. When I run this query, all I get returned is:

<workItem />
<workItem />
<workItem />
<workItem />
<workItem />
<workItem />

What am I missing so that I actually get some fields returned in the response?! FYI, my query is:

https://<server:port>/ccm/rpt/repository/workitem?fields=workitem/workItem/itemHistory[modified > 2014-09-11T10:00:28.000-0000]/*

Karthik Krishnan commented Sep 12 '14, 5:45 a.m.

Do you have any record which were modified on or after this date? In my experience, if there aren't any records matching, you would always get an empty <workItem />

Brian Fleming commented Sep 12 '14, 10:05 a.m.

I see similar behavior.  I'm not sure why the API returns those empty <workItem/> tags when you filter on itemHistory in this fashion.  You likely have a paged result set though.  If you traverse the "next" links given in your response do any of them contain data?  The other thing you could try is to filter at the workItem level as well:
https://<server:port>/ccm/rpt/repository/workitem?fields=workitem/workItem[modified > 2014-09-11T10:00:28.000-0000]/itemHistory[modified > 2014-09-11T10:00:28.000-0000]/*

Henry Armburg Jennings commented Sep 15 '14, 8:12 a.m.

Thank you both for your quick responses! Karthik, there were hundreds of WIs modified after that date. If there were none, in my experience it doesn't return any elements at all. And Brian, I tried iterating through the many next pages and I got the same response throughout all of the pages. 

However, the link you posted at the bottom has worked for me so thank you very much for that! I am intrigued to know why that works but the original link doesn't - we are on v 4.0.1 - but as long as I have a working solution I'm happy!

Henry Armburg Jennings commented Sep 15 '14, 9:03 a.m.

Actually, one extra question. Is it possible to get, within the same query, fields from the Work Item in addition to fields in itemHistory? For example, finding the latest state ID of the Work Item so that I can verify which Item History element is the current one. 

Your answer

Register or to post your answer.