diff --git a/docs/README.md b/docs/README.md index 5ae6d0113..93df60481 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,126 @@ +# CoE Starter Kit Troubleshooting Documentation + +This directory contains troubleshooting guides for common issues encountered when using the CoE Starter Kit. + +## Available Troubleshooting Guides + +### Data Sync Issues +- [AI Credits Usage Data Not Updating](TROUBLESHOOTING-AI-CREDITS-USAGE.md) - Learn why AI Credits Usage data stops updating and how to fix it + +## General Troubleshooting Steps + +### For Data Not Updating Issues +If any data in your CoE Power BI report is not updating (Apps, Flows, AI Credits, etc.): + +1. **Check if Sync Flows are On** + - Navigate to Power Automate → Solutions → Core Components + - Verify all "Admin | Sync Template v4" flows are turned **On** + - Check the "Admin | Audit Logs" flows if audit data is missing + +2. **Review Flow Run History** + - Open each flow and check the Run History + - Look for failed runs (red status) + - Click on failed runs to see error details + +3. **Verify Dataverse Tables Have New Data** + - Navigate to your CoE Dataverse environment + - Open the relevant tables (admin_apps, admin_flows, admin_aicreditsusages, etc.) + - Check if rows exist with recent Modified On dates + - If no new rows exist, the sync flows are not running or receiving data + +4. **Check the Sync Flow Errors Table** + - Navigate to Tables → Sync Flow Errors (`admin_syncflowerrorses`) + - Look for recent error entries + - Use error messages to diagnose specific issues + +5. **Manually Trigger Sync Flows** + - Run the **Admin | Sync Template v4 (Driver)** flow to trigger all sync flows + - Or manually run individual sync flows for specific data types + +6. **Refresh Power BI Report** + - After confirming new data in Dataverse, refresh the Power BI report + - New data should appear in the visualizations + +## Common Causes of Data Sync Issues + +### Flow is Turned Off +- **Symptom**: No new data appears after a certain date +- **Solution**: Turn on the relevant sync flow + +### Authentication Failures +- **Symptom**: Flow runs fail with "Unauthorized" or authentication errors +- **Solution**: + - Re-authenticate connection references + - Verify the flow owner has necessary permissions + - Check if app registrations or service principals are configured correctly + +### Insufficient Permissions +- **Symptom**: Flow runs fail when accessing specific environments +- **Solution**: + - Ensure the flow owner has System Administrator role in all environments + - Verify Power Platform Admin or Global Admin permissions + +### Environment Not Configured +- **Symptom**: Data from some environments is missing +- **Solution**: + - Check if environments are marked as "Excuse from Inventory" (admin_excusefrominventory) + - Verify environments have Dataverse (admin_hascds = true) + - Ensure environments are not deleted (admin_environmentdeleted = false) + +### Flow Throttling +- **Symptom**: Flow runs slowly or times out +- **Solution**: + - Enable the "DelayObjectInventory" environment variable + - This adds random delays to prevent throttling + - Consider running flows during off-peak hours + +## Need More Help? + +### Official Documentation +- [CoE Starter Kit Documentation](https://learn.microsoft.com/power-platform/guidance/coe/starter-kit) +- [Setup Instructions](https://learn.microsoft.com/power-platform/guidance/coe/setup) +- [Troubleshooting Guide](https://learn.microsoft.com/power-platform/guidance/coe/setup-troubleshooting) + +### Community Support +- [GitHub Issues](https://github.com/microsoft/coe-starter-kit/issues) - Report bugs or ask questions +- [Power Apps Community Forum](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps) - General Power Platform governance questions + +### When Opening an Issue +Please include: +1. **CoE Starter Kit version** (e.g., 4.50.6) +2. **Solution affected** (Core Components, Audit Logs, etc.) +3. **App or flow name** (if applicable) +4. **Steps to reproduce** the issue +5. **Screenshots** of errors or unexpected behavior +6. **Flow run error details** (if available) +7. **What you've already tried** to fix the issue +# CoE Starter Kit Documentation + +This directory contains additional documentation and guides for the CoE Starter Kit. + +## Available Documentation + +### [Service Principal Support Guide](./ServicePrincipalSupport.md) +Comprehensive guide on using Service Principals with the CoE Starter Kit, including: +- Understanding Service Principals vs Service Accounts +- Component-specific support details +- Migration guidance from Service Account to Service Principal +- Best practices and FAQs + +## Official Documentation + +For complete setup instructions and documentation, please visit: +- [Microsoft Power Platform CoE Starter Kit Documentation](https://learn.microsoft.com/power-platform/guidance/coe/starter-kit) + +## Contributing + +If you'd like to contribute to the documentation, please see [HOW_TO_CONTRIBUTE.md](../HOW_TO_CONTRIBUTE.md) in the root of this repository. + +## Questions and Issues + +- **Questions**: Use the [Question issue template](../.github/ISSUE_TEMPLATE/5-coe-starter-kit-question.yml) +- **Bug Reports**: Use the appropriate [issue template](../.github/ISSUE_TEMPLATE/) +- **Discussions**: Visit [GitHub Discussions](https://github.com/microsoft/coe-starter-kit/discussions) # CoE Starter Kit Documentation This directory contains additional documentation, troubleshooting guides, and resources for the Microsoft Power Platform Center of Excellence (CoE) Starter Kit. diff --git a/docs/TROUBLESHOOTING-AI-CREDITS-USAGE.md b/docs/TROUBLESHOOTING-AI-CREDITS-USAGE.md new file mode 100644 index 000000000..fd9e15d30 --- /dev/null +++ b/docs/TROUBLESHOOTING-AI-CREDITS-USAGE.md @@ -0,0 +1,137 @@ +# Troubleshooting: AI Credits Usage Data Not Updating + +## Issue Description +AI Credits Usage data in the CoE Power BI report is not updating after a certain date, even though other data (Apps, Flows, etc.) is syncing regularly. + +## Root Cause +The AI Credits Usage data is populated by the **Admin | Sync Template v4 (AI Usage)** flow, which retrieves AI Builder credit consumption information from the `msdyn_aievents` table in each environment. + +### Key Technical Details +- **Flow Name**: Admin | Sync Template v4 (AI Usage) +- **Source Table**: `msdyn_aievents` (in each environment with Dataverse) +- **Target Table**: `admin_aicreditsusages` (in CoE environment) +- **Trigger**: Runs when an environment record is added or modified in the `admin_environment` table +- **Data Retrieval Window**: The flow uses `LastXDays(PropertyName='msdyn_processingdate',PropertyValue=1)`, which means it only retrieves AI events from the **last 1 day** + +### Why Data Stops Updating +The flow only retrieves data from the last 1 day. If the flow: +- Is turned **OFF** +- Fails to run +- Encounters errors +- Is not triggered due to no environment changes + +Then it will miss historical data, and the Power BI report will show stale information. + +## Solution: Verify and Run the Sync Flow + +### Step 1: Check if the Flow is Turned ON +1. Go to **Power Automate** → **Solutions** → **Core Components** (or **Audit Logs** solution) +2. Locate the flow: **Admin | Sync Template v4 (AI Usage)** +3. Verify the flow **State** is **On** +4. If it's **Off**, turn it on + +### Step 2: Check if the Flow is Running Successfully +1. Open the **Admin | Sync Template v4 (AI Usage)** flow +2. Click **Run history** to see recent executions +3. Look for: + - **Last Run**: Should show recent runs (daily basis expected) + - **Status**: Should show **Succeeded** +4. If there are failures: + - Click on the failed run to see error details + - Common errors: + - Connection authentication issues + - Insufficient permissions (requires System Administrator role in each environment) + - Environment access issues + +### Step 3: Verify Prerequisites +The flow requires: +- **Dataverse environments**: The flow only works for environments with Dataverse (admin_hascds = true) +- **System Administrator privileges**: The user running the flow must have System Admin rights in each environment +- **AI Builder usage**: Only environments with AI Builder usage will have data in `msdyn_aievents` table + +### Step 4: Manually Trigger the Flow +Since the flow is triggered by environment changes, you can manually trigger it: + +#### Option A: Use the Driver Flow +1. Go to **Power Automate** → **Solutions** → **Core Components** +2. Find and run: **Admin | Sync Template v4 (Driver)** +3. This will trigger all Sync Template v4 flows, including AI Usage, for all environments + +#### Option B: Trigger Environment Updates +1. Go to your CoE Dataverse environment +2. Open the **admin_environment** table +3. Make a minor edit to an environment record (e.g., add a space to description and save) +4. This will trigger the **Admin | Sync Template v4 (AI Usage)** flow for that environment + +### Step 5: Check for New Data in Dataverse +After the flow runs successfully: +1. Go to your CoE Dataverse environment +2. Navigate to **Tables** → **AI Credits Usages** (`admin_aicreditsusages`) +3. Check if new records exist with recent **Processing Date** values +4. If no new records appear, verify that: + - The source environments have AI Builder usage + - The `msdyn_aievents` table in source environments contains data + +### Step 6: Refresh the Power BI Report +Once new data is in Dataverse: +1. Open the **CoE Power BI report** +2. Click **Refresh** to reload data from Dataverse +3. Navigate to the **AI Credits Usage** page +4. Verify that new data appears + +## Important Limitations + +### 1-Day Data Retrieval Window +The flow only retrieves data from the **last 1 day** due to the filter: +``` +$filter: msdyn_creditconsumed gt 0 and (Microsoft.Dynamics.CRM.LastXDays(PropertyName='msdyn_processingdate',PropertyValue=1)) +``` + +**Impact**: If the flow is off for multiple days, it cannot retrieve historical data for the missed period. Only data from the last 1 day when the flow runs will be captured. + +**Recommendation**: +- Ensure the flow remains **On** at all times +- Monitor flow run history regularly +- Set up alerts for flow failures using the CoE Sync Flow Errors table + +## Related Flows and Components + +### Full Sync Pipeline +To ensure all CoE data (including AI Credits) updates correctly, verify these flows are **On** and running: + +#### Audit Log Flows +- **Admin | Audit Logs | Office 365 Management API Subscription** +- **Admin | Audit Logs | Sync Audit Logs (V2)** +- **Admin | Audit Logs | Update Data (V2)** + +#### Inventory Sync Flows (Sync Template v4) +- **Admin | Sync Template v4 (Driver)** - Triggers all other sync flows +- **Admin | Sync Template v4 (Apps)** +- **Admin | Sync Template v4 (Flows)** +- **Admin | Sync Template v4 (AI Usage)** ← This flow +- **Admin | Sync Template v4 (Connectors)** +- **Admin | Sync Template v4 (Environments)** +- All other Sync Template v4 flows + +### Dataverse Tables +- **Source**: `msdyn_aievents` (in each environment) +- **Target**: `admin_aicreditsusages` (in CoE environment) +- **Lookup**: `admin_powerplatformusers` (users table) +- **Lookup**: `admin_environments` (environments table) + +## Additional Resources +- [CoE Starter Kit Documentation](https://learn.microsoft.com/power-platform/guidance/coe/starter-kit) +- [Audit Logs Setup](https://learn.microsoft.com/power-platform/guidance/coe/setup-auditlog) +- [Core Components Setup](https://learn.microsoft.com/power-platform/guidance/coe/setup-core-components) + +## Need More Help? +If the issue persists after following these steps: +1. Check the **admin_syncflowerrorses** table for detailed error messages +2. Verify connection references are properly configured +3. Ensure environment variables are set correctly +4. Review the flow run history for specific error details +5. Open a [GitHub issue](https://github.com/microsoft/coe-starter-kit/issues) with: + - CoE Starter Kit version + - Flow run error details + - Screenshots of the issue + - Steps already attempted