diff --git a/CenterofExcellenceCoreComponents/SolutionPackage/src/Workflows/SYNCHELPER-Apps-B677AA25-8DE4-ED11-A7C7-0022480813FF.json b/CenterofExcellenceCoreComponents/SolutionPackage/src/Workflows/SYNCHELPER-Apps-B677AA25-8DE4-ED11-A7C7-0022480813FF.json index 4579678e6..e94b2be7c 100644 --- a/CenterofExcellenceCoreComponents/SolutionPackage/src/Workflows/SYNCHELPER-Apps-B677AA25-8DE4-ED11-A7C7-0022480813FF.json +++ b/CenterofExcellenceCoreComponents/SolutionPackage/src/Workflows/SYNCHELPER-Apps-B677AA25-8DE4-ED11-A7C7-0022480813FF.json @@ -746,6 +746,9 @@ "runAfter": { "Get_App_Role_Assignments_as_Admin": [ "Succeeded" + ], + "Handle_Failed_Role_Assignment": [ + "Skipped" ] }, "metadata": { @@ -753,7 +756,7 @@ }, "type": "Query", "inputs": { - "from": "@outputs('Get_App_Role_Assignments_as_Admin')?['body/value']", + "from": "@coalesce(outputs('Get_App_Role_Assignments_as_Admin')?['body/value'], outputs('Handle_Failed_Role_Assignment'))", "where": "@equals(item()?['properties/principal/type'], 'Tenant')" } }, @@ -785,6 +788,19 @@ "minimumItemCount": 100000 } } + }, + "Handle_Failed_Role_Assignment": { + "runAfter": { + "Get_App_Role_Assignments_as_Admin": [ + "Failed", + "TimedOut" + ] + }, + "metadata": { + "operationMetadataId": "handle-failed-role-assignment-12345" + }, + "type": "Compose", + "inputs": [] } }, "runAfter": {}, diff --git a/docs/troubleshooting/README.md b/docs/troubleshooting/README.md index 0662ee847..edb9781ce 100644 --- a/docs/troubleshooting/README.md +++ b/docs/troubleshooting/README.md @@ -8,6 +8,10 @@ This directory contains troubleshooting guides for common issues encountered whe - **[Power BI Connection Timeout Error](power-bi-connection-timeout.md)** - Troubleshoot timeout and connection errors when connecting Power BI dashboards to Dataverse, specifically for the Admin Planning Component dashboard. +### Sync Flow Issues + +- **[SYNC HELPER - Apps Role Assignment Failure](sync-helper-apps-role-assignment-failure.md)** - Troubleshoot blank errors at Get_App_Role_Assignments_as_Admin action in the SYNC HELPER - Apps flow. + ## General Troubleshooting Resources For comprehensive setup and troubleshooting information, please refer to: diff --git a/docs/troubleshooting/sync-helper-apps-role-assignment-failure.md b/docs/troubleshooting/sync-helper-apps-role-assignment-failure.md new file mode 100644 index 000000000..1dcea75f3 --- /dev/null +++ b/docs/troubleshooting/sync-helper-apps-role-assignment-failure.md @@ -0,0 +1,340 @@ +# Troubleshooting: SYNC HELPER - Apps Fails at Get_App_Role_Assignments_as_Admin + +## Problem Description + +The **SYNC HELPER - Apps** flow fails at the `Get_App_Role_Assignments_as_Admin` action with a blank or empty error message, even though the app exists in the tenant. + +### Symptoms + +- Flow run shows **ActionFailed** status +- Error occurs at the `Get_App_Role_Assignments_as_Admin` action +- Error message is blank or shows: `"message": ""` +- The flow was processing an app that exists in the environment +- The condition `only if not SP App Edited` evaluated to `true` + +### Example Error + +``` +Flow run failed. +Action: Get_App_Role_Assignments_as_Admin +Status: ActionFailed +Message: An action failed. No dependent actions succeeded. +Error details: (blank) +``` + +## Root Cause Analysis + +The error occurs due to missing error handling in the `Get_App_Role_Assignments_as_Admin` action. This action calls the Power Platform for Admins API operation `Get-AdminAppRoleAssignment`, which can fail for several reasons: + +### Common Causes + +1. **App deleted between calls**: The app was present during the `Get_App_as_Admin` call but was deleted before `Get_App_Role_Assignments_as_Admin` executed +2. **Permissions issues**: The Power Platform for Admins connector doesn't have sufficient permissions to retrieve role assignments for the specific app +3. **API throttling or timeout**: The API call timed out or was throttled due to service protection limits +4. **Corrupted app metadata**: The app has corrupted or orphaned metadata in the environment +5. **SharePoint app type edge cases**: Apps with unusual SharePoint integration configurations +6. **Environment synchronization issues**: The app record is not fully synchronized across Power Platform services + +### Technical Details + +#### Flow Structure (Before Fix) + +The flow had the following structure: + +``` +only_if_not_SP_App_Editted (Condition) +├── Get_App_Role_Assignments_as_Admin (API Call) +│ └── On Success: Filter_to_tenant +└── No error handling ❌ +``` + +**Problem**: When `Get_App_Role_Assignments_as_Admin` fails, there is no error handler, causing the entire flow run to fail. + +#### Flow Structure (After Fix) + +``` +only_if_not_SP_App_Editted (Condition) +├── Get_App_Role_Assignments_as_Admin (API Call) +│ ├── On Success: Filter_to_tenant +│ └── On Failure: Handle_Failed_Role_Assignment +├── Handle_Failed_Role_Assignment (Error Handler) ✅ +│ └── Returns empty array when API call fails +└── Filter_to_tenant (Uses coalesce to handle both paths) +``` + +**Solution**: The new `Handle_Failed_Role_Assignment` action catches failures and provides an empty array, allowing the flow to continue and treat the app as not shared with tenant. + +## Resolution + +### Option 1: Upgrade to Fixed Version (Recommended) + +The fix has been implemented in **CoE Starter Kit version 4.50.7+** (or the next release after January 2026). + +**Steps:** +1. Download the latest release from [GitHub Releases](https://github.com/microsoft/coe-starter-kit/releases) +2. Import the Core Components solution +3. Update connections if prompted +4. The fix will be automatically applied + +### Option 2: Manual Fix for Existing Installations + +If you cannot upgrade immediately, you can manually add error handling: + +#### Step 1: Export the Flow + +1. Navigate to **Power Automate** > **Solutions** > **Center of Excellence - Core Components** +2. Find the **SYNC HELPER - Apps** flow +3. Click **Edit** to open the flow designer + +#### Step 2: Add Error Handling + +1. Locate the `Get_App_Role_Assignments_as_Admin` action inside the `only if not SP App Edited` condition +2. Add a new **Compose** action after it with the following settings: + - **Name**: `Handle_Failed_Role_Assignment` + - **Inputs**: `[]` (empty array) + - **Configure run after**: Set to run after `Get_App_Role_Assignments_as_Admin` with status **has failed** and **has timed out** + +3. Update the `Filter_to_tenant` action: + - **Configure run after**: Set to run after: + - `Get_App_Role_Assignments_as_Admin` with status **is successful** + - `Handle_Failed_Role_Assignment` with status **is skipped** + - **From**: Change to `@coalesce(outputs('Get_App_Role_Assignments_as_Admin')?['body/value'], outputs('Handle_Failed_Role_Assignment'))` + +4. Save the flow + +#### Visual Guide + +**Before:** +``` +Get_App_Role_Assignments_as_Admin + ↓ (Succeeded) +Filter_to_tenant +``` + +**After:** +``` +Get_App_Role_Assignments_as_Admin + ↓ (Succeeded) ↓ (Failed/TimedOut) + | | + | Handle_Failed_Role_Assignment + | ↓ (Skipped) + ↓ (Succeeded) | +Filter_to_tenant <------------------┘ +``` + +### Option 3: Workaround (Temporary) + +If you cannot apply the fix immediately, use this workaround: + +#### Identify Problematic Apps + +1. Navigate to **Dataverse** > **Tables** > **admin_apps** +2. Find apps that failed during sync +3. Note their App IDs + +#### Run Cleanup Flow + +1. Run **CLEANUP HELPER - Check Deleted v4 (Apps)** flow + - This marks deleted apps appropriately + - Prevents re-processing of orphaned app records + +#### Manual Retry + +1. Wait 15-30 minutes for any API throttling to clear +2. Re-run the **Admin | Sync Template v4 (Apps)** flow +3. If the error persists for the same app, it may be corrupted + +#### Handle Corrupted Apps + +For apps that consistently fail: + +1. **Verify app exists**: + - Open **Power Apps** maker portal + - Navigate to the environment + - Search for the app by name or ID + - If the app doesn't exist, proceed to delete the record + +2. **Delete the inventory record**: + - Open **Dataverse** > **Tables** > **admin_apps** + - Find the problematic app record + - Delete it + - The app will be re-discovered and re-inventoried in the next sync if it still exists + +3. **Mark as excluded** (alternative): + - Set `admin_excludefromanalytics` = **Yes** + - The app will be skipped in future syncs + +## Prevention and Best Practices + +### 1. Regular Cleanup Jobs + +Schedule regular cleanup to remove orphaned app references: + +- **Flow**: `CLEANUP HELPER - Check Deleted v4 (Apps)` +- **Frequency**: Weekly or bi-weekly +- **Purpose**: Marks deleted apps to prevent re-processing + +### 2. Monitor Sync Flow Errors + +Set up monitoring: + +1. Use the **Power Platform CoE Dashboard** to track sync flow failures +2. Review the `admin_SyncFlowErrors` table regularly +3. Address recurring errors proactively + +### 3. Verify Connector Permissions + +Ensure proper permissions for the Power Platform for Admins connector: + +1. **Required permissions**: + - Power Platform Administrator or Global Administrator role + - Access to all environments in the tenant + +2. **Verify connection**: + - Navigate to **Data** > **Connections** + - Check the **Power Platform for Admins V2** connection + - Ensure it's authenticated with the correct service account + - Refresh the connection if it shows as expired or invalid + +### 4. Implement Throttling Management + +If you have a large number of apps: + +1. Enable the `admin_DelayObjectInventory` environment variable + - This adds delays to avoid API throttling + - Set to **Yes** for large tenants (500+ apps) + +2. Monitor API request limits: + - Review [Service protection limits](https://learn.microsoft.com/power-platform/admin/api-request-limits-allocations) + - Ensure your service account has adequate API request capacity + +## Understanding the Fix + +### What the Fix Does + +1. **Catches API failures**: When `Get_App_Role_Assignments_as_Admin` fails, the new error handler (`Handle_Failed_Role_Assignment`) catches the failure + +2. **Provides default value**: Returns an empty array `[]` to indicate no role assignments + +3. **Continues flow execution**: The `Filter_to_tenant` action uses a `coalesce` expression to use either: + - The API response (if successful), OR + - The empty array (if failed) + +4. **Sets sharing status**: The app is treated as not shared with tenant when role assignments cannot be retrieved + +### Why This Approach + +- **Fail gracefully**: Better to inventory the app with incomplete sharing data than to fail the entire sync +- **Eventual consistency**: The next sync will retry and may succeed if the issue was transient +- **Consistent with other flows**: The CLEANUP HELPER flow uses the same pattern +- **Minimal impact**: Apps with failed role assignment retrieval are simply marked as not shared with tenant + +### What Happens to the App + +When `Get_App_Role_Assignments_as_Admin` fails: + +- ✅ The app is still inventoried in the `admin_apps` table +- ✅ All other app properties are captured (owner, created date, connections, etc.) +- ⚠️ Sharing information defaults to: + - `admin_appsharedwithtenant` = **No** (false) + - Specific user/group sharing details may be incomplete +- 🔄 The next sync will retry fetching role assignments + +## When to Escalate + +This issue typically doesn't require escalation and can be resolved using the steps above. However, consider creating a GitHub issue if: + +1. **Systematic failures**: Multiple apps fail consistently with this error +2. **After fix applied**: The error persists after applying the fix and retrying +3. **Connector issues**: You've verified connector permissions and the error continues +4. **Pattern identified**: You identify a specific app type or configuration that consistently fails + +### Creating a GitHub Issue + +If you need to create an issue, include: + +1. **CoE Starter Kit version** (e.g., 4.50.6) +2. **Error details**: + - Screenshot of the flow run failure + - The specific app ID that failed + - Whether the app exists in the environment +3. **Environment details**: + - Number of apps in the environment + - Whether this is a new installation or an upgrade + - Any recent changes (app deletions, permission changes, etc.) +4. **Steps already tried** from this guide +5. **Connector verification**: + - Power Platform for Admins V2 connection status + - Service account role (Global Admin, PP Admin, etc.) + +## Frequently Asked Questions + +### Q: Will this error cause data loss? + +**A:** No. This error only prevents complete sharing information from being inventoried for the specific app. All other app data is captured. The sharing data will be retried in the next sync. + +### Q: Should I delete apps that consistently fail? + +**A:** Not from the environment. Only delete the **inventory record** in Dataverse if: +- The app has been deleted from the environment, AND +- The cleanup flow hasn't marked it as deleted yet + +### Q: How often does this error typically occur? + +**A:** This is typically a rare, transient error (less than 1% of app processing runs). If you see it occurring frequently, there may be an underlying issue with permissions, API limits, or corrupted app metadata. + +### Q: Does this affect my Power Apps or environments? + +**A:** No. This error only affects the CoE Starter Kit's ability to inventory sharing information for the app. The app itself functions normally and is not impacted. + +### Q: Will the sharing information be updated eventually? + +**A:** Yes. The next sync run will retry fetching role assignments. If the issue was transient (deleted app, temporary throttling), the next run will succeed and update the sharing information. + +### Q: What's the difference between this and the CLEANUP HELPER flow? + +**A:** The CLEANUP HELPER flow has the same API call (`Get-AdminAppRoleAssignment`) but includes error handling. This fix brings the SYNC HELPER flow in line with the CLEANUP HELPER's error handling pattern. + +## Related Issues and Known Limitations + +### CoE Starter Kit Limitations + +- The CoE Starter Kit is provided as-is with best-effort support +- Complex synchronization scenarios may have edge cases +- API throttling can occur in large tenants (500+ apps, 10,000+ objects) + +### Power Platform API Behavior + +- The `Get-AdminAppRoleAssignment` API can return blank errors for several edge cases +- Eventual consistency: App metadata may not be immediately available across all APIs +- Service protection limits apply to all Power Platform for Admins operations + +### Recommended Reading + +- [CoE Starter Kit Documentation](https://learn.microsoft.com/power-platform/guidance/coe/starter-kit) +- [CoE Starter Kit Setup and Configuration](https://learn.microsoft.com/power-platform/guidance/coe/setup) +- [Service Protection API Limits](https://learn.microsoft.com/power-platform/admin/api-request-limits-allocations) +- [Troubleshooting: Entity Does Not Exist](../troubleshooting-sync-helper-cloud-flows-entity-not-exist.md) + +## Summary + +The "blank error" at `Get_App_Role_Assignments_as_Admin` in SYNC HELPER - Apps is caused by missing error handling when the Power Platform for Admins API fails to retrieve role assignments. This can be resolved by: + +1. **Immediate**: Upgrade to the fixed version (4.50.7+) +2. **Short-term**: Manually add error handling to the flow +3. **Temporary**: Use cleanup flows and manual retries + +The fix ensures the flow continues even when role assignments cannot be retrieved, treating the app as not shared with tenant and allowing the sync to complete successfully. + +## Document Information + +- **Created**: 2026-01-29 +- **Last Updated**: 2026-01-29 +- **Applies to**: CoE Starter Kit v4.50.6 and earlier +- **Fixed in**: CoE Starter Kit v4.50.7+ (or next release) +- **Issue**: [CoE Starter Kit - BUG] SYNC HELPER - Apps fails at Get_App_Role_Assignments_as_Admin +- **Solution Component**: Core - SYNC HELPER - Apps + +--- + +For additional help, consult the [CoE Starter Kit GitHub Issues](https://github.com/microsoft/coe-starter-kit/issues) or the [Power Platform Community](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps).