Understanding and Using Get-CMCollection and Set-CMCollection in SCCM

A comprehensive guide to managing SCCM collections with PowerShell cmdlets

Key Takeaways

• Cmdlets Overview: Learn how Get-CMCollection retrieves collections and how Set-CMCollection modifies collection properties.
• Usage and Best Practices: Understand the prerequisites, module loading, and permissions required for executing these commands in an SCCM environment.
• Detailed Operations: Explore various approaches and parameters including renaming collections, updating limiting collections, and scheduling collection refreshes.

Introduction

In System Center Configuration Manager (SCCM), managing collections of users or devices is a crucial task for IT administrators. Two of the key PowerShell cmdlets used for this purpose are Get-CMCollection and Set-CMCollection. The former is used for retrieving and displaying the details of collections, while the latter is used for modifying various properties associated with a collection. These are essential for automating routine tasks, ensuring consistency, and keeping the configuration management environment up to date.

Understanding Get-CMCollection

The Get-CMCollection cmdlet is designed to fetch device or user collection objects. It plays a vital role in organizing resources within SCCM, allowing administrators to view current collection details and perform operations on them. By retrieving these collections, administrators can review settings, verify membership criteria, and audit system configurations.

Key Features

When using Get-CMCollection, you can retrieve:

• Single Collection Details: By specifying parameters such as the collection name or ID, you can quickly find a specific collection.
• All Collections: If no filter parameters are provided, the cmdlet will list all available collections, making it particularly useful in large environments.
• Specialized Collections: Versions of the cmdlet, like Get-CMDeviceCollection or Get-CMUserCollection, are tailored to different resource types.

Usage Scenarios

Typical scenarios where Get-CMCollection is useful include:

• Auditing and Reporting: Administrators can extract details about collections to review membership, applied queries, and configuration settings.
• Scripting and Automation: In combination with other cmdlets, Get-CMCollection is essential for automating bulk operations such as modifying properties or implementing change tracking across collections.
• Environment Overview: Quickly obtaining a list of collections helps provide a snapshot of how resources are organized and managed in the SCCM database.

Example Usage

Here is a practical example of how to retrieve a collection by name:

# Retrieve a user or device collection by its name
Get-CMCollection -Name "Test Collection"
  

You can also search for a collection using its unique identifier:

# Retrieve a collection by its Collection ID
Get-CMCollection -CollectionId "XYZ00001"
  

Understanding Set-CMCollection

The Set-CMCollection cmdlet is used to update and configure properties of an existing collection. Whether you want to rename a collection or update its limiting settings, refresh schedules, or other attributes, this command offers the flexibility to modify the collection to meet current administrative requirements.

Key Modifications

Some of the primary modifications using Set-CMCollection include:

• Renaming Collections: Changing the name of a collection provides clarity and aids in organizing collections in a more meaningful way.
• Updating Limiting Collections: A limiting collection restricts the pool of resources available to a collection. This parameter is essential for ensuring that only relevant devices or users are included.
• Configuring Refresh Types: A collection’s membership can be updated manually, periodically, or incrementally, which can be critical for maintaining accurate and timely resource data.
• Other Properties: Modifications might also include comments, maintenance windows, or integration settings such as cloud synchronization with Microsoft Entra groups (formerly Azure AD), depending on the organization’s needs.

Usage Scenarios

Administrators use Set-CMCollection for various operations, such as:

• Corrections and Updates: When a collection’s criteria change, or its configuration needs to align with updated IT policies, this cmdlet enables fast updates.
• Batch Processing: Administrators can script modifications across multiple collections simultaneously by importing data (for example, from a CSV file) and processing each entry in a loop.
• Performance Optimization: Adjusting the refresh type, such as moving from manual to periodic updates, can help optimize system performance and ensure timely application of changes.

Example Usage

Renaming a Collection

The following example demonstrates how you can rename a collection:

# Retrieve the collection and then rename it using the Set-CMCollection cmdlet
$userCollection = Get-CMCollection -Name "testUser"
Set-CMCollection -InputObject $userCollection -NewName "newTestUser"
  

Updating the Limiting Collection

In this example, the limiting collection is updated to restrict the pool of resources:

# Update the limiting collection for a specific collection by its Collection ID
Set-CMCollection -CollectionId "XYZ00001" -LimitingCollectionId "ABC00001"
  

Changing Collection Refresh Type

Changing how and when the collection updates its membership can be essential. In this example, the refresh type is updated:

# Update the collection refresh type to periodic so that membership is updated based on a schedule
Set-CMCollection -CollectionId "XYZ00001" -RefreshType Periodic
  

Batch Renaming Multiple Collections

For larger environments, administrators might need to update multiple collections simultaneously. The process often involves importing data from a CSV file and iterating over each entry:

# Import a CSV file containing old and new collection names, then rename each collection
$Collections = Import-Csv -Path "C:\temp\CollectionRename.csv"

foreach ($Collection in $Collections) {
    try {
        $Result = Set-CMCollection -Name $Collection.OldCollectionName -NewName $Collection.NewCollectionName -PassThru -ErrorAction Stop
        Write-Host "Renamed '$($Collection.OldCollectionName)' to '$($Collection.NewCollectionName)'" -ForegroundColor Green
    }
    catch {
        Write-Error "Error renaming '$($Collection.OldCollectionName)' to '$($Collection.NewCollectionName)'"
    }
}
  

Best Practices and Prerequisites

Preliminary Setup

Before running these cmdlets, make sure your environment is properly set up:

• Ensure Installation: The Configuration Manager Console must be installed, and the appropriate PowerShell module should be loaded to make the cmdlets available.
• Connect to the SCCM Site: Launch the SCCM Console and use the “Connect via Windows PowerShell” option, or manually import the module using a command similar to:

Import-Module "$($ENV:SMS_ADMIN_UI_PATH)\..\ConfigurationManager.psd1"
Set-Location ABC:
  

Replace "ABC" with your actual site code.

Permissions and Security

Adequate permissions are essential for retrieving and modifying collections. Always ensure you have the correct administrative rights before executing these cmdlets since both reading and updating collection properties require security privileges within SCCM.

Testing Changes in a Lab Environment

Administrators should always test any changes in a lab or development environment before applying them to production systems. This cautious approach helps prevent unintended disruptions and allows you to verify that your scripts function as expected.

Verification after Changes

After applying changes with Set-CMCollection, verify the success of your operation by using Get-CMCollection again to retrieve the collection details. Additionally, update membership if necessary:

# Force the collection to update its membership, particularly if the collection is query-based
Update-CMCollectionMembership -CollectionId "XYZ00001"
  

Comparative Overview: Get-CMCollection vs. Set-CMCollection

The following table provides a side-by-side comparison of the two cmdlets, highlighting their primary functions and common use cases:

Get-CMCollection -Name "SampleCollection"

Set-CMCollection -InputObject $coll -NewName "RenamedCollection"

Advanced Considerations and Expanded Use Cases

Beyond the basic functionalities, advanced scenarios using Get-CMCollection and Set-CMCollection can streamline complex administrative tasks:

Scripting Complex Environments

In large-scale environments where hundreds or thousands of collections exist, combining both cmdlets in PowerShell scripts enables automated audits and bulk updates. For example, administrators can create scripts that:

• Retrieve collections based on custom criteria (like naming conventions or collection IDs) and export the data for reporting.
• Automatically update outdated collection names or reallocate devices/users from one limiting collection to another based on organizational changes.
• Periodically check for changes in collection membership and refresh the collections automatically, thus guaranteeing that the configuration management database remains current.

Integrating with Other SCCM Cmdlets

The power of these cmdlets is magnified when used in conjunction with related SCCM PowerShell commands. For instance, once you retrieve a collection using Get-CMCollection, you might use additional cmdlets to inspect settings in greater detail. An example is using:

# Retrieve extended settings for a collection
Get-CMCollection -CollectionId "XYZ00014" | Get-CMCollectionSetting -CollectionType Device
  

This integration allows detailed verification and configuration of device management settings such as power management and maintenance windows.

Managing Collection Queries

Many collections in SCCM are query-based, meaning their membership is determined by a dynamic query. While the basic Set-CMCollection cmdlet is sufficient for many updates, advanced scenarios might require the use of specialized cmdlets to modify the underlying query expressions directly. It is important to ensure that queries are correctly formatted and error-free, as improper queries might lead to incomplete or incorrect collection membership.

Automation and Error Handling

In a dynamic IT environment, automation is key. Scripts that incorporate both Get-CMCollection and Set-CMCollection should be designed to handle errors gracefully. Common practices include:

• Employing Try/Catch blocks to catch errors and log issues.
• Using the -PassThru parameter to confirm changes immediately.
• Validating input objects by retrieving them first before making changes. This avoids accidental misconfigurations.

Practical Implementation Tips

As you implement these cmdlets in your daily operations, consider the following practical tips:

• Documentation: Always document any script changes. Knowing which modifications were applied and when is essential for ongoing management and troubleshooting.
• Testing: Begin by testing in non-production environments. This avoids potential disruptions caused by script errors or unforeseen consequences of mass updates.
• Permissions: Make sure your account has the necessary rights. A failure in execution because of inadequate privileges can be time-consuming to troubleshoot.
• Scripting Conventions: Use clear variable names and comment frequently to help others understand your scripts. This is particularly beneficial when these scripts are shared or maintained over long periods.

Example Scenario: Automating Collection Updates

Suppose an organization requires that all device collections with obsolete naming be updated to reflect new departmental structures. A well-planned PowerShell script would:

1. Retrieve all collections using Get-CMCollection.
2. Filter collections based on naming patterns (e.g., those that start with "Legacy").
3. Use Set-CMCollection to rename these collections or update their limiting collections to align with the new organizational structure.
4. Force a membership update with Update-CMCollectionMembership to ensure that the new criteria are applied in real time.

By automating such processes, IT departments can not only save significant time but also minimize errors that can occur with manual modifications.

Conclusion

In summary, Get-CMCollection and Set-CMCollection are indispensable PowerShell cmdlets for managing collections in SCCM. They empower administrators to retrieve detailed information about device and user collections, and to perform essential updates that keep the collections current and correctly configured. By following best practices such as preliminary environment setup, permission verification, and extensive testing in lab environments, IT professionals can streamline their workflow, reduce manual errors, and maintain a robust configuration management system. The integration of these cmdlets with other SCCM PowerShell commands further enhances the overall efficiency, making it easier to automate complex tasks and manage large deployments effectively.

References

• Get-CMCollection - Microsoft Learn
• Set-CMCollection - Microsoft Learn
• SCCM CMDlets Documentation - GitHub
• Get-CMCollectionMember Documentation - GitHub

More

Automation of SCCM Collections using PowerShell

Managing Query-Based Collections in SCCM

Scripting for System Center Configuration Manager

Best Practices for Mass Updating SCCM Collections