New-SCOMMaintenanceSchedule

Reference

Module:: OperationsManager

Creates a maintenance schedule.

Syntax

New-SCOMMaintenanceSchedule
   [-Name] <String>
   [-Recursive]
   [-Enabled]
   [-MonitoringObjects] <Guid[]>
   [-ActiveStartTime] <DateTime>
   [[-ActiveEndDate] <DateTime>]
   [-Duration] <Int32>
   [-ReasonCode] <MaintenanceModeReason>
   [[-Comments] <String>]
   [-FreqType] <Int32>
   [[-FreqInterval] <Int32>]
   [[-FreqRecurrenceFactor] <Int32>]
   [[-FreqRelativeInterval] <Int32>]
   [-SCSession <Connection[]>]
   [-ComputerName <String[]>]
   [-Credential <PSCredential>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

The New-SCOMMaintenanceSchedule cmdlet creates a maintenance schedule.

When a resource is in maintenance mode, Operations Manager suppresses alerts, notifications, rules, monitors, automatic responses, state changes, and new alerts. A maintenance schedule can be used to schedule a set of resources to go into maintenance mode.

You could use this cmdlet to create schedules that run once, daily, weekly or monthly on a particular day or a day of the week. This cmdlet will return the GUID of the created schedule.

By default, this cmdlet uses the active persistent connection to a management group. Use the SCSession parameter to specify a different persistent connection. You can create a temporary connection to a management group by using the ComputerName and Credential parameters. For more information, type Get-Help about_OpsMgr_Connections.

Examples

Example 1: Add Windows Computer object into new maintenance schedule

PS C:\>$windowsComputer = Get-SCOMClass -DisplayName "Windows Computer" | Get-SCOMClassInstance | Where-Object { $_.DisplayName -eq 'Agent01.contoso.local' }
PS C:\>New-SCOMMaintenanceSchedule -Name 'Test Maintenance Schedule' -MonitoringObjects $windowsComputer.Id -ActiveStartTime $((Get-Date).AddMinutes(2)) -DurationInMinutes 240 -ReasonCode PlannedOther -FreqType 1 -Enabled

Example showing how to add a Windows Computer Object for a specific server: Agent01.contoso.com into the new Maintenance Schedule, for a duration of 240 minutes, running only 1 time.

Example 2: Create a Daily maintenance schedule

PS C:\>$monitoringObjects = Get-SCOMClassInstance -Name 'Agent01.contoso.local'
PS C:\># Timezone is UTC (Coordinated Universal Time)
PS C:\>$startDate = [DateTime]::SpecifyKind([DateTime]"2024-03-30T01:00:00", [System.DateTimeKind]::Utc)
PS C:\>$durationInMinutes = 90
PS C:\>
PS C:\>New-SCOMMaintenanceSchedule -Name "Daily Maintenance at 1AM" -MonitoringObjects $monitoringObjects.Id -ActiveStartTime $startDate -Duration $durationInMinutes -ReasonCode PlannedOther -FreqType 4 -FreqInterval 1 -Enabled

Example showing how to set up a daily maintenance schedule for a specific server and associated monitoring objects: Agent01.contoso.local, starting at 1:00 AM and lasting for 90 minutes.

Example 3: Create a Weekly maintenance schedule

PS C:\>$monitoringObjects = Get-SCOMClassInstance -Name 'Agent01.contoso.local'
PS C:\># Timezone is set to local timezone
PS C:\>$startDate = [DateTime]"2024-03-29T02:00:00"
PS C:\>$durationInMinutes = 120
PS C:\>
PS C:\>New-SCOMMaintenanceSchedule -Name "Weekly Wednesday Maintenance" -MonitoringObjects $monitoringObjects.Id -ActiveStartTime $startDate -Duration $durationInMinutes -ReasonCode PlannedOther -FreqType 8 -FreqInterval 8 -FreqRecurrenceFactor 1 -Enabled

Example showing how to configure a weekly maintenance schedule every Wednesday for a specific server and associated monitoring objects: Agent01.contoso.local, beginning at 2:00 AM and lasting for 120 minutes.

Example 4: Create a Monthly Maintenance Schedule

PS C:\>$monitoringObjects = Get-SCOMClassInstance -Name 'Agent01.contoso.local'
PS C:\># Timezone is set to local timezone
PS C:\>$startDate = [DateTime]"2024-04-01T03:00:00"
PS C:\>$durationInMinutes = 180
PS C:\>
PS C:\>New-SCOMMaintenanceSchedule -Name "Monthly Second Tuesday Maintenance" -MonitoringObjects $monitoringObjects.Id -ActiveStartTime $startDate -Duration $durationInMinutes -ReasonCode PlannedOther -FreqType 32 -FreqInterval 2 -FreqRelativeInterval 2 -FreqRecurrenceFactor 1 -Enabled

Example showing how to establish a monthly maintenance schedule on the second Tuesday of each month for a specific server and associated monitoring objects: Agent01.contoso.local, starting at 3:00 AM and lasting for 180 minutes.

Parameters

-ActiveEndDate

Specifies the end date and the end time when the schedule should stop executing. If this parameter is not specified, the schedule will continue to run for ever (or until it is deleted or disabled).

For instance, if you want to create a schedule that should end on 1st May 2016 at 9:00 AM, you must specify "01-05-2016 09:00:00" as the ActiveEndDate. You can pass a string specifying the time you want in your local time. However, if you want to specify a UTC time, you should specify a DateTime object with the DateTimeKind set to UTC.

Type:	DateTime
Position:	5
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ActiveStartTime

Specifies the start date and the time when the schedule must go active. For instance, if you want to create a schedule that should begin from 1st May 2016 and must run at 9:00 AM, you must specify "01-05-2016 09:00:00" as the ActiveStartTime. You can pass a string specifying the time you want in your local time. However, if you want to specify a UTC time, you need to specify a DateTime object with the DateTimeKind set to UTC.

Type:	DateTime
Position:	4
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Comments

Specifies any human readable comments for a maintenance schedule.

Type:	String
Position:	8
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ComputerName

Specifies an array of names of computers. The cmdlet establishes temporary connections with management groups for these computers. You can use NetBIOS names, IP addresses, or fully qualified domain names (FQDNs). To specify the local computer, type the computer name, localhost, or a dot (.).

The System Center Data Access service must be active on the computer. If you do not specify a computer, the cmdlet uses the computer for the current management group connection.

Type:	String[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Credential

Specifies a PSCredential object for the management group connection. To obtain a PSCredential object, use the Get-Credential cmdlet. For more information, type Get-Help Get-Credential.If you specify a computer in the ComputerName parameter, use an account that has access to that computer. The default is the current user.

Type:	PSCredential
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Duration

Specifies the duration of the maintenance schedule. The duration of a maintenance schedule is the time for which the maintenance schedule will last.

Type:	Int32
Aliases:	DurationInMinutes
Position:	6
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Enabled

Indicates whether the schedule will be enabled or disabled upon creation. If you set this to false, the schedule will be created but it will be disabled.

Type:	SwitchParameter
Position:	2
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-FreqInterval

Specifies when the job is to be executed. This parameter can be one of the following values:

1 (once). Frequency interval is unused.
4 (daily). Every frequency interval days.
8 (weekly). The FreqInterval parameter is one or more of the following (combined with an OR logical operator):
- 1 - Sunday
- 2 - Monday
- 4 - Tuesday
- 8 - Wednesday
- 16 - Thursday
- 32 - Friday
- 64 - Saturday
16 (monthly). On the frequency interval day of the month.
- 1 - Sunday
- 2 - Monday
- 3 - Tuesday
- 4 - Wednesday
- 5 - Thursday
- 6 - Friday
- 7 - Saturday
32 (monthly relative). The FreqInterval parameter is one of the following values:
- 8 - Day
- 9 - Weekday
- 10 - Weekend day

Type:	Int32
Position:	10
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-FreqRecurrenceFactor

Number of weeks or months between the scheduled execution of the job. FreqRecurrenceFactor is used only if the FreqType parameter is set to 8, 16, or 32. The FreqRecurrenceFactor parameter is an integer, with a default value of 0.

Type:	Int32
Position:	11
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-FreqRelativeInterval

Day that the job is executed. This is mandatory if the schedule is anything other than OnceRecurrence schedule. The value depends on the value of FreqType.

This parameter can be one of the following values:

1 (First)
2 (Second)
4 (Third)
8 (Fourth)
16 (Last)

Type:	Int32
Position:	12
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-FreqType

Specifies when the job is to be executed. The acceptable values for this parameter are:

1 (once)
4 (daily)
8 (weekly)
16 (monthly)
32 (Monthly, relative to parameter FreqInterval)

Type:	Int32
Position:	9
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-MonitoringObjects

Specifies an array of monitoring objects GUIDS which will be put to maintenance mode. To specify a monitoring object which the created schedule will put into maintenance mode, you must pass the ID attribute of the monitoring object.

You can specify one or more monitoring objects for a schedule. However, you cannot create a schedule without any monitoring object.

Type:	Guid[]
Position:	3
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Name

Specifies name of the schedule that this cmdlet creates.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ReasonCode

Specifies the reason code for a maintenance schedule that specifies the reason for the maintenance window.

The acceptable values for this parameter are:

PlannedOther
UnplannedOther
PlannedHardwareMaintenance
UnplannedHardwareMaintenance
PlannedHardwareInstallation
UnplannedHardwareInstallation
PlannedOperatingSystemReconfiguration
UnplannedOperatingSystemReconfiguration
PlannedApplicationMaintenance
UnplannedApplicationMaintenance
ApplicationInstallation
ApplicationUnresponsive
ApplicationUnstable
SecurityIssue
LossOfNetworkConnectivity

Type:	MaintenanceModeReason
Accepted values:	PlannedOther, UnplannedOther, PlannedHardwareMaintenance, UnplannedHardwareMaintenance, PlannedHardwareInstallation, UnplannedHardwareInstallation, PlannedOperatingSystemReconfiguration, UnplannedOperatingSystemReconfiguration, PlannedApplicationMaintenance, UnplannedApplicationMaintenance, ApplicationInstallation, ApplicationUnresponsive, ApplicationUnstable, SecurityIssue, LossOfNetworkConnectivity
Position:	7
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Recursive

Indicates whether the schedule is applicable to the top level resource or to all the contained resources. If the recursive parameter is set to false, only the specified resource will go into maintenance mode when the schedule is run. If this is set to true, the specified resource and all resources that have a containment relationship with this resource will also go into maintenance mode.

Type:	SwitchParameter
Position:	1
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SCSession

Specifies an array of Connection objects.

Type:	Connection[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Share via

New-SCOMMaintenanceSchedule

Syntax

Description

Examples

Example 1: Add Windows Computer object into new maintenance schedule

Example 2: Create a Daily maintenance schedule

Example 3: Create a Weekly maintenance schedule

Example 4: Create a Monthly Maintenance Schedule

Parameters

-ActiveEndDate

-ActiveStartTime

-Comments

-ComputerName

-Confirm

-Credential

-Duration

-Enabled

-FreqInterval

-FreqRecurrenceFactor

-FreqRelativeInterval

-FreqType

-MonitoringObjects

-Name

-ReasonCode

-Recursive

-SCSession

-WhatIf

Additional resources

Share via

New-SCOMMaintenanceSchedule

Syntax

Description

Examples

Example 1: Add Windows Computer object into new maintenance schedule

Example 2: Create a Daily maintenance schedule

Example 3: Create a Weekly maintenance schedule

Example 4: Create a Monthly Maintenance Schedule

Parameters

-ActiveEndDate

-ActiveStartTime

-Comments

-ComputerName

-Confirm

-Credential

-Duration

-Enabled

-FreqInterval

-FreqRecurrenceFactor

-FreqRelativeInterval

-FreqType

-MonitoringObjects

-Name

-ReasonCode

-Recursive

-SCSession

-WhatIf

Related Links

Additional resources