PowerShell

Manage Microsoft Teams With Graph PowerShell

Managing Microsoft Teams effectively is a critical task for IT administrators. This PowerShell script leverages the Microsoft Graph API to offer an interactive console-based solution, allowing admins to perform core Teams management tasks - listing teams, creating a team, updating a team, and deleting a team - all from the command line.

The Script:


    # Microsoft Graph API connection
    Connect-MgGraph -Scopes "Group.ReadWrite.All", "User.Read.All"
    Write-Host "Connected to Microsoft Graph"

    function List-Teams {
        Write-Host "Fetching all Teams in the organization..."
        $teams = Get-MgGroup -Filter "resourceProvisioningOptions/Any(x:x eq 'Team')"
        $teams | ForEach-Object {
        Write-Host "Team Name: $($_.DisplayName) - ID: $($_.Id)"
    }
    }

    function Create-Team {
        Write-Host "Creating a new team..."
        $displayName = Read-Host "Enter the name of the new Team"
        $description = Read-Host "Enter a description for the new Team"
        $mailNickName = Read-Host "Enter the mail nickname for the Team"
        $visibility = Read-Host "Enter the visibility (Public or Private)"

        $teamParams = @{
        DisplayName = $displayName
        Description = $description
        MailNickname = $mailNickName
        Visibility = $visibility
        GroupTypes = @("Unified")
        MailEnabled = $true
        SecurityEnabled = $false
        }

        $newTeam = New-MgGroup -BodyParameter $teamParams
        Write-Host "Team '$displayName' created successfully with ID: $($newTeam.Id)"
    }

    function Update-Team {
        Write-Host "Updating an existing team..."
        $teamId = Read-Host "Enter the ID of the Team you want to update"
        $newName = Read-Host "Enter the new name for the Team (leave blank to skip)"
        $newDescription = Read-Host "Enter the new description for the Team (leave blank to skip)"

        $updateParams = @{}
        if ($newName) { $updateParams.DisplayName = $newName }
        if ($newDescription) { $updateParams.Description = $newDescription }

        if ($updateParams.Count -gt 0) {
        Update-MgGroup -GroupId $teamId -BodyParameter $updateParams
        Write-Host "Team updated successfully."
        } else {
        Write-Host "No updates were made."
        }
    }

    function Delete-Team {
        Write-Host "Deleting a team..."
        $teamId = Read-Host "Enter the ID of the Team you want to delete"
        $confirmation = Read-Host "Are you sure you want to delete this Team? (y/n)"
        if ($confirmation -eq "y") {
        Remove-MgGroup -GroupId $teamId -Confirm:$false
        Write-Host "Team deleted successfully."
        } else {
        Write-Host "Team deletion canceled."
        }
    }

    # Main Script Loop
    while ($true) {
        Write-Host "`nChoose an action:"
        Write-Host "1. List Teams"
        Write-Host "2. Create a Team"
        Write-Host "3. Update a Team"
        Write-Host "4. Delete a Team"
        Write-Host "5. Exit"
        $choice = Read-Host "Enter the number corresponding to your choice"

        switch ($choice) {
        "1" { List-Teams }
        "2" { Create-Team }
        "3" { Update-Team }
        "4" { Delete-Team }
        "5" { Write-Host "Exiting..."; break }
        default { Write-Host "Invalid choice, please try again." }
        }
    }

    # Disconnect from Microsoft Graph
    Disconnect-MgGraph
    Write-Host "Disconnected from Microsoft Graph"

See the Script in Action by clicking and playing this GIF:

How the Script Works

This script provides an interactive way for administrators to manage Microsoft 365 Teams. Here's how each function works:

Connect to Microsoft Graph: The script begins by connecting to the Microsoft Graph API with Group.ReadWrite.All and User.Read.All permissions.
List-Teams: Fetches all teams by filtering Groups with the resourceProvisioningOptions value of "Team."
Create-Team: Gathers details such as the team’s name, description, mail nickname, and visibility from the user, then creates a new team using New-MgGroup.
Update-Team: Allows updating of a team’s name and description by collecting inputs, preparing a parameter hash, and updating the specified team.
Delete-Team: Prompts the user for confirmation, then deletes the selected team if confirmed.
Main Menu: Runs an interactive console menu, allowing the user to choose an action until they exit the script.

Further Enhancements

There are several ways to further enhance this script for more robust Microsoft 365 Teams management:

Error Handling: Implement more detailed error-catching mechanisms to handle API connectivity issues or permissions errors gracefully.
Role-Based Access Control: Limit team creation, update, or delete options based on user role to ensure security.
Bulk Operations: Extend the script to allow bulk team creation, updates, or deletions via CSV import to streamline mass management.
Logging: Add logging functionality to capture each operation's details for audit and compliance purposes.

Possible Errors & Solutions

AuthenticationFailed

Cause: Insufficient permissions or expired authentication.
Solution: Ensure your account has Group.ReadWrite.All and User.Read.All permissions. Re-authenticate if needed.

Not Found in Listing or Updating

Cause: The specified team ID doesn’t exist.
Solution: Verify the team ID using the List-Teams function and try again.

Invalid Request on Creation

Cause: Incorrect or missing team properties, such as mail nickname or display name.
Solution: Double-check input fields (e.g., MailNickname must be unique) and try again.

Conclusion

This PowerShell script provides a robust foundation for managing Microsoft Teams interactively through Microsoft Graph API. It simplifies listing, creating, updating, and deleting Teams, enhancing administrative control and efficiency. Future customizations like bulk operations, role-based access, and logging can elevate the script further, making it a powerful tool for scalable Teams management.