> For the complete documentation index, see [llms.txt](https://www.osdeploy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.osdeploy.com/archive/blog/2021/scheduled-tasks/building-a-task.md).

# Building a Task

Things can get very complicated when building a task as there are several parameters to define, so its much easier to use Splatting to define the Variables. I suggest you get to know what Splatting is before going any further

{% embed url="<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting?view=powershell-5.1>" %}

## Building a Scheduled Task

I'll start with some basic information I need about the Scheduled Task. Since this Scheduled Task will run Admin level, it will need to run with Admin level access

#### TASKNAME

This will be the Name of the Task you are creating in Task Scheduler

#### TASKPATH

While not necessary, it keeps Tasks from cluttering up the ROOT of Task Scheduler. If you are creating several Tasks for your Organization, I recommend using a common root, such as 'Corporate'

![](https://3996045416-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDKRxGiKLYjW1gana2O%2F-MRQFDRQNHzPSIVCldQN%2F-MRQFdUM2-4LchCikdfL%2Fimage.png?alt=media\&token=1d3bdbc4-3176-42f5-bb48-534de9291bf1)

#### DESCRIPTION

Again, not necessary, but highly recommended so you know exactly what is happening in the Task. I recommend putting some Version information in the Description

### Task Properties

In this example, I am going to create a Scheduled Task that will set the PowerShell ExecutionPolicy to Bypass ... so here is how things look

```
#Requires -RunAsAdministrator
$TaskName = "Set-ExecutionPolicy Bypass"
$TaskPath = "\Corporate\PowerShell"
$Description = @"
Set-ExecutionPolicy Bypass -Force  
Runs as SYSTEM and does not display any progress or results
"@
```

### New-ScheduledTaskAction

The Action is what is going to run in the Scheduled Task, which will be PowerShell with a Command

```
$Action = @{
    Execute = 'powershell.exe'
    Argument = 'Set-ExecutionPolicy Bypass -Force'
}
```

{% embed url="<https://docs.microsoft.com/en-us/powershell/module/scheduledtasks/new-scheduledtaskaction?view=win10-ps>" %}

### New-ScheduledTaskPrincipal

The Principal is the account that will be used to run the Scheduled Task. For this Task I will use SYSTEM at the Highest RunLevel. The Scheduled Task will run whether someone is logged in or not

```
$Principal = @{
    UserId = 'SYSTEM'
    RunLevel = 'Highest'
}
```

{% embed url="<https://docs.microsoft.com/en-us/powershell/module/scheduledtasks/new-scheduledtaskprincipal?view=win10-ps>" %}

### New-ScheduledTaskSettingsSet

This function will define the settings. For this Scheduled Task I want to make sure it will run whether the computer has AC power or is on Battery, as well as limiting it to running for a maximum of 60 minutes. Win8 Compatibility is for Windows 10, and multiple instances are run in Parallel (at the same time) if it is currently running

```
$Settings = @{
    AllowStartIfOnBatteries = $true
    Compatibility = 'Win8'  
    MultipleInstances = 'Parallel'
    ExecutionTimeLimit = (New-TimeSpan -Minutes 60)
}
```

{% embed url="<https://docs.microsoft.com/en-us/powershell/module/scheduledtasks/new-scheduledtasksettingsset?view=win10-ps>" %}

### New-ScheduledTask

Once I have all of my settings defined, I can now splat the Scheduled Task variables

```
$ScheduledTask = @{
    Action = New-ScheduledTaskAction @Action
    Principal = New-ScheduledTaskPrincipal @Principal
    Settings = New-ScheduledTaskSettingsSet @Settings
    Description = $Description
}
```

{% embed url="<https://docs.microsoft.com/en-us/powershell/module/scheduledtasks/new-scheduledtask?view=win10-ps>" %}

### Register-ScheduledTask

Registering a Scheduled Task is what publishes it into Scheduled Tasks. Its important to use the `-Force` parameter as this will allow me to overwrite previous Tasks

```
New-ScheduledTask @ScheduledTask | Register-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath -Force
```

{% embed url="<https://docs.microsoft.com/en-us/powershell/module/scheduledtasks/register-scheduledtask?view=win10-ps>" %}

## The Complete Script

With a complete script, run in PowerShell (as Admin) to create the Task

```
#Requires -RunAsAdministrator

$TaskName = 'Set-ExecutionPolicy Bypass'
$TaskPath = '\Corporate\PowerShell'
$Description = @"
Version 21.1.19  
Set-ExecutionPolicy Bypass -Force  
Runs as SYSTEM and does not display any progress or results
"@

$Action = @{
    Execute = 'powershell.exe'
    Argument = 'Set-ExecutionPolicy Bypass -Force'
}
$Principal = @{
    UserId = 'SYSTEM'
    RunLevel = 'Highest'
}
$Settings = @{
    AllowStartIfOnBatteries = $true
    Compatibility = 'Win8'
    MultipleInstances = 'Parallel'
    ExecutionTimeLimit = (New-TimeSpan -Minutes 60)
}
$ScheduledTask = @{
    Action = New-ScheduledTaskAction @Action
    Principal = New-ScheduledTaskPrincipal @Principal
    Settings = New-ScheduledTaskSettingsSet @Settings
    Description = $Description
}

New-ScheduledTask @ScheduledTask | Register-ScheduledTask -TaskName $TaskName -TaskPath $TaskPath -Force
```

## The New Scheduled Task

The screenshots below are the Scheduled Task Properties. The highlighted areas were modified as a result of the values from the PowerShell script

![](https://3996045416-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDKRxGiKLYjW1gana2O%2F-MRQFDRQNHzPSIVCldQN%2F-MRQGI_ZEcWNNeK1H3i1%2Fimage.png?alt=media\&token=0f4a81aa-c9b6-4587-8585-73a17234255a)

![](https://3996045416-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDKRxGiKLYjW1gana2O%2F-MRQFDRQNHzPSIVCldQN%2F-MRQGSPBPMalrseBc09E%2Fimage.png?alt=media\&token=b1a5c894-ad98-4db6-8a11-538c3c32415b)

![](https://3996045416-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDKRxGiKLYjW1gana2O%2F-MRQFDRQNHzPSIVCldQN%2F-MRQGXW40tDUblkwmiVi%2Fimage.png?alt=media\&token=870dc93c-bc1a-4328-a15b-04bb8f806a7f)

![](https://3996045416-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDKRxGiKLYjW1gana2O%2F-MRQFDRQNHzPSIVCldQN%2F-MRQGebfBzcVlVMy98Pe%2Fimage.png?alt=media\&token=373f61b3-7ead-4550-b795-ba6b349f7a84)

## Testing

The Scheduled Task runs perfectly as an Administrator in the GUI, and it can also be run in PowerShell by usin&#x67;**`Start-ScheduledTask`**. You will need to specify the **`TaskPath`** if the Task is not in the ROOT of Task Scheduler, or **`Get-ScheduledTask`** and pipe it t&#x6F;**`Start-ScheduledTask`**

![](https://3996045416-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDKRxGiKLYjW1gana2O%2F-MRQGjdte5xe-4-Lv-eY%2F-MRQHhV09sXp6LZ9UJl3%2Fimage.png?alt=media\&token=24070ba8-f944-46e5-942c-a624a393fb24)

![](https://3996045416-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDKRxGiKLYjW1gana2O%2F-MRQGjdte5xe-4-Lv-eY%2F-MRQIKkMSOExzxLwQHa7%2Fimage.png?alt=media\&token=28acded0-dbf0-4562-9e49-83df9728866a)

When logged in as a Standard User, the Task will not show up. This is due to the fact that the Task does not have permissions to run in a Standard User profile

![](https://3996045416-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDKRxGiKLYjW1gana2O%2F-MRQGjdte5xe-4-Lv-eY%2F-MRQIrpaoUr2nxEDfKX_%2Fimage.png?alt=media\&token=3a684acd-0cf1-47c3-8933-026e05f5a5f4)

![](https://3996045416-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDKRxGiKLYjW1gana2O%2F-MREIQgmsl2DY_WE_0hX%2F-MREQ4UC2oPnFtdN3-YF%2Fimage.png?alt=media\&token=9af48b6c-4869-489d-b315-00066c1f738b)

The reason the Task does not show for the Standard User is that the Standard User does not have READ and EXECUTE permissions to the Scheduled Task. Time to read the next page


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.osdeploy.com/archive/blog/2021/scheduled-tasks/building-a-task.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.