Agent Policies
An agent 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 agent policy
•Add Windows patch tasks
•Add Linux patch tasks
•Delete an agent 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 |
||||||
|
https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID} |
|||||||
|
https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}/tasks |
URL Parameters | ||||||
|
https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}/tasks/{task ID} |
|||||||
|
POST |
https://<consoleFQDN:port>/st/console/api/v1.0/policies |
||||||
|
https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}/tasks/windowspatch |
|||||||
|
https://<consoleFQDN:port>/st/console/api/v1.0/policies/{policy ID}/tasks/linuxpatch |
|||||||
Input Models
URL Parameters
| Name | Type | Description |
|---|---|---|
|
name |
String |
The name of the agent policy or task. |
Policy Request Body
| 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 | 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 mintues. 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. |
WindowsPatchTask Request Body
| 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 |
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 |
LinuxPatchTask Request Body
| 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 |
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 |
ScheduleRequest Body
| 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 |
|
DailyOnSpecified |
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 |
Saturday |
Run the task on the selected days. |
ScheduleIntervalType
| 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. |
SelectedWeekdays
| 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
{
"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.fakedomain.com:3121/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9"
},
"tasks": {
"href": "https://device-name.fakedomain.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 a task from an agent policy
DELETE Request
https://<consoleFQDN:port>/st/console/api/v1.0/policies/fcd2e3af-5d06-4bff-9d7a-8b715d6b8f1e/tasks/84a8d474-08d5-4448-be50-c10c8d06b34a
Find the policy named Sample Agent Policy
GET Request
https://<consoleFQDN:port>/st/console/api/v1.0/policies?Name=Sample Agent Policy
Find the agent policy with ID 4997c76c-3e47-4b97-bae5-265d586431e9
GET Request
https://<consoleFQDN:port>/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9
Find all Windows and Linux patch tasks in an existing agent policy
GET Request
https://<consoleFQDN:port>/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9/tasks
Find a patch task named Sample Patch Task in an existing agent policy
GET Request
https://<consoleFQDN:port>/st/console/api/v1.0/policies/4997c76c-3e47-4b97-bae5-265d586431e9/tasks?Name=Sample Patch Task
Create a new agent policy with default settings and no tasks
POST Request
https://<consoleFQDN:port>/st/console/api/v1.0/policies
{
"name": "SampleAgentPolicy"
}
Add a Linux patch task to an existing agent policy
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
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"
}
Add an hourly Windows patch task to an existing agent policy
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
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"
}
Add a weekly Windows patch task to an existing agent policy
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
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"
}
Add a Windows patch task that runs on a specific day each month
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
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"
}
Add a monthly Windows patch task that runs on the Nth occurrence of a particular day
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
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"
}
A more complete look at the use of an agent policy within a PowerShell script
For a fuller understanding of how to create and use an agent policy, see PowerShell Example: Create and Install an Agent.
Output Models
Policy
| 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 |
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 mintues. 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. |
AgentLoggingLevel
| 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. |
WindowsPatchTask
| 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 |
Specifies when the task will be executed (hourly, daily, or monthly). |
LinuxPatchTask
| 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 |
The schedule that specifies when the task will be executed. |
Schedule
| 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 |
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. |