Using Invoke-MgGraphRequest to Archive a Team

Archiving a Microsoft Team is an essential task when managing inactive teams that you may want to preserve for historical reference without allowing further modifications. Although there is a dedicated Graph API endpoint for archiving a team, you can also accomplish this task using the Invoke-MgGraphRequest cmdlet in Graph PowerShell, which allows you to send custom Graph API requests directly. In this article, we’ll explore how to use this versatile cmdlet to archive a team with specific examples, tips, common errors, and best practices.

Cmdlet Syntax for Archiving a Team

Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/teams/{teamId}/archive" -Body @{}

• -Method: Specifies the HTTP method (POST in this case).
• -Uri: The full API URL where {teamId} is replaced with the ID of the team you want to archive.
• -Body: Although the body is technically empty for this API call, the -Body parameter is required and should contain an empty hashtable @{}.

Usage Examples

Example 1: Archiving a Single Team

$teamId = "0e984fab-a9d5-4bc1-97c2-623fb344f3d4"
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/teams/$teamId/archive" -Body @{}

This command archives the team, making it read-only for members while still retaining its content and files.

Example 2: Bulk Archiving Multiple Teams

$teams = Import-Csv -Path "C:\TeamsToArchive.csv"
foreach ($team in $teams) {
    $teamId = $team.TeamId
    Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/teams/$teamId/archive" -Body @{}
    Write-Host "Team with ID $teamId has been archived."
}

This script reads team IDs from a CSV file (with a column named TeamId) and archives each team in the list.

Cmdlet Tips

• Required Permissions: Ensure you have the necessary permissions. The Teamwork.MicrosoftTeams.Archive permission is needed to archive a team. Running this cmdlet without the right permissions will result in an error.
• Archiving Impact: Once a team is archived, it becomes read-only. Members can still access the content but cannot edit or post new messages. Owners can restore the team from the archived state if needed.
• Efficient for Custom Actions: Using Invoke-MgGraphRequest for archiving is beneficial when you need custom or batch operations that the dedicated cmdlet (Set-MgTeam) might not support directly.
• Real-Time Status: The archive process may take some time. There is no immediate indication if the team has been successfully archived when using this method. However, you can query the team's status to confirm the archive state after the request completes.

Possible Errors & Solutions

Error	Cause	Solution
Permission Denied	Insufficient privileges to complete the operation.	Ensure the user has the Teamwork.MicrosoftTeams.Archive permission assigned. You may need to request permissions from your Azure AD administrator or use a service principal with the correct permissions.
Invalid Team ID	The team ID provided does not exist or is incorrect.	Double-check the team ID by listing all teams using Get-MgTeam | Select-Object Id, DisplayName.
The Team Is Already Archived	You’re attempting to archive a team that is already archived.	Verify the team's status using the Get-MgTeam cmdlet and ensure that it is not already archived.

Use Cases

• Project-Based Teams: In organizations where teams are created for specific projects, archiving is a useful way to retain the content after a project’s completion without cluttering the active team space. This reduces unnecessary notifications and enables easier access to critical historical data.
• Compliance and Retention: Teams related to sensitive subjects like legal or HR investigations may need to be archived after they are no longer active. Archiving ensures the content remains intact for future reference but no further modifications can be made.
• Bulk Archival for Organizational Cleanup: Automating the archival of outdated teams using Invoke-MgGraphRequest ensures that teams are properly managed, improving performance and usability in the long run.

Conclusion

The Invoke-MgGraphRequest cmdlet is an excellent tool for making custom Graph API calls such as archiving a Microsoft Team. It allows administrators to manage teams effectively, especially in cases where built-in cmdlets may not provide the flexibility needed. This cmdlet is highly useful in scenarios involving custom workflows, bulk operations, or managing complex actions like archiving across multiple teams.

By following the examples and tips provided in this article, you can streamline your team's lifecycle management, automate the archival process, and avoid common pitfalls. Whether you're archiving individual teams or managing a large number of them in bulk, Invoke-MgGraphRequest offers a powerful and efficient solution.