Forge Home

scheduled_task

pdk
supported
Manage scheduled tasks for Windows Server 2008 and newer operating systems.

260,322 downloads

17,210 latest version

4.0 quality score

Version information

  • 3.0.1 (latest)
  • 3.0.0
  • 2.3.1
  • 2.3.0
  • 2.2.1
  • 2.2.0
  • 2.1.0
  • 2.0.1
  • 2.0.0
  • 1.0.1
  • 1.0.0
  • 0.4.0
  • 0.3.0
  • 0.2.0
  • 0.1.0
released Jun 14th 2021
This version is compatible with:
  • Puppet Enterprise 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x
  • Puppet >= 6.0.0 < 8.0.0
  • Windows

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'puppetlabs-scheduled_task', '3.0.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppetlabs-scheduled_task
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-scheduled_task --version 3.0.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

puppetlabs/scheduled_task — version 3.0.1 Jun 14th 2021

Reference

Table of Contents

Resource types

Resource types

scheduled_task

Installs and manages Windows Scheduled Tasks.

  • Note All attributes except name, command, and trigger are optional; see the description of the trigger attribute for details on setting schedules."

Properties

The following properties are available in the scheduled_task type.

arguments

Any arguments or flags that should be passed to the command. Multiple arguments should be specified as a space-separated string.

command

The full path to the application to run, without any arguments.

compatibility

Valid values: 1, 2, 3, 4, 5, 6

The compatibility level associated with the task. May currently be set to 1 for compatibility with tasks on a Windows XP or Windows Server 2003 computer, 2 for compatibility with tasks on a Windows 2008 computer, 3 for compatibility with new features for tasks introduced in Windows 7 and 2008R2, 4 for compatibility with new features for tasks introduced in Windows 8, Server 2012R2 and Server 2016, or 5 / 6 for compatibility with new features for tasks introduced in Windows 10

Default value: 1

enabled

Valid values: true, false

Whether the triggers for this task should be enabled. This attribute affects every trigger for the task; triggers cannot be enabled or disabled individually.

Default value: true

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

trigger

One or more triggers defining when the task should run. A single trigger is represented as a hash, and multiple triggers can be specified with an array of hashes.

A trigger can contain the following keys:

  • For all triggers:
    • schedule (Required) --- What kind of trigger this is. Valid values are daily, weekly, monthly, or once. Each kind of trigger is configured with a different set of keys; see the sections below. (once triggers only need a start time/date.)
    • start_time (Required) --- The time of day when the trigger should first become active. Several time formats will work, but we suggest 24-hour time formatted as HH:MM.
    • start_date --- The date when the trigger should first become active. Defaults to the current date. You should format dates as YYYY-MM-DD, although other date formats may work. (Under the hood, this uses Date.parse.)
    • minutes_interval --- The repeat interval in minutes.
    • minutes_duration --- The duration in minutes, needs to be greater than the minutes_interval.
    • disable_time_zone_synchronization --- Whether or not to disable the synchronise across time zones function. Due to difficulties with the api this is non idempotent. Defaults to false
  • For daily triggers:
    • every --- How often the task should run, as a number of days. Defaults to 1. ("2" means every other day, "3" means every three days, etc.)
  • For weekly triggers:
    • every --- How often the task should run, as a number of weeks. Defaults to 1. ("2" means every other week, "3" means every three weeks, etc.)
    • day_of_week --- Which days of the week the task should run, as an array. Defaults to all days. Each day must be one of mon, tues, wed, thurs, fri, sat, sun, or all.
  • For monthly (by date) triggers:
    • months --- Which months the task should run, as an array. Defaults to all months. Each month must be an integer between 1 and 12.
    • on (Required) --- Which days of the month the task should run, as an array. Each day must be an integer between 1 and 31 or the string last. The string last is only supported for tasks with level 2 compatibility or higher.
  • For monthly (by weekday) triggers:
    • months --- Which months the task should run, as an array. Defaults to all months. Each month must be an integer between 1 and 12.
    • day_of_week (Required) --- Which day of the week the task should run, as an array with only one element. Each day must be one of mon, tues, wed, thurs, fri, sat, sun, or all.
    • which_occurrence (Required) --- The occurrence of the chosen weekday when the task should run. Must be one of first, second, third, fourth, or fifth.
  • For logon triggers:
    • user_id --- The user_id specifies which user this task will trigger for when they logon. If unspecified, or if specified as undef or an empty string, the task will trigger whenever any user logs on. This property can be specified in one of the following formats:
      • Local User: "Administrator"
      • Domain User: "MyDomain\\MyUser"
      • SID: "S-15-..."
      • Any User: '' or undef

Examples:

# Run once on January 1, 2018, at 11:20PM
trigger => {
  schedule   => 'once',
  start_time => '23:20',     # Defines the time the task should run; required.
  start_date => '2018-01-01' # Defaults to the current date; not required.
}

# Run daily at 11:20PM
trigger => {
  schedule   => 'daily',
  start_time => '23:20'
}

# Run every day at 7:00AM and once per hour until 7:00PM
trigger => {
  'schedule'         => 'daily',
  'start_time'       => '07:00',
  'minutes_duration' => '720',   # Specifies the length of time, in minutes, the task is active
  'minutes_interval' => '60'     # Causes the task to run every hour
}

# Run every weekday at 7:00AM and once per hour until 7:00PM
# Will NOT run on Saturday/Sunday
trigger => {
  'schedule'         => 'weekly',
  'start_time'       => '07:00',
  'day_of_week'      => ['mon', 'tues', 'wed', 'thu', 'fri'], # Note the absence of Sunday and Monday
  'minutes_interval' => '60',
  'minutes_duration' => '720'
}

# Run on the first of every month at 7:00AM
trigger => {
  'schedule'   => 'monthly',
  'start_time' => '07:00',
  'on'         => [1]        # Run every month on the first day of the month.
}

# Run on the first _Saturday_ of every month at 7:00AM
trigger => {
  'schedule'        => 'monthly',
  'start_time'      => '07:00',
  'day_of_week'     => 'sat',     # Specify the day of the week to trigger on
  'which_occurence' => 'first'    # Specify which occurance to trigger on, up to fifth
}

# Run on boot, then once per hour for 12 hours
trigger => {
  'schedule'         => 'boot',
  'minutes_interval' => '60',   # This setting in can only be used with compatibility 2 or higher
  'minutes_duration' => '720'   # This setting in can only be used with compatibility 2 or higher
}

# Run whenever MyDomain\\SomeUser logs onto the computer
trigger => {
  schedule => 'logon',
  user_id  => 'MyDomain\\SomeUser'
}
user

The user to run the scheduled task as. Please note that not all security configurations will allow running a scheduled task as 'SYSTEM', and saving the scheduled task under these conditions will fail with a reported error of 'The operation completed successfully'. It is recommended that you either choose another user to run the scheduled task, or alter the security policy to allow v1 scheduled tasks to run as the 'SYSTEM' account. Defaults to 'SYSTEM'.

Please also note that Puppet must be running as a privileged user in order to manage scheduled_task resources. Running as an unprivileged user will result in 'access denied' errors.

If a user is specified without an accompanying password, and the user does not end with a dollar sign ($) signifying a Group Managed Service Account (gMSA), the task will be created with Run only when user is logged on specified.

Default value: system

working_dir

The full path of the directory in which to start the command.

Parameters

The following parameters are available in the scheduled_task type.

name

namevar

The name assigned to the scheduled task. This will uniquely identify the task on the system. If specifying a scheduled task inside of subfolder(s), specify the path from root, such as subfolder/mytaskname. This will create the scheduled task mytaskname in the container named subfolder. You can only specify a taskname inside of subfolders if the compatibility is set to 2 or higher and when using the taskscheduler2_api provider.

password

The password for the user specified in the 'user' attribute. This is only used if specifying a user other than 'SYSTEM'. Since there is no way to retrieve the password used to set the account information for a task, this parameter will not be used to determine if a scheduled task is in sync or not.

provider

The specific backend to use for this scheduled_task resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.