Is there any documentation about how Revision.Description is populated and under what condition?
I’m writing a Custom Application for Rally so that I can view changes made to Task and HierarchicalRequirement objects via a table with a rolling 7 day period.
The attributes that I’m interested in are:
HierarchicalRequirement
- PlanEstimate
- TaskEstimateTotal
- TaskActualTotal
- TaskRemainingTotal
Task
- Estimate
- ToDo
- Actuals
I’m traversing Revisions to get snapshot views of tasks and stories:
It’s easy to retrieve these attributes for the current day. However, I need to traverse RevisionHistory -> Revisions and then parse the Revision.Description to apply the differences for Task and HierarchicalRequirement objects. This may provide a daily snapshot of each object.
For example: the following were appended to Revision.Description after took place:
TASK REMAINING TOTAL changed from [7.0] to [4.0]
TASK ESTIMATE TOTAL changed from [7.0] to [4.0]
The “rolling 7 day” period is just an example. My intention is to create a table with a breakdown of Team -> Story -> Task -> Estimate -> ToDo along the y-axis and Iteration -> daily-date along the x-axis.
Tim.
The Revision.description field on many of the Rally object types was not originally intended for developers to get change information but rather for display purposes for our Rally ALM SaaS tool – that’s why changes are put in a Revision attribute called ‘description’ which is just a text field. So there is no developer documentation on the format of this data since it is a text field and not intended to be parsed and the format could change in the future (in the future there will be a better way to get object change information. More on this later in this post…)
However, there is a pattern in this data. It is:
ATTRIBUTE_NAME action VALUE_CLAUSE
The actions are ‘added’ or ‘changed’.
The value clause format is based on the action type. For the ‘added’ action the value clause is [value]. For the ‘changed’ action the value clause is ‘from [old value] to [new value]’.
For example, for an existing User Story that had an owner set to ‘Newt’ from ‘No Entry’, a new revision instance is created the description would have this contained in it:
OWNER added [Newt]
If then later the user changed the owner to ‘John’, then a new revision will be created that looks like this:
OWNER changed from [Newt] to [John]
If there is more than one attribute change then the changes are separated by commas and there is no guaranteed sorting order of the changes.
Now for the better way to do this in the future. Since you are not the only developer that wants to get at object changes we have a new product under development that will have WSAPI endpoints exposed where you can get changes for an object in a programatic way that should avoid you needing to parse data. But since this product is under development you’ll have to do what you are doing now and hopefully my explanation of the format of the data in the description will help you in the meantime.
Hope this helps.