QUICKSTART.txt
|
╔═══════════════════════════════════════════════════════════════════════════════╗
║ ║ ║ 🎉 MODULE COMPLETED 🎉 ║ ║ ║ ║ M365PlannerPro v1.0.0 ║ ║ Advanced Microsoft Planner Management with PowerShell ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════╝ 📦 MODULE CONTENTS ═══════════════════════════════════════════════════════════════════════════════ ✅ 6 Core Functions Implemented: 1. Copy-M365PPlan - Complete plan cloning 2. Export-M365PPlan - Backup/export plan to JSON/XML 3. Import-M365PPlan - Restore/import plan from JSON/XML 4. Import-M365PTasksFromCsv - Bulk import from CSV 5. Get-M365PUserWorkload - Workload reporting 6. Update-M365PTaskSmart - Safe updates with ETags ✅ Complete Documentation: • README.md - Complete guide with examples • CHANGELOG.md - Version history • STRUCTURE.md - Project structure • Examples.ps1 - Practical usage examples • Tests.ps1 - Unit tests with Pester ✅ Utilities: • Install.ps1 - Automated installation script • example-tasks.csv - Sample CSV for testing • .gitignore - Git configuration 🎯 KEY TECHNICAL FEATURES ═══════════════════════════════════════════════════════════════════════════════ ✨ Automatic Concurrency Control (ETags) └─ All updates/deletions implement: • Automatic Get of object to retrieve ETag • Pass ETag to -IfMatch parameter • Retry logic for 412 (Precondition Failed) errors • Exponential backoff between retries ✨ PowerShell Best Practices • Verb-Noun naming standard • Complete Comment-Based Help with examples • Pipeline support (ValueFromPipeline) • Parameter validation (ValidateRange, ValidateScript) • ShouldProcess support (WhatIf/Confirm) • Comprehensive verbose logging • Robust error handling with try/catch ✨ Performance Optimizations • Bucket caching in bulk imports • User caching for assignments • Batch operations when possible • Automatic pagination with -All 📊 PROJECT STATISTICS ═══════════════════════════════════════════════════════════════════════════════ Total Files: 14 files Total Size: ~100 KB Lines of Code: ~1,500 lines Public Functions: 6 functions Unit Tests: 30+ tests Examples: 15+ examples 🚀 HOW TO GET STARTED ═══════════════════════════════════════════════════════════════════════════════ 1️⃣ INSTALL THE MODULE Option A: Complete Installation (Recommended) ─────────────────────────────────────────────────────────────────────────── cd <ModuleDirectory> .\Install.ps1 -InstallToUserModules -TestConnection Option B: Direct Import (Testing) ─────────────────────────────────────────────────────────────────────────── Import-Module ".\M365PlannerPro\M365PlannerPro.psd1" -Force 2️⃣ CONNECT TO MICROSOFT GRAPH Connect-MgGraph -Scopes "Group.Read.All","Tasks.ReadWrite","User.Read.All" 3️⃣ VERIFY AVAILABLE FUNCTIONS Get-Command -Module M365PlannerPro 4️⃣ GET HELP Get-Help Copy-M365PPlan -Full Get-Help Export-M365PPlan -Examples Get-Help Import-M365PPlan -Examples Get-Help Import-M365PTasksFromCsv -Examples Get-Help Get-M365PUserWorkload -Detailed Get-Help Update-M365PTaskSmart -Full 5️⃣ RUN EXAMPLES . ".\Examples.ps1" 📚 QUICK EXAMPLES ═══════════════════════════════════════════════════════════════════════════════ # Clone a plan ─────────────────────────────────────────────────────────────────────────── Copy-M365PPlan -SourceGroupId "abc-123" ` -SourcePlanId "plan-456" ` -DestinationGroupId "xyz-789" ` -NewPlanTitle "Q1 2026 Project" # Export a plan to a JSON file ─────────────────────────────────────────────────────────────────────────── Export-M365PPlan -PlanId "plan-123" ` -OutputPath "C:\Backups\plan-backup.json" # Import a plan from a JSON file ─────────────────────────────────────────────────────────────────────────── Import-M365PPlan -InputPath "C:\Backups\plan-backup.json" ` -GroupId "group-456" ` -PlanTitle "Restored Plan" # Import tasks from CSV ─────────────────────────────────────────────────────────────────────────── Import-M365PTasksFromCsv -PlanId "plan-123" ` -CsvPath ".\example-tasks.csv" ` -GroupId "group-456" # Get workload report ─────────────────────────────────────────────────────────────────────────── Get-M365PUserWorkload | Sort-Object TotalTasks -Descending | Export-Csv "workload-report.csv" # Update task safely ─────────────────────────────────────────────────────────────────────────── Update-M365PTaskSmart -TaskId "task-123" ` -PercentComplete 100 ` -Priority 1 # Bulk update with pipeline ─────────────────────────────────────────────────────────────────────────── Get-MgPlannerPlanTask -PlannerPlanId "plan-123" -All | Where-Object { $_.Title -like "*Review*" } | ForEach-Object { Update-M365PTaskSmart -TaskId $_.Id -PercentComplete 100 } 🧪 RUN TESTS ═══════════════════════════════════════════════════════════════════════════════ # Install Pester (if not installed) Install-Module Pester -Force -SkipPublisherCheck # Run all tests cd <ModuleDirectory> Invoke-Pester .\Tests.ps1 -Output Detailed # Run only basic tests (without Graph connection) Invoke-Pester .\Tests.ps1 -ExcludeTag Integration 📖 AVAILABLE DOCUMENTATION ═══════════════════════════════════════════════════════════════════════════════ 📄 README.md Complete module guide with examples 📄 CHANGELOG.md Version history and roadmap 📄 STRUCTURE.md Detailed project structure 📄 Examples.ps1 Practical commented examples 📄 Tests.ps1 Unit test suite Open documentation: code ".\README.md" 🔧 REQUIREMENTS ═══════════════════════════════════════════════════════════════════════════════ ✓ PowerShell 7.0 or higher ✓ Microsoft.Graph.Planner module (v2.0.0+) ✓ Graph Permissions: Group.Read.All, Tasks.ReadWrite, User.Read.All 🎨 MAIN USE CASES ═══════════════════════════════════════════════════════════════════════════════ ✅ Project migration between teams ✅ Bulk task onboarding from templates ✅ Workload auditing ✅ Bulk date/priority updates ✅ Planner workflow automation ✅ Productivity reporting 🛡️ ETAG CONCURRENCY CONTROL ADVANTAGES ═══════════════════════════════════════════════════════════════════════════════ ❌ Problem without ETags: User A and User B read task → User A updates → User B updates = User A's changes are lost (race condition) ✅ Solution with ETags (implemented in this module): User A and User B read task (with ETags) → User A updates ✓ → User B tries to update → 412 Error → Retries → Updates ✓ = Both changes are preserved correctly 🌟 UNIQUE FEATURES ═══════════════════════════════════════════════════════════════════════════════ ⚡ AUTOMATIC - ETag control without manual intervention 🔄 RESILIENT - Retry logic with exponential backoff 📝 TRACEABLE - Verbose logging of all operations 🧩 MODULAR - Independent and reusable functions 🎯 PROFESSIONAL - Follows all PowerShell best practices 📦 COMPLETE - Includes documentation, tests and examples 📞 SUPPORT AND HELP ═══════════════════════════════════════════════════════════════════════════════ If you encounter issues or have questions: 1. Review README.md for complete documentation 2. Run Get-Help <Function> -Full for function help 3. Review Examples.ps1 for practical use cases 4. Run with -Verbose for detailed diagnostics 5. Review Tests.ps1 to validate installation ✨ SUGGESTED NEXT STEP ═══════════════════════════════════════════════════════════════════════════════ cd <ModuleDirectory> .\Install.ps1 -InstallToUserModules -TestConnection ═══════════════════════════════════════════════════════════════════════════════ 🎉 CONGRATULATIONS! You have a professional PowerShell module ready for production use. 💡 TIP: Start with the Examples.ps1 file to see all use cases in action. ⭐ REMEMBER: All functions implement automatic concurrency control with ETags - no more race conditions! ═══════════════════════════════════════════════════════════════════════════════ Created with ❤️ for the PowerShell community © 2026 Microsoft Planner Pro Team |