Set-DbaAgentJob

Synopsis

Modifies existing SQL Server Agent job properties and notification settings.

Description

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.

Syntax

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

Examples

Example: 1

PS C:\> Set-DbaAgentJob sql1 -Job Job1 -Disabled

Changes the job to disabled

Example: 2

PS C:\> Set-DbaAgentJob sql1 -Job Job1 -OwnerLogin user1

Changes the owner of the job

Example: 3

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

Example: 4

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

Example: 5

PS C:\> Set-DbaAgentJob -SqlInstance sql1 -Job Job1, Job2, Job3 -Enabled

Changes multiple jobs to enabled

Example: 6

PS C:\> Set-DbaAgentJob -SqlInstance sql1, sql2, sql3 -Job Job1, Job2, Job3 -Enabled

Changes multiple jobs to enabled on multiple servers

Example: 7

PS C:\> Set-DbaAgentJob -SqlInstance sql1 -Job Job1 -Description 'Just another job' -Whatif

Doesn’t Change the job but shows what would happen.

Example: 8

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

Example: 9

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

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.

-Job

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.

-Schedule

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.

-ScheduleId

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.

-NewName

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.

-Enabled

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.

-Disabled

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.

-Description

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.

-StartStepId

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.

-Category

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.

-OwnerLogin

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.

-EventLogLevel

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.

-EmailLevel

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.

-NetsendLevel

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.

-PageLevel

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.

-EmailOperator

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.

-NetsendOperator

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.

-PageOperator

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.

-DeleteLevel

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.

-Force

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.

-InputObject

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.

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