New-DbaAgentOperator

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

Synopsis

Creates a new SQL Server Agent operator with notification settings for alerts and job failures.

Description

Creates SQL Server Agent operators who receive notifications when alerts fire or jobs fail. Operators are contacts that SQL Server Agent can notify via email, pager, or net send when specific events occur. You can configure pager schedules with different time windows for weekdays, weekends, and specific days to control when pager notifications are sent. This replaces the manual process of creating operators through SQL Server Management Studio and ensures consistent operator setup across multiple instances. If the operator already exists, it will not be created unless -Force is used to drop and recreate it.

Syntax

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

Examples

Example: 1

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

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

Example: 2

PS C:\> New-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.

Required Parameters

-Operator

Name of the SQL Server Agent operator to create. This becomes the operator name that shows up in SSMS and can be referenced by alerts and jobs for notifications.
Use descriptive names like 'DBA Team' or 'On-Call Admin' to identify who receives notifications.

Optional Parameters

-SqlInstance

The target SQL Server instance or instances. You must have sysadmin access and server version must be SQL Server version 2000 or greater.

-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.

-EmailAddress

Email address where SQL Server Agent sends alert notifications and job failure notifications. This is the primary notification method for most operators.
Specify a monitored email address or distribution list that reaches the appropriate support staff.

-NetSendAddress

Network address for receiving net send messages from SQL Server Agent. This is a legacy Windows messaging system rarely used in modern environments.
Most organizations use email notifications instead since net send requires specific network configurations and may not work across subnets.

-PagerAddress

Email address for pager notifications, typically used for SMS gateways or mobile alerts. This works with email-to-SMS services provided by cellular carriers.
Configure pager schedules with PagerDay and time parameters to control when these urgent notifications are sent.

-PagerDay

Controls which days pager notifications are active for this operator. Use this to match on-call schedules or business hours when immediate alerts are needed.
Choose 'Weekdays' for business-hour coverage, 'EveryDay' for 24/7 support, or specific days like 'Monday' through 'Sunday' for rotation schedules.

-SaturdayStartTime

Starting time for Saturday pager notifications in HHMMSS format (e.g., '080000' for 8:00 AM). Required when PagerDay includes Saturday, Weekend, or EveryDay.
Use '000000' for midnight start times or specify business hours to limit when urgent alerts are sent.

-SaturdayEndTime

Ending time for Saturday pager notifications in HHMMSS format (e.g., '180000' for 6:00 PM). Must be specified with SaturdayStartTime.
Use '235959' for end-of-day coverage or match your organization's Saturday support hours.

-SundayStartTime

Starting time for Sunday pager notifications in HHMMSS format (e.g., '090000' for 9:00 AM). Required when PagerDay includes Sunday, Weekend, or EveryDay.
Configure based on your weekend support schedule or emergency-only coverage requirements.

-SundayEndTime

Ending time for Sunday pager notifications in HHMMSS format (e.g., '170000' for 5:00 PM). Must be specified with SundayStartTime.
Set to match your organization's weekend support availability or use '235959' for full-day coverage.

-WeekdayStartTime

Starting time for weekday pager notifications in HHMMSS format (e.g., '060000' for 6:00 AM). Required when PagerDay includes Weekdays or individual weekdays.
Typically set to business hours start time or earlier for critical production monitoring.

-WeekdayEndTime

Ending time for weekday pager notifications in HHMMSS format (e.g., '190000' for 7:00 PM). Must be specified with WeekdayStartTime.
Configure to match business hours end time or extend for after-hours support coverage.

-IsFailsafeOperator

Designates this operator as the failsafe operator for the SQL Server instance. The failsafe operator receives notifications when all other operators are unavailable.
Only one failsafe operator can exist per instance, and this setting replaces any existing failsafe operator configuration.

-FailsafeNotificationMethod

Specifies how the failsafe operator receives notifications when used with IsFailsafeOperator. Choose 'NotifyEmail' for email notifications or 'NotifyPager' for pager alerts.
Defaults to 'NotifyEmail' which works with most modern notification systems and email-to-SMS gateways.

-Force

Drops and recreates the operator if it already exists on the target instance. Without this switch, the function will skip existing operators to prevent accidental overwrites.
Use this when updating operator configurations or when you need to ensure consistent settings across multiple environments.

-InputObject

Accepts SQL Server Management Objects (SMO) server instances from Connect-DbaInstance via pipeline. This allows you to create operators on pre-authenticated server connections.
Use this when you have existing server connections or need to process multiple instances with specific connection properties.

-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.