Set-DbaAgentOperator

Want to see the source code for this command? Check out Set-DbaAgentOperator on GitHub.
Want to see the Bill Of Health for this command? Check out Set-DbaAgentOperator.

Synopsis

Modifies existing SQL Agent operator contact details, pager schedules, and failsafe settings.

Description

Modifies existing SQL Agent operators by updating their contact information, pager notification schedules, and failsafe operator configuration. This lets you change email addresses, pager contacts, net send addresses, and specify when pager notifications should be active without having to manually update operators through SQL Server Management Studio. You can also designate an operator as the failsafe operator that receives notifications when the primary assigned operators are unavailable.

Syntax

Set-DbaAgentOperator
    [[-SqlInstance] <DbaInstanceParameter[]>]
    [[-SqlCredential] <PSCredential>]
    [[-Operator] <String[]>]
    [[-Name] <String>]
    [[-EmailAddress] <String>]
    [[-NetSendAddress] <String>]
    [[-PagerAddress] <String>]
    [[-PagerDay] <String>]
    [[-SaturdayStartTime] <String>]
    [[-SaturdayEndTime] <String>]
    [[-SundayStartTime] <String>]
    [[-SundayEndTime] <String>]
    [[-WeekdayStartTime] <String>]
    [[-WeekdayEndTime] <String>]
    [-IsFailsafeOperator]
    [[-FailsafeNotificationMethod] <String[]>]
    [[-InputObject] <Operator[]>]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Set-DbaAgentOperator -SqlInstance sql01 -Operator DBA -EmailAddress [email protected] -PagerDay Everyday

This sets the operator named DBA with the above email address with default values to alerts everyday for all hours of the day.

Example: 2

PS C:\> Set-DbaAgentOperator -SqlInstance sql01 -Operator DBA -EmailAddress [email protected] `
>>  -NetSendAddress dbauser1 -PagerAddress [email protected] -PagerDay Everyday `
>>  -SaturdayStartTime 070000 -SaturdayEndTime 180000 -SundayStartTime 080000 `
>>  -SundayEndTime 170000 -WeekdayStartTime 060000 -WeekdayEndTime 190000

Creates a new operator named DBA on the sql01 instance with email address [email protected], net send address of dbauser1, pager address of [email protected], page day as every day,
Saturday start time of 7am, Saturday end time of 6pm, Sunday start time of 8am, Sunday end time of 5pm, Weekday start time of 6am, and Weekday end time of 7pm.

Optional Parameters

-SqlInstance

The target SQL Server instance or instances.

-SqlCredential

Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential).
Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported.
For MFA support, please use Connect-DbaInstance.

-Operator

Specifies the name of the existing SQL Agent operator to modify. Use this when targeting a specific operator by name instead of piping operator objects.

-Name

Renames the operator to the specified value. Use this when you need to change an operator's name while preserving all other settings and alert assignments.

-EmailAddress

Sets the email address where SQL Agent will send email notifications for this operator. This is the primary contact method for most alert notifications and job failure messages.

-NetSendAddress

Specifies the network computer name for net send notifications. This legacy notification method sends popup messages to Windows computers on the same network domain.

-PagerAddress

Sets the pager email address for urgent notifications. Typically used for SMS gateways or mobile email addresses when immediate notification is required outside normal business hours.

-PagerDay

Controls which days pager notifications are active for this operator. Use 'Weekdays' for business hours coverage, 'Weekend' for off-hours support, or specific days for rotating on-call schedules.
Valid values are 'EveryDay', 'Weekdays', 'Weekend', 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', and 'Saturday'.

-SaturdayStartTime

Sets when pager notifications begin on Saturday in HHMMSS format (e.g., '080000' for 8:00 AM). Use this to define weekend on-call coverage hours for the operator.

-SaturdayEndTime

Sets when pager notifications end on Saturday in HHMMSS format (e.g., '180000' for 6:00 PM). Notifications outside this window will use email instead of pager for the operator.

-SundayStartTime

Sets when pager notifications begin on Sunday in HHMMSS format (e.g., '080000' for 8:00 AM). Use this to define weekend on-call coverage hours for the operator.

-SundayEndTime

Sets when pager notifications end on Sunday in HHMMSS format (e.g., '170000' for 5:00 PM). Notifications outside this window will use email instead of pager for the operator.

-WeekdayStartTime

Sets when pager notifications begin on weekdays (Monday-Friday) in HHMMSS format (e.g., '060000' for 6:00 AM). Use this to define business hours pager coverage for the operator.

-WeekdayEndTime

Sets when pager notifications end on weekdays (Monday-Friday) in HHMMSS format (e.g., '190000' for 7:00 PM). Notifications outside this window will use email instead of pager for the operator.

-IsFailsafeOperator

Designates this operator as the failsafe operator who receives notifications when primary operators are unavailable. Only one failsafe operator can exist per SQL Server instance, so this replaces any
existing failsafe operator.

-FailsafeNotificationMethod

Specifies how the failsafe operator receives notifications when primary operators cannot be reached. Use 'NotifyEmail' for standard alerts, 'Pager' for urgent notifications, or 'NotifyAll' for
maximum coverage.
Valid values are 'None', 'NotifyEmail', 'Pager', 'NetSend', 'NotifyAll'. Multiple methods can be combined except 'None' and 'NotifyAll' which must be used alone.

-InputObject

Accepts SQL Agent operator objects from the pipeline, typically from Get-DbaAgentOperator. Use this to modify multiple operators or when working with operator objects in a pipeline workflow.

-EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.

-WhatIf

Shows what would happen if the command were to run. No actions are actually performed.

-Confirm

Prompts you for confirmation before executing any changing operations within the command.