Private/New-SpecScheduledTaskTrigger.ps1

Function New-SpecScheduledTaskTrigger {
    <#
    .SYNOPSIS
    This function creates a new scheduled task trigger based on the provided parameters.
 
    .DESCRIPTION
    The New-SpecScheduledTaskTrigger function creates a new scheduled task trigger based on the specified parameters. It supports different types of triggers such as "AtStartup," "AtLogon," and "Daily."
 
    .PARAMETER trigger
    Specifies the type of trigger to create: "AtStartup," "AtLogon," or "Daily."
 
    .PARAMETER time
    Specifies the time for the trigger (used with the "Daily" trigger type).
 
    .PARAMETER RandomiseTaskUpToXMinutes
    Specifies the number of minutes to randomly delay the task execution (used with the "Daily" trigger type). If you need over an hour please use minutes eg 78 (Equivalent to 1 hour 18 minutes)
 
    .PARAMETER DelayTaskUpToXMinutes
    Specifies the number of minutes to delay the task execution. If you need over an hour please use minutes eg 78 (Equivalent to 1 hour 18 minutes)
 
    .EXAMPLE
    $taskTrigger = New-SpecScheduledTaskTrigger -trigger "AtLogon"
    Creates a new scheduled task trigger that executes at user logon.
 
    .EXAMPLE
    $taskTrigger = New-SpecScheduledTaskTrigger -trigger "Daily" -time "02:00" -RandomiseTaskUpToXMinutes 30
    Creates a new scheduled task trigger that executes daily at 2:00 AM and includes a random delay of up to 30 minutes.
 
    .EXAMPLE
    $taskTrigger = New-SpecScheduledTaskTrigger -trigger "Daily" -time "08:00" -DelayTaskUpToXMinutes 15
    Creates a new scheduled task trigger that executes daily at 8:00 AM and includes a fixed delay of 15 minutes.
 
    .NOTES
    Author: owen.heaume
    Date: August 10, 2023
    Version: 1.0
    Status Codes:
    - Successful assignment: Returns the created task trigger object.
    - Error occurred: Returns 911.
    #>


    [cmdletbinding()]

    param (
        [string]$trigger,

        [datetime]$time,

        [int]$RandomiseTaskUpToXMinutes,

        [int]$DelayTaskUpToXMinutes
    )

    # Task Trigger
    try {
        write-verbose "Assigning Trigger settings"
        switch ($trigger) {
            'AtStartup' { Write-Verbose "Selected trigger is: AtStartup"; $taskTrigger = New-ScheduledTaskTrigger -AtStartup -ea Stop -ev x }
            'AtLogon' { Write-Verbose "Selected trigger is: AtLogon"; $taskTrigger = New-ScheduledTaskTrigger -AtLogOn -ea Stop -ev x }
            'Daily' {
                Write-Verbose "Selected trigger is: Daily";
                $taskTrigger = New-ScheduledTaskTrigger -Daily -At $time -ea Stop -ev x
                if ($RandomiseTaskUpToXMinutes) {
                    # $randomDelay = New-TimeSpan -Minutes 0 -ea Stop -ev x
                    $randomDelay = New-TimeSpan -Minutes $RandomiseTaskUpToXMinutes -ea stop
                    $randomDelayString = 'PT' + $randomDelay.Hours.ToString('00') + 'H' + $randomDelay.Minutes.ToString('00') + 'M' + $randomDelay.Seconds.ToString('00') + 'S'
                    $taskTrigger.RandomDelay = $randomDelayString
                    write-verbose "A new time span: $($randomDelayString) has been set. ($randomiseTaskUpToXMinutes minutes)"
                }
            }
        }

        # Add a task delay if selected
        if ($DelayTaskUpToXMinutes) {
            $taskDelay = New-TimeSpan -Minutes $DelayTaskUpToXMinutes

            $delayTime = "PT" + $taskDelay.ToString('hh') + "H" + $taskDelay.ToString('mm') + "M" + $taskDelay.ToString('ss') + "S"
            $tasktrigger.delay = $delaytime
            write-verbose "A new time span: $($delayTime) has been set. ($DelayTaskUpToXMinutes minutes)"
        }

        write-verbose "Trigger settings assigned successfully"
        return $taskTrigger
    } catch {
        write-warning "An error occured assigning the Trigger settings: $x"
        return 911
    }
}