Merge pull request #2741 from MicrosoftDocs/main

Auto Publish – main to live - 2025-08-25 05:00 UTC

Author: learn-build-service-prod[bot]

articles/azure-monitor/app/work-item-integration.md

@@ -7,50 +7,52 @@ ms.date: 08/21/2025
 
 # Work item integration
 
-Work item integration lets you create issues, bugs, or tasks in GitHub or Azure DevOps directly from Application Insights experiences. Templates embed Kusto Query Language (KQL) queries and workbook content so that new work items include relevant telemetry.
+Work item integration lets you create issues, bugs, or tasks in [GitHub](https://github.com) or [Azure DevOps](/azure/devops/user-guide/what-is-azure-devops) directly from [Application Insights](app-insights-overview.md) experiences. Templates embed [Kusto Query Language (KQL)](/kusto/query) queries and [workbook](../visualize/best-practices-visualize.md) content so new work items include relevant telemetry.
 
-Work item integration offers the following features compared to classic integration:
+Work item templates are [Azure Monitor Workbooks](../visualize/workbooks-overview.md) saved as the `Microsoft.Insights/workbooks` resource type. Author and automate these workbooks like any other workbook.
+
+Work item integration includes the following features:
 
 > [!div class="checklist"]
-> - Repository icons that differentiate between GitHub and Azure DevOps workbooks.
-> - The Application Insights resource is in the same subscription as the target resource.
-> - Multiple configurations for any number of repositories or work items.
-> - Deployment by using Azure Resource Manager templates.
-> - Pre-built and customizable KQL queries that add Application Insights data to work items.
-> - Customizable workbook templates.
+> - Indicate whether a template targets [GitHub](https://github.com) or [Azure DevOps](/azure/devops/user-guide/what-is-azure-devops) by using repository icons.
+> - Support multiple configurations for any number of repositories or work items.
+> - Deploy by using [Azure Resource Manager (ARM)](/azure/azure-resource-manager/management/overview) templates.
+> - Include prebuilt and customizable [Kusto Query Language (KQL)](/kusto/query) queries that add [Application Insights](app-insights-overview.md) data to work items.
+> - Provide customizable [workbook](../visualize/best-practices-visualize.md) templates.
+
+> [!NOTE]
+> [Release annotations](annotations.md) require the Application Insights resource and the target resource to be in the same subscription. This requirement doesn't apply to creating work items in GitHub or Azure DevOps.
+
+## Permissions
+
+To create or edit a work item template, use an Azure role with `Microsoft.Insights/workbooks/write`, such as **Workbook Contributor** or **Monitoring Contributor**.  
+
+To create the work item itself, you need sufficient permission in the target system ([GitHub](https://github.com) or [Azure DevOps](/azure/devops/user-guide/what-is-azure-devops)). The item is created in that system after the portal opens a new tab.
 
 ## Create and configure a work item template
 
-1. Open your Application Insights resource. Under **Configure**, open **Work Items**, and then select **Create a new template**.
-1. Alternatively, start from **End-to-end transaction details** when no template exists. Select an event, select **Create a work item**, and then select **Start with a workbook template**.
-1. After you select **Create a new template**, choose your tracking systems, name the workbook, link to your tracking system, and choose a region for template storage. The URL parameters are the default URLs for your repositories, for example, `https://github.com/myusername/reponame` or `https://dev.azure.com/{org}/{project}`.
+1. Open your [Application Insights](app-insights-overview.md) resource. Under **Configure**, open **Work Items**, and then select **Create a new template**.
+1. Or, start from [**End-to-end transaction details**](failures-performance-transactions.md#transaction-diagnostics-experience) when no template exists. Select an event, select **Create a work item**, and then select **Start with a workbook template**.
+1. After you select **Create a new template**, choose your tracking system, name the workbook, link to your tracking system, and choose a region for template storage. Enter the default repository URL, such as `https://github.com/myusername/reponame` or `https://dev.azure.com/{org}/{project}`. The selected region is the Azure location of the saved workbook resource. It doesn't change where Application Insights data is stored or queried.
 1. Set default work item properties in the template. Properties include assignee, iteration path, and projects. Available properties depend on your tracking system.
 
 > [!NOTE]
-> For on-premises Azure DevOps environments, use a placeholder URL such as `https://dev.azure.com/test/test` when you create the template. After creation, update the URL and its validation rule in the generated [Azure workbook](/azure/azure-monitor/visualize/workbooks-create-workbook).
+> For on-premises [Azure DevOps](/azure/devops/user-guide/what-is-azure-devops) environments, use a placeholder URL such as `https://dev.azure.com/test/test` when you create the template. After creation, open the generated [Azure workbook](/azure/azure-monitor/visualize/workbooks-create-workbook), edit the repository URL text parameter, and add a validation rule (regular expression) that matches your Azure DevOps Server host, for example `^https://devops\.contoso\.corp/.*$`.
 
 ## Create a work item
 
-You can use a template from **End-to-end transaction details**, which you can open from **Performance**, **Failures**, **Availability**, and other tabs.
+Use a template from [**End-to-end transaction details**](failures-performance-transactions.md#transaction-diagnostics-experience), which is available from [**Performance**, **Failures**](failures-performance-transactions.md), [**Availability**](availability.md), and other tabs.
 
-1. Open **End-to-end transaction details**, select an event, select **Create work item**, and then choose a template.
-1. A new browser tab opens in your tracking system. In Azure DevOps, you can create a bug or task. In GitHub, you can create an issue in your repository. The work item is prepopulated with contextual information from Application Insights.
+1. Open [**End-to-end transaction details**](failures-performance-transactions.md#transaction-diagnostics-experience), select an event, select **Create work item**, and then choose a template.
+1. A new browser tab opens in your tracking system. In [Azure DevOps](/azure/devops/user-guide/what-is-azure-devops), create a bug or task. In GitHub, create an issue in your repository. The work item is prepopulated with contextual information from [Application Insights](app-insights-overview.md).
 
 ## Edit a template
 
-1. Open **Work Items** under **Configure**, and then select the pencil icon next to the workbook to update.
+1. Open **Work Items** under **Configure**, and then select the pencil icon next to the [workbook](../visualize/best-practices-visualize.md) to update.
 1. Select **Edit** in the top toolbar.
-1. To standardize workbook deployment across environments, use Azure Resource Manager templates and create multiple configurations for different scenarios.
-
-## Classic work item integration
-
-1. In your Application Insights resource, open **Work Items** under **Configure**.
-1. Select **Switch to Classic**, fill out the fields, and authorize.
-1. Create a work item by opening **End-to-end transaction details**, selecting an event, and then selecting **Create work item (Classic)**.
-
-### Migrate to the new integration
+1. To standardize workbook deployment across environments, use [Azure Resource Manager (ARM)](/azure/azure-resource-manager/management/overview) templates. Create multiple configurations for different scenarios.
 
-To migrate, delete the classic configuration and then create a new template.
+## Troubleshooting
 
-1. In your Application Insights resource, open **Work Items** under **Configure**, select **Switch to Classic**, and then select **Delete**.
-1. Create and configure a new template by using the steps in [Create and configure a work item template](#create-and-configure-a-work-item-template).
+- **Create work item** doesn't appear in **End-to-end transaction details**: First create a template or start with **Start with a workbook template** from the **Create a work item** flow.
+- On-premises Azure DevOps URL is rejected: To match your host, update the workbook's repository URL text parameter and its validation rule (regular expression).