Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The Azure DevOps Work Items Microsoft Graph connector allows your organization to index work items in its instance of the Azure DevOps service. After you configure the connector, end users can search for work items from Azure DevOps in Microsoft Search and Microsoft 365 Copilot.
This article is for Microsoft 365 administrators or anyone who configures, runs, and monitors an Azure DevOps Work Items Microsoft Graph connector.
Important
The Azure DevOps Work Items Microsoft Graph connector supports only the Azure DevOps cloud service. The connector doesn't support Azure DevOps Server 2019, TFS 2018, TFS 2017, TFS 2015, and TFS 2013.
Capabilities
- Index Work Items from Azure DevOps
- Enable your end users to ask questions related to work items.
- Use Semantic search in Copilot to enable users to find relevant content based on keywords, personal preferences, and social connections.
Limitations
- The connector only indexes one ADO organization per connection.
Prerequisites
You must be the search admin for your organization's Microsoft 365 tenant.
Crawl Account: The connector utilizes the logged-in Microsoft 365 Admin's account as the crawl service account. To connect to Azure DevOps and allow the Microsoft Graph connector to update work items regularly, you need to grant the Microsoft 365 Admin account with the following permissions.
Permission name Permission type Required for View project-level information Project permission Crawling Azure DevOps Work Items. This permission is mandatory for the projects that need to be indexed. View analytics Project permission Crawling Azure DevOps Work Items. This permission is mandatory for the projects that need to be indexed. View work items in this node Area path Crawling Work Items in an area path. This permission is optional. Only those area paths are crawled for which the user account has permission.
Important
The crawl account must have Basic access level. To learn more about access levels in Azure DevOps, read supported access levels.
Get Started
1. Display name
A display name is used to identify each citation in Copilot, helping users easily recognize the associated file or item. Display name also signifies trusted content. Display name is also used as a content source filter. A default value is present for this field, but you can customize it to a name that users in your organization recognize.
2. ADO Organization
The Azure DevOps connector allows indexing of one organization per connection. To connect to your Azure DevOps service, provide the name of the organization to be indexed.
Important
- Ensure that you enter the name of the organization only and not the complete URL of the organization.
- Here's an example of incorrect input -
https://dev.azure.com/<Organization_name>/ - Here's an example of correct input -
<Organization_name>
3. Authentication type
To authenticate and sync work items from Azure DevOps, follow the below steps:
Important
- Microsoft Entra ID OAuth is the recommended OAuth mechanism.
- Azure DevOps OAuth is the legacy authentication mechanism, not being actively invested upon. This method is now on the path to deprecation.
Microsoft Entra ID OAuth
Ensure your ADO Organization is connected to Microsoft Entra
The Azure DevOps Graph connector only indexes content from an ADO organization connected with Microsoft Entra of your tenant. To ensure that your ADO organization is connected with Microsoft Entra account, use the following steps.
- Navigate to Azure DevOps and select the required organization.
- Select
Organization settings. - On the left navigation pane, select
Microsoft Entraunder the 'General' header. - Ensure that the organization is connected to your tenant's Microsoft Entra account.
Create an app on Microsoft Entra ID
- Go to the Azure portal and sign in with admin credentials for the tenant.
- Navigate to Microsoft Entra ID -> Identity -> Applications -> App registrations from the navigation pane and select New registration.
- Provide a name for the app and select Register.
- Make a note of the Application (client) ID. This ID is used to grant the Microsoft Entra app access to projects in the ADO organization.
- Open API permissions from the navigation pane and select Add a permission.
- Select Azure DevOps and then Delegated permissions.
- Search for the following permissions under vso and select Add permissions.
a. vso.analytics - Analytics (read)
b. vso.graph - Graph (read)
c. vso.identity - Identity (read)
d. vso.project - Project and team (read)
e. vso.variablegroups_read - Variable Groups (read)
f. vso.work - Work items (read) - Select Grant admin consent for [TenantName] and confirm by selecting Yes.
- Check that the permissions are in the "Granted" state.
- Open Authentication from the navigation pane. Select
Add a platformand chooseWeb. Add one of the following URIs under "Redirect URIs":- For M365 Enterprise: https://gcs.office.com/v1.0/admin/oauth/callback
- For M365 Government: https://gcsgcc.office.com/v1.0/admin/oauth/callback
- Under Implicit grant and hybrid flows, check the option for
ID tokens (used for implicit and hybrid flows)and click Configure. - From the navigation pane, select Certificates and secrets under Manage.
- Select New Client secret and select an expiry period for the secret. Copy the generated secret (Value) and save it because it isn't shown again.
- Use this Client secret and the application ID to configure the connector.
Authenticate the Microsoft Entra app with crawl account
Your Entra app should automatically get authenticated with the logged in Admin account due to single sign-on. Microsoft Entra issues an access token to the application. This access token contains information about the user and the delegated permissions that have been granted. The application uses the access token to make requests to Azure DevOps. The application can only access data and perform actions that the signed-in user is also authorized to do.
4. Roll out to limited audience
Deploy this connection to a limited user base if you want to validate it in Copilot and other Search surfaces before expanding the rollout to a broader audience. To know more about limited rollout, see staged rollout.
At this point, you're ready to create the connection for Azure DevOps work items. You can click Create to publish your connection and index work items from your Azure DevOps organization.
For other settings, like Access Permissions, Data Inclusion Rules, Schema, Crawl frequency, etc., we have defaults based on what works best with ADO data. You can see the default values below:
| Users | Description |
|---|---|
| Access permissions | Only people with access to content in Data source. |
| Map Identities | Data source identities mapped using Microsoft Entra IDs. |
| Content | Description |
|---|---|
| Projects | All projects are indexed. |
| Manage Properties | To check default properties and their schema, see content |
| Sync | Description |
|---|---|
| Incremental Crawl | Frequency: Every 15 mins |
| Full Crawl | Frequency: Every Day |
If you want to edit any of these values, you need to choose the "Custom Setup"
Custom Setup
Custom setup is for those admins who want to edit the default values for settings listed in the above table. Once you click on the "Custom Setup" option, you see three more tabs - Users, Content, and Sync.
Users
Access Permissions
The Azure DevOps Work Items connector supports search permissions visible to Everyone or Only people with access to this data source. If you choose Everyone, indexed data appears in the search results for all users. If you choose Only people with access to this data source, indexed data appears in the search results for users who have access to them.
Note
Updates to groups governing access permissions are synced in full crawls only. Incremental crawls don't support processing of updates to permissions.
Content
Choose projects
In this step, you specify the scope of data that you want to index using the Azure DevOps Work Items Microsoft Graph connector. You can then choose for the connection to index either the entire organization or specific projects within the selected organization.
If you choose to index the entire organization, work items in all projects in the organization are indexed. New projects and work items are indexed during the next crawl after they're created.
If you choose to index individual projects, only work items in the selected projects are indexed.
Note
Azure DevOps projects can be crawled after granting the View project-level information and View analytics permissions.
Manage Properties
Here, you can add or remove available properties from your Azure DevOps data source, assign a schema to the property (define whether a property is searchable, queryable, retrievable, or refinable), change the semantic label and add an alias to the property. Properties that are selected by default are listed below.
| Source Property | Label | Description | Schema |
|---|---|---|---|
| AreaPath | The area path to the work item | Query, Retrieve, Search | |
| AssignedTo | Name of person the work item is assigned to | Query, Retrieve, Search | |
| Authors | Authors | Retrieve | |
| ChangedBy | Last modified by | Person name who last modified the work item | Query, Retrieve |
| ChangedDate | Last modified date time | Query, Retrieve | |
| CreatedBy | Created by | Person name who created the work item | Query, Retrieve, Search |
| CreatedDate | Created date time | Timestamp when work item was created | Query, Retrieve |
| Description | Content | Description of work item | Search |
| IconUrl | IconUrl | Retrieve | |
| Id | Work item ID | Query, Retrieve, Search | |
| Priority | Priority of work item | Query, Retrieve | |
| ReproSteps | Steps to reproduce a condition described in work item | ||
| State | Current state of the work item | Query, Retrieve, Search | |
| Tags | Query, Retrieve, Search | ||
| TeamProject | Retrieve | ||
| Title | Title | Title of the work item | Retrieve, Search |
| URL | url | URL of the work item | Retrieve |
| WorkItemType | Query, Retrieve, Search |
Preview Data
Use the preview results button to verify the sample values of the selected properties.
Sync
The refresh interval determines how often your data is synced between the data source and the Graph connector index. There are two types of refresh intervals - full crawl and incremental crawl. For more information, see refresh settings.
You can change the default values of refresh interval from here if you want to.
Tip
Default result type
- The Azure DevOps Work Items Microsoft Graph connector automatically registers a result type once the connector is published. The result type uses a dynamically generated result layout based on the fields selected in step 3.
- You can manage the result type by navigating to Result types in the Microsoft 365 admin center. The default result type is named "
ConnectionIdDefault". For example, if your connection ID isAzureDevOps, your result layout is named: "AzureDevOpsDefault" - Also, you can choose to create your own result type if needed.
Troubleshooting
After publishing your connection, you can review the status under the Data sources tab in the admin center. To learn how to make updates and deletions, see Manage your connector. You can find troubleshooting steps for commonly seen issues here.
If you have issues or want to provide feedback, contact Microsoft Graph | Support.