diff --git a/docs/coe-knowledge/COE-Kit-Common GitHub Responses.md b/docs/coe-knowledge/COE-Kit-Common GitHub Responses.md new file mode 100644 index 000000000..04390970b --- /dev/null +++ b/docs/coe-knowledge/COE-Kit-Common GitHub Responses.md @@ -0,0 +1,337 @@ +# CoE Starter Kit - Common GitHub Responses + +This document provides ready-to-use explanations, limits, workarounds, and guidance for common issues reported in the CoE Starter Kit GitHub repository. + +## Table of Contents + +1. [General Guidelines](#general-guidelines) +2. [Setup Wizard Issues](#setup-wizard-issues) +3. [Power BI Dashboard Issues](#power-bi-dashboard-issues) +4. [Data Export and Dataflows](#data-export-and-dataflows) +5. [Inventory and Telemetry](#inventory-and-telemetry) +6. [Licensing and Pagination](#licensing-and-pagination) +7. [Language and Localization](#language-and-localization) +8. [Standard Questionnaire](#standard-questionnaire) + +--- + +## General Guidelines + +### Support Model + +The CoE Starter Kit is provided as **best-effort/unsupported**. Issues should be investigated through GitHub only, and there is no SLA for resolution. The kit is designed as a template and starting point that organizations should customize for their specific needs. + +**Standard Response:** +> Thank you for reporting this issue. The CoE Starter Kit is provided as a community-supported template without formal SLA. We'll investigate through this GitHub issue. For immediate assistance, please review the [official documentation](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) and check for similar resolved issues in our repository. + +### Where to Get Help + +- **CoE Starter Kit specific issues**: [GitHub Issues](https://github.com/microsoft/coe-starter-kit/issues) +- **General Power Platform governance questions**: [Power Apps Community Forum](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps) +- **Product support issues**: Microsoft Support (for licensed customers) + +--- + +## Setup Wizard Issues + +### Configure Dataflows (Data Export) Step Skipped + +**Issue:** After successfully completing "Run Inventory Flows" step, the setup wizard skips the "Configure dataflows (Data export)" step and moves directly to "Share Apps". + +**Root Cause:** This is expected behavior in most scenarios. The "Configure dataflows (Data export)" step is **optional** and only appears when specific conditions are met: + +1. You must select "Data Export" as your inventory method in earlier steps +2. Data Export features must be enabled in your environment +3. Your tenant must have the appropriate licensing for Dataverse Data Export + +**Standard Response:** +> The "Configure dataflows (Data export)" step being skipped is expected behavior. This step only appears when: +> +> 1. You selected "Data Export" as your inventory and telemetry method +> 2. Data Export features are enabled in your environment +> +> If you selected "Cloud flows" (recommended for most scenarios) or "None" as your inventory method, the setup wizard will skip the dataflow configuration step. This is by design. +> +> **Note on Data Export / BYODL:** As of recent guidance, BYODL (Bring Your Own Data Lake) is no longer the recommended approach. Microsoft is moving toward Fabric integration for advanced analytics scenarios. For most organizations, using Cloud flows for inventory collection is sufficient. +> +> Reference: [Choose your inventory and telemetry method](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#inventory-and-telemetry) + +--- + +## Power BI Dashboard Issues + +### Power BI Dashboard Shows Blank/No Data + +**Issue:** After completing setup wizard and opening the Power BI dashboard, charts show no data or display "There are no Environments in this view to create a Environments chart." + +**Root Causes:** + +1. **Inventory flows haven't run yet** - First-time inventory collection can take several hours +2. **Inventory flows haven't completed successfully** - Check flow run history +3. **Data refresh not configured** - Power BI dashboard needs connection to Dataverse +4. **Insufficient permissions** - User doesn't have read access to CoE tables +5. **Wrong environment connection** - Power BI connected to different environment than where CoE is installed + +**Troubleshooting Steps:** + +1. **Verify inventory flows have run:** + - Navigate to Cloud flows in your CoE environment + - Check the run history of "Admin | Sync Template v3" and other inventory flows + - Flows should show successful runs (green checkmarks) + - First run can take 4-8 hours depending on tenant size + +2. **Check data in Dataverse:** + - Open the CoE environment in Power Apps + - Navigate to Tables (under Dataverse) + - Check if tables like "Environment", "Power Apps App", "Flow" contain data + - If tables are empty, inventory flows haven't completed successfully + +3. **Configure Power BI Dashboard Connection:** + - Download the Power BI template file (.pbit) from the solution + - Open in Power BI Desktop + - When prompted, enter your Dataverse environment URL + - Format: `https://[orgname].crm.dynamics.com/` or `https://[orgname].crm[region].dynamics.com/` + - Click "Load" and sign in with appropriate credentials + - Publish to Power BI Service if needed + +4. **Verify Permissions:** + - User viewing dashboard needs read access to CoE Dataverse tables + - Check security roles in the CoE environment + +**Standard Response:** +> Thank you for reporting this issue. A blank Power BI dashboard is typically caused by one of the following: +> +> 1. **Inventory collection hasn't completed yet** - First-time inventory can take 4-8 hours depending on tenant size +> 2. **Power BI connection not configured correctly** - The dashboard needs to be connected to your CoE Dataverse environment +> +> **Steps to resolve:** +> +> 1. Verify inventory flows have run successfully: +> - Navigate to Cloud flows in your CoE environment +> - Check run history of "Admin | Sync Template v3" and related flows +> - Wait for all flows to complete (check every hour) +> +> 2. Configure Power BI connection: +> - Open the downloaded .pbit file in Power BI Desktop +> - Enter your CoE environment URL when prompted: `https://[orgname].crm.dynamics.com/` +> - Sign in with credentials that have access to the CoE environment +> - Refresh the data +> +> 3. Verify data in tables: +> - In Power Apps, open your CoE environment +> - Navigate to Dataverse > Tables +> - Check if "Environment", "Power Apps App", "Flow" tables contain records +> +> Reference: [Set up the Power BI dashboard](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-powerbi) + +--- + +## Data Export and Dataflows + +### BYODL (Bring Your Own Data Lake) Status + +**Current Recommendation:** BYODL is **no longer recommended** for new implementations. + +**Reasons:** +- Microsoft is moving toward Microsoft Fabric integration for advanced analytics +- BYODL setup is complex and has ongoing maintenance requirements +- Cloud flows provide sufficient inventory for most scenarios +- Fabric will be the recommended path for advanced analytics integration + +**Standard Response:** +> **Note on BYODL/Data Export:** As of current guidance, BYODL (Bring Your Own Data Lake) is no longer the recommended approach for the CoE Starter Kit. Microsoft is moving toward integration with Microsoft Fabric for advanced analytics scenarios. +> +> For most organizations, using **Cloud flows** for inventory collection is the recommended and sufficient approach. This method: +> - Is easier to set up and maintain +> - Works within standard Power Platform licensing +> - Provides all necessary data for CoE dashboards and apps +> +> We recommend avoiding new BYODL setups and using Cloud flows instead. +> +> Reference: [Choose your inventory method](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components) + +--- + +## Inventory and Telemetry + +### Inventory Collection Takes Long Time + +**Expected Behavior:** +- First-time inventory: 4-8 hours (can be longer for very large tenants) +- Incremental updates: 1-2 hours +- Depends on: Number of environments, apps, flows, and tenant size + +**Standard Response:** +> Inventory collection is expected to take several hours, especially on first run: +> - **First-time inventory**: 4-8 hours (can be longer for large tenants) +> - **Incremental updates**: 1-2 hours +> +> This is normal behavior due to API rate limits and the volume of data being collected. Please wait for the flows to complete before expecting data in dashboards. + +### Cleanup and Full Inventory + +**When to run full inventory:** +- After initial setup +- When data appears incorrect or incomplete +- After major tenant changes +- When troubleshooting data issues + +**How to trigger:** +1. Navigate to "Admin | Sync Template v3" flow +2. Manually trigger with appropriate parameters +3. Wait for completion + +--- + +## Licensing and Pagination + +### Pagination Limits and License Requirements + +**Issue:** Some users experience pagination limits when running inventory flows, causing incomplete data collection. + +**Root Cause:** Trial licenses or insufficient license profiles may hit API pagination limits. + +**License Requirements:** +- Power Apps Per App or Per User license (or included with Microsoft 365 licenses) +- Power Automate Per User license (recommended for reliability) +- Appropriate admin roles (Power Platform Admin, Global Admin, or delegated admin) + +**Testing License Adequacy:** + +To test if your license is adequate for CoE Starter Kit: + +1. Check your Power Platform license assignment +2. Verify you have one of: + - Power Apps Per User license + - Power Automate Per User license + - Microsoft 365 E3/E5 (includes limited Power Platform) +3. Test inventory flow runs for pagination errors + +**Standard Response:** +> Pagination limits typically indicate insufficient licensing. The CoE Starter Kit requires adequate Power Platform licensing to function properly. +> +> **Required licenses:** +> - Power Apps Per User or Per App license +> - Power Automate Per User license (recommended) +> - Appropriate admin roles +> +> **To verify:** +> 1. Check your license assignment in Microsoft 365 admin center +> 2. Ensure you're not using trial licenses for production CoE +> 3. Review flow run history for specific pagination errors +> +> Trial licenses may work initially but can hit limitations. For production CoE deployment, proper licensing is essential. + +--- + +## Language and Localization + +### English Language Pack Requirement + +**Issue:** CoE Starter Kit has issues in non-English environments. + +**Limitation:** The CoE Starter Kit currently supports **English only**. The environment where CoE is installed must have the English language pack enabled. + +**Standard Response:** +> The CoE Starter Kit currently supports **English language only**. Please ensure: +> +> 1. Your Power Platform environment has the English language pack installed +> 2. The base language or a secondary language in your environment is English +> 3. Flows and apps may not function correctly in non-English-only environments +> +> We recommend creating a dedicated CoE environment with English as the primary language for best results. + +--- + +## Standard Questionnaire + +When an issue lacks sufficient detail, use this questionnaire template: + +> Thank you for raising this issue. To help us resolve it efficiently, could you please provide the following details: +> +> 1. **Solution name and version**: Which CoE solution are you using (Core, Governance, Nurture, etc.) and what version? +> 2. **App or flow affected**: Specific app or flow name where you're experiencing the issue +> 3. **Inventory/telemetry method**: Are you using Cloud flows, Data Export, or None? +> 4. **Environment details**: +> - Is this a production or trial environment? +> - What region is your environment in? +> - What licensing do you have? +> 5. **Steps to reproduce**: Detailed steps that led to the issue +> 6. **Expected vs Actual behavior**: What did you expect to happen vs. what actually happened? +> 7. **Screenshots/errors**: Any error messages, screenshots, or flow run history +> 8. **Timing**: When did this issue start? After an upgrade, initial setup, or has it always been an issue? +> +> This information will help us analyze and suggest the most appropriate fix. Thank you! + +--- + +## Additional Common Issues + +### Unmanaged Layers Preventing Updates + +**Issue:** Solution updates fail due to unmanaged customizations. + +**Standard Response:** +> Solution updates can fail if you have unmanaged customizations (unmanaged layers) on top of the managed CoE solution. +> +> **To resolve:** +> 1. In Power Apps, go to Solutions +> 2. Select the CoE solution +> 3. Check for "See solution layers" on affected components +> 4. Remove unmanaged customizations before updating +> +> **Best practice:** Don't customize managed CoE components directly. Instead: +> - Extend functionality in separate solutions +> - Copy and customize components you need to modify +> - Keep the base CoE solution unmodified for easier updates + +### DLP Policies Blocking Flows + +**Issue:** Flows fail with connector policy violations. + +**Standard Response:** +> DLP (Data Loss Prevention) policies can block CoE flows if required connectors are in different policy groups. +> +> **Required connectors for CoE (must be in same DLP group):** +> - Dataverse +> - Office 365 Users +> - Office 365 Outlook +> - Power Apps for Admins +> - Power Automate for Admins +> - Power Platform for Admins +> - HTTP (for some scenarios) +> +> **Resolution:** +> 1. Check DLP policies applied to your CoE environment +> 2. Create a DLP policy exception for the CoE environment, or +> 3. Ensure all required connectors are in the "Business" data group +> +> Reference: [DLP considerations](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#dlp-impact) + +--- + +## References + +- [CoE Starter Kit Overview](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) +- [Setup Core Components](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components) +- [Setup Power BI Dashboard](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-powerbi) +- [Troubleshooting Guide](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#troubleshooting) +- [GitHub Issues](https://github.com/microsoft/coe-starter-kit/issues) +- [Power Apps Community Forum](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps) + +--- + +## Contributing to This Document + +This document is maintained by the CoE Starter Kit community. If you have additional common responses, troubleshooting steps, or resolved issue patterns, please contribute via pull request. + +**Update process:** +1. Identify recurring issue pattern +2. Document root cause and resolution +3. Create standard response template +4. Add to appropriate section +5. Submit PR with changes + +--- + +*Last updated: 2025-12-10* diff --git a/docs/coe-knowledge/IMPLEMENTATION-SUMMARY.md b/docs/coe-knowledge/IMPLEMENTATION-SUMMARY.md new file mode 100644 index 000000000..0a54d6a31 --- /dev/null +++ b/docs/coe-knowledge/IMPLEMENTATION-SUMMARY.md @@ -0,0 +1,318 @@ +# CoE Knowledge Base Implementation Summary + +## Overview + +This document summarizes the implementation of the CoE Starter Kit Knowledge Base, created to address recurring support issues and provide standardized responses to common problems. + +## Problem Statement + +The GitHub issue that triggered this implementation reported two common problems: + +1. **Setup Wizard Issue**: The "Configure dataflows (Data export)" step was being skipped after completing the "Run Inventory Flows" step +2. **Power BI Dashboard Issue**: The dashboard showed blank/no data after completing setup + +These issues are very common and have standard explanations and resolutions. However, there was no centralized documentation for support team members to reference when responding to similar issues. + +## Solution Implemented + +Created a comprehensive knowledge base in `/docs/coe-knowledge/` with the following components: + +### 1. COE-Kit-Common GitHub Responses.md (15KB) + +**Purpose**: Master playbook with ready-to-use responses for common issues + +**Contents**: +- General support guidelines and policies +- Setup wizard issue patterns and resolutions +- Power BI dashboard troubleshooting +- Data export and dataflow information +- Inventory and telemetry guidance +- Licensing and pagination requirements +- Language and localization limitations +- Standard questionnaire template +- DLP policy guidance +- References to official documentation + +**Key Topics Covered**: +- ✅ Why dataflow step is skipped (expected behavior) +- ✅ BYODL/Data Export deprecation status +- ✅ Power BI blank dashboard root causes +- ✅ Inventory timing expectations (4-8 hours) +- ✅ Required licenses and permissions +- ✅ English-only language requirement +- ✅ Best practices for issue reporting + +### 2. Setup-Wizard-Troubleshooting.md (8KB) + +**Purpose**: Detailed troubleshooting guide specifically for Setup Wizard issues + +**Contents**: +- Setup wizard flow overview +- Configure dataflows step skip explanation (with decision tree) +- Inventory flows not running diagnostics +- Setup wizard progress not saving +- Pre-requisites verification checklist +- Step-by-step resolution procedures + +**Use Cases**: +- User reports dataflow step missing +- Inventory flows don't start +- Wizard doesn't save progress +- Pre-requisite warnings + +### 3. PowerBI-Dashboard-Troubleshooting.md (14KB) + +**Purpose**: Comprehensive diagnostic guide for Power BI dashboard issues + +**Contents**: +- Dashboard overview and types +- Blank dashboard root cause analysis +- Wrong environment URL diagnosis +- Data source configuration steps +- Permission verification procedures +- Data refresh troubleshooting +- Connection error resolutions +- Partial data missing scenarios +- Diagnostic checklist +- Quick resolution flowchart + +**Use Cases**: +- Dashboard shows no data +- Connection errors +- Refresh failures +- Permission issues +- Partial data display problems + +### 4. Sample-Issue-Responses.md (16KB) + +**Purpose**: Copy-paste templates for responding to specific issue patterns + +**Contents**: +- Setup wizard dataflow step skipped response +- Power BI blank dashboard response +- Combined setup and Power BI issues response (matches the reported issue exactly) +- Missing information request template + +**Use Cases**: +- Quickly respond to common issue patterns +- Maintain consistency in responses +- Ensure all key troubleshooting steps are included +- Provide appropriate links to documentation + +### 5. Quick-Reference-Guide.md (12KB) + +**Purpose**: Fast lookup guide for the most common questions + +**Contents**: +- Top 5 most common issues with quick answers +- Quick check procedures +- Common error messages and fixes +- Environment URLs by region table +- Setup wizard steps overview +- Decision trees for troubleshooting +- Licensing quick reference +- When to escalate guidelines +- Best practices checklist +- Emergency troubleshooting steps + +**Use Cases**: +- Quick answer lookup +- First-time responder guidance +- Rapid triage +- Common patterns recognition + +### 6. README.md (2KB) + +**Purpose**: Directory overview and usage instructions + +**Contents**: +- Purpose and scope of knowledge base +- Document summaries +- Usage guidelines for support team +- Contribution guidelines +- References to external resources + +## How to Use This Knowledge Base + +### For Issue Responders + +1. **Start with Quick Reference Guide** - Check if it's a top 5 issue +2. **Use Sample Responses** - Copy appropriate template +3. **Customize response** - Add specific details from the issue +4. **Reference detailed guides** - Link to Setup or Power BI troubleshooting docs +5. **Update knowledge base** - Add new patterns you discover + +### For Issue Reporters + +While this knowledge base is primarily for support team members, users can also: +1. Review Quick Reference Guide before reporting issues +2. Check if their issue matches common patterns +3. Follow troubleshooting steps to self-resolve +4. Gather required information before reporting + +## Key Learnings Documented + +### Setup Wizard Dataflow Step + +**Finding**: The "Configure dataflows (Data export)" step being skipped is **expected behavior** when: +- User selected "Cloud flows" inventory method (recommended) +- User selected "None" inventory method +- Data Export not configured in environment + +**Action**: No user action needed. This is by design. + +**Documentation Impact**: Many users reported this as a bug. Now documented as expected behavior with clear explanation. + +### Power BI Dashboard Blank + +**Finding**: Most common cause is timing - users expect immediate data but inventory takes 4-8 hours minimum. + +**Resolution Steps**: +1. Verify inventory flows are running +2. Check Dataverse tables have records +3. Ensure correct environment URL in Power BI +4. Wait adequate time for data collection + +**Documentation Impact**: Clear timeline expectations and step-by-step verification procedures now available. + +### BYODL/Data Export Status + +**Finding**: BYODL (Bring Your Own Data Lake) is **no longer recommended** by Microsoft. + +**Recommendation**: Use Cloud flows for inventory collection. + +**Future Direction**: Microsoft Fabric integration for advanced analytics. + +**Documentation Impact**: Clear guidance to avoid new BYODL implementations. + +## Integration Points + +### 1. CoE Custom Agent + +The agent instructions in `.github/agents/my-agent.agent.md` already reference: +```yaml +knowledge_playbook: "docs/coe-knowledge/COE-Kit-Common GitHub Responses.md" +``` + +The agent is instructed to: +- Consult the playbook for ready-to-use explanations +- Use the standard questionnaire when details are missing +- Reference specific sections for BYODL, pagination, licensing, etc. + +### 2. Issue Templates + +Existing issue templates (`.github/ISSUE_TEMPLATE/`) collect appropriate information that maps to knowledge base troubleshooting steps. + +### 3. Official Documentation + +All knowledge base documents reference official Microsoft documentation: +- [CoE Starter Kit Overview](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) +- [Setup Core Components](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components) +- [Setup Power BI Dashboard](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-powerbi) + +## Metrics and Success Criteria + +### Success Indicators + +✅ **Reduced response time**: Standard responses available for copy-paste +✅ **Consistency**: All responders use same troubleshooting steps +✅ **Completeness**: Responses include all necessary verification steps +✅ **Self-service**: Users can find answers before reporting issues +✅ **Knowledge retention**: New patterns documented for future use + +### Measurable Outcomes + +Track these metrics to measure impact: +- Time to first response on common issues +- Number of follow-up questions needed +- User satisfaction with responses +- Frequency of similar issues reported +- Self-service resolution rate + +## Maintenance and Updates + +### When to Update + +Update the knowledge base when: +- ✅ New common issue pattern identified +- ✅ Existing issue resolved in new way +- ✅ Microsoft releases new guidance +- ✅ Product changes affect troubleshooting steps +- ✅ Community identifies gaps in documentation + +### How to Update + +1. Identify the pattern or gap +2. Document root cause and resolution +3. Create sample response if applicable +4. Update appropriate knowledge base file(s) +5. Submit PR with changes +6. Tag with "documentation" label + +### Review Schedule + +Recommend reviewing quarterly: +- Q1: Review and update all documents +- Q2: Check for new patterns from Q1-Q2 issues +- Q3: Align with any product updates +- Q4: Prepare for year-end release cycles + +## Future Enhancements + +### Potential Additions + +1. **Video Guides**: Screen recordings for common troubleshooting +2. **Decision Tree Diagrams**: Visual flowcharts for complex scenarios +3. **FAQ Bot**: Automated responses for common questions +4. **Telemetry Integration**: Track which issues are most common +5. **Multi-language Support**: Translate key documents (if CoE adds language support) + +### Automated Features + +Potential automations: +- Auto-suggest relevant knowledge base articles when issue is created +- Auto-tag issues based on content matching knowledge base patterns +- Auto-close duplicates with link to resolution +- Generate reports on most common issues + +## References + +### Created Files + +``` +docs/coe-knowledge/ +├── README.md (2KB) +├── COE-Kit-Common GitHub Responses.md (15KB) +├── Setup-Wizard-Troubleshooting.md (8KB) +├── PowerBI-Dashboard-Troubleshooting.md (14KB) +├── Sample-Issue-Responses.md (16KB) +├── Quick-Reference-Guide.md (12KB) +└── IMPLEMENTATION-SUMMARY.md (this file) +``` + +### External Links + +- [Microsoft Learn - CoE Starter Kit](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) +- [GitHub Repository](https://github.com/microsoft/coe-starter-kit) +- [Power Apps Community Forum](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps) + +## Conclusion + +This knowledge base provides a comprehensive resource for: +- **Support team members** responding to GitHub issues +- **Community contributors** helping others troubleshoot +- **End users** self-diagnosing common problems +- **Product team** understanding common pain points + +The documentation addresses the specific issues reported while building a foundation for handling similar future issues efficiently and consistently. + +--- + +**Implementation Date**: December 10, 2025 +**Primary Issue Addressed**: Setup wizard dataflow step skipped + Power BI dashboard blank +**Documents Created**: 7 markdown files totaling ~67KB of documentation +**Coverage**: Top 10+ most common CoE Starter Kit issues + +--- + +*For questions or suggestions about this knowledge base, please open an issue with the "documentation" label.* diff --git a/docs/coe-knowledge/INDEX.md b/docs/coe-knowledge/INDEX.md new file mode 100644 index 000000000..d7987e4ff --- /dev/null +++ b/docs/coe-knowledge/INDEX.md @@ -0,0 +1,217 @@ +# CoE Knowledge Base Index + +Quick navigation to find answers to specific questions. + +## 🔍 Quick Search by Issue Type + +| Issue Type | Go To | +|------------|-------| +| Setup wizard skips dataflow step | [Setup Wizard Troubleshooting](./Setup-Wizard-Troubleshooting.md#configure-dataflows-step-skipped) | +| Power BI dashboard blank/no data | [Power BI Troubleshooting](./PowerBI-Dashboard-Troubleshooting.md#blank-dashboard---no-data-showing) | +| Inventory flows not running | [Setup Wizard Troubleshooting](./Setup-Wizard-Troubleshooting.md#inventory-flows-not-running) | +| Which inventory method to use | [Common Responses](./COE-Kit-Common%20GitHub%20Responses.md#data-export-and-dataflows) | +| License requirements | [Common Responses](./COE-Kit-Common%20GitHub%20Responses.md#licensing-and-pagination) | +| Connection errors | [Power BI Troubleshooting](./PowerBI-Dashboard-Troubleshooting.md#connection-errors) | +| DLP policy issues | [Common Responses](./COE-Kit-Common%20GitHub%20Responses.md#dlp-policies-blocking-flows) | +| Refresh failures | [Power BI Troubleshooting](./PowerBI-Dashboard-Troubleshooting.md#refresh-failures) | + +## 📚 By Document + +### [Quick Reference Guide](./Quick-Reference-Guide.md) +**Best for**: Fast answers, first-time responders, quick lookups + +- Top 5 most common issues +- Quick verification checks +- Common error messages +- Environment URLs by region +- Decision trees +- Emergency troubleshooting + +### [Common GitHub Responses](./COE-Kit-Common%20GitHub%20Responses.md) +**Best for**: Complete response templates, policy questions, general guidance + +- Support model and guidelines +- Setup wizard issues +- Power BI dashboard issues +- Data export and dataflows (BYODL status) +- Inventory and telemetry +- Licensing and pagination +- Language requirements +- Standard questionnaire + +### [Setup Wizard Troubleshooting](./Setup-Wizard-Troubleshooting.md) +**Best for**: Setup wizard specific issues + +- Setup wizard overview +- Dataflow step skip explanation +- Inventory flows not running +- Progress not saving +- Pre-requisites not met + +### [Power BI Dashboard Troubleshooting](./PowerBI-Dashboard-Troubleshooting.md) +**Best for**: Dashboard configuration and data issues + +- Dashboard overview +- Blank dashboard diagnosis +- Connection configuration +- Permission issues +- Refresh failures +- Diagnostic checklist + +### [Sample Issue Responses](./Sample-Issue-Responses.md) +**Best for**: Copy-paste responses for common patterns + +- Dataflow step skipped response +- Power BI blank response +- Combined setup + Power BI response +- Missing information request + +### [Implementation Summary](./IMPLEMENTATION-SUMMARY.md) +**Best for**: Understanding the knowledge base structure and purpose + +- What this knowledge base covers +- How to use it +- Key learnings +- Maintenance guidelines + +## 🎯 By Common Question + +### "Why doesn't my dashboard show data?" + +1. Start: [Quick Reference - Dashboard Shows No Data](./Quick-Reference-Guide.md#2-power-bi-dashboard-shows-no-data-) +2. Detailed: [Power BI Troubleshooting - Blank Dashboard](./PowerBI-Dashboard-Troubleshooting.md#blank-dashboard---no-data-showing) +3. Response: [Sample Response - Power BI Blank](./Sample-Issue-Responses.md#power-bi-dashboard-blankno-data) + +### "Why did setup skip the dataflow step?" + +1. Start: [Quick Reference - Dataflow Step Skipped](./Quick-Reference-Guide.md#1-setup-wizard-skips-dataflow-step-) +2. Detailed: [Setup Wizard - Configure Dataflows](./Setup-Wizard-Troubleshooting.md#configure-dataflows-step-skipped) +3. Response: [Sample Response - Dataflow Skipped](./Sample-Issue-Responses.md#setup-wizard---dataflow-step-skipped) + +### "How long until I see data?" + +1. Quick: [Quick Reference - Timeline](./Quick-Reference-Guide.md#5-how-long-does-initial-setup-take-) +2. Detailed: [Power BI - Expected Timeline](./PowerBI-Dashboard-Troubleshooting.md#expected-timeline) +3. Context: [Common Responses - Inventory Time](./COE-Kit-Common%20GitHub%20Responses.md#inventory-collection-takes-long-time) + +### "Should I use Cloud flows or Data Export?" + +1. Quick: [Quick Reference - Inventory Method](./Quick-Reference-Guide.md#4-which-inventory-method-should-i-use-) +2. Detailed: [Common Responses - BYODL Status](./COE-Kit-Common%20GitHub%20Responses.md#byodl-bring-your-own-data-lake-status) + +### "What licenses do I need?" + +1. Quick: [Quick Reference - Licensing](./Quick-Reference-Guide.md#licensing-quick-reference) +2. Detailed: [Common Responses - License Requirements](./COE-Kit-Common%20GitHub%20Responses.md#pagination-limits-and-license-requirements) + +### "My flows aren't running" + +1. Quick: [Quick Reference - Flows Not Running](./Quick-Reference-Guide.md#3-inventory-flows-not-running-) +2. Detailed: [Setup Wizard - Inventory Flows](./Setup-Wizard-Troubleshooting.md#inventory-flows-not-running) + +### "I need to respond to an issue" + +1. Start: [Sample Issue Responses](./Sample-Issue-Responses.md) - find matching pattern +2. Customize: Add specific details from the issue +3. Reference: Link to detailed troubleshooting guide +4. Follow up: Use standard questionnaire if info is missing + +## 🏷️ By Topic + +### Setup & Configuration +- [Setup Wizard Troubleshooting](./Setup-Wizard-Troubleshooting.md) +- [Common Responses - Setup Wizard](./COE-Kit-Common%20GitHub%20Responses.md#setup-wizard-issues) + +### Data & Inventory +- [Common Responses - Inventory](./COE-Kit-Common%20GitHub%20Responses.md#inventory-and-telemetry) +- [Common Responses - Data Export](./COE-Kit-Common%20GitHub%20Responses.md#data-export-and-dataflows) + +### Power BI +- [Power BI Dashboard Troubleshooting](./PowerBI-Dashboard-Troubleshooting.md) +- [Common Responses - Power BI](./COE-Kit-Common%20GitHub%20Responses.md#power-bi-dashboard-issues) + +### Licensing & Permissions +- [Common Responses - Licensing](./COE-Kit-Common%20GitHub%20Responses.md#licensing-and-pagination) +- [Power BI - Permissions](./PowerBI-Dashboard-Troubleshooting.md#permission-issues) + +### Policies & Compliance +- [Common Responses - DLP](./COE-Kit-Common%20GitHub%20Responses.md#dlp-policies-blocking-flows) +- [Common Responses - Language](./COE-Kit-Common%20GitHub%20Responses.md#language-and-localization) + +## 🚀 Quick Start Guides + +### For Support Team Members + +**First time responding to an issue?** +1. Read: [Quick Reference Guide](./Quick-Reference-Guide.md) +2. Check: [Sample Issue Responses](./Sample-Issue-Responses.md) for matching pattern +3. Reference: Link to detailed guide from [Setup Wizard](./Setup-Wizard-Troubleshooting.md) or [Power BI](./PowerBI-Dashboard-Troubleshooting.md) + +**Regular responder?** +1. Bookmark: [Common GitHub Responses](./COE-Kit-Common%20GitHub%20Responses.md) +2. Use: [Sample Issue Responses](./Sample-Issue-Responses.md) as templates +3. Update: Add new patterns you discover + +### For Contributors + +**Adding new knowledge?** +1. Review: [Implementation Summary](./IMPLEMENTATION-SUMMARY.md) +2. Update: Appropriate document based on topic +3. Add: Sample response if new pattern +4. Update: This INDEX.md file + +### For Users + +**Self-diagnosing issues?** +1. Start: [Quick Reference Guide](./Quick-Reference-Guide.md) +2. Check: Specific troubleshooting guide +3. Follow: Verification steps +4. Report: If still unresolved, include findings + +## 📊 Coverage Map + +| Issue Category | Coverage | Documents | +|----------------|----------|-----------| +| Setup Wizard | ✅ Complete | Setup Wizard Troubleshooting, Common Responses, Sample Responses | +| Power BI Dashboard | ✅ Complete | Power BI Troubleshooting, Common Responses, Sample Responses | +| Inventory & Data | ✅ Complete | Common Responses, Setup Wizard Troubleshooting | +| Licensing | ✅ Complete | Common Responses, Quick Reference | +| Permissions | ✅ Complete | Power BI Troubleshooting, Common Responses | +| DLP Policies | ✅ Complete | Common Responses | +| Language/Localization | ✅ Complete | Common Responses | +| Connection Issues | ✅ Complete | Power BI Troubleshooting | + +## 🔄 Recently Added + +- 2025-12-10: Initial knowledge base implementation +- 2025-12-10: Setup wizard dataflow skip documentation +- 2025-12-10: Power BI blank dashboard comprehensive guide +- 2025-12-10: BYODL deprecation status documentation +- 2025-12-10: Licensing requirements clarification + +## 📞 Getting Help + +**Knowledge base questions?** +- Open an issue with "documentation" label +- Reference this INDEX.md +- Suggest improvements via PR + +**CoE Starter Kit issues?** +- Use [Sample Issue Responses](./Sample-Issue-Responses.md) as guide +- Follow [Standard Questionnaire](./COE-Kit-Common%20GitHub%20Responses.md#standard-questionnaire) +- Check [Quick Reference](./Quick-Reference-Guide.md) first + +## 🔗 External Resources + +- [Microsoft Learn - CoE Starter Kit](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) +- [Setup Documentation](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components) +- [Power BI Setup](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-powerbi) +- [GitHub Issues](https://github.com/microsoft/coe-starter-kit/issues) +- [Community Forum](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps) + +--- + +*Last updated: 2025-12-10* +*Total documents: 7* +*Total lines: 2,347* +*Coverage: Top 10+ most common issues* diff --git a/docs/coe-knowledge/PowerBI-Dashboard-Troubleshooting.md b/docs/coe-knowledge/PowerBI-Dashboard-Troubleshooting.md new file mode 100644 index 000000000..1a683e601 --- /dev/null +++ b/docs/coe-knowledge/PowerBI-Dashboard-Troubleshooting.md @@ -0,0 +1,514 @@ +# Power BI Dashboard Troubleshooting Guide + +This document provides detailed troubleshooting steps for common issues with the CoE Starter Kit Power BI Dashboard. + +## Table of Contents + +1. [Dashboard Overview](#dashboard-overview) +2. [Blank Dashboard - No Data Showing](#blank-dashboard---no-data-showing) +3. [Partial Data Missing](#partial-data-missing) +4. [Connection Errors](#connection-errors) +5. [Refresh Failures](#refresh-failures) +6. [Permission Issues](#permission-issues) + +--- + +## Dashboard Overview + +The CoE Starter Kit Power BI Dashboard provides: +- Environment overview and trends +- App and Flow inventory analytics +- Maker activity and engagement metrics +- Compliance and governance insights +- Connector usage analysis + +### Dashboard Types + +1. **Power BI Dashboard (Desktop)** + - Template file: `Production_CoEDashboard_MMMYYYY.pbit` + - Requires Power BI Desktop + - Connects directly to Dataverse + - User must have appropriate permissions + +2. **Power BI Service Dashboard** + - Published from Desktop + - Can be shared with broader audience + - Requires Power BI Pro/Premium licenses + - Supports scheduled refresh + +--- + +## Blank Dashboard - No Data Showing + +### Symptom + +When opening the Power BI dashboard, one or more of the following occurs: +- All charts show "blank" or no data +- Message: "There are no Environments in this view to create a Environments chart" +- All visualizations are empty +- Tables show no records + +![Example of blank dashboard](https://github.com/user-attachments/assets/910d8877-9d2c-401d-a932-52d0196c81a2) + +### Root Causes (In Order of Likelihood) + +1. **Inventory hasn't completed** - Most common cause +2. **Wrong environment URL** - Dashboard connected to different environment +3. **Data source not configured** - First-time setup not complete +4. **Insufficient permissions** - User can't read CoE tables +5. **Data refresh needed** - Stale data cached + +--- + +### Cause 1: Inventory Collection Not Complete + +**Most common cause** - Initial inventory collection takes several hours. + +#### How to Verify + +1. **Check when setup was completed:** + - If setup was just finished: Wait 4-8 hours + - If setup was days/weeks ago: Proceed to other checks + +2. **Verify inventory flows are running:** + - Navigate to Cloud flows in CoE environment + - Find "Admin | Sync Template v3" flow + - Check 28-day run history + - Look for: + - ✅ Successful runs (green checkmarks) + - ❌ Failed runs (red X) + - ⏱️ In-progress runs + +3. **Check data in Dataverse tables:** + - Open CoE environment in Power Apps + - Navigate to **Tables** (under Dataverse) + - Check key tables: + + | Table Name | What to Check | + |------------|---------------| + | Environment | Should have entries for your tenant's environments | + | Power Apps App | Should contain app inventory | + | Flow | Should contain flow inventory | + | Power Apps Connector | Should list connectors | + | Maker | Should show maker information | + +4. **Verify record counts:** + - If tables are empty → Inventory flows haven't run successfully + - If tables have data but dashboard is blank → Connection/permission issue + +#### Expected Timeline + +- **First-time inventory**: 4-8 hours minimum +- **Large tenants** (1000+ environments): Up to 24 hours +- **Incremental updates**: 1-2 hours + +#### Resolution + +If inventory hasn't completed: + +1. **Wait for completion:** + - Check flow run history every 2-3 hours + - Don't interrupt running flows + +2. **If flows failed:** + - Review error messages in flow run history + - Common issues: + - DLP policy violations + - Connection authentication failures + - License/permission issues + - Fix underlying issue and re-run + +3. **If flows aren't running at all:** + - See [Setup Wizard Troubleshooting - Inventory Flows Not Running](./Setup-Wizard-Troubleshooting.md#inventory-flows-not-running) + +--- + +### Cause 2: Wrong Environment URL + +Dashboard is connected to a different environment than where CoE is installed. + +#### How to Verify + +1. In Power BI Desktop, go to **Transform Data** > **Data source settings** +2. Check the Dataverse URL configured +3. Compare with your CoE environment URL + +#### Finding Your CoE Environment URL + +1. Go to [Power Platform Admin Center](https://admin.powerplatform.microsoft.com) +2. Select **Environments** +3. Find your CoE environment +4. Note the **Environment URL** field +5. Format should be: `https://[orgname].crm[region].dynamics.com/` + +Example URLs: +- North America: `https://contoso.crm.dynamics.com/` +- Europe: `https://contoso.crm4.dynamics.com/` +- Asia: `https://contoso.crm5.dynamics.com/` + +#### Resolution + +1. Open Power BI file (.pbit template) +2. When prompted for parameters: + - Enter correct CoE environment URL + - Don't include trailing slash if not required +3. Sign in with appropriate credentials +4. Wait for data to load +5. Save as .pbix file + +--- + +### Cause 3: Data Source Not Configured (First Time Setup) + +First-time opening of .pbit template requires configuration. + +#### Proper Setup Steps + +1. **Download the correct template:** + - Get latest .pbit file from CoE Starter Kit release + - File name: `Production_CoEDashboard_[version].pbit` + - Don't use old/outdated templates + +2. **Open template in Power BI Desktop:** + - Requires Power BI Desktop (latest version recommended) + - Don't try to open .pbit in Power BI Service + +3. **Enter parameters when prompted:** + ``` + Parameter: CDS Environment Instance URL + Value: https://[your-org].crm[region].dynamics.com/ + ``` + +4. **Sign in:** + - Use your organizational account + - Account must have access to CoE environment + - May need to authenticate multiple times + +5. **Load data:** + - Click "Load" (not "Transform Data" for first time) + - Wait for all data to load (may take several minutes) + - Progress bar shows loading status + +6. **Verify data:** + - Check that visualizations show data + - Navigate through all report pages + - Verify counts seem reasonable + +7. **Save as .pbix:** + - File > Save As + - Save to local location or OneDrive + - Can now publish to Power BI Service if desired + +--- + +### Cause 4: Insufficient Permissions + +User doesn't have read access to CoE Dataverse tables. + +#### Required Permissions + +User viewing dashboard needs: +- Read access to CoE environment +- Access to CoE Dataverse tables +- Appropriate security role assignment + +#### How to Verify + +1. **Check environment access:** + - Can you open the CoE environment in Power Apps? + - Can you see the environment in your environment list? + +2. **Check table access:** + - In CoE environment, try to open "Environments" table + - Can you view records? + - If "Access Denied" → Permission issue + +3. **Check security roles:** + - In CoE environment, go to Settings > Security > Users + - Find your user + - Check assigned security roles + - Should have role with read access to CoE tables + +#### Resolution + +Have an admin grant appropriate permissions: + +1. **Option A: Add to CoE security role** + - Assign "CoE Dashboard Reader" role (if exists) + - Or create custom role with read access + +2. **Option B: Share environment** + - Share environment with user + - Assign appropriate role + +3. **Verify:** + - Sign out of Power BI Desktop + - Close and reopen + - Re-authenticate + - Try loading data again + +--- + +### Cause 5: Data Refresh Needed + +Cached data is stale or corrupted. + +#### Resolution + +In Power BI Desktop: + +1. Click **Refresh** button in ribbon +2. Wait for refresh to complete +3. Check if data now appears + +If refresh fails: +- Check error message +- May indicate connection or permission issue +- See [Connection Errors](#connection-errors) section + +--- + +## Partial Data Missing + +### Symptom + +Dashboard shows some data but specific sections are empty: +- Some charts show data, others don't +- Specific pages are blank while others work +- Specific time periods missing + +### Common Causes + +1. **Filters applied** - Report/page filters hiding data +2. **Selective inventory** - Some object types not collected yet +3. **Query failures** - Specific queries timing out or failing + +### Resolution + +1. **Check filters:** + - Click "Filter pane" in Power BI + - Check page-level and report-level filters + - Clear filters and refresh + +2. **Verify inventory scope:** + - Check which inventory flows have run successfully + - Some flows collect different object types + - May need to wait for specific flows to complete + +3. **Check query diagnostics:** + - In Power BI Desktop: Transform Data > View > Query Diagnostics + - Enable diagnostics and refresh + - Check for failed queries + - May indicate timeout or permission issues + +--- + +## Connection Errors + +### Symptom + +Error messages when trying to connect or refresh: +- "Unable to connect" +- "Access denied" +- "Invalid connection credentials" +- "Datasource.Error" + +### Common Connection Errors and Resolutions + +#### Error: "Unable to connect to the datasource" + +**Cause:** Network connectivity or URL issues + +**Resolution:** +1. Verify internet connectivity +2. Check environment URL is correct +3. Ensure environment is accessible (not deleted/disabled) +4. Try accessing environment via Power Apps to confirm it's available + +#### Error: "Access is denied" + +**Cause:** Permission issues + +**Resolution:** +1. Verify user has environment access +2. Check security role assignments +3. Ensure user is not disabled in Azure AD +4. Try signing out and back in + +#### Error: "Invalid credentials" + +**Cause:** Authentication issues + +**Resolution:** +1. In Power BI Desktop: File > Options > Data source settings +2. Find the Dataverse connection +3. Click "Edit Permissions" +4. Click "Edit" under Credentials +5. Sign in again with valid credentials +6. Ensure using organizational account (not personal) + +#### Error: "Gateway is required" + +**Cause:** On-premises data gateway configuration issue + +**Resolution:** +1. CoE Dataverse connection should NOT require gateway +2. Check data source settings +3. Ensure connection is set to "Cloud" not "On-premises" +4. May need to delete and recreate connection + +--- + +## Refresh Failures + +### Symptom + +When clicking refresh in Power BI Desktop or scheduled refresh in Power BI Service fails. + +### Common Causes and Resolutions + +#### Timeout Errors + +**Symptom:** Query timeout, operation cancelled + +**Causes:** +- Large data volume +- Slow network +- Complex queries + +**Resolution:** +1. Reduce query complexity if custom queries added +2. Limit data to recent time periods +3. Check network connection quality +4. Try refreshing during off-peak hours + +#### Authentication Failures + +**Symptom:** Refresh fails with credential errors + +**Resolution:** +1. Re-authenticate data sources +2. Ensure credentials haven't expired +3. Check if MFA is required +4. Verify service account (if used) is still valid + +#### Power BI Service Refresh Failures + +**Symptom:** Scheduled refresh in Power BI Service fails + +**Resolution:** +1. Check if using personal/local data sources (not supported) +2. Verify gateway configuration if required +3. For Dataverse: Should use cloud connection (no gateway) +4. Check dataset credentials in Power BI Service +5. Review refresh history for specific error messages + +--- + +## Permission Issues + +### Granting Dashboard Access to Others + +#### Scenario 1: Share Power BI Report (Service) + +1. Publish .pbix to Power BI Service +2. Users need: + - Power BI Pro license (or workspace in Premium) + - Access to CoE Dataverse environment + - Appropriate security role + +3. In Power BI Service: + - Click **Share** on report + - Add users/groups + - Grant "Read" permission + - Users will also need environment access + +#### Scenario 2: Share Power BI Desktop File + +1. Share .pbix file with users +2. Users need: + - Power BI Desktop installed + - Access to CoE Dataverse environment + - Appropriate security role + - Network access to environment + +3. Users open file and authenticate + +#### Scenario 3: Create "Reader" Role + +Best practice for dashboard-only access: + +1. Create custom security role "CoE Dashboard Reader" +2. Grant read access to CoE tables: + - Environment + - Power Apps App + - Flow + - Power Apps Connector + - Maker + - etc. +3. Assign role to dashboard users +4. Users can now refresh data + +--- + +## Diagnostic Checklist + +Use this checklist to systematically troubleshoot blank dashboard: + +- [ ] Setup wizard completed successfully +- [ ] At least 4-8 hours elapsed since setup completion +- [ ] Inventory flows show successful run history +- [ ] Dataverse tables contain records (Environment, Apps, Flows) +- [ ] Power BI template (.pbit) is latest version +- [ ] Correct environment URL used in Power BI connection +- [ ] User has access to CoE environment +- [ ] User has read permissions on CoE tables +- [ ] Authentication successful in Power BI +- [ ] No DLP policies blocking connection +- [ ] Data refresh completes without errors +- [ ] No filters hiding data +- [ ] Using supported browser/Power BI Desktop version + +--- + +## Quick Resolution Steps + +For the most common scenario (blank dashboard after setup): + +1. ✅ **Confirm inventory completion** + - Check: Cloud flows > "Admin | Sync Template v3" > Run history + - Check: Dataverse tables have records + +2. ✅ **Verify Power BI configuration** + - Open .pbit template (not .pbix) + - Enter correct environment URL: `https://[org].crm[region].dynamics.com/` + - Sign in with admin account + +3. ✅ **Wait for data load** + - Initial load may take 5-10 minutes + - Don't close during loading + +4. ✅ **Verify visualizations** + - Check all report pages + - Clear any filters + - Save as .pbix when confirmed working + +--- + +## Additional Resources + +### Documentation +- [Setup Power BI Dashboard](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-powerbi) +- [Power BI Dashboard Explained](https://learn.microsoft.com/en-us/power-platform/guidance/coe/power-bi) +- [Troubleshooting Guide](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#troubleshooting) + +### Video Tutorials +- [Power BI Dashboard Walkthrough](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-powerbi#watch-a-walk-through) + +### Community Support +- [GitHub Issues](https://github.com/microsoft/coe-starter-kit/issues) +- [Power BI Community](https://community.powerbi.com/) + +--- + +*Last updated: 2025-12-10* diff --git a/docs/coe-knowledge/Quick-Reference-Guide.md b/docs/coe-knowledge/Quick-Reference-Guide.md new file mode 100644 index 000000000..eb8821042 --- /dev/null +++ b/docs/coe-knowledge/Quick-Reference-Guide.md @@ -0,0 +1,440 @@ +# CoE Starter Kit - Quick Reference Guide + +This guide provides quick answers to the most common questions and issues reported on GitHub. + +## Most Common Issues + +### 1. Setup Wizard Skips Dataflow Step ⚡ + +**Q:** Why does the setup wizard skip "Configure dataflows (Data export)"? + +**A:** This is **expected behavior**. The step only appears if you selected "Data Export" as your inventory method. If you selected "Cloud flows" (recommended), it will be skipped. + +**Action:** ✅ No action needed. Continue with setup. + +[Detailed guide →](./Setup-Wizard-Troubleshooting.md#configure-dataflows-step-skipped) + +--- + +### 2. Power BI Dashboard Shows No Data ⚡ + +**Q:** Dashboard is blank or shows "no data" messages. + +**A:** Most commonly caused by inventory collection not completing yet. First-time collection takes **4-8 hours minimum**. + +**Action:** +1. ✅ Wait 4-8 hours after setup completion +2. ✅ Check flow run history for "Admin | Sync Template v3" +3. ✅ Verify Dataverse tables contain records +4. ✅ Ensure Power BI is connected to correct environment URL + +[Detailed guide →](./PowerBI-Dashboard-Troubleshooting.md#blank-dashboard---no-data-showing) + +--- + +### 3. Inventory Flows Not Running ⚡ + +**Q:** Inventory flows don't start or don't collect data. + +**A:** Common causes: permissions, DLP policies, or connections. + +**Action:** +1. ✅ Verify admin permissions (Power Platform Admin or Global Admin) +2. ✅ Check DLP policies allow required connectors +3. ✅ Verify flow connections are authenticated +4. ✅ Ensure proper licensing (not trial) + +[Detailed guide →](./Setup-Wizard-Troubleshooting.md#inventory-flows-not-running) + +--- + +### 4. Which Inventory Method Should I Use? ⚡ + +**Q:** Should I use Cloud flows or Data Export? + +**A:** Use **Cloud flows** (recommended for 95% of organizations). + +**Cloud flows:** +- ✅ Easier setup +- ✅ Standard licensing +- ✅ All necessary data +- ✅ Recommended by Microsoft + +**Data Export:** +- ❌ More complex +- ❌ Requires additional setup +- ❌ BYODL no longer recommended +- ⚠️ Only for advanced scenarios + +[Detailed info →](./COE-Kit-Common%20GitHub%20Responses.md#data-export-and-dataflows) + +--- + +### 5. How Long Does Initial Setup Take? ⚡ + +**Q:** How long before I see data? + +**A:** +- Setup wizard: 30-60 minutes +- Inventory collection: **4-8 hours minimum** (can be 24+ hours for large tenants) +- Power BI configuration: 15-30 minutes + +**Timeline:** +1. Complete setup wizard → 30-60 min +2. Wait for inventory → 4-8 hours +3. Configure Power BI → 15-30 min +4. View dashboard → Immediate after step 3 + +[Detailed info →](./PowerBI-Dashboard-Troubleshooting.md#expected-timeline) + +--- + +## Quick Checks + +### Is My Inventory Complete? + +✅ **Check this:** +1. Go to Cloud flows in CoE environment +2. Open "Admin | Sync Template v3" +3. Check run history for green checkmarks +4. Go to Tables > Check "Environment", "Power Apps App", "Flow" have records + +If all above are ✅, inventory is complete. + +--- + +### Is My Power BI Connected Correctly? + +✅ **Check this:** +1. Open .pbit template in Power BI Desktop +2. Verify environment URL: `https://[org].crm[region].dynamics.com/` +3. Sign in with admin account +4. Wait for data load +5. Check visualizations show data + +If all above are ✅, Power BI is configured correctly. + +--- + +### Do I Have the Right Permissions? + +✅ **Check this:** + +**Required roles (at least one):** +- Power Platform Administrator +- Global Administrator +- Dynamics 365 Administrator + +**Required licenses:** +- Power Apps Per User or Per App +- Power Automate Per User (recommended) + +**Test access:** +- Can you access Power Platform Admin Center? +- Can you see all environments in your tenant? +- Can you view Dataverse tables in CoE environment? + +If all above are ✅, permissions are adequate. + +--- + +## Common Error Messages + +### "Access is denied" + +**Cause:** Insufficient permissions + +**Fix:** +- Verify admin role assignment +- Check security roles in CoE environment +- Ensure user not disabled in Azure AD + +--- + +### "Unable to connect to datasource" + +**Cause:** Connection or URL issues + +**Fix:** +- Verify environment URL is correct +- Check internet connectivity +- Ensure environment is accessible +- Format: `https://[org].crm[region].dynamics.com/` + +--- + +### "Invalid credentials" + +**Cause:** Authentication issues + +**Fix:** +- Re-authenticate in Power BI data source settings +- Use organizational account (not personal) +- Verify MFA completion if required + +--- + +### "DLP policy violation" + +**Cause:** Required connectors blocked + +**Fix:** +- Check DLP policies on CoE environment +- Ensure these connectors in same data group: + - Dataverse + - Power Apps for Admins + - Power Automate for Admins + - Office 365 Users + - Office 365 Outlook + +--- + +## Environment URLs by Region + +Power BI needs your environment URL in this format: + +| Region | URL Format | Example | +|--------|-----------|---------| +| North America | `https://[org].crm.dynamics.com/` | `https://contoso.crm.dynamics.com/` | +| South America | `https://[org].crm2.dynamics.com/` | `https://contoso.crm2.dynamics.com/` | +| Canada | `https://[org].crm3.dynamics.com/` | `https://contoso.crm3.dynamics.com/` | +| Europe | `https://[org].crm4.dynamics.com/` | `https://contoso.crm4.dynamics.com/` | +| Asia Pacific | `https://[org].crm5.dynamics.com/` | `https://contoso.crm5.dynamics.com/` | +| Australia | `https://[org].crm6.dynamics.com/` | `https://contoso.crm6.dynamics.com/` | +| Japan | `https://[org].crm7.dynamics.com/` | `https://contoso.crm7.dynamics.com/` | +| India | `https://[org].crm8.dynamics.com/` | `https://contoso.crm8.dynamics.com/` | +| UK | `https://[org].crm11.dynamics.com/` | `https://contoso.crm11.dynamics.com/` | +| France | `https://[org].crm12.dynamics.com/` | `https://contoso.crm12.dynamics.com/` | + +**How to find yours:** +1. Go to [Power Platform Admin Center](https://admin.powerplatform.microsoft.com) +2. Select **Environments** +3. Find your CoE environment +4. Copy the **Environment URL** + +--- + +## Setup Wizard Steps Overview + +Understanding the flow helps troubleshoot issues: + +1. ✅ **Confirm pre-requisites** - Admin permissions, licensing +2. ✅ **Configure communication** - Email settings +3. ✅ **Configure mandatory settings** - Required configuration +4. ✅ **Configure inventory source** - **Choose Cloud flows or Data Export** +5. ✅ **Run setup flows** - Initialize configuration +6. ✅ **Run inventory flows** - Start data collection +7. ⚠️ **Configure dataflows** - *Only if Data Export selected* +8. ✅ **Share apps** - App permissions +9. ✅ **Publish Power BI** - Dashboard info (manual setup required) +10. ✅ **Finish** - Complete + +**Key point:** Step 7 only appears if you selected "Data Export" in step 4. + +--- + +## CoE Components Overview + +Understanding what each component does: + +### Core Components +- **Inventory flows** - Collect tenant data +- **Power BI Dashboard** - Analytics and reporting +- **Admin apps** - Governance tools +- **Dataverse tables** - Data storage + +### Setup Wizard +- Guided configuration experience +- One-time setup process +- Configures core components + +### Power BI Dashboard +- Separate component from Power Apps +- Requires Power BI Desktop +- Connects to Dataverse +- Shows analytics and insights + +--- + +## Decision Trees + +### Dataflow Step Missing? + +``` +Is "Configure dataflows" step missing? +│ +├─ Yes → Did you select "Cloud flows"? +│ │ +│ ├─ Yes → ✅ EXPECTED - Continue to next step +│ └─ No → Check if Data Export is configured +│ +└─ No → Step should appear if Data Export selected +``` + +### Dashboard Shows No Data? + +``` +Power BI dashboard blank? +│ +├─ How long since setup completed? +│ │ +│ ├─ Less than 8 hours → ⏱️ WAIT - Inventory needs time +│ └─ More than 24 hours → Check inventory flows +│ +└─ Do Dataverse tables have records? + │ + ├─ Yes → Check Power BI connection/URL + └─ No → Check flow run history for errors +``` + +--- + +## Licensing Quick Reference + +### Minimum Requirements + +**For CoE Admin:** +- Power Apps Per User OR Per App +- Power Automate Per User (recommended) +- Power Platform Admin role + +**For Dashboard Viewers:** +- Power BI Pro (for Power BI Service sharing) +- OR Power BI Desktop (for local viewing) +- Read access to CoE environment + +**Not Recommended:** +- ❌ Trial licenses for production +- ❌ Microsoft 365 only (limited) +- ❌ Free Power Apps (insufficient) + +--- + +## When to Escalate + +Contact Microsoft Support when: + +1. ❌ Flow errors persist after following troubleshooting +2. ❌ Licensing questions about enterprise agreements +3. ❌ Platform issues (not CoE specific) +4. ❌ Azure AD or tenant-level configuration + +**Note:** CoE Starter Kit is community-supported via GitHub, not official Microsoft Support. + +--- + +## Best Practices + +### For Setup + +✅ **Do:** +- Use dedicated environment for CoE +- Wait for inventory to complete (4-8 hours) +- Use Cloud flows for inventory +- Follow setup wizard sequentially +- Keep setup wizard open during configuration + +❌ **Don't:** +- Use default environment +- Expect immediate results +- Skip steps in wizard +- Run setup from multiple sessions +- Customize managed components directly + +### For Troubleshooting + +✅ **Do:** +- Check flow run history first +- Verify Dataverse tables have data +- Wait adequate time for inventory +- Document error messages +- Search existing GitHub issues + +❌ **Don't:** +- Repeatedly re-run failed flows without fixing root cause +- Delete and reinstall without understanding issue +- Modify managed solution components +- Ignore DLP policy violations + +--- + +## Helpful Commands & Checks + +### Power Platform CLI + +Check environment details: +```powershell +pac admin list +pac env select --environment [environment-id] +``` + +### PowerShell (Admin) + +List environments: +```powershell +Get-AdminPowerAppEnvironment +``` + +### Web Browser Checks + +| What to Check | URL | What to Look For | +|--------------|-----|------------------| +| Admin Center | https://admin.powerplatform.microsoft.com | Environments list, CoE environment exists | +| Power Apps | https://make.powerapps.com | CoE environment, flows running, tables have data | +| Power BI | https://app.powerbi.com | Published reports (if published) | + +--- + +## Emergency Troubleshooting + +If everything seems broken: + +1. ✅ **Verify environment exists** - Admin Center +2. ✅ **Check solution is installed** - Power Apps > Solutions +3. ✅ **Verify user has access** - Can you open the environment? +4. ✅ **Check flows exist** - Navigate to Cloud flows +5. ✅ **Look at run history** - Any successful runs? +6. ✅ **Check tables** - Do they exist and have records? +7. ✅ **Review DLP policies** - Any violations? +8. ✅ **Verify connections** - All authenticated? + +If all above fail, consider: +- Check recent tenant changes +- Review Azure AD changes +- Check license expiration +- Look for platform-wide issues + +--- + +## Links & Resources + +### Official Documentation +- [CoE Starter Kit Overview](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) +- [Setup Guide](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components) +- [Power BI Setup](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-powerbi) +- [Troubleshooting](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#troubleshooting) + +### Community +- [GitHub Issues](https://github.com/microsoft/coe-starter-kit/issues) +- [Power Apps Community](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps) + +### Video Guides +- [Setup Walkthrough Videos](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#watch-a-walk-through) + +--- + +## Quick Wins + +After setup, try these to verify everything works: + +1. ✅ **Open Admin Apps** - Verify apps load +2. ✅ **Check Power Apps App table** - See your apps +3. ✅ **View an environment record** - Data looks correct +4. ✅ **Open Power BI in Desktop** - Dashboard shows data +5. ✅ **Run a simple flow** - Flows can execute + +If all work → ✅ Setup successful! + +--- + +*Last updated: 2025-12-10* diff --git a/docs/coe-knowledge/README.md b/docs/coe-knowledge/README.md new file mode 100644 index 000000000..768ed1609 --- /dev/null +++ b/docs/coe-knowledge/README.md @@ -0,0 +1,49 @@ +# CoE Starter Kit Knowledge Base + +This directory contains internal knowledge base documentation for the CoE Starter Kit support team and contributors. + +## Quick Navigation + +👉 **[INDEX](./INDEX.md)** - Quickly find answers by issue type, question, or topic + +## Purpose + +These documents provide: +- Common response templates for GitHub issues +- Troubleshooting patterns and resolutions +- Known limitations and workarounds +- Best practices for issue triage +- References to official documentation + +## Documents + +- **[Quick Reference Guide](./Quick-Reference-Guide.md)**: Fast answers to the most common questions and issues. Start here for quick troubleshooting. +- **[COE-Kit-Common GitHub Responses.md](./COE-Kit-Common%20GitHub%20Responses.md)**: Ready-to-use responses for common issues, including setup wizard problems, Power BI dashboard issues, licensing requirements, and more. +- **[Setup Wizard Troubleshooting](./Setup-Wizard-Troubleshooting.md)**: Detailed troubleshooting guide for CoE Setup Wizard issues. +- **[Power BI Dashboard Troubleshooting](./PowerBI-Dashboard-Troubleshooting.md)**: Comprehensive diagnostic guide for Power BI dashboard issues. +- **[Sample Issue Responses](./Sample-Issue-Responses.md)**: Copy-paste templates for responding to common GitHub issues. + +## For Support Team + +When responding to GitHub issues: + +1. Review the issue against patterns in the knowledge base +2. Search for similar closed issues +3. Use standard response templates when applicable +4. Link to official Microsoft documentation +5. Update the knowledge base with new patterns + +## For Contributors + +If you've resolved a recurring issue or identified a new pattern: + +1. Document the issue, root cause, and resolution +2. Create a standard response template +3. Add to the appropriate knowledge base document +4. Submit a PR with your changes + +## References + +- [CoE Starter Kit Official Documentation](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) +- [GitHub Issues](https://github.com/microsoft/coe-starter-kit/issues) +- [Power Apps Community Forum](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps) diff --git a/docs/coe-knowledge/Sample-Issue-Responses.md b/docs/coe-knowledge/Sample-Issue-Responses.md new file mode 100644 index 000000000..a34458e5b --- /dev/null +++ b/docs/coe-knowledge/Sample-Issue-Responses.md @@ -0,0 +1,432 @@ +# Sample Issue Responses + +This document contains sample responses for common issue patterns that can be copied and customized when responding to GitHub issues. + +## Table of Contents + +1. [Setup Wizard - Dataflow Step Skipped](#setup-wizard---dataflow-step-skipped) +2. [Power BI Dashboard Blank/No Data](#power-bi-dashboard-blankno-data) +3. [Combined Setup Wizard and Power BI Issues](#combined-setup-wizard-and-power-bi-issues) +4. [Missing Information Request](#missing-information-request) + +--- + +## Setup Wizard - Dataflow Step Skipped + +**Use when:** User reports that setup wizard skips "Configure dataflows (Data export)" step + +```markdown +Thank you for reporting this issue. The behavior you're seeing with the setup wizard skipping the "Configure dataflows (Data export)" step is **expected behavior** in most scenarios. + +### Why the Step is Skipped + +The "Configure dataflows (Data export)" step only appears when **all** of the following conditions are met: + +1. ✅ You selected **"Data Export"** as your inventory and telemetry method in the "Configure inventory data source" step +2. ✅ Data Export features are enabled in your environment +3. ✅ Your licensing supports Dataverse Data Export capabilities + +If you selected **"Cloud flows"** (which is the recommended method for most organizations) or **"None"** as your inventory method, the dataflows step will automatically be skipped. This is by design. + +### How to Verify Your Selection + +To confirm which method you're using: + +1. In the Setup Wizard, navigate back to the "Configure inventory data source" step +2. Check which option is selected: + - **Cloud flows** → Dataflows step will be skipped ✓ + - **Data Export** → Dataflows step should appear + - **None** → Dataflows step will be skipped ✓ + +### Recommended Approach + +**Cloud flows** is the recommended inventory method for most organizations because: +- ✅ Easier to set up and maintain +- ✅ Works with standard Power Platform licensing +- ✅ Provides all necessary data for CoE dashboards and apps +- ✅ No additional infrastructure required + +**Note:** BYODL (Bring Your Own Data Lake) / Data Export is no longer the recommended approach. Microsoft is moving toward integration with Microsoft Fabric for advanced analytics scenarios. + +### Next Steps + +If you selected "Cloud flows" as your method, you can proceed with the setup: +1. Continue to the next step (Share Apps) +2. Complete the remaining wizard steps +3. Wait for inventory flows to complete (4-8 hours) + +If you intended to use Data Export and need the dataflow step: +1. Return to "Configure inventory data source" step +2. Select "Data Export" +3. Complete the setup with Data Export configuration + +### References + +- [Choose your inventory method](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#inventory-and-telemetry) +- [Setup wizard documentation](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components) +- [CoE Starter Kit setup overview](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup) + +Please let us know if you have any questions or if the issue persists after verifying your inventory method selection. +``` + +--- + +## Power BI Dashboard Blank/No Data + +**Use when:** User reports Power BI dashboard shows no data or blank visualizations + +```markdown +Thank you for reporting this issue. A blank Power BI dashboard is a common scenario that typically has a straightforward resolution. Let me help you troubleshoot this. + +### Most Common Cause: Inventory Collection Not Complete + +The most frequent cause of a blank dashboard is that the **initial inventory collection hasn't completed yet**. This process takes time, especially for the first run. + +**Expected timeline:** +- First-time inventory: **4-8 hours minimum** +- Large tenants (many environments/apps): Up to 24 hours +- Incremental updates: 1-2 hours + +### Verification Steps + +Please complete these steps to diagnose the issue: + +#### 1. Verify Inventory Flows Have Run + +1. Navigate to **Cloud flows** in your CoE environment +2. Find the **"Admin | Sync Template v3"** flow +3. Check the **28-day run history**: + - ✅ Successful runs (green checkmarks) → Inventory is running + - ❌ Failed runs (red X) → There's an issue with the flows + - ⏱️ In-progress runs → Wait for completion + +4. If you just completed the setup wizard: + - **Wait at least 4-8 hours** before expecting data + - Check back periodically for completion + +#### 2. Check Data in Dataverse Tables + +1. Open your **CoE environment** in Power Apps +2. Navigate to **Tables** (under Dataverse in the left menu) +3. Check if these key tables contain records: + - **Environment** - Should have entries for your tenant's environments + - **Power Apps App** - Should contain app inventory + - **Flow** - Should contain flow inventory + - **Power Apps Connector** - Should list connectors in use + +4. If these tables are **empty**: + - Inventory flows haven't completed successfully yet + - Review flow run history for errors + +5. If these tables **have data** but dashboard is still blank: + - Continue to step 3 below + +#### 3. Verify Power BI Configuration + +1. **Use the correct template file:** + - Download the `.pbit` template file from the latest CoE Starter Kit release + - File name: `Production_CoEDashboard_[version].pbit` + +2. **Open template in Power BI Desktop:** + - Requires Power BI Desktop (not Power BI Service) + - Latest version recommended + +3. **Enter your CoE environment URL when prompted:** + - Format: `https://[your-org-name].crm[region].dynamics.com/` + - Example for North America: `https://contoso.crm.dynamics.com/` + - Example for Europe: `https://contoso.crm4.dynamics.com/` + + **How to find your environment URL:** + - Go to [Power Platform Admin Center](https://admin.powerplatform.microsoft.com) + - Select **Environments** + - Find your CoE environment + - Copy the **Environment URL** + +4. **Sign in with appropriate credentials:** + - Use your organizational account + - Account must have access to the CoE environment + +5. **Wait for data to load:** + - Initial load may take 5-10 minutes + - Don't close Power BI during loading + +6. **Verify data appears:** + - Check that visualizations show data + - Navigate through report pages + +### Common Issues and Solutions + +**Issue:** Connected to wrong environment +- **Solution:** Verify the environment URL matches your CoE environment + +**Issue:** Insufficient permissions +- **Solution:** Ensure your user has read access to CoE Dataverse tables + +**Issue:** Stale cached data +- **Solution:** Click **Refresh** button in Power BI Desktop + +### Next Steps + +Based on the symptoms you described, please: + +1. **Check when you completed the setup wizard:** + - If it was less than 8 hours ago → **Wait for inventory to complete** + - If it was more than 24 hours ago → Check flow run history for errors + +2. **Verify the Dataverse tables contain data** (as described above) + +3. **Confirm your Power BI configuration** uses the correct environment URL + +4. **Share your findings** with the following information: + - How long ago did you complete the setup wizard? + - Do the Dataverse tables contain records? + - What environment URL did you use in Power BI? + - Any error messages in flow run history? + +### Additional Resources + +- [Setup Power BI Dashboard](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-powerbi) +- [Troubleshooting Guide](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#troubleshooting) +- [Power BI Dashboard Documentation](https://learn.microsoft.com/en-us/power-platform/guidance/coe/power-bi) + +Please let us know the results of your verification steps, and we can provide more specific guidance based on what you find. +``` + +--- + +## Combined Setup Wizard and Power BI Issues + +**Use when:** User reports both setup wizard behavior and Power BI dashboard issues (like the current issue) + +```markdown +Thank you for reporting these issues. Let me address both of your concerns about the setup wizard and Power BI dashboard. + +## Issue 1: Configure Dataflows Step Skipped + +The behavior you're seeing where the setup wizard skips "Configure dataflows (Data export)" and moves directly to "Share Apps" is **expected behavior** in most scenarios. + +### Why This Happens + +The "Configure dataflows (Data export)" step only appears when you've selected **"Data Export"** as your inventory and telemetry method. If you selected **"Cloud flows"** (which is the recommended method), this step is automatically skipped by design. + +**Cloud flows is recommended** because: +- ✅ Easier to set up and maintain +- ✅ Works with standard licensing +- ✅ Provides all necessary data for dashboards +- ✅ No additional infrastructure required + +**Note:** BYODL (Bring Your Own Data Lake) / Data Export is no longer the recommended approach per Microsoft's latest guidance. + +### To Verify + +Check which inventory method you selected: +1. In Setup Wizard, go to "Configure inventory data source" step +2. If "Cloud flows" is selected → Dataflows step will be skipped (expected ✓) +3. If "Data Export" is selected → Dataflows step should appear + +**Recommendation:** Continue with Cloud flows. The setup wizard behavior is correct. + +## Issue 2: Power BI Dashboard Shows Blank/No Data + +This is a very common scenario with a straightforward resolution. The most likely cause is that **inventory collection hasn't completed yet**. + +### Expected Timeline + +Initial inventory collection takes significant time: +- **Minimum**: 4-8 hours +- **Large tenants**: Up to 24 hours +- **Incremental updates**: 1-2 hours + +### Immediate Action Items + +Please complete these verification steps: + +#### 1. Check Inventory Flow Status + +1. Navigate to **Cloud flows** in your CoE environment +2. Open **"Admin | Sync Template v3"** flow +3. Check the **run history**: + - Look for successful runs (green checkmarks) + - Check if flows are still in progress + - Look for any failed runs (red X) + +**If just completed setup:** Wait at least 4-8 hours before expecting data in the dashboard. + +#### 2. Verify Data in Dataverse + +1. Open your CoE environment in **Power Apps** +2. Go to **Tables** (under Dataverse) +3. Check if these tables contain records: + - **Environment** + - **Power Apps App** + - **Flow** + - **Power Apps Connector** + +**If tables are empty:** Inventory hasn't completed yet - wait for flows to finish. +**If tables have data:** Continue to step 3. + +#### 3. Configure Power BI Dashboard Correctly + +The screenshot you shared shows you're viewing the dashboard in Power Apps, which may not be the right approach. Here's the proper setup: + +1. **Download the Power BI template file:** + - From CoE Starter Kit release: `Production_CoEDashboard_[version].pbit` + +2. **Open in Power BI Desktop:** + - You need Power BI Desktop installed (free download) + - Don't use Power BI Service for initial setup + +3. **Enter your environment URL:** + - Format: `https://[orgname].crm[region].dynamics.com/` + - Find this in Power Platform Admin Center > Environments + +4. **Authenticate and load data:** + - Sign in with your admin account + - Wait for data to load (5-10 minutes) + +5. **Verify visualizations show data** + +### What to Expect at "Publish Power BI Dashboard" Step + +At the "Publish Power BI Dashboard" step in the setup wizard: + +1. **No automatic publishing happens** - This is just informational +2. You need to **manually download and configure** the .pbit file as described above +3. Click "Next" to proceed to "Finish" +4. After wizard completion, set up the dashboard separately + +### Accessing the Dashboard + +There are two ways to access the Power BI dashboard: + +**Option A: Power BI Desktop** (Recommended for initial setup) +- Download and open .pbit template +- Configure with your environment URL +- View and interact with data locally + +**Option B: Power BI Service** (For sharing) +- After configuring in Desktop, publish to Power BI Service +- Requires Power BI Pro/Premium licenses +- Can share with other users + +The dashboard you showed in your screenshot appears to be a Power App, not the Power BI dashboard. The Power BI dashboard is a separate component accessed through Power BI Desktop or Service. + +### Summary of Next Steps + +1. ✅ **Accept that dataflow step being skipped is expected** (if using Cloud flows) +2. ⏱️ **Wait 4-8 hours** after setup completion for inventory to collect +3. ✅ **Verify inventory flows are running** successfully +4. ✅ **Check Dataverse tables** contain records +5. 📊 **Download and configure Power BI template** in Power BI Desktop with correct environment URL +6. 📋 **Report back** with your findings so we can provide more specific help + +### What Information Would Help Us + +To provide more targeted assistance, please share: + +1. **How long ago did you complete the setup wizard?** +2. **What inventory method did you select?** (Cloud flows or Data Export) +3. **Do the Dataverse tables contain records?** (Environment, Apps, Flows) +4. **Have the inventory flows run successfully?** (Check run history) +5. **Are you trying to open the dashboard in Power BI Desktop or elsewhere?** + +### References + +- [Setup Core Components](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components) +- [Setup Power BI Dashboard](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-powerbi) +- [Choose Inventory Method](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#inventory-and-telemetry) +- [Troubleshooting Guide](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#troubleshooting) + +We're here to help! Please provide the requested information, and we'll guide you through resolving these issues. +``` + +--- + +## Missing Information Request + +**Use when:** Issue doesn't contain enough detail for diagnosis + +```markdown +Thank you for raising this issue. To help us resolve it efficiently, could you please provide the following details: + +### Required Information + +1. **Solution name and version:** + - Which CoE solution? (Core, Governance, Nurture, etc.) + - What version number? + +2. **Environment details:** + - Is this a production or trial environment? + - What region is your environment in? + - What licensing do you have? (Power Apps Per User, Microsoft 365, etc.) + +3. **Inventory/telemetry method:** + - Are you using Cloud flows, Data Export, or None? + - Was this selected during setup wizard? + +4. **Timing:** + - When did you complete the setup wizard? + - How long ago did the issue start? + - Is this after an upgrade or initial setup? + +5. **Steps to reproduce:** + - What specific steps led to this issue? + - Can you reproduce it consistently? + +6. **Expected vs Actual behavior:** + - What did you expect to happen? + - What actually happened? + - Are there any error messages? + +7. **Supporting information:** + - Screenshots of the issue + - Flow run history (if applicable) + - Error messages or logs + - Environment URL format (with sensitive info redacted) + +### Why This Information Helps + +These details help us: +- ✅ Identify if this is a known issue with existing solutions +- ✅ Determine root cause more quickly +- ✅ Provide accurate troubleshooting steps +- ✅ Prevent back-and-forth requests for information +- ✅ Help others who may encounter similar issues + +### Next Steps + +Once you provide this information, we'll: +1. Analyze the issue against known patterns +2. Search for similar resolved issues +3. Provide specific troubleshooting steps +4. Guide you toward resolution + +Thank you for helping us help you! We'll respond as soon as you provide the requested details. + +### Helpful Links While You Gather Information + +- [Setup documentation](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components) +- [Troubleshooting guide](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#troubleshooting) +- [CoE Starter Kit overview](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) +``` + +--- + +## Contributing + +When you identify a new pattern or successfully resolve an issue that could benefit others: + +1. Document the issue pattern +2. Create a sample response +3. Add to this file +4. Submit a PR + +Include: +- Clear trigger criteria (when to use this response) +- Complete response text +- Links to official documentation +- Troubleshooting steps where applicable + +--- + +*Last updated: 2025-12-10* diff --git a/docs/coe-knowledge/Setup-Wizard-Troubleshooting.md b/docs/coe-knowledge/Setup-Wizard-Troubleshooting.md new file mode 100644 index 000000000..edeced748 --- /dev/null +++ b/docs/coe-knowledge/Setup-Wizard-Troubleshooting.md @@ -0,0 +1,261 @@ +# Setup Wizard Troubleshooting Guide + +This document provides detailed troubleshooting steps for common issues encountered with the CoE Starter Kit Setup Wizard. + +## Table of Contents + +1. [Setup Wizard Overview](#setup-wizard-overview) +2. [Configure Dataflows Step Skipped](#configure-dataflows-step-skipped) +3. [Inventory Flows Not Running](#inventory-flows-not-running) +4. [Setup Wizard Progress Not Saving](#setup-wizard-progress-not-saving) +5. [Pre-requisites Not Met](#pre-requisites-not-met) + +--- + +## Setup Wizard Overview + +The CoE Setup Wizard provides a guided experience for configuring the CoE Starter Kit. The wizard follows this flow: + +1. **Confirm pre-requisites** - Verify admin permissions and environment setup +2. **Configure communication methods** - Set up email and notification preferences +3. **Configure mandatory settings** - Essential configuration for CoE operation +4. **Configure inventory data source** - Choose between Cloud flows or Data Export +5. **Run setup flows** - Initialize configuration data +6. **Run inventory flows** - Start initial data collection +7. **Configure dataflows (Data export)** - *Optional, only if Data Export selected* +8. **Share apps** - Configure app sharing and permissions +9. **Publish Power BI dashboard** - Configure analytics dashboard +10. **Finish** - Complete setup + +--- + +## Configure Dataflows Step Skipped + +### Symptom + +After completing "Run Inventory Flows" step successfully, the wizard skips "Configure dataflows (Data export)" and moves directly to "Share Apps". + +### Expected Behavior + +**This is normal** - The "Configure dataflows (Data export)" step only appears under specific conditions. + +### When the Step Appears + +The dataflows configuration step ONLY appears when: + +1. ✅ You selected **"Data Export"** as your inventory and telemetry method +2. ✅ Data Export features are enabled in your environment +3. ✅ Your license supports Dataverse Data Export capabilities + +### When the Step is Skipped + +The step is automatically skipped when: + +- ❌ You selected **"Cloud flows"** as your inventory method (most common) +- ❌ You selected **"None"** for inventory method +- ❌ Data Export is not configured in your environment + +### Verification Steps + +To confirm which method you selected: + +1. In the Setup Wizard, navigate to "Configure inventory data source" step +2. Check which radio button is selected: + - **Cloud flows** (recommended) → Dataflows step will be skipped + - **Data Export** → Dataflows step will appear + - **None** → Dataflows step will be skipped + +### Resolution + +**No action needed** - This is expected behavior. If you selected "Cloud flows", proceed to the next step (Share Apps). + +If you intended to use Data Export and the step is missing: + +1. Return to "Configure inventory data source" step +2. Select "Data Export" option +3. Complete subsequent steps +4. The dataflows step should now appear + +### Important Notes + +- **Cloud flows** is the recommended method for most organizations +- **Data Export** is more complex and requires additional setup +- **BYODL (Bring Your Own Data Lake)** is no longer recommended per latest guidance +- Microsoft is moving toward Fabric integration for advanced analytics + +### References + +- [Choose your inventory method](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#inventory-and-telemetry) +- [Setup wizard documentation](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components) + +--- + +## Inventory Flows Not Running + +### Symptom + +After clicking "Run Inventory Flows" in the setup wizard: +- Flows don't appear to start +- No data is collected in Dataverse tables +- Flow run history shows no runs or failures + +### Common Causes + +1. **Insufficient permissions** - User running setup needs admin roles +2. **DLP policies** - Required connectors blocked by policy +3. **Connection issues** - Flows need proper connections configured +4. **Licensing issues** - Inadequate Power Platform licenses + +### Troubleshooting Steps + +1. **Verify Admin Permissions:** + ``` + Required roles (at least one): + - Power Platform Administrator + - Global Administrator + - Dynamics 365 Administrator + ``` + +2. **Check Flow Connections:** + - Navigate to Cloud flows in CoE environment + - Open "Admin | Sync Template v3" flow + - Check connection references are valid (no red exclamation marks) + - Re-authenticate connections if needed + +3. **Review DLP Policies:** + - Check if connectors are in same DLP data group: + - Dataverse + - Power Apps for Admins + - Power Automate for Admins + - Office 365 Users + - Office 365 Outlook + +4. **Verify Licensing:** + - Ensure user has Power Automate license + - Not using trial licenses for production + +5. **Check Flow Run History:** + - Open "Admin | Sync Template v3" flow + - View 28-day run history + - Look for error messages if runs exist + - If no runs, flows may not be turned on + +6. **Manually Turn On Flows:** + - Navigate to Cloud flows + - Search for "Admin | Sync Template" + - Ensure flow is turned "On" + - Manually trigger to test + +### Expected Results + +After successful inventory flow run: +- Flow run history shows green checkmarks +- Dataverse tables contain records: + - Environment table has entries + - Power Apps App table populated + - Flow table has data +- First run takes 4-8 hours for large tenants + +--- + +## Setup Wizard Progress Not Saving + +### Symptom + +- Setup wizard doesn't remember completed steps +- Need to redo steps each time wizard is opened +- Progress indicators don't show completed status + +### Common Causes + +1. Browser session expired +2. Browser cache issues +3. Setup wizard state table not updating +4. Multiple users running setup simultaneously + +### Resolution + +1. **Clear Browser Cache:** + - Close all Power Apps tabs + - Clear browser cache and cookies + - Reopen setup wizard + +2. **Use Supported Browser:** + - Microsoft Edge (Chromium) + - Google Chrome + - Latest versions recommended + +3. **Single User Setup:** + - Only one admin should run setup wizard + - Don't have multiple sessions open + - Complete setup in one session if possible + +4. **Check Setup State Table:** + - In CoE environment, navigate to Tables + - Find "Setup Wizard State" table + - Verify records are being created/updated + +--- + +## Pre-requisites Not Met + +### Symptom + +Setup wizard shows warnings or errors about pre-requisites not being met. + +### Common Pre-requisites + +1. **Admin Permissions:** + - Need Power Platform Admin or Global Admin role + - May need Azure AD permissions for some features + +2. **Environment Requirements:** + - Dedicated environment for CoE (recommended) + - Not using default environment + - Environment in supported region + - Sufficient database capacity + +3. **Licensing:** + - Power Apps license + - Power Automate license + - Not trial licenses for production + +4. **Connectors Enabled:** + - Required connectors not blocked by DLP + - Custom connectors allowed (for some features) + +### Verification Checklist + +- [ ] User has Power Platform Admin or Global Admin role +- [ ] CoE installed in dedicated (non-default) environment +- [ ] Environment has adequate database storage (2GB+ recommended) +- [ ] User has Power Apps and Power Automate licenses +- [ ] DLP policies allow required connectors +- [ ] Environment language includes English + +### Resolution Steps + +1. Verify each pre-requisite above +2. Address any gaps before proceeding +3. Re-run pre-requisites check in wizard +4. Contact Microsoft support if license issues persist + +--- + +## Additional Resources + +### Documentation +- [Setup Core Components](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components) +- [Before you setup](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup) +- [Setup prerequisites](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#before-you-start) + +### Community Support +- [GitHub Issues](https://github.com/microsoft/coe-starter-kit/issues) +- [Power Apps Community Forum](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps) + +### Video Walkthroughs +- [CoE Starter Kit Setup Video Series](https://learn.microsoft.com/en-us/power-platform/guidance/coe/setup-core-components#watch-a-walk-through) + +--- + +*Last updated: 2025-12-10*