Skip to main content

1E 8.1 (on-premises)

Patch.List

Method	List
Module	Patch
Library	Core
Action	List the status of patches.
Parameters	`Source` (string): The source of patch meta-data, typically the installation mechanism used to handle patch(es). One of: `CAB`: A file with a `.cab` extension and appropriate binary structure containing update metadata, located somewhere in the file system available to the local agent. The file is used directly by the local Windows Update agent, without SCCM or WSUS being involved. `SCCM`: System Center Configuration Manager. `WSUSL`: A local (to the enterprise) corporate Windows Server Update Service server. `WSUSR`: The remote Windows Server Update Service feed over the internet at microsoft.com. Note Case is not significant. Note If this parameter is not specified, the Tachyon Agent attempts to deduce the source as follows: If a CAB-file is specified and exists (although is not necessarily valid), the source is implicitly ' `CAB` '. Else if the SCCM client is enabled for software updates, the source is implicitly ' `SCCM` '. Else if a local Windows Software Update server is configured, the source is implicitly ' `WSUSL` '. Else if the remote Windows Software Update Service is configured, the source is implicitly ' `WSUSR` '. Else the source is unknown and must be specified explicitly; this causes an error. Warning SCCM uses WSUSL behind the scenes but it hides certain information. Specifying an explicit `Source` of “`WSUSL`” may reveal more patches that have been installed than by specifying “`SCCM`” or by leaving Tachyon to deduce SCCM. For speed of response, the SCCM option does not run a Software Updates Deployment Evaluation Cycle action, so the data returned may not be completely up to date.
	`PatchSpec` (string; optional, default all available patches): The patches to be matched against the full list of updates. If no specific patches are supplied, all updates will be listed. Note For Windows, this is a comma-separated list of Knowledge Base article numbers (without the "KB" prefix) or the GUIDs of specific patches, or even a mixture. Case is not significant for the hex digits in GUIDs.
	`CheckOnline` (bool; default `false`): Grant permission (or not) as to whether to go over the network or remain purely local to the host. This parameter only affects `WSUSL` and `WSUSR` and will have no effect on `SCCM`, where it will always be set to false. Warning If `CheckOnline` is `false`, the already-installed updates are generally reported accurately but, for obvious reasons, additional updates that are available from a remote server cannot be detected.
	`CabFilePath` (string; default empty): The full path of the location of the `.cab` file if Source is '`CAB`'. Note This must be specified if `Source` is '`CAB`' and should not be specified for any other `Source` value. If the path is specified it must be to a local CAB-file. Shared, i.e. remote, CAB-files are not supported by Windows Update Agent.
	`TimeoutSecs` (int; optional, default `600`): If the Source does not complete within the specified number of seconds, return anyway. A value of 0 means an eternal timeout, i.e. none. A negative value is illegal. Available from v4.0. Note Error status is returned if the timeout occurs.
Return values	For each patch:
	`PatchIds` (string): Comma-separated list of identifiers associated with the update, as would be specified to the Deploy method. Note For Windows these are the associated Knowledge Base article IDs, e.g. "`2267602`".
	`PatchGuid` (string): GUID of the patch, if available. Warning This can be null if the patch is only known from the Windows quick fix engineering (QFE) database.
	`Title` (string): Full title of the patch.
	`IsDownloaded` (boolean): Whether the patch has been downloaded to the device but not yet installed. Note If the patch has been successfully installed (i.e. `IsInstalled` is `true`), this will be `false` even though the patch was actually downloaded at some point. `IsDownloaded` being `true` implies that the patch is ready to install.
	`IsInstalled` (boolean): Whether the patch has been installed on this device.
	`Status` (string): Current status of the patch on this device. One of these: `Available for download` (but not yet downloaded) `Downloading` `Downloaded` (but not yet installed) `Installation aborted` `Installation failed` `Installation in progress` `Installation not started` `Installation successful` `Installation successful pending reboot` `Installation successful with errors` `Installation successful with errors pending reboot` `Uninstallation` `aborted` `Uninstallation failed` `Uninstallation in progress` `Uninstallation not started` `Uninstallation successful` `Uninstallation successful pending reboot` `Uninstallation successful with errors` `Uninstallation successful with errors pending reboot` `Unknown` Note A "pending reboot" status means that the action has been carried out (install or uninstall) but it will not take effect until after the device has been rebooted. Warning WSUS does not always record the most recent status. For example, a few updates can apparently be at "`Installation in progress`" after some years and device reboots. `IsInstalled` is marked as `false` for such patches.
	`Timestamp` (string): When the patch achieved its `Status` value.
	`Source` (string): If the patch has been installed on this device (or is available for installation), what subsystem supplied that information. One of: `MSI`: The Windows MSI (Windows Installer, formerly "Microsoft Installer") API; all such patches are fully installed. `QFE`: The installed patch is known only from the Windows "Quick Fix Engineering" database. `REGISTRY`: The patch is known only from the Windows Registry. Typically this applies to updates that are partially installed but require a reboot to be fully installed. `PandF`: Information about the installed patch was obtained from the same derivation as `Control Panel → Programs and Features → View installed updates`. `CAB`: A file with a `.cab` extension and appropriate binary structure containing update metadata, located somewhere in the file system available to the local agent. The file is used directly by the local Windows Update agent, without SCCM or WSUS being involved. `SCCM`: System Center Configuration Manager. `WSUSL`: A local (to the enterprise) corporate Windows Server Update Service server. `WSUSR`: The remote Windows Server Update Service feed over the internet at microsoft.com. Warning For a patch that requires a reboot, data can be incomplete following install but prior to reboot compared with after reboot. Prior to reboot we see just this: `PatchIds`:null, `PatchGuid`:"`3bfc94d2-adb3-41c0-a5f0-a5d54e8fa824`", `Title`:null, `InInstalled`:`true`, `Status`:"`Installation successful pending reboot`", `Source`:"`unknown`" After reboot we get: `PatchIds`:"`4091664`", `PatchGuid`:"`8e16108f-4a20-4231-ad07-b41f662accb0`", `Title`:"`2018-10 Update for Windows Server 2016 for x64-based Systems (KB4091664)`", `Status`:"`Installation successful`", `Source`:"`WSUSR`" The problem is that Windows does not supply enough information to the Tachyon Agent prior to reboot; even the GUIDs are inconsistent.
Example	Patch.List(Source: "WSUSL", PatchSpec:"004226dc-aaf5-4adc-9dd5-285ce0e1ad36,3182545,1CF1F075-360E-4E95-AB8D-D6B0F4B09D9B");
Platforms	Windows
Notes	This method usually returns a different number of records than are displayed by `Control Panel` → `Programs and Features` → `Installed Updates` for a number of reasons, including: `Installed Updates` can display a single line for a KB ID that has multiple patches, whereas Tachyon lists all the patches. `Installed Updates` displays a patch shared between a number of products for each of the products, whereas Tachyon lists it just once. The `IsDownloaded` and `IsInstalled` properties are not strictly necessary because the `Status` implies their values, but they are useful as summaries. Patch Success uses 4 instructions, 1 from SLA inventory and 3 from the 1E-PatchSuccess product packs. Patch Success uses this method it its 1E-PatchSuccessRefresh instruction and then aggregates the status for each update into the following headings: Fully patched WHEN IsInstalled = 1 AND Status = 'Installation successful' THEN "Installed successfully" Requires rebooting WHEN IsInstalled = 1 AND Status = 'Installation successful pending reboot' THEN "Installed successfully - pending reboot" Requires attention WHEN Status LIKE '%with errors%' OR Status LIKE 'Installation failed' THEN "Failed - " \|\| Status Requires patching WHEN IsInstalled = 0 THEN "Missing" No patches if there are no patches reported. Patch Success uses this method in its 1E-PatchSuccessExplore instruction to return the following for each patch on a device: Title Status Source PatchGuid as PatchIdent Timestamp Patch Success uses this method in its 1E-PatchSuccess-PatchStatus instruction (from SLA inventory) to return the following for each patch on a device: PatchGuid as PatchIdent Title IsDownloaded IsInstalled Status Timestamp Source The 4th instruction is described in Patch.Deploy.

In this section: