Policies

A policy defines exactly what an agent can or cannot do. You can:

  • Get information about existing agent policies
  • Get information about Windows and Linux patch tasks
  • Create a new policy
  • Add Windows patch tasks
  • Add Linux patch tasks
  • Delete a policy (you cannot delete a policy that is being used by one or more agents)

Base URL

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

Supported Requests

Method URL Input Return

DELETE

https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}

 

Success code

https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}/tasks/{task Id}

 

Success code

GET

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

URL Parameters

Policy

https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}

 

Policy

https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}/tasks

URL Parameters

WindowsPatchTask

LinuxPatchTask

https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}/tasks/{task ID}

 

WindowsPatchTask or

LinuxPatchTask

POST

 

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

Policy Request Body

Policy

https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}/tasks/windowspatch

WindowsPatchTask Request Body

WindowsPatchTask

https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}/tasks/linuxpatch

LinuxPatchTask Request Body

LinuxPatchTask

https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}/tasks/contentlesslinuxpatch

LinuxPatchTask Request Body

LinuxPatchTask

Input Models

Name Type Description

name

String

The name of the agent policy or task.
Name Required? Type Default Value Description

allowCancelOperations

No

Boolean

 True

Allow the user to cancel operations.

allowManualOperations

No

Boolean

 True

Allow the user to manually initiate tasks.

checkInDistributionMinutes

No

Int32

 240

Staggers the exact time the agents will check-in so as not to overtax the console (and the default website or the optional distribution server) with simultaneous requests. The valid range is 1 - 999 minutes.

checkInOption

No

Enum

 Minutes

Specifies how often the agents will check in (synchronize) with the console.

  • Unknown: Unknown check-in state.
  • Minutes: Check in every N minutes.
  • Days: Check in every N days.

daysCheckInIntervalDays

No

Int32

 1

Applies only if checkInOption = Days. Specifies the number of days between check-ins. Valid values are 1 - 15.

daysCheckInTimeOfDay

No

TimeSpan

 00:00:00

Applies only if checkInOption = Days. Specifies the specific time of time to perform the check-in. Valid values are 00:00:00 - 24:00:00.

displayIconInNotificationArea

No

Boolean

 True

(Windows only) Specify if you want to install an icon in the notification area of each agent machine that provides the users of the machines a certain amount of control over the service.

distributionServerId

No

Int32

 None

Specifies the ID of the distribution server that will be used as the download location.

downloadSource

No

Enum

 VendorOnly

Specifies the location from which the agent will download data.

  • VendorOnly: From the vendor over the internet.
  • DistributionServerByIp: From a distribution server based on the endpoint's IP address.
  • DistributionServerSpecific: From a specific distribution server.

internetProxyCredentialId

No

Guid

 None

The internet proxy credential ID. This must be a service credential.

isAgentUIEnabled

No

Boolean

 True

(Windows only) Specifies if the agent user interface will be installed on the endpoints.

listeningAgentPort

No

Int32

 4155

Specifies the port that the agent will listen on for console commands. If no port number is specified, then the value is nullable and the agent will not be a listening agent.

loggingLevel

No

AgentLoggingLevel

Normal

The amount of logging you want the agent to perform.

maximumLogSizeMB

No

Int32

 5

Specifies the maximum log size (in MBs). Valid values are 1 - 50 MB.

minutesCheckInIntervalMinutes

No

Int32

 480

Specify if you want the agents to check in more than once a day. Valid values are from 10 - 600 minutes. If no value is specified, then the value is nullable and the value will default to 480 minutes.

name

Yes

String

 None

Provides a name for the policy.

synchronizeWithProtectCloud

No

Boolean

 False

Specifies if the agent will have the option to use Protect Cloud to retrieve the latest agent policy information, enabling it to perform synchronization via the cloud.

useVendorAsBackupSource

No

Boolean

 True

If the designated distribution server is not available, the agent will download the latest engine components and data files from the default websites.
Name Required? Type Default Value Description

approvedPatchGroupId

No

Int32

None

Specifies the patch group ID. Cannot be specified when patchDeployment = All or None.

approvedProductLevelId

No

Int32

None

Specifies the product level group ID. Cannot be specified when productLevelDeployment = None or Latest.

deploymentConfigurationId

No

Guid

The ID of the Agent Standard template

Specifies the ID of the template to use when performing a deployment.

deploymentEnabled

No

Boolean

True

Specifies whether to perform a patch deployment.

limitProductLevelDeploymentsPerDay

No

Boolean

None

Specifies whether to limit the number of product level deployments per day. Cannot be specified when productLevelDeployment = None.

maximumProductLevelDeploymentsPerDay

No

Byte

None

Specifies the maximum number of product levels to deploy per day.

name

Yes

String

None

Provides a name for the task.

patchDeployment

No

Enum

All

Specifies if patches that were scanned for and reported missing will be automatically deployed.

  • None: Patches are not deployed.
  • All: All patches are deployed.
  • PatchGroupOnly: Only patches specified in the provided group are deployed.
  • PatchGroupPlusVendorCritical: Only patches specified in the provided group are deployed, plus any critical patches.

productLevelDeployment

No

Enum

None

Specifies if the agent will automatically deploy product levels that are identified as missing by the patch scan.

  • None: Product levels are not deployed.
  • Latest: All latest product levels are deployed.
  • ProductLevelGroupOnly: Only product levels that are specified in the provided group are deployed.

scanConfigurationId

No

Guid

The ID of the Security Patch Scan template

Specifies the ID of the template to use when performing a scan.

schedule

No

ScheduleRequest
Body

See description

Specifies how often the task will run on the target machine. The default schedule is:

  • atStartup = False
  • intervalType = DailyOnSpecifiedDays
  • timeOfDay = 00:00:00
  • daysOfWeek = Saturday
Name Required? Type Default Value Description

deploymentConfigurationId

No

GUID

The ID of the predefined Update All deployment configuration

Specifies the deployment configuration ID to use with this task.

deploymentEnabled

No

Boolean

True

Specifies whether to perform a patch deployment. This is required if deploymentConfigurationId is specified.

name

Yes

String

None

Provides a name for the task.

scanConfigurationId

No

GUID

The ID of the predefined All Patches scan configuration

Specifies the scan configuration ID to use with this task.

schedule

No

ScheduleRequest
Body

See description

Specifies how often the task will run on the target machine. The default schedule is:

  • atStartup = False
  • intervalType = DailyOnSpecifiedDays
  • timeOfDay = 00:00:00
  • daysOfWeek = Saturday
Name Required? Type Default Value Description

atStartup

No

Boolean

False

Specifies if the task will execute at start up. If a scheduled task is missed while a machine is powered off, this can be used to force the task to run whenever a machine is restarted. Also see startupOffset.

initialStartTime

No

TimeSpan

None

Specifies the time of day this task will run for the first time.

Example: 00:00:00

interval

No

TimeSpan

None

Specifies the interval at which this task will run. Valid values are 1 - 100 hours.

intervalType

No

ScheduleIntervalType

DailyOnSpecified
Days

Specifies the choice of schedule interval (hourly, daily, monthly)

dayOfMonth

No

Int16

None

Specifies the day of the month to schedule the task.

randomizedOffset

No

TimeSpan

None

Specifies that the exact start time will be staggered so as not to overtax the console or distribution server with simultaneous requests. Valid values are 1 - 100 minutes.

relativeDayAdditionalDays

No

Int32

None

If non-zero, this value represents an additional day offset to the schedule.

weekOfMonth

No

Int16

None

Specifies the ordinal of the weekday within the month. Valid range of values is 1 - 5.

Example: The 3rd Sunday of the month.

startupOffset

No

TimeSpan

None

Specifies the amount of time (in minutes) to wait when initiating a task on system startup. Valid values are 0 - 100 minutes.

timeOfDay

No

TimeSpan

00:00:00

Specifies the start time of the task at each selected day or relative month day.

daysOfWeek

No

SelectedWeekdays

Saturday

Run the task on the selected days.
Name Description

none

The task is not scheduled to automatically run.

hoursFromSpecifiedTime

Every N hours from the specified time of day.

dailyOnSpecifiedDays

Daily or weekly on the specified days of the week

monthlyOnSpecificDayOfMonth

Monthly on the specified day of the month.

monthlyOnWeekOfMonth

Monthly on the first, second, third, fourth or last occurrence of the specified day during the month.
Name Description

none

No week day specified.

sunday

The task will run on Sunday.

monday

The task will run on Monday.

tuesday

The task will run on Tuesday.

wednesday

The task will run on Wednesday.

thursday

The task will run on Thursday.

friday

The task will run on Friday.

saturday

The task will run on Saturday.

all

All days of the week.

Example with Sample Response

Find all agent policies

GET Request

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

Sample Response

Copy 
{
    "count": 1,
    "value": [
        {
            "allowCancelOperations": True,
            "allowCloudTelemetry": True,
            "allowManualOperations": True,
            "checkInDistributionMinutes": 240,
            "checkInOption": "Minutes",
            "displayIconInNotificationArea": True,
            "id": "4997c76c-3e47-4b97-bae5-265d586431e9",
            "links": {
                "self": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9"
                },
                "tasks": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9/tasks"
                }
            },
            "listeningAgentPort": 4155,
            "loggingLevel": "Normal",
            "maximumLogSizeMB": 5,
            "minutesCheckInIntervalMinutes": 480,
            "name": "Sample Agent Policy",
            "synchronizeWithProtectCloud": False
        }
    ]
}

Other Request Examples

DELETE Request

https://<consoleFQDN:port>/st/console/api/v1.0/policies/fcd2e3af-5d06-4bff-9d7a-8b715d6b8f1e/tasks/84a8d474-08d5-4448-be50-c10c8d06b34a

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/policies?Name=Sample Agent Policy

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9/tasks

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9/tasks?Name=Sample Patch Task

POST Request

Copy 
https://<consoleFQDN:port>/st/console/api/v1.0/policies

{
    "name": "SampleAgentPolicy"
}

This request creates a Linux patch task that uses previously-defined custom scan and deployment configurations. The task will use the default scheduling parameters.

POST Request

Copy 
https://<consoleFQDN:port>/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9/tasks/linuxpatch

{
    "name": "LinuxPatchTaskWithScanDeployConfigs",
    "deploymentEnabled": "True",
    "deploymentConfigurationId": "805a9fe0-2d47-46dd-af0e-b32eb760b3b9",
    "scanConfigurationId": "1dedbb1f-fd3c-48d5-b466-01268dfcee4e"
}

This request creates a Windows patch task that will begin at 12:00 am and then runs every four hours. A patch scan will be performed and all missing patches will be deployed.

POST Request

Copy 
https://<consoleFQDN:port>/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9/tasks/windowspatch

{
    "name": "HourlyWinPatchTask",
    "schedule": {
        "initialStartTime": "00:00:00",
        "intervalType": "HoursFromSpecifiedTime",
        "interval": "04:00:00"
    },
    "deploymentConfigurationId": "227b75d2-8dab-4580-a64a-a5ed381776db",
    "deploymentEnabled": "True",
    "patchDeployment": "All",
    "scanConfigurationId": "69de3984-1d62-4413-bed9-8d388a79405b"
}

This request creates a Windows patch task that runs every Saturday and Sunday at 6:00 pm. It will stagger the exact time the task will be performed by 50 minutes so as not to overtax the console. Only those patches contained in the specified patch group will be deployed by the agent.

POST Request

Copy 
https://<consoleFQDN:port>/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9/tasks/windowspatch

{
    "name": "SaturdayWindowsPatchTask",
    "schedule": {
        "atStartup": "False",
        "intervalType": "DailyOnSpecifiedDays",
        "timeOfDay": "18:00:00",
        "randomizedOffset": "00:50:00",
        "startupOffset": "5",
        "daysOfWeek": "Saturday, Sunday"
    },
    "approvedPatchGroupId": "2",
    "deploymentConfigurationId": "227b75d2-8dab-4580-a64a-a5ed381776db",
    "deploymentEnabled": "true",
    "patchDeployment": "PatchGroupOnly",
    "scanConfigurationId": "69de3984-1d62-4413-bed9-8d388a79405b"
}

This request creates a Windows patch task that runs on the 15th day of each month. The task will run at 10:00 pm and will run at startup if the agent machine was powered off at the scheduled run time.

POST Request

Copy 
https://<consoleFQDN:port>/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9/tasks/windowspatch

{
    "name": "Day15WinPatchTask",
    "schedule": {
        "intervalType": "MonthlyOnSpecificDayOfMonth",
        "dayOfMonth": "15",
        "timeOfDay": "22:00:00",
        "atStartup": "True"
    },
    "deploymentConfigurationId": "227b75d2-8dab-4580-a64a-a5ed381776db",
    "deploymentEnabled": "True",
    "patchDeployment": "All",
    "scanConfigurationId": "69de3984-1d62-4413-bed9-8d388a79405b"
}

This request creates a Windows patch task that runs on the third Saturday of every month. All missing patches will be deployed. In addition, a maximum of two product levels can be deployed in a single day.

POST Request

Copy 
https://<consoleFQDN:port>/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9/tasks/windowspatch

{
    "name": "3rdSaturdayWinPatchTask",
    "schedule": {
        "atStartup": "True",
        "intervalType": "MonthlyOnWeekOfMonth",
        "randomizedOffset": "00:50:00",
        "weekOfMonth": "3",
        "startupOffset": "00:05:00",
        "timeOfDay": "18:00:00",
        "daysOfWeek": "Saturday"
    },
    "approvedProductLevelId": "1",
    "deploymentConfigurationId": "227b75d2-8dab-4580-a64a-a5ed381776db",
    "deploymentEnabled": "true",
    "limitProductLevelDeploymentsPerDay": "True",
    "maximumProductLevelDeploymentsPerDay": "2",
    "patchDeployment": "All",
    "scanConfigurationId": "69de3984-1d62-4413-bed9-8d388a79405b"
}

For a fuller understanding of how to create and use an agent policy, see PowerShell Example: Create and Install an Agent.

Output Models

Name Type Description

allowCancelOperations

Boolean

Allow the user to cancel operations.

allowManualOperations

Boolean

Allow the user to manually initiate tasks.

checkInDistributionMinutes

Int32

Staggers the exact time the agents will check-in so as not to overtax the console (and the default website or the optional distribution server) with simultaneous requests. The valid range is 1 - 999 minutes.

checkInOption

Enum

Specifies how often the agents will check in (synchronize) with the console.

  • Unknown: Unknown check-in state.
  • Minutes: Check in every N minutes.
  • Days: Check in every N days.

daysCheckInIntervalDays

Int32

Applies only if checkInOption = Days. Specifies the number of days between check-ins. Valid values are 1 - 15.

daysCheckInTimeOfDay

TimeSpan

Applies only if checkInOption = Days. Specifies the specific time of time to perform the check-in.

displayIconInNotificationArea

Boolean

(Windows only) Specify if you want to install an icon in the notification area of each agent machine that provides the users of the machines a certain amount of control over the service.

distributionServerId

Int32

Specifies the ID of the distribution server that will be used as the download location.

downloadSource

Enum

Specifies the location from which the agent will download data.

  • VendorOnly: From the vendor over the internet.
  • DistributionServerByIp: From a distribution server based on the endpoint's IP address.
  • DistributionServerSpecific: From a specific distribution server.

id

Guid

The policy ID.

internetProxyCredentialsId

Guid

The internet proxy credentials ID.

links

Links

Shows the related links for the agent policy.

listeningAgentPort

Int32

Specifies the port that the agent will listen on for console commands. If no port number is specified, then the value is nullable and the agent will not be a listening agent.

loggingLevel

AgentLoggingLevel

The amount of logging you want the agent to perform.

maximumLogSizeMB

Int32

Specifies the maximum log size (in MBs).

minutesCheckInIntervalMinutes

Int32

Specify if you want the agents to check in more than once a day. Valid values are from 10 - 600 minutes. If no value is specified, then the value is nullable and the value will default to 480 minutes.

name

String

The policy name.

synchronizeWithProtectCloud

Boolean

Specifies if the agent will have the option to use Protect Cloud to retrieve the latest agent policy information, enabling it to perform synchronization via the cloud.

useVendorAsBackupSource

Boolean

If the designated distribution server is not available, the agent will download the latest engine components and data files from the default websites.
Name Type Description

normal

Enum

Records messages of type Error, Informational and Warning in the log. This is the default.

verbose

Enum

Records messages of type Error, Informational, Warning and Verbose in the log. Logging all message types is typically only necessary when performing troubleshooting tasks.
Name Type Description

approvedPatchGroupId

Int32

The unique ID for the patch group.

approvedProductLevelId

Int32

The unique ID for the product level.

deploymentConfigurationId

Guid

The unique ID for the Windows deployment configuration.

deploymentEnabled

Boolean

Specifies is patch deployment has been enabled.

id

Guid

The task ID.

limitProductLevelDeploymentsPerDay

Boolean

Specifies if is a limit to the number of product level deployments that can be performed in one day.

links

Links

Shows the related links for the task.

maximumProductLevelDeploymentsPerDay

Byte

Specifies the maximum number of product level deployments that can be performed in one day.

name

String

The name of the task.

patchDeployment

Enum

Specifies how patches will be deployed.

productLevelDeployment

Enum

Specifies how product levels will be deployed. Options are:

  • All missing product levels.
  • By product level group.

policyTaskType

 

Specifies whether the task is a WindowsPatch task or a LinuxPatch task.

scanConfigurationId

Guid

The unique ID for the patch scan template.

schedule

Schedule

Specifies when the task will be executed (hourly, daily, or monthly).
Name Type Description

deploymentConfigurationId

Guid

The unique ID for the deployment configuration.

deploymentEnabled

Boolean

Specifies if patch deployment has been enabled.

id

Guid

The unique ID for the task.

links

Links

Shows the related URL for the task.

name

String

The name of the patch task.

policyTaskType

 

Specifies whether it is a WindowsPatch task or a LinuxPatch task.

scanConfigurationId

Guid

The unique ID for the scan configuration.

schedule

Schedule

The schedule that specifies when the task will be executed.
Name Type Description

atStartup

Boolean

Specifies if the task will execute at start up.

dayOfMonth

Int16

The day of the month at which to schedule the task.

daysOfWeek

Enum

The days of the week on which to run the task.

initialStartTime

TimeSpan

The time of day the task will run for the first time.

interval

TimeSpan

The interval at which the task will run.

intervalType

Schedule
IntervalType

The choice of schedule interval (hourly, daily, monthly)

randomizedOffset

TimeSpan

Specifies that the amount to stagger the start time so as not to overtax the console or distribution server with simultaneous requests.

relativeDayAdditionalDays

Int32

If non-zero, then this value represents an additional day offset to the schedule.

startupOffset

TimeSpan

The amount of time (in minutes) to wait when initiating a task on system startup.

timeOfDay

TimeSpan

The start time of the task at each selected day or relative month day.

weekOfMonth

Int16

The ordinal of the weekday with the month. Valid range is 1 - 5.