Scheduled tasks enable you to automatically
perform specific Server & Workload Protection tasks on a schedule. You can
use the Server & Workload Protection API to perform all the scheduled
task-related activities that you can do using the Server & Workload Protection console, such as performing recommendation scans, checking for security updates,
and
synchronizing cloud accounts. See Schedule Server & Workload Protection to perform tasks for more information
about the available types of scheduled tasks.
After you create a scheduled task you can run
it at any time. You can also run them immediately upon creation and then immediately
delete
them. In this way, scheduled tasks provide access to several powerful and convenient
tools
for automating Server & Workload Protection via the API and SDK.
Related classes
You use the following SDK classes when working
with scheduled tasks:
ScheduledTasksApi
: Provides access to scheduled tasks on Server & Workload Protection. You can create, describe, modify, delete, search, and list scheduled tasksScheduledTask
: Represents the scheduled taskScheduleDetails
: Defines the schedule for running the scheduled task- Task parameter classes: Define the task that the scheduled task performs. (See Configure the task for a list of classes.)
Create a scheduled task
Use the following general procedure to create a
scheduled task (more detailed information
follows):
Procedure
- Create a
ScheduledTask
object and configure the general properties. - Create a
ScheduleDetails
object to define the schedule on which the task runs, and add it to theScheduledTask
object. - Create a task parameter class to define the
task to perform, and add it to the
ScheduledTask
object. A different task parameter class is available for each type of task. Note that the Synchronize Users and Check for Software Updates tasks do not require a task parameter class. - Use a
ScheduledTasksApi
object to create the scheduled task on Server & Workload Protection.
What to do next
Configure general properties
When you create a
ScheduledTask
object, use it to
define the general properties:- Name
- The type of task that it schedules
- Whether the task is enabled
- Whether the task runs after it is created
discover_computer_task = api.ScheduledTask() discover_computer_task.name = "Discover Computers - Daily" discover_computer_task.type = "discover-computers" discover_computer_task.run_now = False
After
you set the general properties, configure the
schedule and the task and add them to the
ScheduledTask
object.Create the schedule
The following properties of a
ScheduleDetails
object controls
when a task runs:- The recurrence type -- either monthly, weekly, daily, hourly, or none (to run once)
- The recurrence of runs for daily, weekly, and monthly schedules. Daily and weekly recurrences are expressed as an interval such as every second day. For monthly recurrence, you specify specific months.
- The number of times the task runs (recurrence count). The task is automatically deleted after the task runs the specified number of times. This is useful when you want to run a scheduled task only once.
- The start time, for daily, weekly, and monthly recurrence types, determines the time of day that the task runs, specified in milliseconds (Epoch time). When the recurrence is expressed in intervals for daily and weekly schedules, the days or weeks on which subsequent runs occur are calculated from the start time. For example, when the recurrence is every second day, a start time that falls on a Monday means that the next day the task runs is Wednesday.
- The time zone to use to interpret the start time.
Note that
ScheduleDetails
objects are not persisted as a separate entity on Server & Workload Protection, but are stored as part of a scheduled task.
You cannot persist a ScheduleDetails
object for later re-use with other
scheduled tasks.Use the following general procedure to create
the schedule:
Procedure
- Create a
ScheduleDetails
object and set the recurrence type. - Create a
ScheduleParameters
object that corresponds with the recurrence type, configure the recurrence of runs and the start time, and add it to theScheduledTask
object. The availableScheduleParameters
objects areDailyScheduleParameters
,HourlyScheduleParameters
,MonthlyScheduleParameters
, andOnceOnlyScheduleParameters
. - Optionally, set the time zone on the
ScheduledTask
object.
What to do next
For example, create a
ScheduleDetails
object for a
daily schedule:daily_schedule = api.ScheduleDetails() daily_schedule.recurrence_type = "daily"
The
DailyScheduleParameters
class
corresponds with a daily schedule. This example
configures the schedule using a custom
interval:daily_schedule_parameters = api.DailyScheduleParameters() daily_schedule_parameters.frequency_type = "custom" daily_schedule_parameters.custom_interval = custom_interval daily_schedule_parameters.start_time = start_time
Finally,
add the schedule parameters to the
ScheduleDetails
object:daily_schedule.daily_schedule_parameters = daily_schedule_parameters
Example: Daily schedule
The following example creates a daily schedule
for use with a scheduled task.
# Create a ScheduleDetails object and set the recurrence type daily_schedule = api.ScheduleDetails() daily_schedule.recurrence_type = "daily" # Specify when the task runs daily_schedule_parameters = api.DailyScheduleParameters() # Use a custom frequency type to run the task at daily intervals. # Every day and only weekdays are other available frequency types. daily_schedule_parameters.frequency_type = "custom" daily_schedule_parameters.custom_interval = custom_interval daily_schedule_parameters.start_time = start_time # Add the schedule parameters to the schedule details daily_schedule.daily_schedule_parameters = daily_schedule_parameters
Example: Monthly schedule
The following example creates a monthly
schedule for use with a scheduled task.
# Create a ScheduleDetails object and set the recurrence type quarterly_schedule = api.ScheduleDetails() quarterly_schedule.recurrence_type = "monthly" # Specify when the task runs monthly_schedule_parameters = api.MonthlyScheduleParameters() # Set the schedule to run on a specific day of the month. # Other options are the last day of the month, or a specific weekday of a specific week monthly_schedule_parameters.frequency_type = "day-of-month" # Set the day monthly_schedule_parameters.day_of_month = day # Set the months to be quarterly monthly_schedule_parameters.months = ["january", "april", "july", "october"] # Add the schedule parameters to the schedule details quarterly_schedule.monthly_schedule_parameters = monthly_schedule_parameters
Configure the task
Each of the following task parameter classes
corresponds with a type of scheduled task. You use
these classes to configure the task:
CheckForSecurityUpdatesTaskParameters
DiscoverComputersTaskParameters
GenerateReportTaskParameters
RunScriptTaskParameters
ScanForIntegrityChangesTaskParameters
ScanForMalwareTaskParameters
ScanForOpenPortsScanParameters
ScanForRecommendationsScanParameters
SendAlertSummaryScanParameters
SendPolicyTaskParameters
SynchronizeCloudAccountTaskParameters
SynchronizeDirectoryTaskParameters
SynchronizeVCenterTaskParameters
UpdateSuspiciousObjectsListTaskParameters
TipThe permissions that have been
granted to your API key determine which task
parameter classes are available. For example, when
the primary tenant restricts tenants from using
scripts, the
RunScriptTaskParameters class is
not available to tenants. |
Use the following general procedure to create
and configure the task object:
Procedure
- Create a task parameters object from the
class that corresponds with the type of scheduled
task that you are creating.
Note
The Synchronize Users and Check for Software Updates tasks do not require configuration. For those tasks, do not create a task parameter class. - Configure the task parameters object to
define how the task behaves:
- Each class defines different properties that you need to configure.
- Several task parameter classes require a
ComputerFilter
object to identify the computers to act on. - Depending on the type of task parameters
object, you might need to add a
Recipients
,TagFilter
, orTimeRange
object.
What to do next
For example, create a
ScheduledTask
object and set the
task type so that it discovers computers:discover_computer_task = api.ScheduledTask() discover_computer_task.type = "discover-computers"
Create
the corresponding DiscoverComputerTaskParameters
object and set the property values:
task_parameters = api.DiscoverComputersTaskParameters() task_parameters.discovery_type = "range" task_parameters.iprange_low = "192.168.60.0" task_parameters.iprange_high = "192.168.60.255" task_parameters.scan_discovered_computers = True
Then, add the DiscoverComputerTaskParameters object to the ScheduledTask object, and
create the
scheduled task on Server & Workload Protection:
discover_computer_task.discover_computers_task_parameters = task_parameters scheduled_tasks_api = api.ScheduledTasksApi(api.ApiClient(configuration)) scheduled_task = scheduled_tasks_api.create_scheduled_task(discover_computer_task, api_version)
Example: Create a scheduled task
The following example creates a scheduled task
that discovers computers.
# Create the ScheduledTask object and set the name and type. Do not run now.
discover_computer_task = api.ScheduledTask()
discover_computer_task.name = "Discover Computers - Daily"
discover_computer_task.type = "discover-computers"
discover_computer_task.run_now = False
# Call the createDailyScheduleDetails method to obtain a daily ScheduleDetails object.
# Set the start time to 03:00 DST.
discover_computer_task.schedule_details = create_daily_schedule_details(api, api_exception, 2, 1536030000000);
# Create a DiscoverComputersTaskParameters object.
# The scan applies to a range of IP addresses, and scans discovered computers for open ports.
task_parameters = api.DiscoverComputersTaskParameters()
task_parameters.discovery_type = "range"
task_parameters.iprange_low = "192.168.60.0"
task_parameters.iprange_high = "192.168.60.255"
task_parameters.scan_discovered_computers = True
discover_computer_task.discover_computers_task_parameters = task_parameters
# Create the scheduled task on Server & Workload Protection
scheduled_tasks_api = api.ScheduledTasksApi(api.ApiClient(configuration))
scheduled_task = scheduled_tasks_api.create_scheduled_task(discover_computer_task, api_version)
return scheduled_task.id
Also
see the Create a Scheduled Task operation in the
API Reference.
Create, run, and delete a scheduled task
Create a scheduled task that runs immediately
when it is created, and then delete the scheduled task. Use scheduled tasks in this
way to
conveniently access many Server & Workload Protection capabilities via the
API.
TipWhen the recurrence count of
the
ScheduleDetails object is set
to 1, the scheduled task is automatically deleted
after it runs. |
Use the following general procedure to create,
run, and delete a scheduled task:
Procedure
- Create and configure a
ScheduledTask
object:- Set the scheduled task to run now.
- Set the task to run once to ensure subsequent runs do not occur.
- Create and configure the task details as required.
- Create a
ScheduledTasksApi
object and use it to create the scheduled task on Server & Workload Protection. - Use the
ScheduledTasksApi
object to delete the scheduled task on Server & Workload Protection.
What to do next
The following example creates, runs, and
deletes a scheduled task that checks for security
updates.
# Set the name and task type
check_for_security_updates = api.ScheduledTask()
check_for_security_updates.name = "Check For Security Updates"
check_for_security_updates.type = "check-for-security-updates"
# Run when the scheduled task is created
check_for_security_updates.run_now = True
# Use a once-only recurrence
schedule_details = api.ScheduleDetails()
schedule_details.recurrence_type = 'none'
# Set the recurrence count to 1 so that the task is deleted after running
schedule_details.recurrence_count = 1
schedule_parameters = api.OnceOnlyScheduleParameters()
# The start time is not important because it is deleted after running
schedule_parameters.start_time = 0
schedule_details.once_only_schedule_parameters = schedule_parameters
check_for_security_updates.schedule_details = schedule_details
# Scan all computers
computer_filter = api.ComputerFilter()
computer_filter.type = "all-computers"
# Create the task parameters object and add the computer filter
task_parameters = api.CheckForSecurityUpdatesTaskParameters()
task_parameters.computer_filter = computer_filter
check_for_security_updates.check_for_security_updates_task_parameters = task_parameters
# Create the scheduled task on Server & Workload Protection
scheduled_tasks_api = api.ScheduledTasksApi(api.ApiClient(configuration))
scheduled_task = scheduled_tasks_api.create_scheduled_task(check_for_security_updates, api_version)
return scheduled_task.id
Also
see the Create a Scheduled Task operation in the
API Reference.
Run an existing scheduled task
You can run an existing scheduled task at any
time. For example, a scheduled task that scans the network for computers has been
created
on Server & Workload Protection and runs every 2 days. However, you need
to perform the scan now, so you immediately run the scheduled task.
Use the following general procedure to run a
scheduled task:
Procedure
- Create a
ScheduledTask
object and set therunNow
property totrue
. Do not set any other properties. - Obtain the ID of the existing scheduled task to run.
- Create a
ScheduledTasksApi
object and use it to modify the existing scheduled task according to theScheduledTask
object that you created.
What to do next
When you set
runNow
to
true
, the scheduled task is
configured to run at the current time of day for
the configured interval. You might want to reset
the start time to the original value after you run
the scheduled task.The following example runs the discover
computers scheduled task.
# Create the ScheduledTask object and set to run now
scheduled_task = api.ScheduledTask()
scheduled_task.run_now = True
# Modify the scheduled task on Server & Workload Protection
scheduled_tasks_api = api.ScheduledTasksApi(api.ApiClient(configuration))
scheduled_tasks_api.modify_scheduled_task(scheduled_task_id, scheduled_task, api_version)
Also
see the Modify a Scheduled Task operation in the
API Reference.