Security Controls REST API

Home 

Patch Deployment Templates

When deploying patches to machines, patch deployment templates allow you to specify a number of different options. For example, you can specify whether the deployment target should be restarted after the deployment, how fast the patches should be copied to the remote machines, whether reports should be sent, and much more.

Base URL

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

Supported Requests

Method URL Input Return

DELETE

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}

 

Success or failure code

 

   

GET

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

URL Parameters

PatchDeploymentTemplates[]

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template guid}

 

PatchDeployTemplate

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}/customactions

 

CustomActions[]

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}/customactions/{custom action id}

 

CustomAction

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/{patch deploy template id}/usedby

 

Usedby[]

     

POST

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

Request Body

 

Input Models

URL Parameters

Name Type Description

count

Integer

Provide the count of items to return. The maximum value is 50.

createdByMe

Boolean

Returns only those items created by the user.

name

String

Returns the items whose name matches the specified name.

start

Integer

Sets the starting point.

path

String

Sets the path and is used to find templates matching the specified path.

Request Body

Name Required? Type Default Value Description

description

No

String

None

Gets or sets the description.

distributionServerOptions

No

DistributionServerOptions

 

The options corresponding to the Distribution Servers tab of the deployment template.

generalOptions

No

DeployGeneralOptions

 

The options corresponding to the General tab of the deployment template.

name

Yes

String

None

Gets or sets the name.

path

No

String

None

Gets or sets the path.

postDeploymentReboot

No

PostDeployReboot

 

The options corresponding to the Post-deploy Reboot tab of the deployment template.

preDeploymentReboot

No

PreDeployReboot

 

The options corresponding to the Pre-deploy Reboot tab of the deployment template.

virtualOptions

No

VirtualMachineAndTemplate
Options

 

The options corresponding to the Hosted VMs/Templates tab of the deployment template.

Example

Create a patch deployment template named "Sample"

POST Request

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

Request Body

{"Name":"Sample","Description":"A sample deployment template created using the REST API"}

Sample Response

{

"creator": "SHAVLIK\\joe.andert",

"description": "A sample deployment template created using the REST API",

"generalOptions": {

"removeTempFiles": false,

"sendTrackerMessages": true,

"shutdownIis": false,

"shutdownSql": false

},

"id": "9b5d4668-48fa-41ed-b424-094e6922a11b",

"isSystem": false,

"isTemporary": false,

"links": {

"customactions": {

"href": "https://device-name.fakedomain.com:3121/st/console/api/v1.0/patch/deploytemplates/9b5d4668-48fa-41ed-b424-094e6922a11b/customactions"

},

"self": {

"href": "https://device-name.fakedomain.com:3121/st/console/api/v1.0/patch/deploytemplates/9b5d4668-48fa-41ed-b424-094e6922a11b"

},

"usedby": {

"href": "https://device-name.fakedomain.com:3121/st/console/api/v1.0/patch/deploytemplates/9b5d4668-48fa-41ed-b424-094e6922a11b/usedby"

}

},

"name": "Sample",

"postDeploymentReboot": {

"options": {

"powerState": "Restart",

"countdownMinutes": 5,

"extendMinutes": 1,

"forceActionAfterMinutes": 10,

"loggedOnUserAction": "ForceActionAfterMinutes",

"systemDialogSeconds": 60,

"userOptions": "AllowExtension"

},

"when": "Immediate"

},

"preDeploymentReboot": {

"when": "NoReboot"

},

"virtualOptions": {

"takePostDeploymentSnapshots": false,

"takePreDeploymentSnapshots": false

}

}

Other Request Examples

Find all patch deployment templates

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

Find all usages of a patch deployment template with GUID 01234567-89AB-CDEF-0123-456789ABCDEF

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/01234567-89AB-CDEF-0123-456789ABCDEF/usedby

Add a patch deployment template with a name of Sample with pre-deployment options specified

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

{ name: "Example5", PreDeploymentReboot = @{ When ='Immediate'; Options = @{ LoggedOnUserAction = 'ForceActionAfterMinutes'; ForceActionAfterMinutes=15; extendMinutes = 1; userOptions='AllowExtension, AllowCancelTimeout, AllowCancelReboot' } }; }

Delete the patch deployment template with ID 01234567-89AB-CDEF-0123-456789ABCDEF

https://<consoleFQDN:port>/st/console/api/v1.0/patch/deploytemplates/01234567-89AB-CDEF-0123-456789ABCDEF

 

Output Models

PatchDeployTemplate

Name Type Description

creator

String

The creator.

description

String

Gets or sets the description.

distributionServerOptions

DistributionServerOptions

The options corresponding to the Distribution Servers tab of the deployment template.

generalOptions

DeployGeneralOptions

The options corresponding to the General tab of the deployment template.

id

Guid

Gets or sets the patch deployment template UID.

isSystem

Boolean

Gets or sets the flag indicating if this is a system template.

isTemporary

Boolean

Indicates that this is temporary and can be deleted after the deployment.

links

Links

Shows the related URLs for the patch deployment template, the custom actions and the usedby list.

name

String

Gets or sets the name.

path

String

Gets or sets the path.

postDeploymentReboot

PostDeployReboot

The options corresponding to the Post-deploy Reboot tab of the deployment template.

preDeploymentReboot

PreDeployReboot

The options corresponding to the Pre-deploy Reboot tab of the deployment template.

virtualOptions

VirtualMachineAndTemplate
Options

The options corresponding to the Hosted VMs/Templates tab of the deployment template.

DeployGeneralOptions

Name Type Description

hoursUntilEmailSent

Integer

Indicates how many hours to wait for patches to be successfully deployed before sending any automatic email messages.

remoteDialogConfig

RemoteDialogConfig

The options corresponding to the Remote Dialog section on the General tab of the deployment template.

removeTempFiles

Boolean

Indicates if the temporary patch files that were copied during the deployment process will be removed.

sendTrackerMessages

Boolean

Indicates if Deployment Tracker status messages will be sent from the machines being patched.

shutdownIis

Boolean

Indicates if the IIS Server will be shut down before the patch deployment process begins.

shutdownSql

Boolean

Indicates if the SQL Server will be shut down before the patch deployment process begins.

RemoteDialogConfig

Name Type Description

caption

String

Specifies the text you want to appear in the Remote dialog caption.

title

String

Specifies the text you want to appear in the Remote dialog box title.

DistributionServerOptions

Name Type Description

byIpRange

 

Boolean

Indicates if the distribution server that will be used will be determined by the IP address of each target machine. You must have defined one or more IP ranges and assigned the ranges to a primary distribution server and to a backup server.

defaultId

Integer

The default distribution server ID when UseSpecificServer is specified.

errorRetry

RelayErrorRetry[]

Specifies when to try again if no patch can be retrieved from the distribution server.

fallbackToVendorSite

Boolean

If the distribution server is not available, the machine being patched will attempt to download the patch files from the patch vendor's website.

staggerStartTime

Integer

Stagger distribution server download times in minutes.

RelayErrorRetry

Name Type Description

None

   

AtReboot

   

Periodic

   

PostDeployReboot

Name Type Description

options

PostDeployRebootOptions

Specifies the reboot options.

when

RebootWhenOption

Specifies when the reboot will occur.

PreDeployReboot

Name Type Description

options

DeployRebootOptions

Specifies the reboot options.

when

RebootWhenOption

Specifies when the reboot will occur.

 

PostDeployRebootOptions

Name Type Description

earliestTime

DateTime

The earliest time the safe reboot action can occur.

powerState

TargetPowerState

The target power state after deployment is complete.

 

TargetPowerState

Enables you to specify what state you want to leave the machines after the reboot. The items in this table are mutually exclusive; you can only specify one option.

Name Type Description

stayOnline

String

The machines are kept in their current state.

sleep

String

The machines are put into sleep mode.

hibernate

String

The machines are put into a hibernation mode.

shutdown

String

The machines are powered off without being restarted.

restart

String

The machines are restarted and left in a powered on state.

restartThenSleep

String

The machines are restarted and then put into sleep mode.

restartThenHibernate

String

The machines are restarted and then put into a hibernation state.

restartThenShutdown

String

The machines are restarted and then powered off.

RebootWhenOption

Name Type Description

noReboot

String

Do not reboot the machine after patch deployment.

immediate

String

Reboot the machine immediately after deployment.

scheduledTime

String

Reboot the machine at the next occurrence of the scheduled time.

scheduledDateTime

String

Reboot the machine at the scheduled date and time.

immediateIfRequired

String

Reboot the machine immediately, but only if required.

scheduledTimeIfRequired

String

Reboot the machine at the scheduled time, but only if required.

scheduledDateTimeIfRequired

String

Reboot the machine at the scheduled date and time, but only if required.

DeployRebootOptions

Name Type Description

countDownMinutes

Integer

The countdown minutes.

extendMinutes

Integer

The number of minutes a user is allowed to extend the countdown.

forceActionAfterMinutes

Integer

The number of minutes before the safe reboot option action will occur.

forceActionOnLatestTime

DateTime

The latest time the safe reboot action will occur.

loggedOnUserAction

LoggedOnUserAction[]

The action to take if a user is logged on.

systemDialogSeconds

Integer

The number of seconds the system dialog will display during shutdown.

userOptions

RebootInteractionOptions[]

The options a user is allowed to do during the safe reboot action.

RebootInteractionOptions

If you elect to restart machines, you can specify the degree of control the user will have over the restart process. These are flags, so you can add several of them at once in an array.

Name Description

None

The user will have no control over the restart process.

AllowExtension

Allow the user to extend the time-out countdown up to a specified maximum.

AllowCancelTimeout

Allow the user to cancel the time-out. The patches will not be deployed until the user manually restarts the machine.

AllowCancelReboot

Allow the user to cancel the reboot. The patches will not be installed until the machine is restarted.

AllowNoTimeout

 

NoRestart

 

LoggedOnUserAction

If you elect to restart machines, you can specify the amount of warning that a logged-on user will receive.

Name Description

AlertUser

Alert the user that a restart will occur when they log off.

ForceActionAfterMinutes

Force a restart after a number of minutes have passed.

ForceActionOn

Force a restart at a specific date and time.

VirtualMachineAndTemplateOptions

Name Type Description

maxSnapshotCount

Integer

The maximum snapshot count to manage.

oldestSnapshotInDays

Integer

The number of days a snapshot will be allowed to exist.

takePostDeploymentSnapshots

Boolean

Indicates if a snapshot will be taken of the offline virtual machine after deploying missing patches or service packs.

takePreDeploymentSnapshots

Boolean

Indicates if a snapshot will be taken of the virtual machine prior to deploying missing patches or service packs.

CustomAction

Name Type Description

actionType

CustomDeploymentAction[]

Specifies the action type.

command

String

The location of the .exe file that is to be executed.

id

Integer

The unique identifier of this CustomAction object.

kb

String

The KB number.

links

Links

Shows the related URLs

patchActedOn

String

The patch that will be acted on during installation.

CustomDeploymentAction

Specifies when during the patch deployment process the custom command will be triggered.

Name Description

Push

Pushes a custom batch file or custom executable file to the target machines as part of the deployment.

First

Before any patches are installed.

Before

Before each patch or service pack is installed.

After

After each patch or service pack is installed.

Last

After all patches are installed (but before reboot)

Reboot

After the reboot.

UsedBy

Name Type Description

name

String

The name of the item using the template.

usageType

 

The type of component using the template.


Was this article useful?    

The topic was:

Inaccurate

Incomplete

Not what I expected

Other