Deep-Dive: New $expand Support on TeamworkSection Items in Microsoft Graph

Microsoft has made an important update to the Graph API: the $expand query option is now supported on the items relationship for both list and get operations on teamworkSection resources. This enhancement impacts how admins and developers can retrieve and analyze section contents within Teams, improving data access and automation possibilities for Entra ID-managed environments.

WHAT’S CHANGING

The $expand query parameter can now be used with the items relationship on teamworkSection endpoints:

• GET: Retrieve a single teamworkSection and expand its items.
• LIST: Enumerate teamworkSections with expanded items.

System-defined sections (e.g., “General”) will return an empty items array; their contents aren’t exposed via public Graph API.

This feature is available in Graph beta as of June 2024. Production roll-out timing remains subject to future announcements.

WHO’S AFFECTED

• Tenants with Teams deployed and users leveraging sectioned organization (e.g., planners, document libraries).
• Admins with delegated permissions (Directory.Read.All, Teamwork.Read.All) or app registrations with proper Graph scopes.
• Developers integrating Teams section data into workflows, reporting, or automation.
• Any Entra admin tracking resource lifecycle, guest access, or team content management.

WHY IT MATTERS

This update provides:

• Efficiency: Retrieve a teamworkSection and its items in a single query, reducing API calls and complexity.
• Visibility: Improved ability to audit, report, or automate content and permissions within Teams sections.
• Integration: Opens possibilities for richer PowerShell/Graph automation, onboarding, and governance tools.

However, system-defined sections (like “General”) will not expose contents, limiting full coverage for some scenarios.

WHAT TO DO

1. Review App Permissions: Ensure your delegated or app permissions cover Teamwork.Read.All or similar.
2. Update Automation: Modify scripts or workflows to leverage $expand for optimized section-item retrieval.
3. Educate Stakeholders: Notify developers and process owners about new possibilities and limitations (system sections).
4. Audit Usage: Identify existing team sections and test $expand queries for item visibility.
5. Monitor Beta Changes: Track Graph beta release notes for potential production API changes or deprecations.

CHECK IT YOURSELF

Use PowerShell with the modern Microsoft.Graph module (beta endpoint) to audit teamworkSections and their items. This script retrieves all teamworkSections in your tenant, expands items, handles pagination, and reports empty item arrays for system-defined sections. It includes error handling and never modifies data.

# Requires Microsoft.Graph v2.x and beta endpoint
Connect-MgGraph -Scopes 'Teamwork.Read.All' -Environment 'Global' -NoWelcome
$headers = @{ 'ConsistencyLevel' = 'eventual' }
$uri = 'https://graph.microsoft.com/beta/me/teamwork/teamworkSections?$expand=items'

function Get-TeamworkSectionsWithItems {
    [CmdletBinding()]
    param()
    $results = @()
    try {
        $response = Invoke-MgGraphRequest -Uri $uri -Method GET -Headers $headers
        $results += $response.value
        while ($response.'@odata.nextLink') {
            $response = Invoke-MgGraphRequest -Uri $response.'@odata.nextLink' -Method GET -Headers $headers
            $results += $response.value
        }
    } catch {
        Write-Warning "Failed to query teamworkSections: $_"
    }
    foreach ($section in $results) {
        $itemsCount = ($section.items | Measure-Object).Count
        Write-Output "Section: $($section.displayName) | Items: $itemsCount"
        if ($itemsCount -eq 0) {
            Write-Output "  (System-defined or empty section)"
        } else {
            foreach ($item in $section.items) {
                Write-Output "    - Item: $($item.displayName)"
            }
        }
    }
}

Get-TeamworkSectionsWithItems

Notes: Replace me with a specific user or team ID as needed. This script is read-only and safe for production audits.

PORTAL PATH

To view teamworkSections in the admin center:

• Go to Microsoft Entra admin center → Azure Active Directory → Enterprise Applications → Microsoft Teams.
• Browse Teams → Manage team settings → Sections.
  (Note: Item-level visibility may not reflect API $expand results; use PowerShell/Graph for detailed auditing.)

BOTTOM LINE

• Prioritize updating automation and auditing scripts to leverage $expand for teamworkSection items.
• Inform developers and governance owners of new data access capabilities and limitations on system-defined sections.
• Monitor Graph beta for updates and prepare for potential wider rollout.