I was recently asked by a teammate to assist them with creating a script to automatically reboot an application environment after monthly Windows patching. The environment has multiple servers which need to be rebooted in a certain order with pre- and post-reboot validations. An automation script would save the team dozens of hours a month. The most interesting part of this script would be to check the status of the patching deployment and use this for reporting when rebooting the environment. We use Microsoft Endpoint Configuration Manager (MECM, formerly SCCM) to deploy patches so I decided to use the MECM ConfigurationManager PowerShell module for this task.
Most articles I found on the topic of querying deployment statuses eschewed using the module cmdlets in favor of running WMI queries to obtain the deployment status. This somewhat makes sense as the GUI Console runs WMI queries and it’s essentially what the cmdlets are doing when you run them as well. Unfortunately, in order to use remote WMI queries, administrator access is required to the Config Manager site server, or you need to muck around in WMI security permissions. I didn’t find either option appealing. As a user of the MECM Console, I already had the required permissions to access the data and the PowerShell cmdlets work without needing extra permissions on the MECM server. I decided to figure out how to do this using only the module’s cmdlets.
Note: Please reference the Getting Started page to learn how to install and import the Configuration Manager PowerShell module. Once imported you can proceed.
The first step is to find the deployment using Get-CMDeployment. In this example I provide the collection name and software name, where the software is the current month’s Windows Updates. I also created a custom view definition to see the retuned data more easily in the console. This format .ps1xml file can be found here.
$collectionName = "MSU - Application - Dev"
$wsuSoftwareName = "Windows Server Updates 2023-01"
$deploymentDetails = Get-CMDeployment -CollectionName $collectionName -SoftwareName $wsuSoftwareName
If your Success count equals the Targeted systems, you’re probably good to go. However, if you have other statuses or want more detailed information like individual system names, we need to go deeper.
Next, we will get the assignment information for this deployment. Different deployment types use different cmdlets. Windows Updates are Feature Type “Software Update”, so use Get-CMSoftwareUpdateDeployment and provide the Deployment Id.
$suAssignment = Get-CMSoftwareUpdateDeployment -DeploymentId $deploymentDetails.DeploymentID
Once we have the assignment, we can use this information to get the deployment summary by using Get-CMSoftwareUpdateDeploymentStatus. This returns information for all of the software updates (configuration items) included in the assignment. If there are multiple configuration items included in the deployment, multiple objects will be returned.
$suDeploymentSummary = Get-CMSoftwareUpdateDeploymentStatus -InputObject $suAssignment
Note: I’ve found that in practice that the individual Software Update Configuration Items don’t seem to return accurate status. However, you can still use these items to get accurate final deployment details. Let me know in the comments if you have any information about this.
The deployment summary shows how many systems are targeted (the Total count), but it does not include any detail about the configuration item other than the CI_ID. Fortunately, it’s easy to view the item by using Get-CMConfigurationItem with the CI_ID.
Get-CMConfigurationItem -Fast -Id $suDeploymentSummary.CI_ID
The final step to determine the deployment status of the collection is to use Get-CMDeploymentStatusDetails with the deployment summary object. This will retrieve the list of servers in the deployment and show the status of each server. If there are multiple configuration items in the deployment summary you can just use the first item in the array.
$deploymentStatusDetails = Get-CMDeploymentStatusDetails -InputObject $suDeploymentSummary[0]
We now see the deployment status and description of each server in the collection. StatusType will only show a number by default. You can create a small function and use an expression in the select statement to convert the numbers to something useful. The list of status types is found in this article: MECM Deployment Asset Details.
# Function to convert StatusType integer to description
Function Get-CmStatusType ($statusNumber) {
switch ($statusNumber) {
1 {$getStatusDesc = "Success"}
2 {$getStatusDesc = "InProgress"}
4 {$getStatusDesc = "Unknown"}
5 {$getStatusDesc = "Error"}
Default {$getStatusDesc = $statusNumber}
}
return $getStatusDesc
}
# Select statement with expression
$deploymentStatusDetails | Select-Object DeviceName, IsCompliant, StatusTime, @{expression = {Get-CmStatusType $_.StatusType}; label="StatusType"}, StatusDescription, AssignmentName | Format-Table
Finally! We have a per-server status of the deployment of the software update to the desired collection. Now that we have a scripted method to determine patching status, we can do reporting or take actions based on certain statuses.
I hope this helps demystify a bit how to use the ConfigurationManager PowerShell module. Happy scripting!
Sample Script
# Function to convert StatusType integer to description
Function Get-CmStatusType ($statusNumber) {
switch ($statusNumber) {
1 {$getStatusDesc = "Success"}
2 {$getStatusDesc = "InProgress"}
4 {$getStatusDesc = "Unknown"}
5 {$getStatusDesc = "Error"}
Default {$getStatusDesc = $statusNumber}
}
return $getStatusDesc
}
# Connect to ConfigurationManager - Requires Console to be installed
# Refer to Getting Started article for more information how to configure the module
# https://learn.microsoft.com/en-us/powershell/sccm/overview?view=sccm-ps
Import-Module "C:\Program Files (x86)\ConfigMgr\bin\ConfigurationManager.psd1"
Update-FormatData "mecmFormats.ps1xml"
Set-Location CB1:
# Targeted Collection & Software Name
$collectionName = "MSU - Application - Dev"
$wsuSoftwareName = "Windows Server Updates 2023-01"
# Get Per-Server Deployment Details by Collection Name
$deploymentDetails = Get-CMDeployment -CollectionName $collectionName -SoftwareName $wsuSoftwareName
$suAssignment = Get-CMSoftwareUpdateDeployment -DeploymentId $deploymentDetails.DeploymentID
$suDeploymentSummary = Get-CMSoftwareUpdateDeploymentStatus -InputObject $suAssignment
$deploymentStatusDetails = Get-CMDeploymentStatusDetails -InputObject $suDeploymentSummary[0]
$deploymentStatusDetails | Select-Object DeviceName, IsCompliant, StatusTime, @{expression = {Get-CmStatusType $_.StatusType}; label="StatusType"}, StatusDescription, AssignmentName | Format-Table
References
Get started with Configuration Manager cmdlets
CM Configuration Item Enforcement Status Descriptions
CM Configuration Item Type ID Descriptions
Pwsh+ 