Azure DevOps Work Items Microsoft Graph connector

The Azure DevOps Graph connector allows your organization to index work items in its instance of the Azure DevOps service. After you configure the connector and index content from Azure DevOps, end users can search for those items in Microsoft Search.

Note

Read the Setup for your Microsoft Graph connector article to understand the general connectors setup instructions.

This article is for anyone who configures, runs, and monitors an Azure DevOps connector. It supplements the general setup process, and shows instructions that apply only for this connector.

Important

The Azure DevOps connector supports only the Azure DevOps cloud service. Azure DevOps Server 2019, TFS 2018, TFS 2017, TFS 2015, and TFS 2013 are not supported by this connector.

Before you get started

You must be the admin for your organization's M365 tenant as well as the admin for your organization's Azure DevOps instance.

To allow the connector to connect to your Azure DevOps Organization, you must enable Third-party application access via OAuth. Refer Azure DevOps documentation to manage security policies to learn more.

You will need the following permissions granted to the user account whose credentials are used during the connector configuration:

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 will be crawled for which the user account has permissions.

Important

The user account must have Basic access level. To learn more about access levels in Azure DevOps, read supported access levels.

Step 1: Add a connector in the Microsoft 365 admin center

Follow the general setup instructions.

Step 2: Name the connection

Follow the general setup instructions.

Step 3: Configure the connection settings

To connect to your Azure DevOps instance, you need your Azure DevOps organization name, its App ID, and client secret for OAuth authentication.

Register an app

Register an app in Azure DevOps so that the Microsoft Search app can access the instance. To learn more, see Azure DevOps documentation on how to register an app.

The following table provides guidance on how to fill out the app registration form:

Mandatory Fields	Description	Recommended Value
Company Name	The name of your company.	Use an appropriate value
Application name	A unique value that identifies the application that you're authorizing.	Microsoft Search
Application website	The URL of the application that will request access to your Azure DevOps instance during connector setup. (Required).	For M365 Enterprise: https://gcs.office.com/, For M365 Government: https://gcsgcc.office.com/
Authorization callback URL	A required callback URL that the authorization server redirects to.	For M365 Enterprise: https://gcs.office.com/v1.0/admin/oauth/callback, For M365 Government: https://gcsgcc.office.com/v1.0/admin/oauth/callback
Authorized scopes	The scope of access for the application	Select the following scopes: Identity (read), Work Items (read), Variable Groups (read), Project and team (read), Graph (read), Analytics (read)

Important

The authorized scopes that you select for the app should match the scopes exactly as listed above. If you omit one of the authorized scopes in the list, or add another scope, the authorization will fail.

On registering the app with the details above, you'll get the App ID and Client Secret that will be used to configure the connector.

Note

To revoke access to any app registered in Azure DevOps, go to User settings at the right top of your Azure DevOps instance. Select Profile and then select Authorizations in the Security section of the side pane. Hover over an authorized OAuth app to see the Revoke button at the corner of the app details.

Connection settings

After registering the Microsoft Search app with Azure DevOps, you can complete the connection settings step. Enter your organization name, App ID, and Client secret.

Configure data: select projects and fields

You can choose for the connection to index either the entire organization or specific projects.

If you choose to index the entire organization, items in all projects in the organization will get indexed. New projects and items will be indexed during the next crawl after they're created.

If you choose individual projects, only work items in those projects will be indexed.

Note

Azure DevOps projects can be crawled after granting them the View project-level information and View analytics permissions.

Next, select which fields you want the connection to index and preview data in these fields before proceeding.

Step 4: Manage search permissions

The Azure DevOps connector supports search permissions visible to Only people with access to this data source or Everyone. If you choose Only people with access to this data source, indexed data will appear in the search results for users who have access to them based on permissions to users or groups at the Organization, Project or Area path level in Azure DevOps. If you choose Everyone, indexed data will appear in the search results for all users.

Step 5: Assign property labels

Follow the general setup instructions.

Step 6: Manage schema

Follow the general setup instructions.

Step 7: Choose refresh settings

The Azure DevOps connector supports refresh schedules for both full and incremental crawls. The recommended schedule is one hour for an incremental crawl and one day for a full crawl.

Step 8: Review connection

Follow the general setup instructions.

Tip

Default Result type

• The Azure DevOps 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 will be named as "ConnectionIdDefault". For example, if your connection id is AzureDevOps, your result layout will be named: "AzureDevOpsDefault"
• Also, you can choose to create your own result type if needed.

Troubleshooting

The following are common errors observed while configuring the connector, or during crawling, and its possible reasons.

Step	Error message	Possible reason(s)
Connection settings	Invalid Credentials detected. Try signing in with a different account or check the permissions for your account	Third-party application access via OAuth may be disabled. Follow steps to manage security policies to enable OAuth.
Connection settings	Bad state message in OAuth pop-up window with URL stating error=InvalidScope	Wrong scopes provided to the registered app.
Connection settings	400 - Bad request message in OAuth pop-up window	Incorrect App ID
Connection settings	BadRequest: Bad Request on api request message in OAuth pop-up window	Incorrect Client secret
Crawl time (post connector configuration)	The account associated with the connector doesn't have permission to access the item.	The registered app does not have any of the required OAuth scopes. (Note - A new OAuth scope requirement 'Analytics:read' was introduced on 8/31/2021)
Crawl time (post connector configuration)	You don't have permission to access this data source. You can contact the owner of this data source to request permission.	Third-party application access via OAuth is disabled. Follow steps to manage security policies to enable OAuth.
Crawl time (post connector configuration)	Credentials associated with this data source have expired. Renew the credentials and then update the connection	The registered app may have been deleted or expired.
Crawl time (post connector configuration)	Item listed but no longer accessible or no longer exists	The crawling account may be missing 'Basic' access level. Crawls fail with 'Stakeholder' access.