🚀 Feature: Azure Boards Dashboard in Component entity

[adityasinghal26]

🔖 Feature description

The Azure Boards dashboard should provide the following views, based on the label provided in Entity catalog YAML

• Overview Card: Count of all the Work Items for a particular entity, grouped by their types (such as Epic, Feature, Story, Task, Bug, etc)
• Tab Content: List of all the Work Items for a particular entity

🎤 Context

In my organization, we are using Azure Boards for Project Management. This feature will allow us to bring project management aspect in our IDP.

✌️ Possible Implementation

I am thinking that it can be implement in the existing Azure DevOps plugin as an additional feature. It will be more sensible to put it together with the rest of the Azure DevOps features.

👀 Have you spent some time to check if this feature request has been raised before?

• I checked and didn't find similar issue

🏢 Have you read the Code of Conduct?

• I have read the Code of Conduct

Are you willing to submit PR?

Yes I am willing to submit a PR!

[freben]

Sure, that sounds like it makes sense and would be useful to many.

You've hit us at a slightly unfortunate time, since we want to stop accepting plugins to this particular repo, and we haven't yet had the time to spin up a separate community owned plugins repo. If you are about to make something like this immediately, you may want to host it from your own repositories in the mean time. Sorry for the inconvenience; we hope to make advancements with a separate repo to help contributors have a place to put their work, some time in the near-to-intermediate future.

[deepan10]

@adityasinghal26 It's a nice idea to have a Board for Azure DevOps. azure-devops is an existing plugin in the Backstage main repo. It has GitTag, Pipeline, and PullRequest components, it's the better place to keep the Board component too.

https://github.com/backstage/backstage/tree/master/plugins/azure-devops/src/components

Also, only the new plugin PR is currently frozen, but the existing one still we can improve.

WDYT? @freben

[adityasinghal26]

@freben I was thinking to do the same as @deepan10 suggested. Since, it'll be an additional feature in the already existing azure-devops plugin, the AzureBoards can be implemented in this repository on top of the existing plugin.

Let us know your POV and I can start development for the same based on your feedback.

[awanlin]

Hi @adityasinghal26, I'm the initial author and maintainer of the Azure DevOps plugin. Overall I think your feature suggestion makes sense to me. I'd like to get an idea of how you would approach this at a high level before we get to submitting any PRs if you don't mind?

I'll be honest this support for work items is actually something that very rarely comes ups. I'm very active on Discord so that's where my data comes from. Over the last 2 years it's only come up once or twice and this is the first time someone has logged an issue about it. Compounding this is that when I first looked at the APIs for this they were a bit of a mess and not easy to get at the data you wanted. That's some of the background as to why I haven't built this myself.

Hopefully the APIs have improved and perhaps this will be a lot easier to build and support. Looking forward to hear about how you are thinking of approaching this on a technical level 🚀

[awanlin]

We use azure-devops-node-api as the way we interact with the APIs in the backend plugin. It looks to have support for Work Items so that's good.

But looking at the REAT API themselves:

• List: https://learn.microsoft.com/en-us/rest/api/azure/devops/wit/work-items/list?view=azure-devops-rest-7.1&tabs=HTTP
• Get Work Items Batch: https://learn.microsoft.com/en-us/rest/api/azure/devops/wit/work-items/get-work-items-batch?view=azure-devops-rest-7.1&tabs=HTTP

I don't see an easy way to filter this data down in any way to be able to do what you'd like: work item counts by entity or list of work items for a team. I'd be very happy to see I'm just missing something super obvious though

[awanlin]

Perhaps you could use the Search API? https://learn.microsoft.com/en-us/rest/api/azure/devops/search/work-item-search-results/fetch-work-item-search-results?view=azure-devops-rest-7.1&tabs=HTTP. That's not supported by azure-devops-node-api but it's used by the Discovery Entity Provider so it's being used elsewhere in Backstage.

My biggest question is: How do you know a work item is associated to a given entity? I don't have an answer but it would help us determine how we could build this features.

[adityasinghal26]

Hi @awanlin ,

I am thinking to use Wiql - Query By Wiql mechanism to fetch the Work Items list. This would allow us to fetch the work items by writing queries (similar to Queries in Azure DevOps).

The plan is to capture the required entity tag and pass it in the query. Possible implementation approach includes (as below):

• Capture entity tag: dev.azure.com/boards-tag: <entity-name>
• Trigger a REST API call for Wiql, with query passed in the request-body:

SELECT [System.Id], [System.WorkItemType], [System.Title], [System.AssignedTo], [System.State], [System.Tags] from WorkItems
WHERE [System.TeamProject] = 'PROJECT-NAME' 
AND [System.WorkItemType] <> '' 
AND [System.Tags] CONTAINS '<entity-name>'

• Capture the workItems array and categorise the work items by System.WorkItemType, to show number of Features, Tasks, Bugs, etc.
• The obtained workItems array can also be used to populate the list of work items for that entity tag

This will allow us to filter the work items tagged with entity name. Let me know if this answers your concern.

I was checking whether this exists in azure-devops-node-api and probably QueryHierarchyItem (https://github.com/microsoft/azure-devops-node-api/blob/bf07d23edfaa6677c4a4da98fddb6f8745486ebf/api/interfaces/WorkItemTrackingInterfaces.ts#L782) might be our solution. I haven't yet checked it in code but this does make me feel positive about the solution approach.

[awanlin]

OK, that seems like this is more viable from a technical perspective. I totally forgot about WIQL, probably due to my past issues with in from the days of TFS.

My new issue is that we are now dictating how people work with Azure Boards in order to make this work. In the past Orgs I've worked with they would not tags things this way at all. It would be in the Area Path and/or Iteration Path. Obviously that's a small sample size of two so could easily be the exception. Is this how your Org works? @deepan10 @afscrome do you tags your work items like this?

[afscrome]

Tags wouldn't have worked at the places I used ADO with - across two companies and several teams. Area paths would get closer, but even that often wouldn't get you down to a specific component.

My experience is that companies (and even teams within companies) use work items very differently, so I'd be very hesitant about any model that forces an opinion on how to structure work items. The best generic model I could think of would be to have a dev.azure.com/work-item-query annotation which takes in a WQL query on a per entity basis. If a company has a strong convention, they could pre-populate this annotation through a custom entity processor to set the annotaiton. But this feels like a really rough solution.

Another complication to be aware of is that I've often often seen the work items being managed in a different project to the code.

[deepan10]

@awanlin @afscrome @adityasinghal26
We don't use tags like this on work items. dev.azure.com/boards-tag is definitely a good idea, but unfortunately, we are forcing them to work this way in ADO.
The area path may point to a specific team or group, not to a component, especially the one that has the largest number of individual components.

In the Jira Board Plugin, they are doing a pretty similar way of using the component name.

https://github.com/RoadieHQ/roadie-backstage-plugins/blob/500ec31addff07f72a657adb4c207d83d9434af3/plugins/frontend/backstage-plugin-jira/src/api/index.ts#L192-L198

I like the idea of having a generic annotation dev.azure.com/work-item-query and letting the adopters do it with entity processor or entity creator add the query in annotation to get it. I don't see any other way to get the right work items for a particular component without tagging/labeling the component name. Potentially, we can get the same result for tagged work items with dev.azure.com/work-item-query, which also gives way for more customization.

dev.azure.com/work-item-query: SELECT [System.Id], [System.WorkItemType], [System.Title], [System.AssignedTo], [System.State], [System.Tags] from WorkItems WHERE [System.TeamProject] = 'PROJECT-NAME'  AND [System.WorkItemType] <> ''  AND [System.Tags] CONTAINS '<entity-name>'

Another question to you all is, how do we plan the FrontEnd, Table View with filter by work type alone or more similar to JIRA one offers?

As described in the Feature description counting the items by type may break/give false info, if the custom query doesn't have the necessary info type.

[awanlin]

Yeah, with Jira that's a more common pattern to need to provide a project key and component whereas Azure Boards has always been a choose your own adventure everyone seems to have a different way of approaching this.

Thanks for your comments @afscrome and @deepan10, this is largely my concern is that this really doesn't work for a broad segment of people looking for this functionality.

[Rugvip]

Embedding queries in annotations is something we've been avoiding, simply due to how cumbersome it is to update and troubleshoot from the end user perspective. I wonder what something like a dedicated backend CRUD API for managing the filters per entity would look like? Certainly more work to build, but could allow for a cleaner and easier to use frontend experience.

[deepan10]

As per @Rugvip suggestion. We should have more filter Tag, Work Type, Area, Iteration & State based filter along with date.

As an example

dev.azure.com/boards-tag: example-tag
dev.azure.com/boards-worktype: epic,features,userstory,task,bug
dev.azure.com/boards-area: example-area
dev.azure.com/boards-iteration: example-iteration-2024
dev.azure.com/boards-item-state: Active,Closed,InProgress,Resolved

Also this needs to be a combination of one or more too to cover most of the scenario.

Option 1: Pull Tasks & Bug based on Tags

dev.azure.com/boards-tag: example-tag
dev.azure.com/boards-worktype: task,bug

Option 2: Pull only UserStory on based on Tags & Area

dev.azure.com/boards-tag: example-tag
dev.azure.com/boards-worktype: userstory
dev.azure.com/boards-area: example-area

Option 3: Pull All Work Type based on Tags, Area & Iteration

dev.azure.com/boards-tag: example-tag
dev.azure.com/boards-area: example-area
dev.azure.com/boards-iteration: example-iteration-2024

Option 4: Pull only User Story on particular Iteration

dev.azure.com/boards-worktype: userstory
dev.azure.com/boards-iteration: example-iteration-2024-q2

Again Except Tags, How can we identity is the work item is related to one or this component?

[deepan10]

@awanlin @afscrome @Rugvip @adityasinghal26
Friendly pinging no rush. How can we procced now? Any suggestions?.

[awanlin]

I'm still concerned that we are forcing conventions on Orgs that just won't work.

I feel that this should be a stand-alone plugin, ideally developed internally where they are actively using this so that it can be iterated on to find the right UX/DX. Then it could be easily contributed to the community-plugins repo if they so desire.

[daniel-crouch]

Hi all. I was literally looking for this feature myself today and a colleague pointed me in the direction of this issue. We were until recently using Jira as our issue tracker which as mentioned above, the plugin has the ability to specify a component which which makes it reasonably straight forward.

@deepan10's suggestion looks quite flexible, but equally I understand your concern @awanlin as to the convention enforcing approach this brings.

It's clear that adding too much config will make it difficult to maintain and consume, not knowing the logic of and/or conditions.

However, I imagine most organisations will be having to make some customisations to their Azure Boards setup in order for them to organise/group work items per service (component) that they manage.

As such, would an option of a field or custom field in the plug in be a reasonable ask to consumers? e.g.

dev.azure.com/organisation: <organisation>
dev.azure.com/project: <project>
dev.azure.com/boards-area-path: <area-path>
dev.azure.com/boards-component-identifier-field-name: <custom field or existing field>
dev.azure.com/boards-component-identifier-field-value: <could default to the component name defined elsewhere or explicitly set>

I am somewhat still new to Azure Boards, but I dont think the iteration path would be needed, as the area path is probably enough to narrow the search results.

[awanlin]

However, I imagine most organisations will be having to make some customisations to their Azure Boards setup in order for them to organise/group work items per service (component) that they manage.

@afscrome, @deepan10, and my experience is that's not how things worked. I know when we were using Work Items this would be a huge shift away from how we worked and we simply would not use this feature. We ran Backstage for about a year while we still used Work Items and this was never something that came up as a need. Not a great data point but it does hold based on the other experiences shared here.

My challenge with this is less the technical and more around building something that fits a common way that Organizations work with Work Items. Which is why I made this comment:

"I feel that this should be a stand-alone plugin, ideally developed internally where they are actively using this so that it can be iterated on to find the right UX/DX. Then it could be easily contributed to the community-plugins repo if they so desire."

[daniel-crouch]

Thanks for the reply @awanlin, it's all greatly appreciated, and your suggestion of a stand-alone plugin makes perfect sense.

I guess I was exploring the concept further to see if it made anything else logical sense. The fact that the work items are so highly customisable would raise a further challenge; if you were to then present the data, how would you define which fields to show.

Out of pure interest and slightly off topic, how do you see organisations (or your own experience) modelling work items around their services? It feels like a logical approach is setting an 'area path' per service, but then that provides a challenge for teams trying to view their backlog in a single place if they own more than one service.

[afscrome]

It feels like a logical approach is setting an 'area path' per service

Area Paths are shared by stories, features and epics. Whilst an Area Path per service may work ok for stories, it is likely to break down at features and epics. Features and epics are likely to span multiple components (e.g. front end work, backend work, monitoring & alerting work etc.), but can only be assigned a single area path. Additionally a lot of work items will spend the beginning of their life where the component the implementation will go in is unknown - it's not really until you further refine the items, and get to discussing implementation details that you can narrow down a specific component the work belongs to. And some items (particularly spike type items) may even start implementation with the related component being ambiguous.

I've generally seen area paths aligned with higher level concepts. I've fairly commonly seen some kind of general Tech Debt / Continuous Improvement type area path for items the team want to work on as opposed to customer requested. I've also seen area paths that map to core business objectives or initiatives. I've also seen area paths mapped to Cost Centres. You may find there is some correlation between Area Paths and System and Domain entities.

It feels like a logical approach is setting an 'area path' per service, but then that provides a challenge for teams trying to view their backlog in a single place if they own more than one service.

Azure Devops provides ways for you to see work items at a team level. As long as all those area paths are owned by your team in ADO, they'll show up in your teams' combined view / dashboard 1. In fact, if we wanted to do a Group based work item plugin rather than Component, we could probably do one fairly generically - have each Group entity provide a dev.azure.com/team annotation. That would map the entity onto a Team in Azure Devops. Teams in azure devops are associated with one or more area paths. You can then list the work items for those area paths.

I guess the question at this point is what do you want by breaking that list further down by component? Many work items may not yet be refined enough to link to a specific component. And then beyond that, some of those views may provide misleading information - the top prioritised item for FooService may actually be years away as there may be hundreds of work items in other services owned by your team which are prioritised higher than that work item.

[daniel-crouch]

All makes sense. At my organisation we are using Area Path as a way of representing a team backlog, and within that there are multiple services being managed. Currently these are organised/grouped via a custom field called Components which is a multi select field.

The fact that there is nothing "out of the box" to represent a consistent grouping of components to work items, as you have already mentioned, is the ultimate reason for hesitation here. I get that.

Your suggestion of the dev.azure.com/team config works well to a point which is somewhat the previously suggested dev.azure.com/boards-area-path: <area-path>. The annotation query would definitely solve the problem of allowing consumers to apply a custom filter to aid this, but understand @Rugvip's point on trying to avoid this.

Is it fair to summarise this as:

Won't do due to, albeit it technically possible, the implementation would be too cumbersome to maintain and consume due to the nature of Azure DevOps Boards not having a default/consistent approach to grouping work items to a logical component.

@adityasinghal26, just to say I appreciate having seen this issue raised as it has given me visibility of the challenge and reasoning of something I thought would be straight forward/out of the box offering.

[awanlin]

On the topic of area paths, when you create a team doesn't it create an area path based on the team name as the default? It's been a while since I've done this so it might have changed. But guess what I'm try to highlight is just the default experience on how Microsoft sees them being used.

Generally as been highlighted by @afscrome work item management can be messy and it's not always clear what will be all part of the change. Everyones experience will be different though.

On a more technical side, why not just have an annotation that's the name of a work item query? Then the user can build the query in Boards and then this data would be pulled in as is - aggregated or as a table. Pretty sure the API supports this. That would then allow the User to better tune this without needing to make changes to catalog-info.yaml files a bunch of times to get it right.

I'd say "won't do" is not right. Building it as part of the Azure DevOps plugin is something I would push back against. If someone wanted to build this as it's own plugin - Azure Boards - that is totally acceptable in my mind and I would support that at a high level. I also think this should be done internally where you can really learn what the right way to do this is and then open source it. We need a dedicated person who is passionate about this and who will find the right "product market fit"!

[deepan10]

Yes, I totally agreed with @awanlin & @afscrome. Since there is no common approach for Azure DevOps work items and there be many ways to customize it as per Organization needs. Standalone plugin is a good way for now to go with later it can be contributed to the community-plugin.

Annotation to query the work items solves this since the Adopters/Entity Writer can build their own query to fetch the work items but @Rugvip point also valid.
This is more generalized approach for everyone. Just to note there is a plugin prometheus has the annotation query concept to fetch the metrics, so Azure DevOps Board is not the 1st one.

To avoid the direct query in the annotation get only the condition from the annotation and build the query in the backend system

dev.azure.com/work-items: 'TeamProject=ProjectName,WorkItemType=UserStory,Tags=entityname'

In backend system parse the annotation and build the query. since only where condition may vary for entity.

SELECT [System.Id], [System.WorkItemType], [System.Title], [System.AssignedTo], [System.State], [System.Tags] from WorkItems WHERE [System.TeamProject] = 'PROJECT-NAME-FROM-ANNOTATION'  AND [System.WorkItemType] = "TYPE-FROM-ANNOTATION''  AND [System.Tags] = 'TAGS-FROM-ANNOTATION'

WDYT @awanlin @afscrome ??

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.