New-SCOMMaintenanceSchedule
Creates a maintenance schedule.
Syntax
Default (Default)
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.
Parameter properties
| Type: | DateTime |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 5 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | DateTime |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 4 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Comments
Specifies any human readable comments for a maintenance schedule.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 8 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Confirm
Prompts you for confirmation before running the cmdlet.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | cf |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | PSCredential |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | DurationInMinutes |
Parameter sets
(All)
| Position: | 6 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 2 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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
- 1 - Sunday
- 16 (monthly). On the frequency interval day of the month.
- 1 - Sunday
- 2 - Monday
- 3 - Tuesday
- 4 - Wednesday
- 5 - Thursday
- 6 - Friday
- 7 - Saturday
- 1 - Sunday
- 32 (monthly relative). The FreqInterval parameter is one of the following values:
- 8 - Day
- 9 - Weekday
- 10 - Weekend day
- 8 - Day
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 10 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 11 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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)
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 12 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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)
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 9 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | Guid[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 3 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Name
Specifies name of the schedule that this cmdlet creates.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 0 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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
Parameter properties
| Type: | MaintenanceModeReason |
| Default value: | None |
| Accepted values: | PlannedOther, UnplannedOther, PlannedHardwareMaintenance, UnplannedHardwareMaintenance, PlannedHardwareInstallation, UnplannedHardwareInstallation, PlannedOperatingSystemReconfiguration, UnplannedOperatingSystemReconfiguration, PlannedApplicationMaintenance, UnplannedApplicationMaintenance, ApplicationInstallation, ApplicationUnresponsive, ApplicationUnstable, SecurityIssue, LossOfNetworkConnectivity |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 7 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 1 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-SCSession
Specifies an array of Connection objects.
Parameter properties
| Type: | Connection[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | wi |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.