New History REST API

[Alex Fomin]

Hi,

Starting from 2.24.0 the REST API has a new History API. The old one (Histories/Changes) has been removed.

The new API is added for the following resources:

• Bug
  
• Feature
  
• Impediment
  
• Request
  
• Task
  
• UserStory
  

The new History API will track state changes for the resources.

A history record has the following four fields:

1. Date of modification

2. New entity state

3. Who has  updated a state

4. An updated resource 

For example: /api/v1/Bugs/48000/History

<BugHistories>

<BugHistory Id="136111">

<Date>2012-04-20T00:09:43</Date>

<EntityState Id="160" Name="Planned"/>

<Modifier Id="4">

<FirstName>Oleg</FirstName>

<LastName>Seriaga</LastName>

</Modifier>

<Bug Id="48000" Name="View mode: There is no separation line when no scroll"/>

</BugHistory>

<BugHistory Id="145262">

<Date>2012-06-19T11:42:16.497</Date>

<EntityState Id="6" Name="Coded"/>

<Modifier Id="4136">

<FirstName>Alex</FirstName>

<LastName>Tsayun</LastName>

</Modifier>

<Bug Id="48000" Name="View mode: There is no separation line when no scroll"/>

</BugHistory>

<BugHistory Id="145634">

<Date>2012-06-26T10:54:42.147</Date>

<EntityState Id="397" Name="Tested"/>

<Modifier Id="3362">

<FirstName>Nadia</FirstName>

<LastName>Bulynia</LastName>

</Modifier>

<Bug Id="48000" Name="View mode: There is no separation line when no scroll"/>

</BugHistory>

<BugHistory Id="151417">

<Date>2012-07-16T10:46:02.89</Date>

<EntityState Id="8" Name="Closed"/>

<Modifier Id="10666">

<FirstName>Anastasiya</FirstName>

<LastName>Yurchenkova</LastName>

</Modifier>

<Bug Id="48000" Name="View mode: There is no separation line when no scroll"/>

</BugHistory>

</BugHistories>

The history collection is a regular REST collection and supports all of the REST features (http://dev.targetprocess.com/rest/response_format), including 'take', 'where', and so on.

Unfortunately, there's no way to request history for abstract entities such as Assiganble or General, so if you need this history, you have to get it via a resource (Bugs, 

UserStories and so on).

Note, that TP audit history keeps no exact track of all the updates made within 5 minutes, only the latest update will take over. 

For example, there's no 'In dev' state  in the example above because the bug has been fixed really quickly.

Please, let us know if you want to include any other fields to the new History API or add a history API to the other resources.

P.S. It is not a joke :)

Thanks,

Alex, TP Team

[Alex Fomin]

Some use cases:

1. Get all user story changes performed by some user:
   /api/v1/userStoryHistories?where=Modifier.Id%20eq%201
2. Get all bugs changes for last 30 days:
   /api/v1/BugHistories?where=Date%20gt%20'2013-03-01'
   
3. In what state was the bug at '2013-03-05':
   /api/v1/Bugs/59241/History?where=Date%20lte%20'2013-03-05'&orderbyDesc=Date&take=1&include=[EntityState]
4. How many times do bugs chnage its state?
   /api/v1/Bugs?include=[History-Count]

Thanks,

Alex

[dand...@gmail.com]

Glad to see histories brought into the mix - this is very key for looking at your history (if one of the built in report doesn't do exactly what you want).  It would be helpful if the history record held both the "from" and "to" status as well as a snapshot of the effort columns at the time.
Finally, knowing the status at a date in order to collect entities with certain statuses is so common that it would be helpful to have a function on entities (like bugs) so that the "include" syntax will allow you to constrain based on what the state WAS on a certain date.  Like in the first example in the documentation on REST API making the query return the entities "DONE" during a certain week in the past (rather than DONE currently).

Dan (MICROS)

[Alex Fomin]

Hi Dan,

Both "from" and "to" is not a good way to expand history - we would have to add "from" and "to" for all other fields and we do not want to bloat history records. You can track the changes using previous history record as well.

I'll add effort columns adding to our backlog.

Not exactly understand your last suggestion. Could you provide more examples\use cases?

Thanks,

Alex, TP Team

[ch...@freedomvoice.com]

Hello,

I'd like to be able to track items dropped from iterations or releases.  Could you add those field changes to the History API?

Thanks,

Chris

[Nicholas Elliott]

In the UI, Track -> Audit History allows us to review all the changes that occurred to the ticket, not just the state change. (So for example, a description edit, what it was edited from, and what it was edited to.).  Is this something that is or will be included in the History API? Or is there another way to access it? 

On Monday, April 1, 2013 7:15:55 AM UTC-4, Alex Fomin wrote:

[Alex Fomin]

We have added Iteraion, Release and efforts to History API. I'll add a description field to our backlog.

As for changed from-changed too - it could be easily get from history records.