lowlydba.sqlserver.agent_job_step module – Configures a SQL Agent job step

Note

This module is part of the lowlydba.sqlserver collection (version 2.7.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install lowlydba.sqlserver. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: lowlydba.sqlserver.agent_job_step.

New in lowlydba.sqlserver 0.1.0

Synopsis

  • Configures a step for an agent job.

Requirements

The below requirements are needed on the host that executes this module.

Parameters

Parameter

Comments

command

string

The commands to be executed by SQLServerAgent service through subsystem.

database

string

The name of the database in which to execute a Transact-SQL step.

Default: "master"

job

string / required

The name of the job to which to add the step.

on_fail_action

string

The action to perform if the step fails.

Choices:

  • "QuitWithSuccess"

  • "QuitWithFailure" ← (default)

  • "GoToNextStep"

  • "GoToStep"

on_fail_step_id

integer

The ID of the step in this job to execute if the step fails and on_fail_action=GoToStep.

Default: 0

on_success_action

string

The action to perform if the step succeeds.

Choices:

  • "QuitWithSuccess" ← (default)

  • "QuitWithFailure"

  • "GoToNextStep"

  • "GoToStep"

on_success_step_id

integer

The ID of the step in this job to execute if the step succeeds and on_success_action=GoToStep.

Default: 0

output_file

string

added in lowlydba.sqlserver 2.7.0

The full path to the output file for the job step.

This specifies where the output of the job step will be written.

retry_attempts

integer

The number of retry attempts to use if this step fails. The default is 0.

Default: 0

retry_interval

integer

The amount of time in minutes between retry attempts.

Default: 0

sql_instance

string / required

The SQL Server instance to modify.

sql_password

string

Password for SQL Authentication.

sql_username

string

Username for SQL Authentication.

state

string

Whether or not the object should be present or absent.

Choices:

  • "present" ← (default)

  • "absent"

step_id

integer

The sequence identification number for the job step. Step identification numbers start at 1 and increment without gaps.

Required if state=present.

step_name

string

The name of the step. Required if state=present.

subsystem

string

The subsystem used by the SQL Server Agent service to execute command.

Choices:

  • "CmdExec"

  • "Distribution"

  • "LogReader"

  • "Merge"

  • "PowerShell"

  • "QueueReader"

  • "Snapshot"

  • "Ssis"

  • "TransactSql" ← (default)

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

platform

Platforms: all

Target OS/families that can be operated against.

Examples

- name: Create a job
  lowlydba.sqlserver.agent_job:
    sql_instance: sql-01.myco.io
    job: MyJob
    force: true

- name: Create a job step
  lowlydba.sqlserver.agent_job_step:
    sql_instance: sql-01.myco.io
    job: MyJob
    step_name: Step1
    step_id: 1
    command: "TRUNCATE TABLE dbo.TestData;"

- name: Create a job step with output file
  lowlydba.sqlserver.agent_job_step:
    sql_instance: sql-01.myco.io
    job: MyJob
    step_name: Step2
    step_id: 2
    command: "SELECT * FROM sys.databases;"
    output_file: "C:\\Logs\\MyJob_Step2.log"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

data

dictionary

Output from the New-DbaAgentJobStep, Set-DbaAgentJobStep, or Remove-DbaAgentJobStep function.

Returned: success, but not in check_mode.

Authors

  • John McCall (@lowlydba)