Changing language

Author: kainawroth

support/azure/azure-monitor/app-insights/troubleshoot-work-item-integration.md

@@ -7,84 +7,90 @@ ms.custom: sap:Application Insights portal experiences
 ---
 # Troubleshoot work item integration issues in Application Insights
 
-[Work item integration](/azure/azure-monitor/app/work-item-integration) in Application Insights might not work as expected. This article offers general recommendations and specific troubleshooting steps.
+[Work item integration](/azure/azure-monitor/app/work-item-integration) in Application Insights allows you to create and link work items directly from telemetry data. If this feature isn't working as expected, the following guidance will help you diagnose and resolve common issues.
 
 ## The "Create work item" option doesn't appear in transaction details
 
-**Cause:** Work item integration isn't enabled or the resource isn't linked to Azure DevOps or GitHub.
+If you don't see the option to create a work item, it usually means that integration hasn't been enabled or the resource isn't linked to Azure DevOps or GitHub.
 
-**Check:** In Application Insights, go to **Work Items** and confirm that integration settings are configured.
+**What to do:**
 
-**Fix:** Enable integration and start from the **Create a work item** flow or use a workbook template.
+* In Application Insights, navigate to **Work Items** and confirm that integration settings are configured.
+* Start the process from the **Create a work item** flow or use a workbook template.
 
 ## On-premises Azure DevOps URL rejected
 
-**Cause:** The URL format doesn't meet validation requirements.
+This issue occurs when the URL format doesn't meet validation requirements.
 
-**Check:** Ensure the URL uses HTTPS and matches the validation rule in the workbook parameter.
+**What to do:**
 
-**Fix:** Update the workbook's repository URL parameter and validation rule.
-
-> [!NOTE]
-> If using a self-hosted Azure DevOps instance, make sure it's accessible from the Azure portal.
+* Make sure the URL uses HTTPS and matches the validation rule in the workbook parameter.
+* If you're using a self-hosted Azure DevOps instance, ensure it is accessible from the Azure portal.
 
 ## Authorization prompt doesn't appear or linking fails
 
-**Cause:** Popup blockers or cached tokens may prevent the prompt from appearing.
+If you don't see the authorization prompt or linking fails, it may be caused by popup blockers or cached tokens.
 
-**Check:** Disable popup blockers, allow third-party cookies, and clear your browser cache.
+**What to do:**
 
-**Fix:** Retry linking. If using OAuth, confirm that the required scopes are granted.
+* Disable popup blockers and allow third-party cookies in your browser.
+* Clear your browser cache and try linking again.
+* If you're using OAuth, verify that the required scopes are granted.
 
 ## Work item creation fails with permission errors
 
-**Cause:** Your account doesn't have sufficient permissions in Azure DevOps or GitHub.
-
-**Check:** Verify account roles:
+Permission errors typically mean your account doesn't have sufficient rights in Azure DevOps or GitHub.
 
-* Azure DevOps: Needs *Contribute* permission.
-* GitHub: Needs *Write* access.
+**What to do:**
 
-**Fix:** If using a Personal Access Token (PAT), ensure it includes **Work Items (read/write)** scope.
+* For Azure DevOps, ensure you have *Contribute* permissions.
+* For GitHub, confirm you have *Write* access to the repository.
+* If you're using a Personal Access Token (PAT), make sure it includes *the Work Items (read/write)* scope.
 
 ## Template fails to load or save
 
-**Cause:** Region limitations or missing permissions can prevent templates from loading or saving.
+This problem often occurs due to region limitations or missing permissions.
 
-**Check:** Confirm that the region supports the *Microsoft.Insights/workbooks* resource type and that the resource provider is registered in your subscription.
+**What to do:**
 
-**Fix:** Assign the *Microsoft.Insights/workbooks/write* role or try saving the template in a supported region.
+* Verify that the region supports the *Microsoft.Insights/workbooks* resource type.
+* Check that the resource provider is registered in your subscription.
+* Assign the *Microsoft.Insights/workbooks/write* role or try saving the template in a supported region.
 
 ## Contextual data is missing from created work items
 
-**Cause:** The Kusto Query Language (KQL) query doesn't return the expected schema.
+If the work item doesn't include expected data, the Kusto Query Language (KQL) query may not return the correct schema.
 
-**Check:** Run the query in **Logs** and validate the output fields.
+**What to do:**
 
-**Fix:** Update the query or bindings to match the expected schema.
+* Run the query in **Logs** to confirm the output fields.
+* Update the query or bindings to match the expected schema.
 
 ## Template isn't visible to other users
 
-**Cause:** The template is saved as private or RBAC permissions are insufficient.
+This usually happens when the template is saved as private or RBAC permissions are insufficient.
 
-**Check:** Ensure the template is stored in a shared resource group and not saved as *My Reports*.
+**What to do:**
 
-**Fix:** Grant other users at least *Reader* access to the resource.
+* Ensure the template is stored in a shared resource group and not saved as *My Reports*.
+* Grant other users at least *Reader* access to the resource.
 
 ## Deleting a template doesn't remove existing links
 
-**Cause:** Cached configuration persists after deletion.
+Removing a workbook doesn't automatically clear cached configuration.
 
-**Check:** Refresh the **Work Items** pane in Application Insights or clear your browser cache.
+**What to do:**
 
-**Fix:** If links persist, manually unlink them in the resource settings.
+* Refresh the **Work Items** pane in Application Insights or clear your browser cache.
+* If links persist, manually unlink them in the resource settings.
 
 ## GitHub issue or Azure DevOps item opens in the wrong repository or project
 
-**Cause:** Incorrect default parameters or multiple templates override settings.
+This happens when the default repository or organization URL is incorrect or multiple templates override settings.
 
-**Check:** Open the workbook and confirm the default repository or organization URL parameter.
+**What to do:**
 
-**Fix:** Update defaults or remove conflicting templates.
+* Open the workbook and confirm the default repository or organization URL parameter.
+* Remove or update conflicting templates.
 
 [!INCLUDE [Azure Help Support](../../../includes/azure-help-support.md)]