API to get Percentage complete for an Epic in AzureDevops

Question

Hi All,

I am trying to integrate Azuredevops with the ServiceNow application. I have configured the service hooks for my project.

This is my use case :

I have 10 User Stories under an Epic.

5 of them are closed. which means the percentage complete is 50 %.

If any UserStory state is updated, then the percentage completed also gets changed.

1. Is there any service hook event just like 'workitem updated' to get the percentage completed for an epic ???
2. Is there any API available wherein if I pass the list of EPIC ids, I get the percentage completed values ??

Answer 1

No because you're putting an emphasis on something that has value to you but not DevOps. You use Epic like it is special but it isn't. It is just 1 work item type of 1 process template. It has no special meaning whatsoever to DevOps. In fact you can remove it if you want and DevOps wouldn't care. The only thing that DevOps really cares about is whether a work item type is categorized as a backlog work item (e.g. stories) or not (e.g. tasks). Beyond that you can have any work item types you want (many people create custom ones) and the work items can have relationships with other work items (not enforced by DevOps outside backlog work items).

Given this we can generalize your question to "how do I get the % of child work items are completed for a given work item". Here you are specifically interested in Epic but it could be applied to Stories/Features and whatever other work item types you use. It is easy to get a count of child work items given the parent work item. It is also easy to get the state of each child work item. Combining this together you should query the parent work item for its children using Get Work Item. Then get the children using List. Given the children you now have the ability to calculate the percentage as (completed / total). Note that how you define completed is up to you, hence why there is no API. You might use specific states to mark completed or perhaps the IsComplete attribute (or whatever it is called). For Epics that tie to User Story you might use the Closed indicator. It is up to you to decide the rules.

As an aside also note that the relationships are customizable. You probably haven't customized yours so for the "children" you should just be looking for that one relationship. However ensure you do validate the relationship type as you wouldn't want to accidentally include other relationships like successors, related, etc.

1. Given a work item you can determine the % of "complete" it is. You mention service hooks but these are notifications. So I'm assuming you get a notification when a work item is updated. It is at that point you would then go through the aforementioned process of getting the updated %. To do that I'm assuming you're getting notified that a child has been updated. Since you probably only care when the child is moving to the "completed" state I would say that when your handler determines the work item has transitioned states (either way), then get the parent of the current work item and use the earlier code to calculate the parent's completion.
2. Yes you can use the List operation to get a list of work items. You'll use that to get the children when calculating the %.

For perf/reporting reasons you might want to consider adding a custom field to your Epic (or whatever types you care about). Store the completion % in there and make it read only on any UI you show. This might also allow you to get a hook call when you update the work item's field. Normally I would handle this via a state change rule but I don't think the state change rules are flexible enough to do what you want here.