Edit

Share via

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 new work items include relevant telemetry.

Work item templates are Azure Monitor Workbooks saved as the Microsoft.Insights/workbooks resource type. Author and automate these workbooks like any other workbook.

Work item integration includes the following features:

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 or 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.
  2. Or, 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.
  3. 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.
  4. 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, open the generated Azure 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 work items

Use a template from End-to-end transaction details, which is available from Performance, Failures, Availability, and other tabs.

Note

The first time you select Create work item, you're prompted to link Application Insights to your Azure DevOps organization and project.

A screenshot of the end-to-end transaction details view with a button to create a work item.

  1. Open End-to-end transaction details, select an event, and then choose Create work item.
  2. Pick a template. If no template exists, select Start with a workbook template to create one.
  3. Complete the New Work Item pane. Application Insights prepopulates contextual data from the selected event, for example exception details, operation name, and a link back to the transaction. Add any extra information you need, then save.
  4. A new browser tab opens in your tracking system. In Azure DevOps, create a bug or task. In GitHub, create an issue in your repository. The work item includes the context from Application Insights.

Edit a template

  1. Open Work Items under Configure, and then select the pencil icon next to the workbook to update.
  2. Select Edit in the top toolbar.
  3. To standardize workbook deployment across environments, use Azure Resource Manager (ARM) templates. Create multiple configurations for different scenarios.

Troubleshooting

  • 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).