Views:
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 Parent topic

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 tasks
  • ScheduledTask: Represents the scheduled task
  • ScheduleDetails: 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 Parent topic

Use the following general procedure to create a scheduled task (more detailed information follows):

Procedure

  1. Create a ScheduledTask object and configure the general properties.
  2. Create a ScheduleDetails object to define the schedule on which the task runs, and add it to the ScheduledTask object.
  3. 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.
  4. Use a ScheduledTasksApi object to create the scheduled task on Server & Workload Protection.

What to do next

Configure general properties Parent topic

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 Parent topic

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

  1. Create a ScheduleDetails object and set the recurrence type.
  2. Create a ScheduleParameters object that corresponds with the recurrence type, configure the recurrence of runs and the start time, and add it to the ScheduledTask object. The available ScheduleParameters objects are DailyScheduleParameters, HourlyScheduleParameters, MonthlyScheduleParameters, and OnceOnlyScheduleParameters.
  3. 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 Parent topic

The following example creates a daily schedule for use with a scheduled task.
View source
# 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 Parent topic

The following example creates a monthly schedule for use with a scheduled task.
View source
# 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 Parent topic

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
Tip
Tip
The 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

  1. Create a task parameters object from the class that corresponds with the type of scheduled task that you are creating.
    Note
    Note
    The Synchronize Users and Check for Software Updates tasks do not require configuration. For those tasks, do not create a task parameter class.
  2. 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, or TimeRange 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 Parent topic

The following example creates a scheduled task that discovers computers.
View source
# 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 Parent topic

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.
Tip
Tip
When 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

  1. 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.
  2. Create a ScheduledTasksApi object and use it to create the scheduled task on Server & Workload Protection.
  3. 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.
View source
# 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 Parent topic

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

  1. Create a ScheduledTask object and set the runNow property to true. Do not set any other properties.
  2. Obtain the ID of the existing scheduled task to run.
  3. Create a ScheduledTasksApi object and use it to modify the existing scheduled task according to the ScheduledTask 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.
View source
# 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.