Patch Deployments

Patch deployments are used to install patches to target machines that were identified as missing from a patch scan. You can start a deployment, locate existing deployments and delete deployments.

If you initiate a patch deployment remotely via the REST API, you must initialize a session credential.

Base URL

        https://<consoleFQDN:port>/stconsole/api/v1.0/patch/deployments

Supported Requests

Method	URL	Input	Return
DELETE	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deployments/{deployment id}		Success or failure code
GET	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deployments		PatchDeployments[]
	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deployments	URL Parameters	PatchDeployments[]
	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deployments/{deployment id}		PatchDeployment
	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deployments/{deployment id}/machines	URL Parameters	MachineDeployState
	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deployments/{deployment id}/machines/{machine id}		MachineDeployState
POST	https://<consoleFQDN:port>/st/console/api/v1.0/patch/deployments	Request Body	Operation location

Input Models

URL Parameters

Name	Type	Description
count	Integer	Provide the count of items to return. The default is 10 and the maximum value is 1000.
createdByMe	Boolean	Returns only those items created by the user. This parameter will be removed in a future release and should only be used in legacy requests.
name	String	Returns the items whose name matches the specified name.
onOrAfter	DateTime	Returns the deployments started on or after the specified date.
onOrBefore	DateTime	Returns the deployments started on or before the specified date.
start	Integer	Sets the starting point. The items are sorted by their unique identifier and the starting point is the index into that sorted list.

Request Body

If you initiate a patch deployment remotely using the REST API, you must add a session credential.

Name	Required?	Type	Default Value	Description
deployWhat	No	Enum	AllMissingPatches ForScan	Specifies what is being deployed. Valid values are: AllMissingPatchesForMachine AllMissingPatchesForScan SelectedPatchesForMachine
errorPolicy	No	String	Throw	errorPolicy=Throw means the entire request will be rejected errorPolicy=Omit means the problem area will be omitted but the rest of the request will be completed.
machines	Conditional	DeployMachineInput[]	None	Specifies the machines that will be included in the deployment. Its use is conditional based on what is specified for deployWhat. If deployWhat = AllMissingPatchesForScan: machines is not used and can be set with an empty array. If deployWhat = AllMIssingPatchesForMachine or SelectedPatchesForMachine: machines is required.
runAsCredentialId	No	Guid	None	Provides a credential ID to a credential to use to start a deployment. This command is deprecated, use a session credential instead.
runAsDefault	No	Boolean	False	Specifies whether to run the deployment using the integrated authentication credentials of the user who invokes the REST API. This flag cannot be set to true if the REST API is called from a remote client. This command is deprecated.
scanId	Yes	Guid	None	Specifies a scan ID used to identify missing patches and target machines.
templateId	Yes	Guid	None	Specifies the ID of the deployment template used for this deployment.

DeployMachineInput

Name	Required?	Type	Default Value	Description
detectedPatches	Yes	DetectedPatchInput[]	None	Specifies the patches that will be included in the deployment.
domain	Yes	String	None	Specifies the domain of the machine.
name	Yes	String	None	Specifies the name of the machine.
virtualMachinePath	Conditional	String	Null	If the patch is being deployed to a virtual machine, specifies the path to the machine on the virtual server. Required if virtualServer is specified.
virtualServer	Conditional	String	Null	If the patch is being deployed to a virtual machine, specifies the name of the server on which the virtual machine resides.

DetectedPatchInput

Name	Required?	Type	Default Value	Description
cultureName	No	String	Null	Optionally specifies the name of the culture for the current patch. If left as null, whichever culture is associated with the missing patch is deployed. If a cultureName is specified, then only patches that match the name of the culture are deployed. This field is not case sensitive.
instanceName	No	String	Null	Specifies the instance name for products such as SQL Server that have one. This comes from the DetectedPatch of the Patch Scan. This field is not case sensitive.
patchId	Yes	Guid	None	Specifies the ID of the missing patch or service pack. The ID comes from either the patch catalog (Product Level.uid) or from a custom patch specification.

Example with Sample Response

Find all patch deployments using a deployment template named Sample

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deployments?name=Sample

Sample Response

Copy

{
    "count": 1,
    "value": [
    {
        "completedMachineCount": 1,
        "creator": "SHAVLIK\\Test.User",
        "expectedMachineCount": 1
        "isComplete": true
        "lastUpdatedOn": "2018-02-12T14:42:27.923Z"
        "links": "{"
            "self": "{"
                "href": "https://YourConsoleName:3121/st/console/api/v1.0/patch/deployments/d7a59ec7-2bdd-4492-9e41-c23ac84c64d6"
            }
        }
        "name": "Sample"
        "startedOn": "2018-02-12T14:36:41.707Z"
        "id": "d7a59ec7-2bdd-4492-9e41-c23ac84c64d6"
    }
    ]
}

Other Request Examples

Start a patch deployment of all missing patches for a specific machine

Tip: You can use the output of a Patch Scan request (see the Find information about the machines example) to populate the domain and name parameters that are specified in this request.

POST Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deployments

{
    "scanId": "8bce9fdd-0cf8-40b0-8ecc-b0914a9c831a", 
    "templateId": "7b5bc7e4-7437-47ac-ae2e-569ffdb0ccf8"
    "deployWhat": "AllMissingPatchesForMachine",
    "machines": [
        {
            "domain": "MyDomainName",
            "name": "MyMachineName
        }
    ]
}

Start a patch deployment of specific patches to a specific machine

Tip: You can use the output of a Patch Scan request (see the Find all patches detected on a specific machine example) to populate the patchId and cultureName parameters that are specified in this request.

POST Request

Copy

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deployments

{
    "scanId": "8bce9fdd-0cf8-40b0-8ecc-b0914a9c831a", 
    "templateId": "7b5bc7e4-7437-47ac-ae2e-569ffdb0ccf8"
    "deployWhat": "SelectedPatchesForMachine",
    "machines": [
        {
            "domain": "MyDomainName",
            "name": "MyMachineName",
            "detectedPatches": [
                {
                    "patchId": "00009486-0000-0000-0000-000000000000",
                    "cultureName": "en-US"
                },
                {
                    "patchId": "00032e80-0000-0000-0000-000000000000",
                    "cultureName": "en-US"
                }
            ]
        }
    ]
}

Output Models

PatchDeployment

Name	Type	Description
completedMachineCount	Integer	On how many machines has the deployment completed?
creator	String	Who initiated the deployment?
expectedMachineCount	Integer	How many total machines are in this deployment?
isComplete	Boolean	Is the deployment complete?
lastUpdatedOn	DateTime	When was the last status update received?
links	Links	Shows the related URLs for the deployment, the machines and the template.
name	String	What is the name of the deployment template?
startedOn	DateTime	When was the deployment started?
id	Guid	The unique operation identifier assigned to the patch deployment.

MachineDeployState

Name	Type	Description
address	IPAddress	The IP address of the machine.
completedPatches	Integer	The count of in-progress patches
dnsName	String	The DNS name of the machine.
domain	String	The domain name of the machine.
errorCode	Integer	The error code reported on failure by the machine.
id	Integer	The unique machine identifier for the machine being deployed to
lastUpdated	DateTime	Specifies when the deployment status was last updated.
links	Links	Shows the related URL for the deployment to the machine.
name	String	The hostname of the machine.
overallState	DeploymentState	The overall state of the machine deployment (in-progress, completed, failed, etc).
patchStates	PatchDeployState	The status of each patch in the deployment.
statusDescription	String	A description of the status of the deployment.

PatchDeployState

Name	Type	Description
bulletinId	String	The bulletin ID or product being applied.
finishedOn	DateTime	Date and time that the deployment finished installing patches.
hasExecuted	Boolean	Has the patch deployment been executed?
kb	String	The KB number of the patch or service pack level.
lastUpdated	DateTime	Date and time that the patch deployment status was last updated.
nativeCode	Integer	The native error code if the patch deployment failed. See Debug system error codes (opens in a new window) on Microsoft Learn for details.
overallState	DeploymentState	The overall state of the patch deployment (in progress, complete or failed).
overallStateDescription	String	A localized description of the overall deployment state.
patchId	Guid	The patch ID.
scheduledOn	DateTime	The date and time the patch was scheduled for deployment.
startedOn	DateTime	The date and time that the patch deployment started.
status	DeploymentResult	The deployment result status.
statusDescription	String	A localized description of the status.

DeploymentResult

Name	Value	Description
none	0	Initial value when the record is created.
failed	1	Deployment failed for various reasons. Possible examples include: SA password is blank Not enough deployment seats Not licensed to deploy this patch Patch file is not signed Patch file is not found Uninstall and uninstall file is not specified in the XML Uninstall but we were able to confirm that the uninstall file is not on the target machine Copy file to target machine failed
copied	2	Files / data were copied.
scheduled	3	Deployment was scheduled.
executing	4	Before executing the patch file.
executed	5	After executing the patch file, if deployment template specified no reboot.
pendingReboot	6	Deployment is pending a reboot.
verifiedMissing	7	Rescan completed and found the patch is missing.
verifiedFixed	8	Rescan completed and found the patch is not missing.
unableToVerify	9	Could not perform the rescan (e.g. failed to connect to the target machine) or the patch InstallState attribute is present but not "missing" or "installed" in the scan results.
canceled	10	Deployment was canceled.
completeNotVerified	11	CompleteNotVerified in Tracker service UpdatePatchDeploymentStatus is turned into VerifiedFixed.
pendingRescan	12	Deployment is pending a rescan.
inferredFixed	13	Rescan did not report on the patch. It is neither missing nor installed, so it is inferred to be fixed.
waitForServer	20	VM - Waiting for concurrent deployments on the server to drop below the limit.
initialize	21	VM - Disable Sysprep / get system path.
disableNetwork	22	VM - Disable network.
powerOn	23	VM - Power on.
monitorStatus	24	VM - Getting Tracker files.
powerOff	25	VM - Power off.
enableNetwork	26	VM - Enable network.
enableSysprep	27	VM - Enable Sysprep.
takeSnapshot	28	VM - Take snapshot.
cleanupSnapshot	29	VM - Cleanup snapshot.
convertToTemplate	30	VM - Convert to template.
patchDownloadRetry	31	Patch download from distribution server failed; retry scheduled.
buidlingDeploymentPackage	32	Building the deployment package.
deployingPackages	33	Copying files and scheduling the installation.
finishedPendingReboot	34	Installation complete and reboot is scheduled.
downloadedFile	35	Downloaded file.
rescanInProgress	36	Rescan in progress. Set when rescan manager polls results and initiates a rescan.
downloadingFiles	37	Files necessary to the deployment are being downloaded.
fileDownloadStarted	38	Patch download started.
fileDownloadFailed	39	Patch download failed.
fileDownloadCompleted	40	Patch download successfully completed.
fileDownloadCompleted	41	Machine status, all file downloading is complete.
fileDownloadsFailed	42	Machine status, file downloading has critically failed.
installing	43	Vendor patches are being installed.
externalRebootRequested	44	Waiting for the status handler DLL to reboot the machine.
rebooted	45	Machine has booted up (within a deployment workflow). Waiting for post-boot actions.
minimumDetailStatus	Error452	Starting point for specific error states (except for Finished, which is a completion indicator).
error452	80	Cannot connect to the machine, access denied.
error453	81
error230	82	A general network error occurred.
noRegistryAccess	83
platformInNotNT	84
unsupportedOperatingSystemServicePack	85
noAdminShareAccess	86
machineNotFound	87
credentialsInvalid	88	Credentials on the target machine were invalid.
machineFoundButIsNotListeningOn139or445	89
notAdministrator	90
error201	91
machineNotFoundOn139or445IsFirewalled	92
error202	93
unknownCE	94
virtualDeploymentFailed	95	General error for virtual deployment.
virtualDeploymentInProgress	96	Virtual deployment already running in the service for the VM.
preDeploySnapshotFailed	97	Snapshot failed in call to PreDeploy().
convertToVirtualMachineFailed	98	Unable to convert template to virtual machine.
finished	99	Entire deployment / installation is complete including reboot if required.
uninstalled	100	Uninstallation is complete, not waiting (or no longer waiting) for reboot.
stagedDeploymentScheduled	101	Staged deployment scheduled.
failedToScheduleStagedDeployment	102	Failed to schedule staged deployment.
userCanceled	103	Scheduled deployment task was deleted or canceled by the user.
virtualDeploymentFailedNativeError	150
disableNetworkFailed	151
powerOnFailed	152
monitorStatusInvalidHostCredentials	153
monitorStatusInvalidGuestCredentials	154
powerOffFailed	155
enableNetworkFailed	156
enableSysprepFailed	157
takeSnapshotPostDeployFailed	158
cleanupSnapshotRemovalFailed	159	Removal of snapshot during cleanup failed.
convertToTemplateFailed	160
virtualDeploymentFailedInvalidState	161	Internal error; invalid state.
virtualDeploymentFailedExpirationTimeExceeded	162	Virtual deployment failed due to deployment expiration.
virtualDeploymentFailedTimeExceeded	163
monitorStatusVMwareToolsNotRunning	164	Failure to log in to the machine because VMware Tools is not running.
virtualMachineLocked	165
offlineOperationsNotSupported	166	The vSphere server version is not supported for mounting.
nativeError	180	See the error string for details.
unableToConnectToVirtualServer	181
unableToFindVirtualMachine	182	Cannot find the virtual machine on the server.
errorCreatingDeploymentPackage	183	See the log for details.
unableToDeployToSuspendedVirtualMachine	184
unableToDeployToOfflineVirtualMachine UsingDistributionServers	185
onlineCredentialsAreNotAvailable	186
failedToScheduledPatchDeployment	187
patchCopyFailed	188	Failed to copy the file to the target machine.
patchRemovedDueToMissingFile	189	Patch was removed because the uninstall file does not exist on the target machine.
notLicensedToDeployPatch	190	Your license does not support deployment of this patch.
languageDownloadNotAvailable	191	Patch is not available for the selected language.
fileValidationFailed	192
fileIsMissing	193
deploymentLicensesExceeded	194
outOfDiskSpace	195
machineMismatch	270
unableToOpenVmxFile	817

Patch Deployments

Base URL

Supported Requests

Input Models

Example with Sample Response

Find all patch deployments using a deployment template named Sample

GET Request

Sample Response

Other Request Examples

DELETE Request

GET Request

GET Request

GET Request

GET Request

GET Request

GET Request

GET Request

GET Request

POST Request

POST Request

POST Request

Output Models