Enterprise Admins.org

In my most recent series on vCenter Scheduled Tasks with PowerCLI, I have provided three functions…Get-VIScheduledTasks, Get-VMScheduledSnapshots, and New-VMScheduledSnapshot. To complete the series, I have a final function Remove-VIScheduledTask. I don’t really see the need for this one, as you can easily bulk select scheduled tasks in the vCenter UI and delete them with a single click. However, in the interest of completeness, here is a rough function that will delete a vSphere scheduled task. [A more robust/efficient/complete function could be written that would accept input from the pipeline. If there is a good use case for this please leave a comment below.]

NOTE: This function requires an additional function: Get-VIScheduledTasks to find the task by name. In addition the usage example below requires Get-VMScheduledSnapshots. Both functions are available here: New vCenter Scheduled Tasks with PowerCLI (Part 1).

[cc lang=”Powershell”]
Function Remove-VIScheduledTask {
PARAM ([string]$taskName)
(Get-View -Id ((Get-VIScheduledTasks -Full | ?{$_.Name -eq $taskName}).ScheduledTask)).RemoveScheduledTask()
}
[/cc]

Usage example:

# This example will find all VM Scheduled Snapshots which 
# are not scheduled to run again, then remove each one by name.
Get-VMScheduledSnapshots | 
?{$_.NextRunTime -eq $null} | %{ Remove-VIScheduledTask $_.Name }

In a recent post New vCenter Scheduled Tasks with PowerCLI (Part 1), I provided two functions that return information related to vCenter Scheduled Tasks. This was my first step towards creating a PowerShell function that I could run to create scheduled snapshot tasks. This post will cover the create scheduled snapshot function.

NOTE: This function requires two additional functions, Get-VMScheduledSnapshots and Get-VIScheduledTasks, available here: New vCenter Scheduled Tasks with PowerCLI (Part 1).

[cc lang=”powershell”]
Function New-VMScheduledSnapshot {
PARAM (
[string]$vmName,
[string]$runTime,
[string]$notifyEmail=$null,
[string]$taskName=”$vmName Scheduled Snapshot”
)

# Verify we found a single VM
$vm = (get-view -viewtype virtualmachine -property Name -Filter @{“Name”=”^$($vmName)$”}).MoRef
if (($vm | Measure-Object).Count -ne 1 ) { “Unable to locate a specific VM $vmName”; break }

# Validate datetime value and convert to UTC
try { $castRunTime = ([datetime]$runTime).ToUniversalTime() } catch { “Unable to convert runtime parameter to date time value”; break }
if ( [datetime]$runTime -lt (Get-Date) ) { “Single run tasks can not be scheduled to run in the past. Please adjust start time and try again.”; break }

# Verify the scheduled task name is not already in use
if ( (Get-VIScheduledTasks | ?{$_.Name -eq $taskName } | Measure-Object).Count -eq 1 ) { “Task Name `”$taskName`” already exists. Please try again and specify the taskname parameter”; break }

$spec = New-Object VMware.Vim.ScheduledTaskSpec
$spec.name = $taskName
$spec.description = “Snapshot of $vmName scheduled for $runTime”
$spec.enabled = $true
if ( $notifyEmail ) {$spec.notification = $notifyEmail}
($spec.scheduler = New-Object VMware.Vim.OnceTaskScheduler).runAt = $castRunTime
($spec.action = New-Object VMware.Vim.MethodAction).Name = “CreateSnapshot_Task”
$spec.action.argument = New-Object VMware.Vim.MethodActionArgument[] (4)
($spec.action.argument[0] = New-Object VMware.Vim.MethodActionArgument).Value = “$vmName scheduled snapshot”
($spec.action.argument[1] = New-Object VMware.Vim.MethodActionArgument).Value = “Snapshot created using $taskName”
($spec.action.argument[2] = New-Object VMware.Vim.MethodActionArgument).Value = $false # Snapshot memory
($spec.action.argument[3] = New-Object VMware.Vim.MethodActionArgument).Value = $false # quiesce guest file system (requires VMware Tools)

[Void](Get-View -Id ‘ScheduledTaskManager-ScheduledTaskManager’).CreateScheduledTask($vm, $spec)
Get-VMScheduledSnapshots | ?{$_.Name -eq $taskName }
}
[/cc]

# Create a snapshot of the VM test002 at 9:40AM on 3/2/13
New-VMScheduledSnapshot test002 "3/2/13 9:40AM"

# Create a snapshot and send an email notification
New-VMScheduledSnapshot test002 "3/2/13 9:40AM" myemail@mydomain.com

# Use all of the options and name the parameters
New-VMScheduledSnapshot -vmname 'test001' -runtime '3/2/13 9:40am' -notifyemail 'myemail@mydomain.com' -taskname 'My scheduled task of test001'

I hope someone finds this function useful.

I work with a lot of scheduled tasks. Typically, these tasks run powershell scripts from the Windows Task Scheduler. However, when working with simple VMware tasks (like creating snapshots right before a maintenance window) I like to use the Scheduled Tasks feature from right inside vCenter. The other day I thought it would be interesting if I had a PowerShell function that I could run to create these snapshot tasks. The first step in this process is to figure out what tasks we already have…and understand where some of these properties are located using PowerCLI.

The following two functions can be used to get information on Scheduled Tasks inside vCenter. The first function Get-VIScheduledTasks will simply return a list of all scheduled tasks that exist in a vCenter environment. I picked out a handful of properties that I figured would be needed and return those by default, casting the date/time values into local time. If you need all of the properties (the native .Net view of the Scheduled Task Info objects) you can include the parameter -Full and all of the properties will be returned.

[cc lang=”powershell”]
Function Get-VIScheduledTasks {
PARAM ( [switch]$Full )
if ($Full) {
# Note: When returning the full View of each Scheduled Task, all date times are in UTC
(Get-View ScheduledTaskManager).ScheduledTask | %{ (Get-View $_).Info }
} else {
# By default, lets only return common headers and convert all date/times to local values
(Get-View ScheduledTaskManager).ScheduledTask | %{ (Get-View $_ -Property Info).Info } |
Select-Object Name, Description, Enabled, Notification, LastModifiedUser, State, Entity,
@{N=”EntityName”;E={ (Get-View $_.Entity -Property Name).Name }},
@{N=”LastModifiedTime”;E={$_.LastModifiedTime.ToLocalTime()}},
@{N=”NextRunTime”;E={$_.NextRunTime.ToLocalTime()}},
@{N=”PrevRunTime”;E={$_.LastModifiedTime.ToLocalTime()}},
@{N=”ActionName”;E={$_.Action.Name}}
}
}
[/cc]

This next function calls above function, but only returns the tasks whose action is “CreateSnapshot_Task”
[cc lang = “Powershell”]
Function Get-VMScheduledSnapshots {
Get-VIScheduledTasks | ?{$_.ActionName -eq ‘CreateSnapshot_Task’} |
Select-Object @{N=”VMName”;E={$_.EntityName}}, Name, NextRunTime, Notification
}
[/cc]

Sample usage would be:

# To find all tasks that failed to execute last run
Get-VIScheduledTasks | ?{$_.State -ne 'success'}

# To find all snapshots that are not scheduled to run again:
Get-VMScheduledSnapshots | ?{$_.NextRunTime -eq $null}

I hope you find these functions useful. Be sure to check out the next post – on creating scheduled snapshots with PowerCLI!