diff --git a/docs/FAQ-ConnectionsAndActionsCollection.md b/docs/FAQ-ConnectionsAndActionsCollection.md new file mode 100644 index 000000000..972257040 --- /dev/null +++ b/docs/FAQ-ConnectionsAndActionsCollection.md @@ -0,0 +1,252 @@ +# FAQ: How CoE Starter Kit Collects App Connection References and Flow Action Details + +## Question + +How does the CoE Starter Kit collect and update: +- **App Connection References** (list of connectors used by a Canvas App) +- **Flow Action Details** (operations used such as SendEmailV2, UserProfile_V2, etc.) + +This document explains which flows are responsible, how the data is extracted, and when/how often it is refreshed. + +--- + +## App Connection References Collection + +### Which Flow is Responsible? + +**Primary Flow:** `SYNC HELPER - Apps` +- **Technical Name:** `SYNCHELPER-Apps-B677AA25-8DE4-ED11-A7C7-0022480813FF` +- **Called By:** `Admin | Sync Template v4 (Apps)` + +### How Are App Connections Extracted? + +App connections are extracted from the **Power Apps for Admins connector** using the following process: + +1. **API Call:** The flow calls `Get-AdminApp` operation from the Power Apps for Admins connector +2. **Data Source:** The connection information comes from the app's metadata via `properties.connectionReferences` property +3. **Processing:** + - The flow parses the `connectionReferences` object from the app metadata + - Extracts connector display names and IDs + - Creates a comma-separated list of connections + - Stores this in the `admin_appconnections` field in Dataverse + +### Example Flow Logic + +``` +Get App as Admin (Power Apps for Admins API) + ↓ +Extract properties.connectionReferences + ↓ +Parse connection references JSON + ↓ +Compose comma-separated list + ↓ +Update/Create App record with admin_appconnections field +``` + +### Data Stored + +The following app connection-related fields are populated: +- `admin_appconnections` - Comma-separated list of connector names +- `admin_hasimplicitconnections` - Boolean indicating if app uses implicit (shared) connections +- `admin_hasinsecureimplicitconnections` - Boolean for insecure implicit connections +- `admin_appcontainsbrokenconnections` - Boolean for broken connection references + +--- + +## Flow Action Details Collection + +### Which Flow is Responsible? + +**Primary Flow:** `Admin | Sync Template v3 (Flow Action Details)` +- **Technical Name:** `AdminSyncTemplatev3FlowActionDetails-7EBB10A6-5041-EB11-A813-000D3A8F4AD6` +- **Trigger:** Runs when an environment record is added or modified in Dataverse + +### How Are Flow Actions Extracted? + +Flow action details are extracted from the **Power Automate Management connector** using the following process: + +1. **API Call:** The flow uses `AdminGetFlow` or `GetFlow` operations from the Power Automate Management connector +2. **Data Source:** The action information comes from: + - `properties.definitionSummary.triggers` - Trigger information + - `properties.definitionSummary.actions` - Action information + - Flow definition metadata via the Power Automate APIs +3. **Processing:** + - Retrieves flows from the environment + - For each flow, calls the Flow Management API to get detailed definition + - Parses the trigger and action arrays + - Extracts action types and operation names (e.g., `SendEmailV2`, `UserProfile_V2`) + - Creates records in the `admin_FlowActionDetail` table in Dataverse + +### Example Flow Logic + +``` +Trigger: Environment record added/modified + ↓ +Get Flows in Environment + ↓ +For each Flow: + → Get Flow Definition (AdminGetFlow) + → Parse definitionSummary.triggers + → Parse definitionSummary.actions + → Extract action types and operations + → Create/Update Flow Action Detail records +``` + +### Data Stored + +Flow action details are stored in the `admin_FlowActionDetail` table with fields such as: +- Action Type (e.g., "Office 365 Outlook", "Office 365 Users") +- Operation Name (e.g., "SendEmailV2", "UserProfile_V2") +- Associated Flow ID +- Connector information + +--- + +## When and How Often Data is Refreshed + +### Refresh Schedule + +The inventory sync follows this pattern: + +1. **Driver Flow Schedule:** `Admin | Sync Template v4 (Driver)` runs on a schedule (typically daily) + - This flow updates environment records in Dataverse + +2. **Triggered by Environment Changes:** When an environment record is updated: + - `Admin | Sync Template v4 (Apps)` → calls → `SYNC HELPER - Apps` (for app connections) + - `Admin | Sync Template v3 (Flow Action Details)` (for flow actions) + +3. **Incremental vs. Full Inventory:** + - **Incremental (Default):** Only syncs resources modified in the last N days (default 7) + - **Full Inventory:** Set environment variable `admin_FullInventory` to `Yes` to scan all resources + +### Environment Variables That Control Refresh + +- `admin_FullInventory` - Run full inventory (Yes/No, default: No) +- `admin_InventoryFilter_DaysToLookBack` - Days to look back for modified resources (default: 7) +- `admin_DelayObjectInventory` - Add random delay to avoid throttling (Yes/No, default: No) + +### On-Demand Refresh + +You can manually trigger a refresh by: + +1. **For App Connections:** + - Run `Admin | Sync Template v4 (Apps)` flow manually for a specific environment + +2. **For Flow Actions:** + - Run `Admin | Sync Template v3 (Flow Action Details)` flow manually + - Or update the environment record to trigger the automated flow + +--- + +## Data Sources Summary + +| What | API/Connector | Specific Operation | Property Path | +|------|--------------|-------------------|---------------| +| **App Connections** | Power Apps for Admins | `Get-AdminApp` | `properties.connectionReferences` | +| **Flow Actions** | Power Automate Management | `AdminGetFlow` or `GetFlow` | `properties.definitionSummary.actions`
`properties.definitionSummary.triggers` | + +--- + +## Architecture Overview + +``` +┌─────────────────────────────────────────────────────────┐ +│ Admin | Sync Template v4 (Driver) │ +│ (Runs on schedule - typically daily) │ +└────────────────────┬────────────────────────────────────┘ + │ + ├─► Updates Environment Records in Dataverse + │ + ┌────────────┴────────────┐ + │ │ + ▼ ▼ +┌───────────────────┐ ┌─────────────────────────────┐ +│ App Sync Triggers │ │ Flow Action Sync Triggers │ +└────────┬──────────┘ └──────────┬──────────────────┘ + │ │ + ▼ ▼ +┌──────────────────────────┐ ┌───────────────────────────────┐ +│ Admin | Sync v4 (Apps) │ │ Admin | Sync v3 (Flow Action │ +│ ↓ │ │ Details) │ +│ SYNC HELPER - Apps │ │ │ +│ ↓ │ │ │ +│ Calls Power Apps Admin │ │ Calls Flow Management API │ +│ ↓ │ │ ↓ │ +│ Gets connectionReferences│ │ Gets definitionSummary.actions │ +│ ↓ │ │ ↓ │ +│ Stores in admin_app... │ │ Stores in admin_FlowAction... │ +│ connections field │ │ Detail table │ +└──────────────────────────┘ └───────────────────────────────┘ +``` + +--- + +## Customizing the Logic + +If you want to review or customize how connections and actions are collected: + +### For App Connections: +1. Open **SYNC HELPER - Apps** flow in the CoE environment +2. Find the action **"Parse Connection References"** +3. Review the **"Compose comma-separated list of connection references"** action +4. Modify the logic to capture additional connection metadata if needed + +### For Flow Actions: +1. Open **Admin | Sync Template v3 (Flow Action Details)** flow +2. Find the actions **"Parse trigger"** and **"Parse actions"** +3. Review how action types and operations are extracted +4. Modify the **admin_FlowActionDetail** record creation logic to capture additional fields + +### Important Considerations: +- **Unmanaged Layers:** If you customize these flows, you will create an unmanaged layer that may prevent future updates from the CoE Starter Kit team +- **Best Practice:** Consider creating a separate custom flow that reads from the existing tables rather than modifying the sync flows directly +- **Testing:** Always test customizations in a non-production environment first + +--- + +## Troubleshooting + +### App Connections Not Showing + +1. **Check the sync flow runs:** + - Review `Admin | Sync Template v4 (Apps)` run history + - Check for errors in `SYNC HELPER - Apps` + +2. **Verify API permissions:** + - Ensure the service account has Power Platform Admin role + - Confirm Power Apps for Admins connector is properly configured + +3. **Check environment variable:** + - If only recent apps show connections, run a full inventory by setting `admin_FullInventory` to `Yes` + +### Flow Actions Not Appearing + +1. **Check the sync flow runs:** + - Review `Admin | Sync Template v3 (Flow Action Details)` run history + - Look for `admin_SyncFlowErrors` records for any errors + +2. **Verify the flow trigger:** + - Ensure environment records are being created/updated + - Manually update an environment record to trigger the flow + +3. **Check pagination:** + - If you have many flows, ensure pagination is working correctly + - Review the flow run to confirm all flows are being processed + +--- + +## Related Documentation + +- [CoE Starter Kit - Setup Core Components](https://learn.microsoft.com/power-platform/guidance/coe/setup-core-components) +- [CoE Starter Kit - Inventory Overview](https://learn.microsoft.com/power-platform/guidance/coe/core-components) +- [CoE Starter Kit - FAQ](https://learn.microsoft.com/power-platform/guidance/coe/faq) +- [Data Retention and Maintenance](../CenterofExcellenceResources/DataRetentionAndMaintenance.md) + +--- + +## Need More Help? + +- **GitHub Issues:** [CoE Starter Kit Issues](https://github.com/microsoft/coe-starter-kit/issues) +- **Community:** [Power Apps Governance Community](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps) +- **Official Documentation:** [CoE Starter Kit Documentation](https://learn.microsoft.com/power-platform/guidance/coe/starter-kit) diff --git a/docs/README.md b/docs/README.md index 5ae6d0113..3471d5fb2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -78,6 +78,11 @@ For comprehensive setup instructions, feature documentation, and best practices, - [Admin Role Requirements FAQ](../CenterofExcellenceResources/FAQ-AdminRoleRequirements.md) +### Frequently Asked Questions (FAQ) + +- **[FAQ: How CoE Collects App Connections and Flow Actions](FAQ-ConnectionsAndActionsCollection.md)** + Detailed explanation of how the CoE Starter Kit collects app connection references and flow action details + ## Getting Help ### Before Creating an Issue