{"id":15022672,"url":"https://github.com/puppetlabs/puppetlabs-scheduled_task","last_synced_at":"2025-06-17T13:39:20.081Z","repository":{"id":27317642,"uuid":"113345451","full_name":"puppetlabs/puppetlabs-scheduled_task","owner":"puppetlabs","description":"Manage Scheduled Tasks on Windows 2008 and above","archived":false,"fork":false,"pushed_at":"2025-02-14T12:19:52.000Z","size":1158,"stargazers_count":6,"open_issues_count":12,"forks_count":36,"subscribers_count":95,"default_branch":"main","last_synced_at":"2025-06-04T02:03:46.579Z","etag":null,"topics":["hacktoberfest","module","supported"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-12-06T17:14:34.000Z","updated_at":"2025-02-14T12:18:42.000Z","dependencies_parsed_at":"2023-02-10T16:01:29.097Z","dependency_job_id":"3ceb552b-1e2f-42a9-b251-edcc7a7e7678","html_url":"https://github.com/puppetlabs/puppetlabs-scheduled_task","commit_stats":{"total_commits":504,"total_committers":65,"mean_commits":7.753846153846154,"dds":0.5654761904761905,"last_synced_commit":"2e33411662f089a3ef428e6357fe2c82ebe9ab42"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/puppetlabs/puppetlabs-scheduled_task","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-scheduled_task","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-scheduled_task/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-scheduled_task/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-scheduled_task/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/puppetlabs-scheduled_task/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-scheduled_task/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260370535,"owners_count":22998847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","module","supported"],"created_at":"2024-09-24T19:58:15.503Z","updated_at":"2025-06-17T13:39:15.029Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# scheduled_task\n\n#### Table of Contents\n\n1. [Description](#description)\n2. [Setup - The basics of getting started with scheduled_task](#setup)\n    * [Beginning with scheduled_task](#beginning-with-scheduled_task)\n3. [Usage - Configuration options and additional functionality](#usage)\n4. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n5. [Limitations - OS compatibility, etc.](#limitations)\n6. [License](#license)\n7. [Development - Guide for contributing to the module](#development)\n\n\u003ca id=\"description\"\u003e\u003c/a\u003e\n## Description\n\nThis module adds a new [scheduled_task](https://puppet.com/docs/puppet/latest/types/scheduled_task.html) provider capable of using the more modern Version 2 Windows API for task management.\nThe legacy API does not receive improvements or new features, meaning that if you want to take advantage of improvements to scheduled tasks on Windows you need to use the V2 API.\n\n\u003ca id=\"setup\"\u003e\u003c/a\u003e\n## Setup\n\n\u003ca id=\"beginning-with-scheduled_task\"\u003e\u003c/a\u003e\n### Beginning with scheduled_task\n\nThe scheduled_task module adapts the Puppet [scheduled_task](https://puppet.com/docs/puppet/latest/types/scheduled_task.html) resource to run using a modern API.\nTo get started, install the module and any existing `scheduled_task` resources will use the V2 API **by default**.\nIf you want to continue using the provider for the legacy API you will _need_ to declare that in your manifests.\nFor example:\n\n~~~ puppet\nscheduled_task { 'Run Notepad':\n  command  =\u003e \"notepad.exe\",\n  ...\n  provider =\u003e 'win32_taskscheduler',\n}\n~~~\n\n\u003ca id=\"usage\"\u003e\u003c/a\u003e\n## Usage\n\nScheduled tasks are commonly used to kick off a script either once or on a regular cadence.\nIn this first example we schedule a cleanup script to run this one time.\n\n~~~ puppet\nscheduled_task { 'Disk Cleanup': # Unique name for the scheduled task\n  command   =\u003e \"$::system32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe\",\n  arguments =\u003e '-File \"C:\\\\Scripts\\\\Clear-DiskSpace.ps1\"',\n  enabled   =\u003e 'true',           # This is the default, but including it is good practice. Flip to 'false' to disable the task.\n  trigger   =\u003e [{\n    schedule   =\u003e 'once',        # Defines the trigger type; required.\n    start_time =\u003e '23:20',       # Defines the time the task should run; required.\n    start_date =\u003e '2018-01-01'   # Defaults to the current date; not required.\n  }],\n}\n~~~\n\nIf we need to have the cleanup script run every night we can use a daily trigger.\nJust changing the trigger schedule from `once` to `daily` will do the trick.\nNote that we removed the `start_date` from the trigger - it isn't required and, for this task, isn't important.\n\n~~~ puppet\nscheduled_task { 'Disk Cleanup Nightly':\n  command   =\u003e \"$::system32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe\",\n  arguments =\u003e '-File \"C:\\\\Scripts\\\\Clear-DiskSpace.ps1\"',\n  enabled   =\u003e 'true',\n  trigger   =\u003e [{\n    schedule   =\u003e 'daily',\n    start_time =\u003e '23:20'\n  }],\n}\n~~~\n\nYou can also set your scheduled tasks to repeat during a set time block.\nUsing the cleanup script again, this scheduled task begins at the same time every day and runs once an hour from seven in the morning to seven at night as the SYSTEM account.\n\n~~~ puppet\nscheduled_task { 'Disk Cleanup Daily Repeating':\n  ensure    =\u003e 'present',\n  command   =\u003e \"$::system32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe\",\n  arguments =\u003e '-File \"C:\\\\Scripts\\\\Clear-DiskSpace.ps1\"',\n  enabled   =\u003e 'true',\n  trigger   =\u003e [{\n    'schedule'         =\u003e 'daily',\n    'start_time'       =\u003e '07:00',\n    'minutes_duration' =\u003e '720',   # Specifies the length of time, in minutes, the task is active\n    'minutes_interval' =\u003e '60'     # Causes the task to run every hour\n  }],\n  user      =\u003e 'system',           # Specifies the account to run the task as\n}\n~~~\n\nThe downside to that task is that it causes the cleanup script to run _every_ day, even on the weekends when there is no activity.\nWe can instead use a weekly trigger to fix this:\n\n~~~puppet\nscheduled_task { 'Disk Cleanup Weekly Repeating':\n  ensure    =\u003e 'present',\n  command   =\u003e \"$::system32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe\",\n  arguments =\u003e '-File \"C:\\\\Scripts\\\\Clear-DiskSpace.ps1\"',\n  enabled   =\u003e 'true',\n  trigger   =\u003e [{\n    'schedule'         =\u003e 'weekly',\n    'start_time'       =\u003e '07:00',\n    'day_of_week'      =\u003e ['mon', 'tues', 'wed', 'thurs', 'fri'], # Note the absence of Saturday and Sunday\n    'minutes_interval' =\u003e '60',\n    'minutes_duration' =\u003e '720'\n  }],\n  user      =\u003e 'system',\n}\n~~~\n\nSimilarly, we can schedule our cleanup script to run monthly if we decide the cleanup script doesn't need to run as often or is particularly resource intensive.\nThe following example sets the scheduled task to run at 0700 on the first day of the month every month:\n\n~~~puppet\nscheduled_task { 'Disk Cleanup Monthly First Day':\n  ensure    =\u003e 'present',\n  command   =\u003e \"$::system32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe\",\n  arguments =\u003e '-File \"C:\\\\Scripts\\\\Clear-DiskSpace.ps1\"',\n  enabled   =\u003e 'true',\n  trigger   =\u003e [{\n    'schedule'   =\u003e 'monthly',\n    'start_time' =\u003e '07:00',\n    'on'         =\u003e [1]        # Run every month on the first day of the month.\n  }],\n  user      =\u003e 'system',\n}\n~~~\n\nWith the monthly trigger above there is no guarantee that the first day of the month is on a weekend.\nThis means that there's a reasonable chance that the script will execute during working hours and impact productivity.\nWe can specify the trigger to run on the task on the _first saturday_ of the month instead of the first day:\n\n~~~puppet\nscheduled_task { 'Disk Cleanup Monthly First Saturday':\n  ensure    =\u003e 'present',\n  command   =\u003e \"$::system32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe\",\n  arguments =\u003e '-File \"C:\\\\Scripts\\\\Clear-DiskSpace.ps1\"',\n  enabled   =\u003e 'true',\n  trigger   =\u003e [{\n    'schedule'        =\u003e 'monthly',\n    'start_time'      =\u003e '07:00',\n    'day_of_week'     =\u003e 'sat',     # Specify the day of the week to trigger on\n    'which_occurence' =\u003e 'first'    # Specify which occurance to trigger on, up to fifth\n  }],\n  user      =\u003e 'system',\n}\n~~~\n\nYou might also want a task to run every time the computer boots.\n\n~~~puppet\nscheduled_task { 'Disk Cleanup On Restart':\n  ensure        =\u003e 'present',\n  compatibility =\u003e 2,\n  command       =\u003e \"$::system32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe\",\n  arguments     =\u003e '-File \"C:\\\\Scripts\\\\Clear-DiskSpace.ps1\"',\n  enabled       =\u003e 'true',\n  trigger       =\u003e [{\n    'schedule'  =\u003e 'boot',\n    'minutes_interval' =\u003e '60',\n    'minutes_duration' =\u003e '720'\n  }],\n  user          =\u003e 'system',\n}\n~~~\n* Note: Duration properties like `minutes_duration` and `minutes_interval` must have `compatibility =\u003e 2` or higher specified for `boot` triggers. Windows does not support those options at the \"Windows XP or Windows Server 2003 computer\" compatibility level which is the default when compatibility is left unspecified.\n\nIf you want a task to run at logon, use the `logon` trigger:\n\n~~~puppet\nscheduled_task { 'example_notepad':\n  compatibility =\u003e 2,\n  command       =\u003e 'C:\\\\Windows\\\\System32\\\\notepad.exe',\n  trigger       =\u003e [{\n    schedule =\u003e 'logon',\n    user_id  =\u003e 'MyDomain\\\\SomeUser'\n  }],\n}\n~~~\n\n\u003ca id=\"reference\"\u003e\u003c/a\u003e\n## Reference\n\n### Provider\n\n* win32_taskscheduler: This legacy provider manages scheduled tasks on Windows imitating the legacy API.\n* taskscheduler_api2: Adapts the Puppet scheduled_task resource to use the modern Version 2 API.\n\n### Type\n\n#### scheduled_task\n\nInstalls and manages Windows Scheduled Tasks.\nAll attributes except `name`, `command`, and `trigger` are optional; see the description of the [`trigger`](#trigger) attribute for details on setting schedules.\n\n##### `name`\n\nThe name assigned to the scheduled task.\nThis will uniquely identify the task on the system.\nIf specifying a scheduled task inside of subfolder(s), specify the path from root, such as `subfolder\\\\mytaskname`.\nThis will create the scheduled task `mytaskname` in the container named `subfolder`.\nYou can only specify a taskname inside of subfolders if the compatibility is set to 2 or higher and when using the taskscheduler2_api provider.\n\n##### `ensure`\n\nThe basic property that the resource should be in.\n\nValid values are `present`, `absent`.\n\n##### `arguments`\n\nAny arguments or flags that should be passed to the command.\nMultiple arguments should be specified as a space-separated string.\n\n##### `command`\n\nThe full path to the application to run, without any arguments.\n\n##### `description`\n\nThe description of the scheduled task.\n\n##### `enabled`\n\nWhether the triggers for this task should be enabled.\nThis attribute affects every trigger for the task; triggers cannot be enabled or disabled individually.\n\nValid values are `true`, `false`.\n\n##### `password`\n\nThe password for the user specified in the 'user' attribute.\nThis is only used if specifying a user other than 'SYSTEM'.\nThis parameter will not be used to determine if a scheduled task is in sync or not because there is no way to retrieve the password used to set the account information for a task.\n\n##### `compatibility`\n\nThis provider feature is only available with the `taskscheduler_api2` provider.\n\nThe compatibility level associated with the task.\nDefaults to 1 for backward compatibility.\nCan be set to:\n\n- `1` for compatibility with tasks on a Windows XP or Windows Server 2003 computer\n- `2` for compatibility with tasks on a Windows 2008 computer\n- `3` for compatibility with new features for tasks introduced in Windows 7 and 2008R2\n- `4` for compatibility with new features for tasks introduced in Windows 8, Server 2012R2 and Server 2016\n- `6` for compatibility with new features for tasks introduced in Windows 10\n  - **NOTE:** This compatibility setting is _not_ documented and we recommend that you do not use it.\n\nSee the [Microsoft documentation on compatibility levels and their differences](https://msdn.microsoft.com/en-us/library/windows/desktop/aa384138\\(v=vs.85\\).aspx) for more information.\n\n##### `provider`\n\nThe specific backend to use for this scheduled_task resource.\nYou will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform.\n\nAvailable providers are:\n\n###### win32_taskscheduler\n\nThis legacy provider manages scheduled tasks on Windows using the v2 api but only manages scheduled tasks whose compatibility level is set to 1 (Windows XP or Windows Server 2003).\nIt is a backward compatible update and replaces the provider of the same name in Puppet core.\n\n###### taskscheduler_api2\n\nThis provider manages scheduled tasks on Windows using the v2 api and can manage scheduled tasks of any compatibility level.\n\n* Default for `operatingsystem` == `windows`.\n\n##### `trigger`\n\nOne or more triggers defining when the task should run.\nA single trigger is represented as a hash, and multiple triggers can be specified with an array of hashes.\n\nA trigger can contain the following keys:\n\nFor all triggers:\n\n* `schedule` (Required) — What kind of trigger this is.\n  Valid values are `daily`, `weekly`, `monthly`, `once`, `boot`, or `logon`.\n  Each kind of trigger is configured with a different set of keys; see the sections below (once triggers only need a start time/date.)\n* `start_time` (Required except for `boot`) — The time of day when the trigger should first become active.\n  Several time formats will work, but we suggest 24-hour time formatted as HH:MM.\n* `start_date` — The date when the trigger should first become active.\n  Defaults to the current date.\n  You should format dates as YYYY-MM-DD, although other date formats may work (under the hood, this uses Date.parse).\n* `minutes_interval` — The repeat interval in minutes.\n* `minutes_duration` — The duration in minutes, needs to be greater than the minutes_interval.\n* For daily triggers:\n  * `every` — How often the task should run, as a number of days.\n    Defaults to 1.\n    \"2\" means every other day, \"3\" means every three days, etc.\n* For weekly triggers:\n  * `every` — How often the task should run, as a number of weeks.\n    Defaults to 1.\n    \"2\" means every other week, \"3\" means every three weeks, etc.\n  * `day_of_week` — Which days of the week the task should run, as an array.\n    Defaults to all days.\n    Each day must be one of `mon`, `tues`, `wed`, `thurs`, `fri`, `sat`, `sun`, or `all`.\n* For monthly (by date) triggers:\n  * `months` — Which months the task should run, as an array.\n    Defaults to all months.\n    Each month must be an integer between 1 and 12.\n  * `on` (Required) — Which days of the month the task should run, as an array.\n    Each day must be an integer between 1 and 31.\n    * The string `last` may be used in the array for this property to trigger a\n    task to run on the last day of each selected month. This feature is only\n    available for tasks with compatibility level `2` or higher.\n* For monthly (by weekday) triggers:\n  * `months` — Which months the task should run, as an array. Defaults to all months. Each month must be an integer between 1 and 12.\n  * `day_of_week` (Required) — Which day of the week the task should run, as an array with only one element.\n    Each day must be one of `mon`, `tues`, `wed`, `thurs`, `fri`, `sat`, `sun`, or `all`.\n  * `which_occurrence` (Required) — The occurrence of the chosen weekday when the task should run. Must be one of `first`, `second`, `third`, `fourth`, or `last`.\n* For `logon` triggers:\n  * `user_id` --- The `user_id` specifies _which_ user this task will trigger\n    for when they logon. If unspecified, or if specified as `undef` or an empty\n    string, the task will trigger whenever **any** user logs on. This property\n    can be specified in one of the following formats:\n    * Local User: `\"Administrator\"`\n    * Domain User: `\"MyDomain\\\\MyUser\"`\n    * SID: `\"S-15-...\"`\n    * Any User: `''` or `undef`\n\n##### `user`\n\nThe user to run the scheduled task as.\nDefaults to 'SYSTEM'.\n\nPlease also note that Puppet must be running as a privileged user in order to manage `scheduled_task` resources.\nRunning as an unprivileged user will result in 'access denied' errors.\n\n##### `working_dir`\n\nThe full path of the directory in which to start the command.\n\n\u003ca id=\"limitations\"\u003e\u003c/a\u003e\n## Limitations\n\nFor a full list of supported OS, check [metadata.json](https://github.com/puppetlabs/puppetlabs-scheduled_task/blob/main/metadata.json).\n\n\u003ca id=\"license\"\u003e\u003c/a\u003e\n## License\n\nThis codebase is licensed under the Apache2.0 licensing, however due to the nature of the codebase the open source dependencies may also use a combination of [AGPL](https://opensource.org/license/agpl-v3/), [BSD-2](https://opensource.org/license/bsd-2-clause/), [BSD-3](https://opensource.org/license/bsd-3-clause/), [GPL2.0](https://opensource.org/license/gpl-2-0/), [LGPL](https://opensource.org/license/lgpl-3-0/), [MIT](https://opensource.org/license/mit/) and [MPL](https://opensource.org/license/mpl-2-0/) Licensing.\n\n\u003ca id=\"development\"\u003e\u003c/a\u003e\n## Development\n\nPuppet modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can't access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve, therefore want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. \nIf you would like to contribute to this module, please follow the rules in the [CONTRIBUTING.md](https://github.com/puppetlabs/puppetlabs-scheduled_task/blob/main/CONTRIBUTING.md). For more information, see our [module contribution guide.](https://puppet.com/docs/puppet/latest/contributing.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-scheduled_task","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-scheduled_task","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-scheduled_task/lists"}