Copy-DbaAgentJobCategory

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

Synopsis

Copies custom SQL Agent categories for jobs, alerts, and operators between SQL Server instances.

Description

Migrates custom SQL Agent categories from a source SQL Server to one or more destination servers, so you don't have to manually recreate organizational structures during server migrations or environment setups.
This function copies only user-defined categories (ID >= 100), preserving built-in system categories on the destination.
Essential for maintaining consistent job categorization across multiple SQL Server instances in enterprise environments.

You can copy all categories at once or filter by category type (Job, Alert, Operator) or specify individual category names.
Categories that already exist on the destination will be skipped unless you use -Force to drop and recreate them.
The function uses SQL Server Management Objects (SMO) to script category definitions and recreate them on the target server.

Syntax

Copy-DbaAgentJobCategory -Source <DbaInstanceParameter>
    [-SourceSqlCredential <PSCredential>]
    -Destination <DbaInstanceParameter[]>
    [-DestinationSqlCredential <PSCredential>]
    [-JobCategory <String[]>]
    [-AgentCategory <String[]>]
    [-OperatorCategory <String[]>]
    [-Force]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Copy-DbaAgentJobCategory -Source <DbaInstanceParameter>
    [-SourceSqlCredential <PSCredential>]
    -Destination <DbaInstanceParameter[]>
    [-DestinationSqlCredential <PSCredential>]
    [-CategoryType <String[]>]
    [-JobCategory <String[]>]
    [-AgentCategory <String[]>]
    [-OperatorCategory <String[]>]
    [-Force]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Copy-DbaAgentJobCategory -Source sqlserver2014a -Destination sqlcluster

Copies all operator categories from sqlserver2014a to sqlcluster using Windows authentication. If operator categories with the same name exist on sqlcluster, they will be skipped.

Example: 2

PS C:\> Copy-DbaAgentJobCategory -Source sqlserver2014a -Destination sqlcluster -OperatorCategory PSOperator -SourceSqlCredential $cred -Force

Copies a single operator category, the PSOperator operator category from sqlserver2014a to sqlcluster using SQL credentials to authenticate to sqlserver2014a and Windows credentials for sqlcluster.
If an operator category with the same name exists on sqlcluster, it will be dropped and recreated because -Force was used.

Example: 3

PS C:\> Copy-DbaAgentJobCategory -Source sqlserver2014a -Destination sqlcluster -WhatIf -Force

Shows what would happen if the command were executed using force.

Required Parameters

-Source

The source SQL Server instance from which to copy Agent job categories. Requires sysadmin permissions to access MSDB and read category definitions.
Use this to specify the server that has the custom categories you want to replicate to other instances.

-Destination

One or more destination SQL Server instances where the Agent job categories will be created. Accepts an array to copy categories to multiple servers simultaneously.
Requires sysadmin permissions to create categories in each destination server's MSDB database.

Optional Parameters

-SourceSqlCredential

Alternative credentials for connecting to the source SQL Server instance. Use this when your current Windows authentication doesn't have sufficient permissions on the source server.
Accepts credentials created with Get-Credential for SQL authentication or different Windows accounts.

-DestinationSqlCredential

Alternative credentials for connecting to the destination SQL Server instances. Use this when different authentication is needed for the destination servers than your current context.
Accepts credentials created with Get-Credential and applies to all destination servers specified.

-CategoryType

Filters the copy operation to specific category types: Job, Alert, or Operator. When specified, copies all categories of the selected type(s) from the source.
Use this for bulk migration of entire category types rather than individual category names. Leave empty to copy all category types.

-JobCategory

Specific job category names to copy from the source server. Use this for selective migration when you only need certain job categories.
Supports tab completion from the source server's existing job categories for convenience.

-AgentCategory

Specific alert category names to copy from the source server. Use this for selective migration when you only need certain alert categories.
Note: This parameter is currently not implemented in the function code and will be ignored if used.

-OperatorCategory

Specific operator category names to copy from the source server. Use this for selective migration when you only need certain operator categories.
Supports tab completion from the source server's existing operator categories for convenience.

-Force

Drops and recreates existing categories on the destination servers instead of skipping them. Use this when you need to overwrite categories that have changed on the source.
Without this switch, categories that already exist on the destination will be skipped to prevent data loss.

-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

If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.

-Confirm

If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.