Public/Get-SCOMGroupMember.ps1
|
function Get-SCOMGroupMember { <# .SYNOPSIS Retrieves all members of a specified SCOM (System Center Operations Manager) group. .DESCRIPTION The Get-SCOMGroupMember function allows you to retrieve all monitoring objects that are members of a specified SCOM group. You can search for the group either by its display name or by its unique identifier (GUID). The function automatically imports the OperationsManager PowerShell module if it's not already loaded and provides comprehensive error handling. This function is particularly useful for: - Auditing group memberships - Troubleshooting group-based monitoring rules - Generating reports on group contents - Bulk operations on group members .PARAMETER DisplayName Specifies the display name of the SCOM group whose members you want to retrieve. This parameter is mandatory when using the 'ByDisplayName' parameter set. Type: String Required: True (when using ByDisplayName parameter set) Aliases: Name .PARAMETER Id Specifies the unique identifier (GUID) of the SCOM group whose members you want to retrieve. This parameter is mandatory when using the 'ById' parameter set. Type: String Required: True (when using ById parameter set) .EXAMPLE Get-SCOMGroupMember -DisplayName "All Windows Computers" Description: Retrieves all members of the SCOM group named "All Windows Computers". This will return all Windows computer objects that are members of this group. Output: Returns a collection of MonitoringObject instances representing all computers in the group. .EXAMPLE Get-SCOMGroupMember -Name "SQL Server Computers" Description: Uses the alias 'Name' instead of 'DisplayName' to retrieve members of the "SQL Server Computers" group. This demonstrates the flexibility of parameter aliases. Output: Returns all SQL Server computer objects that are members of the specified group. .EXAMPLE Get-SCOMGroupMember -Id "12345678-1234-1234-1234-123456789012" Description: Retrieves group members using the group's unique identifier (GUID). This method is more precise when you know the exact GUID of the group and want to avoid any ambiguity with display names. Output: Returns all monitoring objects that are members of the group with the specified GUID. .EXAMPLE $members = Get-SCOMGroupMember -DisplayName "Database Servers" $members | Select-Object DisplayName, HealthState, Path | Format-Table -AutoSize Description: Retrieves members of the "Database Servers" group and displays their key properties in a formatted table. This example shows how to work with the returned objects to extract useful information. Output: A formatted table showing the DisplayName, HealthState, and Path of each group member. .EXAMPLE $groupMembers = Get-SCOMGroupMember -DisplayName "Web Servers" Write-Host "Found $($groupMembers.Count) members in the Web Servers group" foreach ($member in $groupMembers) { Write-Host " - $($member.DisplayName) [$($member.HealthState)]" } Description: Demonstrates how to iterate through group members and display detailed information about each member, including their health state. This is useful for monitoring and reporting purposes. Output: Console output showing the count of group members and detailed information about each member. .EXAMPLE try { $criticalServers = Get-SCOMGroupMember -DisplayName "Critical Infrastructure" $unhealthyServers = $criticalServers | Where-Object { $_.HealthState -ne "Success" } if ($unhealthyServers) { Write-Warning "Found $($unhealthyServers.Count) unhealthy servers in Critical Infrastructure group" $unhealthyServers | Format-Table DisplayName, HealthState, LastModified -AutoSize } } catch { Write-Error "Failed to check critical infrastructure health: $($_.Exception.Message)" } Description: Advanced example showing how to use the function for health monitoring. This retrieves members of a critical infrastructure group and identifies any servers that are not in a healthy state. Output: Warning message and table of unhealthy servers if any are found, or no output if all servers are healthy. .INPUTS String You can pipe a string containing the display name of a SCOM group to this function. .OUTPUTS Microsoft.EnterpriseManagement.Monitoring.MonitoringObject[] Returns an array of MonitoringObject instances representing the members of the specified group. Each object contains properties such as DisplayName, HealthState, Path, Id, and LastModified. .NOTES ==================================================================== Created with: Visual Studio Code Author: Tyson Paul Created: 2025.09.08 Last Modified: 2025.09.08 Version: 1.0 Blog: https://monitoringguys.com ==================================================================== Requirements: - System Center Operations Manager PowerShell module (OperationsManager) - Appropriate permissions to read SCOM groups and their members - Active connection to a SCOM Management Group Error Handling: - Validates that the OperationsManager module can be imported - Checks if the specified group exists before attempting to retrieve members - Provides detailed error messages for troubleshooting Performance Considerations: - Large groups may take longer to process - Consider filtering results for very large groups to improve performance - The function loads all group members into memory at once Related Commands: - Get-SCOMGroup: Retrieves SCOM groups - Get-SCOMMonitoringObject: Retrieves individual monitoring objects - Add-SCOMGroupMember: Adds members to a SCOM group - Remove-SCOMGroupMember: Removes members from a SCOM group .LINK https://monitoringguys.com/2019/11/12/scomhelper/ .LINK https://monitoringguys.com #> [CmdletBinding()] param ( [Parameter(Mandatory = $true, ParameterSetName = 'ByDisplayName')] [Alias('Name')] [string]$DisplayName, [Parameter(Mandatory = $true, ParameterSetName = 'ById')] [string]$Id ) # Import the OperationsManager module if not already imported try { if (-not (Get-Module -Name OperationsManager)) { Import-Module OperationsManager -ErrorAction Stop } } catch { Write-Error "Failed to import OperationsManager module: $($_.Exception.Message)" return } # Get the SCOM group based on parameter set try { if ($PSCmdlet.ParameterSetName -eq 'ByDisplayName') { $group = Get-SCOMGroup -DisplayName $DisplayName -ErrorAction Stop if ($null -eq $group) { Write-Error "Group with DisplayName '$DisplayName' not found." return } } elseif ($PSCmdlet.ParameterSetName -eq 'ById') { $group = Get-SCOMGroup -Id $Id -ErrorAction Stop if ($null -eq $group) { Write-Error "Group with Id '$Id' not found." return } } } catch { Write-Error "Failed to retrieve SCOM group: $($_.Exception.Message)" return } If ($group) { $members = $group.GetRelatedMonitoringObjects() return $members } } |