diff --git a/docs/FEATURE-ENHANCEMENT-SUMMARY.md b/docs/FEATURE-ENHANCEMENT-SUMMARY.md new file mode 100644 index 000000000..f86dad8bd --- /dev/null +++ b/docs/FEATURE-ENHANCEMENT-SUMMARY.md @@ -0,0 +1,305 @@ +# Feature Enhancement Summary: Connection References and Environment Variables + +## Executive Summary + +This document summarizes the proposed enhancements for Connection References and Environment Variables in the CoE Starter Kit, providing a high-level overview for stakeholders and contributors. + +**Issue**: [CoE Starter Kit - Feature]: Connection References and Environment variables should be fully featured + +**Requestor**: @rooobeert + +**Status**: Analysis Complete, Ready for Implementation + +## Problem Statement + +As Microsoft moves away from classic admin centers to the new "environment settings app", administrators need better visibility and management capabilities for Connection References and Environment Variables within the CoE Starter Kit. Currently: + +### Current Gaps - Connection References +- ❌ No dedicated menu item (only accessible via Flows) +- ❌ Display names show connector service name instead of actual connection reference name +- ❌ Owner always appears as the service account, not the actual owner +- ❌ No visible relationship to Solutions + +### Current Gaps - Environment Variables +- ❌ Not tracked at all in the CoE Starter Kit +- ❌ No menu item +- ❌ No visibility into definitions, owners, or values +- ❌ No owner reassignment capability + +## Proposed Solution + +### Connection References Enhancements + +#### 1. Dedicated Menu Item (High Priority) +Add "Connection References" as a top-level menu item in the Power Platform Admin View under the "Monitor" group. + +**Benefit**: Administrators can quickly access and review all connection references across their environments without navigating through Flow relationships. + +#### 2. Accurate Display Names (High Priority - Critical) +Update the display logic to show the actual connection reference name (e.g., "SharePoint Production Connection") instead of the connector service name (e.g., "shared_sharepointonline"). + +**Benefit**: Dramatically improves usability and reduces confusion when identifying specific connection references. + +#### 3. Correct Owner Information (High Priority) +Capture and display the actual owner from Dataverse instead of always showing the CoE service account. + +**Benefit**: Critical for offboarding scenarios - administrators can identify which connection references need reassignment when a user leaves the organization. + +#### 4. Solution Relationships (Medium Priority) +Show which solution contains each connection reference. + +**Benefit**: Helps administrators understand dependencies and manage solutions more effectively. + +### Environment Variables Implementation + +#### 1. New Tracking Entity (High Priority) +Create `admin_EnvironmentVariableDefinition` entity to track environment variables across all environments. + +**Fields**: +- Display Name +- Schema Name +- Type (String, Number, JSON, Data Source) +- Current Value +- Default Value +- Description +- Owner (actual owner from Dataverse) +- Solution (which solution it belongs to) +- Environment +- Is Managed + +**Benefit**: Provides centralized governance and visibility for environment variables. + +#### 2. Dedicated Menu Item (High Priority) +Add "Environment Variables" as a menu item in the Power Platform Admin View under the "Monitor" group. + +**Benefit**: Administrators can review and manage environment variables alongside other Power Platform assets. + +#### 3. Inventory Flow (High Priority) +Create new inventory flow to collect environment variable data from all environments. + +**Benefit**: Automated data collection ensures up-to-date information without manual effort. + +#### 4. Owner Reassignment (Medium Priority) +Enable owner reassignment for environment variables through the standard Dataverse interface. + +**Benefit**: Supports user offboarding and role changes. + +## Implementation Approach + +### Phase 1: Connection References (2-3 days) +1. Add solution and actual owner fields to existing entity +2. Create enhanced views with correct display names +3. Update sitemap with dedicated menu item +4. Update inventory flows to capture new data +5. Update forms + +### Phase 2: Environment Variables (3-5 days) +1. Create new entity with all required fields +2. Create views (Active, By Solution, By Owner) +3. Create forms (Main, Quick Create, Card) +4. Add sitemap menu item +5. Create inventory flow +6. Configure owner reassignment + +### Phase 3: Testing & Documentation (1-2 days) +1. Comprehensive testing of all features +2. Update setup and user guides +3. Create release notes + +**Total Estimated Effort**: 6-10 days of development work + +## Technical Architecture + +### Data Model +``` +┌─────────────────────┐ +│ admin_Solution │ +└──────────┬──────────┘ + │ + │ (1:N) + │ + ┌──────┴──────────────────────┬─────────────────────────┐ + │ │ │ +┌───▼────────────────────┐ ┌─────▼──────────────────┐ │ +│ admin_ConnectionRef │ │ admin_EnvironmentVar │ │ +│ - Display Name │ │ Definition │ │ +│ - Actual Owner* │ │ - Display Name │ │ +│ - Solution* │ │ - Schema Name │ │ +│ - Connector │ │ - Type │ │ +│ - Environment │ │ - Current Value │ │ +└────────────────────────┘ │ - Default Value │ │ + │ - Actual Owner │ │ + * = New fields │ - Solution │ │ + │ - Environment │ │ + └────────────────────────┘ │ + │ + ┌──────────────────────────────┘ + │ + ┌──────▼──────────┐ + │ admin_Environment│ + └─────────────────┘ +``` + +### API Integration Points + +**Connection References**: +- Power Platform API: `/environments/{id}/connectionReferences` +- Dataverse Web API: `/connectionreferences` + +**Environment Variables**: +- Dataverse Web API: `/environmentvariabledefinitions` +- Dataverse Web API: `/environmentvariablevalues` + +## Benefits + +### For Administrators +- ✅ Centralized view of all connection references and environment variables +- ✅ Easy identification of orphaned connections and variables +- ✅ Streamlined user offboarding process +- ✅ Better understanding of solution dependencies +- ✅ Improved governance and compliance + +### For the Organization +- ✅ Reduced security risks from orphaned connections +- ✅ Better asset management +- ✅ Improved audit trail +- ✅ Faster troubleshooting of configuration issues +- ✅ Enhanced compliance with data governance policies + +### For the CoE Starter Kit +- ✅ Feature parity with classic admin center capabilities +- ✅ Improved user experience +- ✅ More comprehensive inventory +- ✅ Alignment with Microsoft's direction (modern admin experiences) + +## Success Metrics + +- ✅ Connection References accessible in ≤2 clicks from main menu +- ✅ 100% accuracy in displaying connection reference names +- ✅ 100% accuracy in displaying actual owners +- ✅ Environment Variables inventory completes in <10 minutes for 100 environments +- ✅ Zero breaking changes to existing CoE Starter Kit functionality +- ✅ Backward compatible with existing deployments + +## Risks and Mitigation + +### Risk 1: Performance with Large Datasets +**Impact**: Medium +**Mitigation**: +- Implement pagination in views +- Use incremental sync in inventory flows +- Add indexes on key fields + +### Risk 2: API Rate Limiting +**Impact**: Medium +**Mitigation**: +- Implement retry logic with exponential backoff +- Batch operations where possible +- Stagger inventory flows + +### Risk 3: Breaking Changes to Existing Customizations +**Impact**: Low +**Mitigation**: +- All changes are additive (new fields, views, menu items) +- Existing functionality remains unchanged +- Thorough testing before release + +### Risk 4: Sensitive Data in Environment Variables +**Impact**: Medium +**Mitigation**: +- Implement field-level security +- Consider masking values in views +- Document security best practices + +## Community Contribution + +This feature is ready for community contribution! The detailed implementation guide provides step-by-step instructions for developers who want to contribute. + +### How You Can Help + +**For Developers**: +- Implement Phase 1 (Connection References) +- Implement Phase 2 (Environment Variables) +- Write unit tests +- Create sample data for testing + +**For Power Platform Experts**: +- Review the proposed data model +- Suggest additional fields or relationships +- Test beta versions +- Provide feedback on UX + +**For Documentation Writers**: +- Enhance the implementation guide +- Create user-facing documentation +- Write blog posts or videos + +### Getting Started +1. Read the [Implementation Guide](./IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md) +2. Fork the repository +3. Create a feature branch +4. Start with Phase 1 or Phase 2 +5. Submit a PR with your changes + +## Questions and Answers + +### Q: Will this work with existing CoE Starter Kit deployments? +**A**: Yes, all changes are backward compatible. New fields are optional, and existing functionality is unchanged. + +### Q: Do I need to reinstall the entire CoE Starter Kit? +**A**: No, these will be delivered as incremental updates that can be applied to existing installations. + +### Q: What about custom fields I've added to admin_ConnectionReference? +**A**: Your customizations will be preserved. The new fields are additive. + +### Q: How long will the initial Environment Variables inventory take? +**A**: Depends on the number of environments and variables. Estimated 5-10 minutes for 100 environments with typical variable counts. + +### Q: Can I exclude certain environment variables from being tracked? +**A**: Yes, the inventory flow can be configured with filters to exclude specific variables or patterns. + +### Q: Will this increase my API usage significantly? +**A**: Minimally. The inventory flows run once daily by default. Impact is similar to existing inventory flows for Apps and Flows. + +## Next Steps + +1. ✅ **Community Review** (Current Phase) + - Gather feedback on the implementation guide + - Refine requirements based on input + - Prioritize features if needed + +2. ⏳ **Implementation** (Looking for volunteers!) + - Phase 1: Connection References enhancements + - Phase 2: Environment Variables implementation + - Phase 3: Testing and documentation + +3. ⏳ **Beta Testing** + - Deploy to test environments + - Gather user feedback + - Iterate on UX and functionality + +4. ⏳ **Release** + - Merge to main branch + - Include in next CoE Starter Kit release + - Announce to community + +## Related Resources + +- [Full Implementation Guide](./IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md) +- [CoE Starter Kit Documentation](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) +- [Connection References Documentation](https://learn.microsoft.com/en-us/power-apps/maker/data-platform/create-connection-reference) +- [Environment Variables Documentation](https://learn.microsoft.com/en-us/power-apps/maker/data-platform/environmentvariables) +- [GitHub Issue - Original Feature Request](#) + +## Contact + +For questions or to volunteer for implementation: +- Comment on the GitHub issue +- Join the discussion in Power Platform Community forums +- Reach out to the CoE Starter Kit maintainers + +--- + +**Last Updated**: December 2024 +**Version**: 1.0 +**Status**: Ready for Implementation diff --git a/docs/GITHUB-ISSUE-RESPONSE.md b/docs/GITHUB-ISSUE-RESPONSE.md new file mode 100644 index 000000000..353691983 --- /dev/null +++ b/docs/GITHUB-ISSUE-RESPONSE.md @@ -0,0 +1,162 @@ +# GitHub Issue Response: Connection References and Environment Variables Enhancement + +## Response to Issue Author + +Hi @rooobeert, + +Thank you for this detailed and valuable feature request! Your feedback aligns perfectly with Microsoft's direction toward modern admin experiences, and these enhancements will significantly improve the CoE Starter Kit's capabilities. + +## Analysis Complete ✅ + +I've completed a comprehensive analysis of your request and created detailed implementation guidance. Here's what I found: + +### Current State +You're absolutely right about the gaps: + +**Connection References** currently: +- ✅ Have a tracking entity (`admin_ConnectionReference`) +- ❌ No dedicated menu item (only accessible through Flow relationships) +- ❌ Display connector service names instead of actual connection reference names +- ❌ Show service account as owner instead of actual owner +- ❌ Don't show solution relationships + +**Environment Variables**: +- ❌ Not tracked at all in the CoE Starter Kit currently + +### What We're Proposing + +#### Connection References Enhancements +1. **New Menu Item**: Add "Connection References" to the Monitor group in Power Platform Admin View +2. **Correct Display Names**: Show actual connection reference names (e.g., "SharePoint Production Connection" instead of "shared_sharepointonline") +3. **Actual Owners**: Capture and display real owners from Dataverse (critical for offboarding!) +4. **Solution Relationships**: Show which solution contains each connection reference + +#### Environment Variables (New Feature) +1. **New Entity**: Create `admin_EnvironmentVariableDefinition` to track variables +2. **New Menu Item**: Add "Environment Variables" to the Monitor group +3. **Comprehensive Fields**: Display Name, Schema Name, Type, Current Value, Default Value, Owner, Solution +4. **Inventory Flow**: Automated data collection across all environments +5. **Owner Reassignment**: Enable ownership changes for offboarding scenarios + +## Documentation Created + +I've created two comprehensive documents to guide implementation: + +### 1. [Implementation Guide](../docs/IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md) +A detailed technical guide with: +- Step-by-step implementation instructions +- Code examples and file locations +- API integration details +- Testing checklist +- Migration path for existing deployments + +**Estimated Implementation Time**: 6-10 days total +- Phase 1 (Connection References): 2-3 days +- Phase 2 (Environment Variables): 3-5 days +- Phase 3 (Testing & Docs): 1-2 days + +### 2. [Feature Enhancement Summary](../docs/FEATURE-ENHANCEMENT-SUMMARY.md) +An executive overview with: +- Problem statement and benefits +- Architecture diagrams +- Risk analysis +- Community contribution guide + +## Your Offer to Help 🙌 + +You mentioned: +> "I would love to help develop this further. I am a Power Platform developer, but my expertise in Model Driven apps and Dataverse is very basic." + +That's perfect! The implementation guide is designed to be accessible to Power Platform developers. Here's how you can contribute: + +### Getting Started (Choose Your Comfort Level) + +**Option 1: Start with Connection References (Easier)** +- Add the new menu item to the sitemap (XML edit) +- Update existing views (XML configuration) +- This requires minimal Dataverse knowledge + +**Option 2: Work on Environment Variables (More involved)** +- Create the new entity following the guide +- Build forms and views +- Create the inventory flow (this is where your Power Platform skills shine!) + +**Option 3: Documentation & Testing** +- Test the proposed changes in a dev environment +- Improve the documentation +- Create user guides + +### Resources to Help You +- The implementation guide includes all file paths and code examples +- The CoE Starter Kit community is very supportive +- We can provide feedback on pull requests iteratively + +## How to Proceed + +### Immediate Next Steps +1. **Review the documentation** in the `docs/` folder +2. **Set up a development environment** with the CoE Starter Kit +3. **Choose a starting point** (Connection References menu item is a good first contribution!) +4. **Fork the repository** and create a feature branch +5. **Start implementing** following the guide +6. **Submit a PR** - even if it's partial work, we can iterate! + +### Community Support +- Comment on this issue with questions +- Join Power Platform Community forums +- Reach out to CoE Starter Kit maintainers + +### For the Broader Community +Anyone interested in implementing these features can follow the same guides! Contributions are welcome from multiple people working on different phases. + +## Technical Highlights + +For those diving into the technical details: + +**Connection References Enhancement**: +- Add fields to existing `admin_ConnectionReference` entity +- Create enhanced views using FetchXML +- Update `AppModuleSiteMap.xml` +- Modify inventory flows to capture actual owners and solution relationships + +**Environment Variables Implementation**: +- Create new `admin_EnvironmentVariableDefinition` entity +- Build forms, views, and relationships +- Create new inventory flow using Dataverse Web API +- Endpoints: `/environmentvariabledefinitions` and `/environmentvariablevalues` + +## Impact & Benefits + +When complete, administrators will have: +- ✅ One-click access to all connection references and environment variables +- ✅ Accurate identification of owners (crucial for offboarding) +- ✅ Clear solution dependencies +- ✅ Centralized governance across all environments +- ✅ Better security posture (identify orphaned connections) + +## Timeline & Expectations + +This is a community-driven enhancement with no specific timeline. Implementation can happen: +- All at once by one contributor +- In phases by multiple contributors +- Iteratively with feedback and improvements + +The goal is to include these features in a future CoE Starter Kit release once tested and validated by the community. + +## Questions? + +Feel free to ask questions on this issue or reach out through: +- GitHub Issues +- Power Platform Community Forums +- CoE Starter Kit discussions + +Thank you again for this excellent suggestion! Let's work together to make this happen. 🚀 + +--- + +**Documentation Links**: +- [Full Implementation Guide](../docs/IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md) +- [Feature Enhancement Summary](../docs/FEATURE-ENHANCEMENT-SUMMARY.md) + +**Status**: ✅ Analysis Complete, 📝 Ready for Implementation + diff --git a/docs/IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md b/docs/IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md new file mode 100644 index 000000000..1c83638b1 --- /dev/null +++ b/docs/IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md @@ -0,0 +1,598 @@ +# Implementation Guide: Enhanced Connection References and Environment Variables Features + +## Overview + +This document provides comprehensive guidance on implementing the enhancement requests for Connection References and Environment Variables in the CoE Starter Kit Power Platform Admin View. + +**Issue Reference**: [Feature Request - Connection References and Environment variables should be fully featured](https://github.com/microsoft/coe-starter-kit/issues/) + +## Current State Analysis + +### Connection References (admin_ConnectionReference) +The CoE Starter Kit currently has: +- ✅ Entity: `admin_ConnectionReference` with basic tracking +- ✅ Data collection flows that inventory connection references +- ⚠️ Limited visibility - currently accessible only through Flow relationships +- ⚠️ Display Name shows connector service name, not the actual connection reference display name +- ⚠️ Owner information not accurately reflected (shows service account) +- ❌ No direct relationship to Solutions shown in views + +### Connection Reference Identity (admin_ConnectionReferenceIdentity) +- ✅ Entity: `admin_ConnectionReferenceIdentity` for tracking connection identities +- ✅ Already has a dedicated menu item in the Users group (line 69-73 in AppModuleSiteMap.xml) +- ✅ Includes fields for connector, environment, account name, and creator tracking + +### Environment Variables +- ❌ No dedicated entity for tracking Environment Variable Definitions +- ❌ Not currently inventoried by the CoE Starter Kit +- ❌ No menu item in Power Platform Admin View +- ❌ No owner reassignment capability + +## Requirements Summary + +### Connection References +1. ✅ **Menu Item**: Add dedicated menu item (high priority - improves discoverability) +2. ✅ **Display Names**: Show actual connection reference display name (high priority - critical usability) +3. ✅ **Owner Information**: Show correct owner from Dataverse (high priority - needed for offboarding) +4. ✅ **Solution Relationship**: Display which solution contains the connection reference (medium priority) + +### Environment Variables +1. ✅ **Menu Item**: Add dedicated menu item (high priority) +2. ✅ **Entity Creation**: Create tracking entity for environment variable definitions (high priority) +3. ✅ **Display Fields**: Show DisplayName, SchemaName, Owner, and other metadata (high priority) +4. ✅ **Solution Relationship**: Display which solution contains the variable (medium priority) +5. ✅ **Owner Reassignment**: Enable owner changes (medium priority - needed for offboarding) + +## Implementation Steps + +### Phase 1: Enhanced Connection References (Estimated: 2-3 days) + +#### Step 1.1: Add Missing Fields to admin_ConnectionReference Entity +The entity already exists but needs additional fields to track solution relationships: + +```xml + + + lookup + admin_solution + admin_solution + none + ValidForAdvancedFind|ValidForForm|ValidForGrid + + + + + lookup + admin_actualowner + admin_actualowner + none + ValidForAdvancedFind|ValidForForm|ValidForGrid + + +``` + +**File Location**: `CenterofExcellenceCoreComponents/SolutionPackage/src/Entities/admin_ConnectionReference/Entity.xml` + +#### Step 1.2: Create Enhanced View for Connection References +Create a new "Active Connection References" view that shows: +- Display Name (actual connection reference name, not connector service name) +- Connector (related connector) +- Actual Owner (from Dataverse) +- Solution (which solution it belongs to) +- Environment +- Created On +- Modified On + +**File Location**: Create new file in `CenterofExcellenceCoreComponents/SolutionPackage/src/Entities/admin_ConnectionReference/SavedQueries/` + +```xml + + + + 1 + 1 + 0 + 0 + 1 + {NEW-GUID-HERE} + + + + + + + + + + + + + 0 + + + + + + + + + + + + + + + + + + + + + + + 1.0 + + + + + +``` + +#### Step 1.3: Add Connection References Menu Item to Sitemap +Update the Power Platform Admin View sitemap to add a dedicated menu item for Connection References in the "Monitor" group. + +**File Location**: `CenterofExcellenceCoreComponents/SolutionPackage/src/AppModuleSiteMaps/admin_PowerPlatformAdminView/AppModuleSiteMap.xml` + +Add after line 29 (after Connectors SubArea): +```xml + + + + </Titles> +</SubArea> +``` + +#### Step 1.4: Update Inventory Flows +Update the existing inventory flows to capture: +- Actual owner information from the connectionreference entity in Dataverse (not just the flow creator) +- Solution relationship (which solution the connection reference belongs to) +- Proper display name from the connectionreference metadata + +**Files to Update**: +- Look for flows in `CenterofExcellenceCoreComponents/SolutionPackage/src/Workflows/` that handle connection reference inventory +- These typically start with `AdminSyncTemplatev4` or similar naming + +**Key API Calls Needed**: +``` +GET https://api.powerplatform.com/environments/{environmentId}/connectionReferences?api-version=2020-10-01 +``` + +The response includes: +- `properties.displayName` - the actual display name +- `properties.createdBy` - the actual creator +- `properties.modifiedBy` - the actual modifier +- `properties.connectionReferenceLogicalName` - the schema name +- Solution information through solutionid property + +#### Step 1.5: Update Forms +Update the main form for Connection References to include the new fields prominently. + +**File Location**: `CenterofExcellenceCoreComponents/SolutionPackage/src/Entities/admin_ConnectionReference/FormXml/main/` + +### Phase 2: Environment Variables Implementation (Estimated: 3-5 days) + +#### Step 2.1: Create admin_EnvironmentVariableDefinition Entity +Create a new custom entity to track Environment Variable Definitions. + +**File Location**: Create new directory `CenterofExcellenceCoreComponents/SolutionPackage/src/Entities/admin_EnvironmentVariableDefinition/` + +**Entity Structure**: +```xml +<?xml version="1.0" encoding="utf-8"?> +<Entity> + <Name LocalizedName="Environment Variable Definition" OriginalName="Environment Variable Definition">admin_EnvironmentVariableDefinition</Name> + <EntityInfo> + <entity Name="admin_EnvironmentVariableDefinition"> + <LocalizedNames> + <LocalizedName description="Environment Variable Definition" languagecode="1033" /> + </LocalizedNames> + <LocalizedCollectionNames> + <LocalizedCollectionName description="Environment Variable Definitions" languagecode="1033" /> + </LocalizedCollectionNames> + <Descriptions> + <Description description="Tracks environment variable definitions across environments for governance" languagecode="1033" /> + </Descriptions> + <attributes> + <!-- Primary Key --> + <attribute PhysicalName="admin_EnvironmentVariableDefinitionId"> + <Type>primarykey</Type> + <Name>admin_environmentvariabledefinitionid</Name> + <!-- Standard primary key configuration --> + </attribute> + + <!-- Display Name (Primary Name Field) --> + <attribute PhysicalName="admin_DisplayName"> + <Type>nvarchar</Type> + <Name>admin_displayname</Name> + <LogicalName>admin_displayname</LogicalName> + <RequiredLevel>required</RequiredLevel> + <DisplayMask>PrimaryName|ValidForAdvancedFind|ValidForForm|ValidForGrid|RequiredForForm</DisplayMask> + <MaxLength>100</MaxLength> + <!-- Display name from Dataverse --> + </attribute> + + <!-- Schema Name --> + <attribute PhysicalName="admin_SchemaName"> + <Type>nvarchar</Type> + <Name>admin_schemaname</Name> + <MaxLength>100</MaxLength> + <!-- Logical/Schema name --> + </attribute> + + <!-- Type (String, Number, JSON, Data Source, etc.) --> + <attribute PhysicalName="admin_Type"> + <Type>picklist</Type> + <Name>admin_type</Name> + <!-- Option set for different types --> + </attribute> + + <!-- Current Value --> + <attribute PhysicalName="admin_CurrentValue"> + <Type>nvarchar</Type> + <Name>admin_currentvalue</Name> + <MaxLength>2000</MaxLength> + <!-- Current value (from environmentvariablevalue table) --> + </attribute> + + <!-- Default Value --> + <attribute PhysicalName="admin_DefaultValue"> + <Type>nvarchar</Type> + <Name>admin_defaultvalue</Name> + <MaxLength>2000</MaxLength> + <!-- Default value defined in the definition --> + </attribute> + + <!-- Description --> + <attribute PhysicalName="admin_Description"> + <Type>ntext</Type> + <Name>admin_description</Name> + <MaxLength>2000</MaxLength> + </attribute> + + <!-- Environment Lookup --> + <attribute PhysicalName="admin_Environment"> + <Type>lookup</Type> + <Name>admin_environment</Name> + <!-- Link to admin_Environment --> + </attribute> + + <!-- Solution Lookup --> + <attribute PhysicalName="admin_Solution"> + <Type>lookup</Type> + <Name>admin_solution</Name> + <!-- Link to admin_Solution --> + </attribute> + + <!-- Actual Owner (from Dataverse) --> + <attribute PhysicalName="admin_ActualOwner"> + <Type>lookup</Type> + <Name>admin_actualowner</Name> + <!-- Link to systemuser --> + </attribute> + + <!-- Dataverse ID (for reference) --> + <attribute PhysicalName="admin_DataverseId"> + <Type>nvarchar</Type> + <Name>admin_dataverseid</Name> + <MaxLength>100</MaxLength> + <!-- The actual environmentvariabledefinitionid from Dataverse --> + </attribute> + + <!-- Is Managed --> + <attribute PhysicalName="admin_IsManaged"> + <Type>bit</Type> + <Name>admin_ismanaged</Name> + <!-- Whether it's from a managed solution --> + </attribute> + + <!-- Standard Owner field for reassignment --> + <attribute PhysicalName="OwnerId"> + <Type>owner</Type> + <Name>ownerid</Name> + <!-- Standard ownership for reassignment capability --> + </attribute> + </attributes> + + <OwnershipTypeMask>UserOwned</OwnershipTypeMask> + <!-- Additional entity configuration --> + </entity> + </EntityInfo> +</Entity> +``` + +#### Step 2.2: Create Views for Environment Variables +Create standard views: + +1. **Active Environment Variables** (default view) +2. **Environment Variables by Solution** +3. **Environment Variables by Owner** +4. **Quick Find Active Environment Variables** + +**Example Active View**: +```xml +<savedquery> + <layoutxml> + <grid name="resultset" jump="admin_displayname" select="1" icon="1" preview="1"> + <row name="result" id="admin_environmentvariabledefinitionid"> + <cell name="admin_displayname" width="200" /> + <cell name="admin_schemaname" width="200" /> + <cell name="admin_type" width="100" /> + <cell name="admin_actualowner" width="150" /> + <cell name="admin_solution" width="150" /> + <cell name="admin_environment" width="150" /> + <cell name="admin_currentvalue" width="200" /> + </row> + </grid> + </layoutxml> + <fetchxml> + <fetch version="1.0" mapping="logical"> + <entity name="admin_environmentvariabledefinition"> + <attribute name="admin_environmentvariabledefinitionid" /> + <attribute name="admin_displayname" /> + <attribute name="admin_schemaname" /> + <attribute name="admin_type" /> + <attribute name="admin_actualowner" /> + <attribute name="admin_solution" /> + <attribute name="admin_currentvalue" /> + <order attribute="admin_displayname" descending="false" /> + <filter type="and"> + <condition attribute="statecode" operator="eq" value="0" /> + </filter> + </entity> + </fetch> + </fetchxml> + <LocalizedNames> + <LocalizedName description="Active Environment Variables" languagecode="1033" /> + </LocalizedNames> +</savedquery> +``` + +#### Step 2.3: Create Forms +Create main form, quick create form, and card form for the new entity. + +**Key Tabs**: +1. **General** - Display Name, Schema Name, Type, Description +2. **Values** - Current Value, Default Value +3. **Relationships** - Environment, Solution, Owner +4. **Advanced** - Dataverse ID, Is Managed, Created/Modified info + +#### Step 2.4: Add Environment Variables Menu Item to Sitemap +Add to the "Monitor" group in the Power Platform Admin View sitemap. + +**File Location**: `CenterofExcellenceCoreComponents/SolutionPackage/src/AppModuleSiteMaps/admin_PowerPlatformAdminView/AppModuleSiteMap.xml` + +Add after the Connection References SubArea (from Step 1.3): +```xml +<SubArea Id="NewSubArea_EnvironmentVariables" + VectorIcon="/WebResources/admin_EnvironmentVariableIcon" + Icon="/WebResources/admin_EnvironmentVariableIcon" + Entity="admin_environmentvariabledefinition" + Client="All,Outlook,OutlookLaptopClient,OutlookWorkstationClient,Web" + AvailableOffline="true" + PassParams="false" + Sku="All,OnPremise,Live,SPLA"> + <Titles> + <Title LCID="1033" Title="Environment Variables" /> + </Titles> +</SubArea> +``` + +#### Step 2.5: Create Inventory Flow for Environment Variables +Create a new cloud flow to inventory environment variable definitions. + +**Flow Name**: `AdminSyncTemplatev4 - Environment Variables` + +**Key Steps**: +1. **Trigger**: Scheduled (runs daily, or can be triggered by the main sync flow) +2. **Get Environments**: List all environments from the inventory +3. **For Each Environment**: + a. Call Dataverse API to get environmentvariabledefinition records + b. For each definition, get associated environmentvariablevalue (current value) + c. Map to admin_EnvironmentVariableDefinition entity + d. Upsert record in CoE environment +4. **Error Handling**: Log errors to admin_SyncFlowErrors + +**API Endpoints**: +``` +GET https://[orgUrl]/api/data/v9.2/environmentvariabledefinitions +GET https://[orgUrl]/api/data/v9.2/environmentvariablevalues +``` + +**Key OData Queries**: +``` +/environmentvariabledefinitions?$select=environmentvariabledefinitionid,schemaname,displayname,type,defaultvalue,description,_ownerid_value,ismanaged&$expand=solution($select=solutionid,uniquename,friendlyname) + +/environmentvariablevalues?$select=environmentvariablevalueid,value,_environmentvariabledefinitionid_value&$filter=_environmentvariabledefinitionid_value eq [GUID] +``` + +**Mapping**: +- `displayname` → `admin_displayname` +- `schemaname` → `admin_schemaname` +- `type` → `admin_type` (map numeric values to option set) +- `defaultvalue` → `admin_defaultvalue` +- `description` → `admin_description` +- `_ownerid_value` → `admin_actualowner` (lookup) +- Solution from expand → `admin_solution` (lookup) +- `value` from environmentvariablevalue → `admin_currentvalue` +- `ismanaged` → `admin_ismanaged` + +#### Step 2.6: Owner Reassignment Configuration +The entity is created with `UserOwned` ownership type, which automatically enables owner reassignment through: +- The "Assign" button in the command bar +- Bulk reassignment workflows +- The standard Dataverse owner reassignment UI + +**Additional Considerations**: +- Create a custom button/action to reassign owners in the actual environment (not just in the CoE inventory) +- This would require calling the Dataverse API to update the owner in the source environment + +### Phase 3: Testing and Documentation (Estimated: 1-2 days) + +#### Step 3.1: Testing Checklist +- [ ] Connection References appear in dedicated menu item +- [ ] Connection Reference views show correct display names (not connector service names) +- [ ] Connection Reference views show actual owner (not service account) +- [ ] Connection Reference views show solution relationships +- [ ] Environment Variables appear in dedicated menu item +- [ ] Environment Variable inventory flow successfully collects data +- [ ] Environment Variable views show all required fields +- [ ] Owner reassignment works for both Connection References and Environment Variables +- [ ] Solution relationships are correctly displayed +- [ ] Quick Find works for both entities +- [ ] Forms display all information correctly +- [ ] Performance is acceptable with large datasets + +#### Step 3.2: Documentation Updates +Update the following documentation: +- **Setup Guide**: Add steps for enabling Environment Variable inventory +- **User Guide**: Document the new Connection References and Environment Variables features +- **API Reference**: Document any new environment variables or configuration options +- **Release Notes**: Add details about the new features + +## Technical Considerations + +### Data Model Relationships + +``` +admin_Solution + ↓ (1:N) +admin_ConnectionReference + ↓ (N:1) +admin_Connector + +admin_Solution + ↓ (1:N) +admin_EnvironmentVariableDefinition + +admin_Environment + ↓ (1:N) +admin_ConnectionReference, admin_EnvironmentVariableDefinition +``` + +### Performance Optimization +- Add indexes on commonly filtered/sorted fields (display name, solution, owner) +- Consider pagination in inventory flows for large environments +- Implement incremental sync (only update changed records) + +### Security +- Respect existing CoE Starter Kit security roles +- Environment Variables may contain sensitive data - ensure proper field-level security +- Consider masking sensitive values in views (show only [VALUE SET] indicator) + +### API Limits +- Connection Reference and Environment Variable APIs are subject to Dataverse API limits +- Implement retry logic with exponential backoff +- Consider batching operations where possible + +## Migration Path for Existing Implementations + +For organizations already using the CoE Starter Kit: + +1. **Backup**: Export existing admin_ConnectionReference data +2. **Schema Update**: Apply new fields to admin_ConnectionReference entity +3. **Data Migration**: Run inventory flows to populate new fields +4. **Sitemap Update**: Merge sitemap changes (existing customizations preserved) +5. **New Entity**: Deploy admin_EnvironmentVariableDefinition entity +6. **Initial Inventory**: Run new Environment Variables inventory flow +7. **Validation**: Verify data accuracy and completeness +8. **Go Live**: Enable new menu items for users + +## Alternative Approaches Considered + +### Alternative 1: Use Out-of-Box Dataverse Tables +**Pros**: No custom entities needed, direct access to source data +**Cons**: +- Requires Dataverse licenses for all admins +- No cross-environment aggregation +- Cannot add custom fields for CoE governance +- **Decision**: Not recommended - goes against CoE Starter Kit architecture + +### Alternative 2: Use Power BI for Visualization Only +**Pros**: Rich visualization, no model-driven app changes needed +**Cons**: +- No owner reassignment capability +- No integration with other CoE features +- Limited filtering and interaction +- **Decision**: Complementary approach, but doesn't meet all requirements + +### Alternative 3: External Database with Power Apps Portal +**Pros**: Fully customizable, separate from Dataverse limits +**Cons**: +- Significantly more complex infrastructure +- Additional licensing costs +- Security and authentication complexity +- **Decision**: Not recommended - over-engineered for the requirements + +## Success Criteria + +✅ **Connection References**: +- Dedicated menu item in Power Platform Admin View +- Display actual connection reference names (not connector service names) +- Show correct owner information (not always service account) +- Display solution relationships + +✅ **Environment Variables**: +- Dedicated menu item in Power Platform Admin View +- Full inventory of environment variable definitions across all environments +- Display name, schema name, owner, type, current value, default value, solution +- Owner reassignment capability enabled + +✅ **General**: +- Solution follows CoE Starter Kit patterns and conventions +- Documentation complete and clear +- Performance acceptable with large datasets (100+ environments, 1000+ variables) +- Backward compatible with existing CoE Starter Kit deployments + +## Resources + +### Microsoft Documentation +- [Environment Variable Definitions](https://learn.microsoft.com/en-us/power-apps/maker/data-platform/environmentvariables) +- [Connection References](https://learn.microsoft.com/en-us/power-apps/maker/data-platform/create-connection-reference) +- [CoE Starter Kit Documentation](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) +- [Dataverse Web API](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/overview) + +### Community Resources +- [CoE Starter Kit GitHub](https://github.com/microsoft/coe-starter-kit) +- [Power Platform Community](https://powerusers.microsoft.com/) + +## Support and Contribution + +This is a community-driven enhancement. Contributions are welcome! + +### How to Contribute +1. Fork the repository +2. Create a feature branch +3. Implement changes following this guide +4. Test thoroughly +5. Submit a pull request with: + - Description of changes + - Screenshots of new UI elements + - Test results + - Documentation updates + +### Getting Help +- [GitHub Issues](https://github.com/microsoft/coe-starter-kit/issues) +- [Power Platform Community Forums](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps) + +--- + +**Last Updated**: December 2024 +**Version**: 1.0 +**Status**: Draft Implementation Guide diff --git a/docs/QUICK-START-GUIDE-CONTRIBUTORS.md b/docs/QUICK-START-GUIDE-CONTRIBUTORS.md new file mode 100644 index 000000000..57e6b7cdf --- /dev/null +++ b/docs/QUICK-START-GUIDE-CONTRIBUTORS.md @@ -0,0 +1,341 @@ +# Quick Start Guide for Contributors + +## Contributing to Connection References and Environment Variables Enhancement + +Want to help implement these features? This guide gets you started quickly! + +## Prerequisites + +### Required Knowledge +- ✅ Basic Power Platform development experience +- ✅ Familiarity with Dataverse or Model-Driven Apps (helpful, but not required) +- ✅ Git/GitHub basics + +### Required Tools +- Power Platform admin account with CoE Starter Kit installed (or access to dev environment) +- Git installed locally +- Code editor (VS Code recommended) +- Power Platform CLI (optional, but helpful) + +## Quick Setup (15 minutes) + +### 1. Fork and Clone +```bash +# Fork the repository on GitHub first, then: +git clone https://github.com/YOUR-USERNAME/coe-starter-kit.git +cd coe-starter-kit +git checkout -b feature/connection-references-env-vars +``` + +### 2. Review Key Files +Navigate to the Core Components directory: +```bash +cd CenterofExcellenceCoreComponents/SolutionPackage/src +``` + +Key locations: +- **Entities**: `Entities/admin_ConnectionReference/` +- **Sitemap**: `AppModuleSiteMaps/admin_PowerPlatformAdminView/` +- **Views**: `Entities/admin_ConnectionReference/SavedQueries/` +- **Forms**: `Entities/admin_ConnectionReference/FormXml/` + +## Choose Your Contribution Path + +### Path A: Easy First Contribution (1-2 hours) +**Add Connection References Menu Item to Sitemap** + +#### What You'll Do +Add a new menu item to make Connection References easily accessible. + +#### Steps +1. Open `AppModuleSiteMaps/admin_PowerPlatformAdminView/AppModuleSiteMap.xml` +2. Find the "Connectors" SubArea (around line 25-29) +3. Add this code right after it: + +```xml +<SubArea Id="NewSubArea_ConnectionReferences" + VectorIcon="/WebResources/admin_ConnectorIcon" + Icon="/WebResources/admin_ConnectorIcon" + Entity="admin_connectionreference" + Client="All,Outlook,OutlookLaptopClient,OutlookWorkstationClient,Web" + AvailableOffline="true" + PassParams="false" + Sku="All,OnPremise,Live,SPLA"> + <Titles> + <Title LCID="1033" Title="Connection References" /> + </Titles> +</SubArea> +``` + +4. Save the file +5. Test by importing the solution to a dev environment +6. Commit and create a PR! + +```bash +git add . +git commit -m "Add Connection References menu item to Power Platform Admin View" +git push origin feature/connection-references-env-vars +``` + +### Path B: Intermediate Contribution (2-4 hours) +**Create Enhanced View for Connection References** + +#### What You'll Do +Create a better view that shows the right information about connection references. + +#### Steps +1. Navigate to `Entities/admin_ConnectionReference/SavedQueries/` +2. Generate a new GUID for your view: + - Online tool: https://www.uuidgenerator.net/ + - Or use: `New-Guid` in PowerShell +3. Create a new file: `{YOUR-NEW-GUID}.xml` +4. Copy this template: + +```xml +<?xml version="1.0" encoding="utf-8"?> +<savedqueries xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> + <savedquery> + <IsCustomizable>1</IsCustomizable> + <CanBeDeleted>1</CanBeDeleted> + <isquickfindquery>0</isquickfindquery> + <isprivate>0</isprivate> + <isdefault>1</isdefault> + <savedqueryid>{YOUR-NEW-GUID}</savedqueryid> + <layoutxml> + <grid name="resultset" jump="admin_displayname" select="1" icon="1" preview="1"> + <row name="result" id="admin_connectionreferenceid"> + <cell name="admin_displayname" width="200" /> + <cell name="admin_connector" width="150" /> + <cell name="ownerid" width="150" /> + <cell name="createdon" width="125" /> + </row> + </grid> + </layoutxml> + <querytype>0</querytype> + <fetchxml> + <fetch version="1.0" mapping="logical"> + <entity name="admin_connectionreference"> + <attribute name="admin_connectionreferenceid" /> + <attribute name="admin_displayname" /> + <attribute name="admin_connector" /> + <attribute name="ownerid" /> + <attribute name="createdon" /> + <order attribute="admin_displayname" descending="false" /> + <filter type="and"> + <condition attribute="statecode" operator="eq" value="0" /> + </filter> + </entity> + </fetch> + </fetchxml> + <IntroducedVersion>1.0</IntroducedVersion> + <LocalizedNames> + <LocalizedName description="Active Connection References" languagecode="1033" /> + </LocalizedNames> + </savedquery> +</savedqueries> +``` + +5. Test by importing to dev environment +6. Commit and create PR! + +### Path C: Advanced Contribution (1-2 days) +**Create Environment Variables Entity** + +#### What You'll Do +Build the new entity for tracking environment variables. + +#### Steps +1. Review the detailed entity structure in [Implementation Guide](./IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md) - Step 2.1 +2. Create directory: `Entities/admin_EnvironmentVariableDefinition/` +3. Create `Entity.xml` with the structure from the guide +4. Create sub-directories: + - `FormXml/main/` + - `FormXml/card/` + - `FormXml/quick/` + - `SavedQueries/` +5. Build forms and views following CoE patterns +6. Test thoroughly in dev environment +7. Document your changes +8. Create PR with screenshots! + +## Testing Your Changes + +### Local Testing (Before PR) +1. **Export the solution** from your CoE environment +2. **Apply your changes** to the exported solution files +3. **Re-import** to a test environment +4. **Verify**: + - Menu items appear correctly + - Views display expected data + - Forms load without errors + - No impact on existing functionality + +### What to Test +- [ ] Menu navigation works +- [ ] Views load and display data +- [ ] Forms open and save correctly +- [ ] Existing features still work +- [ ] No console errors +- [ ] Performance is acceptable + +## Creating Your Pull Request + +### PR Checklist +Before submitting, ensure: +- [ ] Code follows existing patterns in the repo +- [ ] XML is well-formed and indented consistently +- [ ] You've tested in a dev environment +- [ ] You've documented what you changed +- [ ] You've included screenshots if UI changes +- [ ] You've linked to the original issue + +### PR Template +```markdown +## Description +Brief description of what you implemented. + +## Changes Made +- Added Connection References menu item to sitemap +- Created new view showing [specific fields] +- Updated form to include [specific changes] + +## Testing Done +- Tested in dev environment with [X] connection references +- Verified menu navigation +- Confirmed no impact to existing features + +## Screenshots +[Add screenshots showing your changes] + +## Related Issue +Closes #[issue-number] + +## Checklist +- [ ] Code follows repository patterns +- [ ] Tested in dev environment +- [ ] Documentation updated (if needed) +- [ ] Screenshots included (if UI changes) +``` + +## Getting Help + +### Stuck? Here's What to Do + +**1. Check the Documentation** +- [Implementation Guide](./IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md) - Detailed technical steps +- [Feature Summary](./FEATURE-ENHANCEMENT-SUMMARY.md) - High-level overview + +**2. Look at Similar Code** +- Browse `Entities/admin_Flow/` for entity examples +- Check `Entities/admin_Connector/` for similar patterns +- Review existing views in any `SavedQueries/` folder + +**3. Ask Questions** +- Comment on the GitHub issue +- Post in Power Platform Community forums +- Tag @coe-starter-kit maintainers + +**4. Start Small** +- Begin with the sitemap menu item (easiest) +- Move to views (medium) +- Then tackle entity creation (advanced) + +## Common Patterns in CoE Starter Kit + +### Entity Naming +- Use `admin_` prefix for all custom entities +- Use PascalCase for entity names +- Example: `admin_ConnectionReference`, `admin_EnvironmentVariableDefinition` + +### Field Naming +- Use `admin_` prefix for custom fields +- Use lowercase for logical names +- Example: `admin_displayname`, `admin_schemaname` + +### GUID Generation +Always generate new GUIDs for: +- New entities +- New forms +- New views +- New fields + +Never reuse existing GUIDs! + +### XML Formatting +- Use 2 spaces for indentation (consistent with existing files) +- Close all tags properly +- Include XML declaration: `<?xml version="1.0" encoding="utf-8"?>` + +## Pro Tips + +### 1. Use a Dev Environment +Always test in a non-production environment first! + +### 2. Small PRs Are Better +Consider submitting multiple small PRs instead of one large one: +- PR 1: Sitemap changes +- PR 2: View updates +- PR 3: Entity creation + +This makes review easier and faster. + +### 3. Follow Existing Patterns +The CoE Starter Kit has established patterns. Copy existing code structure and modify rather than starting from scratch. + +### 4. Document Your Work +Add comments in your PR explaining: +- What you changed +- Why you made that choice +- Any trade-offs or limitations + +### 5. Screenshots Are Valuable +Include screenshots showing: +- Menu navigation +- View layout +- Form design +- Error messages (if debugging) + +## Contribution Timeline + +| Phase | What | When | Who | +|-------|------|------|-----| +| ✅ Analysis | Requirements & design | Complete | @copilot | +| 📝 Phase 1 | Connection References | Ready to start | You? | +| 📝 Phase 2 | Environment Variables | After Phase 1 | You? | +| ⏳ Testing | Validation & feedback | After implementation | Community | +| ⏳ Release | Include in CoE Kit | After testing | Maintainers | + +## Quick Reference Links + +### Documentation +- [Implementation Guide](./IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md) +- [Feature Summary](./FEATURE-ENHANCEMENT-SUMMARY.md) +- [GitHub Issue Response](./GITHUB-ISSUE-RESPONSE.md) + +### External Resources +- [CoE Starter Kit Docs](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) +- [Connection References Docs](https://learn.microsoft.com/en-us/power-apps/maker/data-platform/create-connection-reference) +- [Environment Variables Docs](https://learn.microsoft.com/en-us/power-apps/maker/data-platform/environmentvariables) +- [Dataverse Web API](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/overview) + +### Tools +- [GUID Generator](https://www.uuidgenerator.net/) +- [XML Formatter](https://www.freeformatter.com/xml-formatter.html) +- [Power Platform CLI](https://learn.microsoft.com/en-us/power-platform/developer/cli/introduction) + +## Ready to Start? + +1. Pick your contribution path (A, B, or C) +2. Set up your environment +3. Make your changes +4. Test thoroughly +5. Submit your PR +6. Celebrate! 🎉 + +Thank you for contributing to the CoE Starter Kit! Every contribution, no matter how small, helps the entire Power Platform community. + +--- + +**Questions?** Open an issue or comment on the feature request! +**Stuck?** Check the documentation or ask for help! +**Excited?** Let's build this together! 🚀 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..03eb962b8 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,218 @@ +# Connection References and Environment Variables Enhancement + +## Overview + +This directory contains comprehensive documentation for implementing enhanced Connection References and Environment Variables features in the CoE Starter Kit. + +## 📋 Documentation Index + +### For All Users +- **[Feature Enhancement Summary](FEATURE-ENHANCEMENT-SUMMARY.md)** ⭐ START HERE + - Executive overview of the enhancement + - Problem statement and proposed solutions + - Benefits and impact + - Architecture diagrams + - Q&A section + +### For Implementers +- **[Implementation Guide](IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md)** 📖 TECHNICAL DETAILS + - Step-by-step implementation instructions + - Code examples with file locations + - API integration details + - Testing procedures + - Migration path for existing deployments + +- **[Quick Start Guide for Contributors](QUICK-START-GUIDE-CONTRIBUTORS.md)** 🚀 GET STARTED + - 15-minute setup guide + - Three contribution paths (Easy/Intermediate/Advanced) + - Code templates ready to use + - Testing checklist + - PR guidelines + +### For Community Discussion +- **[GitHub Issue Response](GITHUB-ISSUE-RESPONSE.md)** 💬 COMMUNITY + - Response to the original feature request + - How to get involved + - Support resources + +## 🎯 Quick Navigation + +### I want to... + +**Understand what this is about** +→ Read [Feature Enhancement Summary](FEATURE-ENHANCEMENT-SUMMARY.md) + +**Implement Connection References enhancements** +→ See [Implementation Guide - Phase 1](IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md#phase-1-enhanced-connection-references-estimated-2-3-days) + +**Implement Environment Variables tracking** +→ See [Implementation Guide - Phase 2](IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md#phase-2-environment-variables-implementation-estimated-3-5-days) + +**Make my first contribution** +→ Follow [Quick Start Guide - Path A](QUICK-START-GUIDE-CONTRIBUTORS.md#path-a-easy-first-contribution-1-2-hours) + +**Review the original issue** +→ See the [GitHub Issue](https://github.com/microsoft/coe-starter-kit/issues/) + +## 📊 Feature Status + +| Component | Status | Estimated Effort | +|-----------|--------|------------------| +| Analysis & Design | ✅ Complete | - | +| Documentation | ✅ Complete | - | +| Connection References - Sitemap | 📝 Ready to implement | 1-2 hours | +| Connection References - Views | 📝 Ready to implement | 2-4 hours | +| Connection References - Forms | 📝 Ready to implement | 2-4 hours | +| Connection References - Inventory | 📝 Ready to implement | 4-8 hours | +| Environment Variables - Entity | 📝 Ready to implement | 1-2 days | +| Environment Variables - Views/Forms | 📝 Ready to implement | 1 day | +| Environment Variables - Inventory | 📝 Ready to implement | 1-2 days | +| Testing & Validation | ⏳ After implementation | 1-2 days | + +## 🏗️ Implementation Phases + +### Phase 1: Connection References (2-3 days) +Enhance existing Connection References entity with: +- ✅ Dedicated menu item +- ✅ Accurate display names +- ✅ Correct owner information +- ✅ Solution relationships + +### Phase 2: Environment Variables (3-5 days) +Create new tracking capability for: +- ✅ Environment Variable Definitions +- ✅ Schema names and types +- ✅ Current and default values +- ✅ Owner information +- ✅ Solution relationships +- ✅ Owner reassignment + +### Phase 3: Testing & Documentation (1-2 days) +- Comprehensive testing +- User documentation +- Release notes + +## 🎯 Success Criteria + +### Connection References +- ✅ Accessible in ≤2 clicks from main menu +- ✅ 100% accuracy in display names +- ✅ 100% accuracy in owner information +- ✅ Solution relationships visible + +### Environment Variables +- ✅ Complete inventory across all environments +- ✅ All metadata fields captured +- ✅ Owner reassignment enabled +- ✅ Performance acceptable for large datasets + +## 🤝 How to Contribute + +### Prerequisites +- Power Platform development experience +- Git/GitHub basics +- Access to CoE Starter Kit environment (or dev environment) + +### Getting Started +1. Read the [Quick Start Guide](QUICK-START-GUIDE-CONTRIBUTORS.md) +2. Choose your contribution path +3. Fork the repository +4. Make your changes +5. Test thoroughly +6. Submit a pull request + +### Contribution Paths + +**Path A: Easy (1-2 hours)** 🟢 +- Add menu items to sitemap +- Update simple XML configurations + +**Path B: Intermediate (2-4 hours)** 🟡 +- Create enhanced views +- Update forms +- Modify existing entities + +**Path C: Advanced (1-2 days)** 🔴 +- Create new entities +- Build inventory flows +- Implement API integrations + +## 📚 Related Resources + +### Microsoft Documentation +- [CoE Starter Kit](https://learn.microsoft.com/en-us/power-platform/guidance/coe/starter-kit) +- [Connection References](https://learn.microsoft.com/en-us/power-apps/maker/data-platform/create-connection-reference) +- [Environment Variables](https://learn.microsoft.com/en-us/power-apps/maker/data-platform/environmentvariables) +- [Dataverse Web API](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/overview) + +### Community Resources +- [CoE Starter Kit GitHub](https://github.com/microsoft/coe-starter-kit) +- [Power Platform Community](https://powerusers.microsoft.com/) +- [Power Platform Governance Forum](https://powerusers.microsoft.com/t5/Power-Apps-Governance-and/bd-p/Admin_PowerApps) + +## ❓ Frequently Asked Questions + +### Will this break existing CoE Starter Kit deployments? +No. All changes are backward compatible and additive. + +### Do I need to reinstall the entire CoE Starter Kit? +No. These features will be delivered as incremental updates. + +### What if I've customized admin_ConnectionReference? +Your customizations will be preserved. New fields are additive. + +### How do I test my changes? +Follow the testing procedures in the [Quick Start Guide](QUICK-START-GUIDE-CONTRIBUTORS.md#testing-your-changes). + +### Where do I ask questions? +- Comment on the GitHub issue +- Post in Power Platform Community forums +- Reach out to CoE Starter Kit maintainers + +## 📝 Document Change Log + +| Date | Document | Changes | +|------|----------|---------| +| 2024-12 | All | Initial documentation created | + +## 🙏 Acknowledgments + +- **Original Request**: @rooobeert +- **Analysis & Documentation**: CoE Starter Kit Community +- **Future Contributors**: You! 🎉 + +## 📞 Support + +### Getting Help +- Review the documentation in this directory +- Check the [Implementation Guide](IMPLEMENTATION-GUIDE-CONNECTION-REFERENCES-ENV-VARS.md) for technical details +- Ask questions on the GitHub issue +- Post in Power Platform Community forums + +### Reporting Issues +If you find problems with the documentation: +1. Open a GitHub issue +2. Tag with `documentation` label +3. Reference the specific document and section + +### Contributing Improvements +Documentation improvements are welcome! Follow the same PR process as code contributions. + +--- + +## 🚀 Let's Build This Together! + +This is a community-driven enhancement. Whether you're a Power Platform expert or just getting started, there's a way for you to contribute. + +**Ready to start?** +1. Read the [Feature Summary](FEATURE-ENHANCEMENT-SUMMARY.md) +2. Check out the [Quick Start Guide](QUICK-START-GUIDE-CONTRIBUTORS.md) +3. Pick a task and get started! + +Every contribution matters. Thank you for helping improve the CoE Starter Kit! 🙌 + +--- + +**Last Updated**: December 2024 +**Status**: Ready for Implementation +**Maintainers**: CoE Starter Kit Community