Agent Job Resource

Synopsis

Manages SQL Server Agent jobs, including job creation, notification settings, and monitoring of job execution status.

Type

OpenDsc.SqlServer/AgentJob

Capabilities

Get
Set
Delete
Export

Properties

Connection properties

serverInstance

SQL Server instance name.

Type: string
Required: Yes
Access: Read/Write
Default value: None

connectUsername

Username for SQL authentication.

Type: string
Required: No
Access: Write-Only
Default value: None

connectPassword

Password for SQL authentication.

Type: string
Required: No
Access: Write-Only
Default value: None

Job properties

name

Name of the Agent job.

Type: string
Required: No
Access: Read/Write
Default value: None

description

Description of the job.

Type: string
Required: No
Access: Read/Write
Default value: None

isEnabled

Whether the job is enabled.

Type: bool
Required: No
Access: Read/Write
Default value: None

ownerLoginName

Login name of the job owner.

Type: string
Required: No
Access: Read/Write
Default value: None

startStepId

Step ID at which execution starts. Minimum value is 1.

Type: int
Required: No
Access: Read/Write
Default value: None

Notification properties

emailLevel

When to send email. Accepts Never, OnSuccess, OnFailure, or Always.

Type: string
Required: No
Access: Read/Write
Default value: None

operatorToEmail

Operator to email.

Type: string
Required: No
Access: Read/Write
Default value: None

pageLevel

When to page. Accepts Never, OnSuccess, OnFailure, or Always.

Type: string
Required: No
Access: Read/Write
Default value: None

operatorToPage

Operator to page.

Type: string
Required: No
Access: Read/Write
Default value: None

netSendLevel

When to net send. Accepts Never, OnSuccess, OnFailure, or Always.

Type: string
Required: No
Access: Read/Write
Default value: None

operatorToNetSend

Operator for net send.

Type: string
Required: No
Access: Read/Write
Default value: None

eventLogLevel

When to write to the event log. Accepts Never, OnSuccess, OnFailure, or Always.

Type: string
Required: No
Access: Read/Write
Default value: None

deleteLevel

When to delete the job. Accepts Never, OnSuccess, OnFailure, or Always.

Type: string
Required: No
Access: Read/Write
Default value: None

Read-only properties

jobId

Unique identifier of the job.

Type: guid
Required: No
Access: Read-Only
Default value: None

dateCreated

Date the job was created.

Type: datetime
Required: No
Access: Read-Only
Default value: None

dateLastModified

Date the job was last modified.

Type: datetime
Required: No
Access: Read-Only
Default value: None

lastRunDate

Date of the last run.

Type: datetime
Required: No
Access: Read-Only
Default value: None

lastRunOutcome

Outcome of the last run. Returns Failed, Succeeded, Retry, or Cancelled.

Type: string
Required: No
Access: Read-Only
Default value: None

nextRunDate

Date of the next scheduled run.

Type: datetime
Required: No
Access: Read-Only
Default value: None

currentRunStatus

Current status. Returns Idle, Executing, WaitingForWorkerThread, or BetweenRetries.

Type: string
Required: No
Access: Read-Only
Default value: None

currentRunStep

Current step being executed.

Type: string
Required: No
Access: Read-Only
Default value: None

currentRunRetryAttempt

Current retry attempt number.

Type: int
Required: No
Access: Read-Only
Default value: None

hasStep

Whether the job has steps defined.

Type: bool
Required: No
Access: Read-Only
Default value: None

hasSchedule

Whether the job has schedules.

Type: bool
Required: No
Access: Read-Only
Default value: None

versionNumber

Job version number.

Type: int
Required: No
Access: Read-Only
Default value: None

DSC properties

_exist

Whether the job should exist.

Type: bool
Required: No
Access: Read/Write
Default value: true

Examples

Example 1 — Get a job

PowerShellShell

$resourceInput = @'
serverInstance: .
name: syspolicy_purge_history
'@

dsc resource get -r OpenDsc.SqlServer/AgentJob --input $resourceInput

resource_input=$(cat <<'EOF'
serverInstance: .
name: syspolicy_purge_history
EOF
)

dsc resource get -r OpenDsc.SqlServer/AgentJob --input "$resource_input"

Example 2 — Create a job

PowerShellShell

$resourceInput = @'
serverInstance: .
name: NightlyMaintenance
description: Nightly index rebuild and statistics update
isEnabled: true
category: Database Maintenance
emailLevel: OnFailure
operatorToEmail: DBA Team
'@

dsc resource set -r OpenDsc.SqlServer/AgentJob --input $resourceInput

resource_input=$(cat <<'EOF'
serverInstance: .
name: NightlyMaintenance
description: Nightly index rebuild and statistics update
isEnabled: true
category: Database Maintenance
emailLevel: OnFailure
operatorToEmail: DBA Team
EOF
)

dsc resource set -r OpenDsc.SqlServer/AgentJob --input "$resource_input"

Example 3 — Configuration document

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Nightly maintenance job
    type: OpenDsc.SqlServer/AgentJob
    properties:
      serverInstance: "."
      name: NightlyMaintenance
      description: Nightly index rebuild and statistics update
      isEnabled: true
      category: Database Maintenance
      emailLevel: OnFailure
      operatorToEmail: DBA Team

Exit codes

Code	Description
0	Success
1	Error
2	Invalid JSON
3	Invalid argument
4	Unauthorized access
5	Invalid operation