Skip to main content

1E 9.x (on-premises)

Patch.List

Method

List

Module

Patch

Library

Core

Action

List the status of patches.

Parameters

Note

If this parameter is not specified, the Tachyon Agent attempts to deduce the source as follows:

  1. If a CAB-file is specified and exists (although is not necessarily valid), the source is implicitly ' CAB '.

  2. Else if the SCCM client is enabled for software updates, the source is implicitly ' SCCM '.

  3. Else if a local Windows Software Update server is configured, the source is implicitly ' WSUSL '.

  4. Else if the remote Windows Software Update Service is configured, the source is implicitly ' WSUSR '.

  5. 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.

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: