| Author | Sander Stad (@sqlstad), sqlstad.nl |
| Availability | Windows, Linux, macOS |
Want to see the source code for this command? Check out Set-DbaAgentJob on GitHub.
Want to see the Bill Of Health for this command? Check out Set-DbaAgentJob.
Modifies existing SQL Server Agent job properties and notification settings.
Updates various properties of SQL Server Agent jobs including job name, description, owner, enabled/disabled status, notification settings, and schedule assignments. This function lets you modify jobs without using SQL Server Management Studio, making it useful for standardizing job configurations across multiple instances or automating job maintenance tasks. You can update individual jobs or perform bulk changes across multiple jobs and SQL Server instances simultaneously.
Set-DbaAgentJob
[[-SqlInstance] <DbaInstanceParameter[]>]
[[-SqlCredential] <PSCredential>]
[[-Job] <Object[]>]
[[-Schedule] <Object[]>]
[[-ScheduleId] <Int32[]>]
[[-NewName] <String>]
[-Enabled]
[-Disabled]
[[-Description] <String>]
[[-StartStepId] <Int32>]
[[-Category] <String>]
[[-OwnerLogin] <String>]
[[-EventLogLevel] <Object>]
[[-EmailLevel] <Object>]
[[-NetsendLevel] <Object>]
[[-PageLevel] <Object>]
[[-EmailOperator] <String>]
[[-NetsendOperator] <String>]
[[-PageOperator] <String>]
[[-DeleteLevel] <Object>]
[-Force]
[[-InputObject] <Job[]>]
[-EnableException]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
PS C:\> Set-DbaAgentJob sql1 -Job Job1 -Disabled
Changes the job to disabled
PS C:\> Set-DbaAgentJob sql1 -Job Job1 -OwnerLogin user1
Changes the owner of the job
PS C:\> Set-DbaAgentJob -SqlInstance sql1 -Job Job1 -EventLogLevel OnSuccess
Changes the job and sets the notification to write to the Windows Application event log on success
PS C:\> Set-DbaAgentJob -SqlInstance sql1 -Job Job1 -EmailLevel OnFailure -EmailOperator dba
Changes the job and sets the notification to send an e-mail to the e-mail operator
PS C:\> Set-DbaAgentJob -SqlInstance sql1 -Job Job1, Job2, Job3 -Enabled
Changes multiple jobs to enabled
PS C:\> Set-DbaAgentJob -SqlInstance sql1, sql2, sql3 -Job Job1, Job2, Job3 -Enabled
Changes multiple jobs to enabled on multiple servers
PS C:\> Set-DbaAgentJob -SqlInstance sql1 -Job Job1 -Description 'Just another job' -Whatif
Doesn't Change the job but shows what would happen.
PS C:\> Set-DbaAgentJob -SqlInstance sql1, sql2, sql3 -Job 'Job One' -Description 'Job One'
Changes a job with the name "Job1" on multiple servers to have another description
PS C:\> sql1, sql2, sql3 | Set-DbaAgentJob -Job Job1 -Description 'Job One'
Changes a job with the name "Job1" on multiple servers to have another description using pipe line
The target SQL Server instance or instances. You must have sysadmin access and server version must be SQL Server version 2000 or greater.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
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.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the name of the SQL Server Agent job to modify. Accepts wildcards and multiple job names.
Use this to target specific jobs for configuration changes rather than modifying all jobs on an instance.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Attaches existing shared schedules to the job by name. Accepts multiple schedule names.
Use this when you need to assign predefined schedules to jobs without recreating scheduling logic.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Attaches existing shared schedules to the job by their numeric ID. Accepts multiple schedule IDs.
Use this when you know the specific schedule ID numbers and want to avoid potential name conflicts.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Renames the job to the specified name. The new name must be unique within the SQL Server instance.
Use this when standardizing job names across environments or fixing naming conventions.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Enables the job so it can be executed by SQL Server Agent schedules or manual execution.
Use this when reactivating disabled jobs or deploying jobs that should run immediately.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Disables the job to prevent it from running on schedule or manual execution.
Use this when temporarily stopping jobs during maintenance windows or permanently deactivating obsolete jobs.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Updates the job's description field with explanatory text about the job's purpose or functionality.
Use this to document what the job does, when it should run, or special requirements for maintenance teams.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Sets which job step should execute first when the job runs. Must correspond to an existing step ID within the job.
Use this when you need to change the job's execution flow or skip initial steps during testing or maintenance.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | 0 |
Assigns the job to a specific job category for organizational purposes. Creates the category if it doesn't exist when used with -Force.
Use this to group related jobs together for easier management and reporting in SQL Server Management Studio.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Changes the job owner to the specified SQL Server login. The login must already exist on the instance.
Use this when reassigning job ownership for security compliance or when the current owner login is being removed.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Controls when job execution results are logged to the Windows Application Event Log. Values: Never, OnSuccess, OnFailure, Always (or 0-3).
Use this to integrate job monitoring with Windows event log monitoring systems or reduce log noise by only logging failures.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | |
| Accepted Values | 0,Never,1,OnSuccess,2,OnFailure,3,Always |
Determines when to send email notifications about job completion. Values: Never, OnSuccess, OnFailure, Always (or 0-3).
Must be used with EmailOperator parameter. Use this to set up automated job failure notifications to the DBA team.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | |
| Accepted Values | 0,Never,1,OnSuccess,2,OnFailure,3,Always |
Controls when to send network messages (net send) about job completion. Values: Never, OnSuccess, OnFailure, Always (or 0-3).
Must be used with NetsendOperator parameter. Note that net send is deprecated and rarely used in modern environments.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | |
| Accepted Values | 0,Never,1,OnSuccess,2,OnFailure,3,Always |
Determines when to send pager notifications about job completion. Values: Never, OnSuccess, OnFailure, Always (or 0-3).
Must be used with PageOperator parameter. Use this for critical jobs requiring immediate attention when they fail.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | |
| Accepted Values | 0,Never,1,OnSuccess,2,OnFailure,3,Always |
Specifies which SQL Server Agent operator receives email notifications when EmailLevel conditions are met. The operator must already exist.
Use this to assign job failure notifications to specific DBA team members or distribution lists.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies which SQL Server Agent operator receives network messages when NetsendLevel conditions are met. The operator must already exist.
Rarely used in modern environments due to the deprecation of the net send functionality.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies which SQL Server Agent operator receives pager notifications when PageLevel conditions are met. The operator must already exist.
Use this for high-priority jobs where immediate mobile notification is required for on-call DBAs.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Controls when the job should automatically delete itself after execution. Values: Never, OnSuccess, OnFailure, Always (or 0-3).
Use this for one-time jobs like data migrations or temporary maintenance tasks that should clean up after completion.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | |
| Accepted Values | 0,Never,1,OnSuccess,2,OnFailure,3,Always |
Bypasses validation checks and creates missing job categories when specified with the Category parameter.
Use this when you want to create new categories during job updates without having to pre-create them separately.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Accepts SQL Server Agent job objects from the pipeline, typically from Get-DbaAgentJob output.
Use this to chain job operations together or when working with job objects retrieved from other dbatools commands.
| Alias | |
| Required | False |
| Pipeline | true (ByValue) |
| Default Value |
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.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Shows what would happen if the command were to run. No actions are actually performed.
| Alias | wi |
| Required | False |
| Pipeline | false |
| Default Value |
Prompts you for confirmation before executing any changing operations within the command.
| Alias | cf |
| Required | False |
| Pipeline | false |
| Default Value |