feat: SQL Agent Job - allow setting output file

CHANGELOG.rst

@@ -4,27 +4,13 @@ lowlydba.sqlserver Release Notes
 
 .. contents:: Topics
 
-v2.6.1
+v2.7.0
 ======
 
 Minor Changes
 -------------
 
-- Added support for Ansible 2.19
-- Updated the test matrix to include Ansible 2.19 and remove Ansible 2.16
-
-v2.6.0
-======
-
-Release Summary
---------------
-
-Added support for contained Availability Groups using dbatools 2.1.15 - thanks @DorBreger!
-
-Minor Changes
--------------
-
-- Added support for contained Availability Groups using dbatools 2.1.15 (https://github.com/lowlydba/lowlydba.sqlserver/pull/249).
+- agent_job - Add new parameter ``output_file`` to configure the SQL Agent job output file path (https://github.com/LowlyDBA/lowlydba.sqlserver/pull/323)
 
 v2.5.0
 ======

changelogs/changelog.yaml

@@ -556,20 +556,11 @@ releases:
       name: login_role
       namespace: ''
     release_date: '2024-12-15'
-  2.6.0:
+  2.7.0:
     changes:
       minor_changes:
-      - Added support for contained Availability Groups using dbatools 2.1.15 (https://github.com/lowlydba/lowlydba.sqlserver/pull/249).
-      release_summary: Added support for contained Availability Groups using dbatools 2.1.15 - thanks @DorBreger!
+      - agent_job - Add new parameter ``output_file`` to configure the SQL Agent job
+        output file path (https://github.com/LowlyDBA/lowlydba.sqlserver/pull/323)
     fragments:
-    - noop.yml
-    release_date: '2025-04-06'
-  2.6.1:
-    changes:
-      minor_changes:
-      - Added support for Ansible 2.19
-      - Updated the test matrix to include Ansible 2.19 and remove Ansible 2.16
-      release_summary: Testing updates for Ansible 2.19 compatibility.
-    fragments:
-    - 314-ansible-2-19-compatibility.yml
-    release_date: '2025-05-03'
+    - 2.7.0-agent_job_output.yml
+    release_date: '2025-08-02'

galaxy.yml

@@ -2,7 +2,7 @@
 
 namespace: lowlydba
 name: sqlserver
-version: 2.6.1
+version: 2.7.0
 readme: README.md
 authors:
   - John McCall (github.com/lowlydba)

plugins/modules/agent_job.ps1

@@ -22,6 +22,7 @@ $spec = @{
         schedule = @{type = 'str'; required = $false; }
         force = @{type = 'bool'; required = $false; default = $false }
         state = @{type = 'str'; required = $false; default = 'present'; choices = @('present', 'absent') }
+        output_file = @{type = 'str'; required = $false; }
     }
 }
 
@@ -36,8 +37,10 @@ $schedule = $module.Params.schedule
 [nullable[int]]$startStepId = $module.Params.start_step_id
 $force = $module.Params.force
 $state = $module.Params.state
+$outputFile = $module.Params.output_file
 $checkMode = $module.CheckMode
 $module.Result.changed = $false
+$PSDefaultParameterValues = @{ "*:EnableException" = $true; "*:Confirm" = $false; "*:WhatIf" = $checkMode }
 
 # Configure Agent job
 try {
@@ -46,7 +49,7 @@ try {
 
     if ($state -eq "absent") {
         if ($null -ne $existingJob) {
-            $output = $existingJob | Remove-DbaAgentJob -Confirm:$false -WhatIf:$checkMode -EnableException
+            $output = $existingJob | Remove-DbaAgentJob
             $module.Result.changed = $true
         }
     }
@@ -55,9 +58,7 @@ try {
             SqlInstance = $sqlInstance
             SqlCredential = $sqlCredential
             Job = $job
-            WhatIf = $checkMode
             Force = $force
-            EnableException = $true
         }
 
         if ($enabled -eq $false) {
@@ -89,7 +90,7 @@ try {
             try {
                 $null = New-DbaAgentJob @jobParams
                 # Explicitly fetch the new job to make sure results don't suffer from SMO / Agent stale data bugs
-                $output = Get-DbaAgentJob -SqlInstance $sqlInstance -SqlCredential $sqlCredential -Job $job -EnableException
+                $output = Get-DbaAgentJob -SqlInstance $sqlInstance -SqlCredential $sqlCredential -Job $job
             }
             catch {
                 $module.FailJson("Failed creating new agent job: $($_.Exception.Message)", $_)
@@ -120,10 +121,37 @@ try {
                 }
             }
         }
+
+        # Set output file if specified
+        if ($null -ne $outputFile) {
+            try {
+                if (-not $checkMode) {
+                    # Set the requested output file
+                    $newObj = Set-DbaAgentJobOutputFile -SqlInstance $sqlInstance -SqlCredential $sqlCredential -Job $job -OutputFile $outputFile
+                    $outputFileResult = @{ OutputFile = $newObj.OutputFile }
+                    $module.Result.changed = $newObj.OldOutputFileName -ne $newObj.OutputFile
+                }
+                else {
+                    # Check mode: predict change without making it
+                    $outputFileResult = @{ OutputFile = $outputFile }
+                    $module.Result.changed = $beforeValue -ne $outputFile
+                }
+            }
+            catch {
+                $module.FailJson("Failed setting agent job output file: $($_.Exception.Message)", $_)
+            }
+        }
     }
 
     if ($output) {
+        # Convert to serializable first
         $resultData = ConvertTo-SerializableObject -InputObject $output
+
+        # Add output file info to result data
+        $resultData | Add-Member -MemberType NoteProperty -Name 'OutputFileInfo' -Value $(
+            if ($null -ne $outputFile) { $outputFileResult } else { $null }
+        ) -Force
+
         $module.Result.data = $resultData
     }
     $module.ExitJson()

plugins/modules/agent_job.py

@@ -55,6 +55,12 @@
       - If I(force=true), any job categories will be created if they don't exist already.
     type: bool
     default: false
+  output_file:
+    description:
+      - The path to the output file for the SQL Agent job. The output file will only be updated if the desired value is different from the current value.
+    type: str
+    required: false
+    version_added: '2.7.0'
 author: "John McCall (@lowlydba)"
 notes:
   - On slower hardware, stale job component data may be returned (i.e., a previous or default job category).
@@ -78,7 +84,7 @@
 
 RETURN = r'''
 data:
-  description: Output from the C(New-DbaAgentJob), C(Set-DbaAgentJob), or C(Remove-DbaAgentJob) function.
+  description: Output from the C(New-DbaAgentJob), C(Set-DbaAgentJob), C(Remove-DbaAgentJob), or output file commands (C(Get-DbaAgentJobOutputFile)).
   returned: success, but not in check_mode.
   type: dict
 '''

tests/integration/targets/agent_job/tasks/main.yml

@@ -15,15 +15,20 @@
       description: "{{ description }}"
       force: true
       enabled: "{{ enabled }}"
+    lowlydba.sqlserver.agent_job_step:
+      sql_instance: "{{ sqlserver_instance }}"
+      sql_username: "{{ sqlserver_username }}"
+      sql_password: "{{ sqlserver_password }}"
+    lowlydba.sqlserver.agent_job_category:
+      sql_instance: "{{ sqlserver_instance }}"
+      sql_username: "{{ sqlserver_username }}"
+      sql_password: "{{ sqlserver_password }}"
   tags: ["agent_job"]
   block:
     # SQL Agent / SMO has delays on returning new data sometimes, and is worse on CI runners -
     # so explicitly pre-create the category to make sure we get timely & accurate results later
     - name: Prep agent job category
       lowlydba.sqlserver.agent_job_category:
-        sql_instance: "{{ sqlserver_instance }}"
-        sql_username: "{{ sqlserver_username }}"
-        sql_password: "{{ sqlserver_password }}"
         category: "{{ category_name }}"
 
     - name: Create agent job
@@ -40,27 +45,18 @@
 
     - name: Create agent job step one
       lowlydba.sqlserver.agent_job_step:
-        sql_instance: "{{ sqlserver_instance }}"
-        sql_username: "{{ sqlserver_username }}"
-        sql_password: "{{ sqlserver_password }}"
         job: "{{ job_name }}"
         step_name: "Step 1"
         step_id: 1
 
     - name: Create agent job step two
       lowlydba.sqlserver.agent_job_step:
-        sql_instance: "{{ sqlserver_instance }}"
-        sql_username: "{{ sqlserver_username }}"
-        sql_password: "{{ sqlserver_password }}"
         job: "{{ job_name }}"
         step_name: "Step 2"
         step_id: 2
 
     - name: Set start job step id
       lowlydba.sqlserver.agent_job:
-        sql_instance: "{{ sqlserver_instance }}"
-        sql_username: "{{ sqlserver_username }}"
-        sql_password: "{{ sqlserver_password }}"
         job: "{{ job_name }}"
         start_step_id: 2
       register: result
@@ -71,9 +67,6 @@
 
     - name: No change
       lowlydba.sqlserver.agent_job:
-        sql_instance: "{{ sqlserver_instance }}"
-        sql_username: "{{ sqlserver_username }}"
-        sql_password: "{{ sqlserver_password }}"
         job: "{{ job_name }}"
         start_step_id: 2
       register: result
@@ -132,15 +125,78 @@
           - result.data.Name == job_name
           - result is changed
 
+    - name: Set initial output file
+      lowlydba.sqlserver.agent_job:
+        output_file: 'C:\SQLJobLogs\job1.txt'
+      register: result
+    - assert:
+        that:
+          - result.data != None
+          - result.data.OutputFileInfo != None
+          - result.data.OutputFileInfo.OutputFile == 'C:\SQLJobLogs\job1.txt'
+          - result is changed
+
+    - name: Set same output file again (idempotency check)
+      lowlydba.sqlserver.agent_job:
+        output_file: 'C:\SQLJobLogs\job1.txt'
+      register: result
+    - assert:
+        that:
+          - result.data != None
+          - result.data.OutputFileInfo != None
+          - result.data.OutputFileInfo.OutputFile == 'C:\SQLJobLogs\job1.txt'
+          - result is not changed
+
+    - name: Change to different output file
+      lowlydba.sqlserver.agent_job:
+        output_file: 'C:\SQLJobLogs\job1_new.txt'
+      register: result
+    - assert:
+        that:
+          - result.data != None
+          - result.data.OutputFileInfo != None
+          - result.data.OutputFileInfo.OutputFile == 'C:\SQLJobLogs\job1_new.txt'
+          - result is changed
+
+    - name: Set initial output file
+      lowlydba.sqlserver.agent_job:
+        output_file: 'C:\SQLJobLogs\job1.txt'
+      register: result
+    - assert:
+        that:
+          - result.data != None
+          - result.data.OutputFileInfo != None
+          - result.data.OutputFileInfo.OutputFile == 'C:\SQLJobLogs\job1.txt'
+          - result is changed
+
+    - name: Set same output file again (idempotency check)
+      lowlydba.sqlserver.agent_job:
+        output_file: 'C:\SQLJobLogs\job1.txt'
+      register: result
+    - assert:
+        that:
+          - result.data != None
+          - result.data.OutputFileInfo != None
+          - result.data.OutputFileInfo.OutputFile == 'C:\SQLJobLogs\job1.txt'
+          - result is not changed
+
+    - name: Change to different output file
+      lowlydba.sqlserver.agent_job:
+        output_file: 'C:\SQLJobLogs\job1_new.txt'
+      register: result
+    - assert:
+        that:
+          - result.data != None
+          - result.data.OutputFileInfo != None
+          - result.data.OutputFileInfo.OutputFile == 'C:\SQLJobLogs\job1_new.txt'
+          - result is changed
+
   always:
     - name: Cleanup agent job
       lowlydba.sqlserver.agent_job:
         state: "absent"
 
     - name: Cleanup agent job category
       lowlydba.sqlserver.agent_job_category:
-        sql_instance: "{{ sqlserver_instance }}"
-        sql_username: "{{ sqlserver_username }}"
-        sql_password: "{{ sqlserver_password }}"
         category: "{{ category_name }}"
         state: absent