I'm using the Lookback API to pull a number of metrics one of which is "unpointed" stories, i.e. stories that do not have a Plan Estimate. I've noticed that stories with no PlanEst are returning from the lookback API with 0.0, which is an issue, because I have teams that enter a zero intentionally as a way to note that they will not point the story for some reason and differentiate it from stories they have yet to point. Am I missing something? Or is there a way to update the API to return Nulls or some other value that could indicate a difference between blank and zero?
You may want to use WSAPI instead of Lookback API for this.
You can run this query against the 'Hierarchical Requirement' endpoint:
(PlanEstimate = null)
Or you can alternatively run:
(PlanEstimate = "")
Both of these will return the stories that don't have Planned Estimate set at all (so they will exclude the stories who intentionally have '0' as their value).
Here is the WS-API page where you can try it (Make sure you are logged on to the correct workspace/project in Rally before trying):
Let us know if helped.
To add to what Sagi_Gabay said, it looks like you're trying to differentiate the results of your LBAPI query — it’s always returning 0.0 even when there is no value set for PlanEst, so isn't differentiating between someone actually entering that value vs. never setting any value at all.
The reason is because of the data type on that attribute, which is double, and will never really return null, even though you can query for null.
Primitives (int, double, float, etc) are by definition not reference types, so they cannot have null values.
If you are using the Lookback API because you're pulling historical info, maybe you can somehow eliminate stories with change rows that include "Plan Estimate changed" AND "to [0.00 Points]" OR "Plan Estimate added [0.00 Points]"
Not sure if that's doable, but it would eliminate stories that are intentionally set to 0.0.
I do understand your point about the data types, but it doesn't really answer my question. In the WSAPI and in Rally's interface you can filter PlanEst by null, but not in the LBAPI, which means that the null state must be recorded in the system in some way. Also, your comment points to the data type within the WSAPI documentation, but that doesn't make sense to me. If it were the correct reason it should then preclude nulls in both APIs, which is not the case, no?
Do you see where I'm confused? The two APIs have different behavior regarding what seems to be the same data. Regardless of data type, the WSAPI has that functionality while the LBAPI does not.
Sagi_Gabay, Thanks for the tip. I was originally trying to avoid calling both APIs to get the data I wanted (just getting it all from LBAPI) as the additional call will increase my script run time. It does seem like a viable option at least in the short term, so I'll probably give that a try.
terry.ginzburg thanks for your suggestion. That seems more complicated than Sagi's thought about calling the other API, so I'll probably just add the additional WSAPI call.
Sagi_Gabay... your solution won't work because the WSAPI will only give me current state. I want to see whether or not a story was pointed at various snapshots in time.
terry.ginzburg may have to try your idea when I have the time to sort through the changesets data.
Thanks for your replies and clarification. I hope my reply here isn't too long, but I'd like to address all that's related to this:
1. When I read your original question/description, I didn't realize you are interested in previous snapshots. Your original question suggested you are using LBAPI, but made it seem that you're interested in current stories.
2. You're correct WS-API is only giving you the current state. So you can use that to distinguish between stories with PlanEstimate that's unset vs. that is set to '0'.
3. I did work a quick reproduction of this. I am finding that you are correct where you say that LBAPI indeed is showing '0' as the value of PlanEstimate for both unset, never-set and also those who have been explicitly set to '0'. I can't find it says '0.0' , I can only see it always reads '0'. See an excerpt below where snapshot 14 was unset, snapshot 15 was explicitly set to '0', snapshot 16 was then set to '34', then snapshot 17 was unset again. You can see '0' in all these snapshots (other than #16).
4. Personally, when I'm coming to think of it, I'm unsure it's wrong of LBAPI to tag unset PlanEstimate as '0'. I guess this field is mainly used for calculations and stats and mostly an unset value should suggest it be calculated as '0'. I believe it's for a reason.
I guess with all that in mind, I have two questions:
a. Why do you have teams that explicitly set it to '0'. What does it mean to you that it's '0' vs. unset? What's the actual difference?
b. Considering in you last update you are suggesting you'd like to read the history of this value and not only the current (which WSAPI will help): Can you tell us more on what you're trying to accomplish, what is the type of data you're trying to collect, what is the calculation you're trying to do?
I'm asking to see if we can find an alternative for you to get it done.
While I can check with Engineering on this, my feeling is that it's set to '0' in LBAPI for a reason and I'm not too sure we'll be able to change it.
To answer your questions:
a. My teams explicitly set stories to 0 points to indicate they do not plan to size them. Our organization assesses us on the quality of our Rally data. PlanEstimate is a "required" field for us, but sometimes there are specific instances where we will never have points, so we apply a 0 to indicate that it was an intentional omission. One reason is that we do not size escalations/defects, but some teams track internal defects as stories to differentiate between those the team discovered from those submitted by our client services org. Another reason for pointing to 0 is that the team forgot to point the story before completing it and they do not wish to waste time going back to point old stories. Usually this case is when the story was a very small amount of work.
b. I'm working on creating a snapshot-based burn-up chart which shows how many story points are included/remaining in the release at the end of each iteration. It also the uses the teams' average velocities to predict if they will accomplish the remaining work. One item that throws a wrench into this prediction is unpointed stories as they represent work missing from the burnup. I want to include the count of scheduled, but unpointed stories to note additional risk to the remaining plan, but I don't want to include stories intentionally pointed zero in that count because they represent work outside of how we calculate our velocities.
All that said, I've been playing around with this today and I actually think the WSAPI call will work for me based on my use-case. Since we pretty much only go from unpointed to 0 and never the other way (unless it was a mistake), I can safely follow some basic logic: if LBAPI has 0 and WSAPI has null, then set the snapshot value to null, otherwise, leave it 0.
I'll keep messing around with it and follow up if/when I get it working (or get stuck again).
Thanks much Nicholas for your thorough explanation. Very appreciated.
So, yes, I agree. I think the formula you laid out where If LBAPI has '0' but WSAPI has 'null' then snapshot should be 'null' - I guess it makes sense for your needs and it probably should work considering the uni-direction from unpointed to '0'.
I'd like to include our Product Owner: grama23
Marianne, please have a look at this. It's a very interesting thread.
- Do you know if LBAPI tags unpointed as '0' , is that intentional?
- What do you make of the practice that Nicholas explained here where '0' is intentionally used to indicate omissions?
I'll be interested to see any followups.
UPDATE: I was able to implement a version that queries the WSAPI to differentiate the nulls from the zeros and combines that data back with the LBAPI results. Interestingly, I ran into a separate issue in which GoogleScript's JSON parser viewed the returned 0's as a nulls, which tripped me up for a while. I ended up using regex to parse the JSON response and get what I needed, so it's working now. It runs a little slower than I'd like because of the extra API call and then regex, but it's still usable.
I did some investigation in to this and we do in fact initialize PlanEstimate to 0 if it's null when the first snapshot for a new work item is created. This behavior goes back to 2012 and is probably a design/implementation flaw since it's out of sync with ALM.