Name

Get-JobSchedulerTaskHistory

SYNOPSIS

Returns the task execution history for jobs.

SYNTAX

Get-JobSchedulerTaskHistory [[-Job] <String>] [[-JobChain] <String>] [[-OrderId] <String>] [[-Directory] <String>] [-Recursive] [[-State] <String>] [[-ExcludeJob] <String[]>] [[-RegEx] <String>] [[-DateFrom] <DateTime>] [[-DateTo] <DateTime>] [[-RelativeDateFrom] <String>] [[-RelativeDateTo] <String>] [[-Timezone] <TimeZoneInfo>] [[-TaskId] <Int32[]>] [[-Limit] <Int32>] [-Successful] [-Failed] [-Incomplete] [<CommonParameters>]

DESCRIPTION

History information is returned for jobs from a JobScheduler Master.
Task executions can be selected by job name, folder, history status etc.

The history information retured includes start time, end time, return code etc.

PARAMETERS

Job

-Job <String>
Optionally specifies the path and name of a job.
If the name of a job is specified then the -Directory parameter is used to determine the folder.
Otherwise the -Job parameter is assumed to include the full path and name of the job.

One of the parameters -Directory, -JobChain or -Job has to be specified.

Required?false
Position?1
Default value
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

JobChain

-JobChain <String>
Optionally specifies the path and name of a job chain that includes jobs.
If the name of a job chain is specified then the -Directory parameter is used to determine the folder.
Otherwise the -JobChain parameter is assumed to include the full path and name of the job chain.

One of the parameters -Directory, -JobChain or -Job has to be specified.

Required?false
Position?2
Default value
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

OrderId

-OrderId <String>
Optionally specifies the identifier of an order to limit results to jobs that
correspond to the order's current state.

Required?false
Position?3
Default value
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

Directory

-Directory <String>
Optionally specifies the folder for which jobs should be returned. The directory is determined
from the root folder, i.e. the "live" directory.

Required?false
Position?4
Default value/
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

Recursive

-Recursive <SwitchParameter>
Specifies that any sub-folders should be looked up when used with the -Directory parameter.
By default no sub-folders will be looked up for jobs.

Required?false
Position?named
Default valueFalse
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

State

-State <String>
Specifies that only jobs are considered that an order is currently passing. This is identified by the
order's state attribute that corresponds to the job node's state attribute.
This parameter requires use of the -JobChain parameter. If used with the -OrderId parameter then
only jobs for that order are considered, otherwise jobs for any orders in the given job chain are considered.

Required?false
Position?5
Default value
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

ExcludeJob

-ExcludeJob <String[]>
This parameter accepts a single job path or an array of job paths that are excluded from the results.

Required?false
Position?6
Default value
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

RegEx

-RegEx <String>
Specifies a regular expression that filters the jobs to be returned.
The regular expression is applied to the path and name of jobs.

Required?false
Position?7
Default value
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

DateFrom

-DateFrom <DateTime>
Specifies the date starting from which history items should be returned.
Consider that a UTC date has to be provided.

Default: Begin of the current day as a UTC date

Required?false
Position?8
Default value(Get-Date -Hour 0 -Minute 0 -Second 0).ToUniversalTime()
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

DateTo

-DateTo <DateTime>
Specifies the date until which history items should be returned.
Consider that a UTC date has to be provided.

Default: End of the current day as a UTC date

Required?false
Position?9
Default value(Get-Date -Hour 0 -Minute 0 -Second 0).AddDays(1).ToUniversalTime()
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

RelativeDateFrom

-RelativeDateFrom <String>
Specifies a relative date starting from which history items should be returned, e.g.

* -1s, -2s: one second ago, two seconds ago
* -1m, -2m: one minute ago, two minutes ago
* -1h, -2h: one hour ago, two hours ago
* -1d, -2d: one day ago, two days ago
* -1w, -2w: one week ago, two weeks ago
* -1M, -2M: one month ago, two months ago
* -1y, -2y: one year ago, two years ago

Optionally a time offset can be specified, e.g. -1d+02:00, as otherwise midnight UTC is assumed.
Alternatively a timezone offset can be added, e.g. by using -1d+TZ, that is calculated by the cmdlet
for the timezone that is specified with the -Timezone parameter.

This parameter takes precedence over the -DateFrom parameter.

Required?false
Position?10
Default value
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

RelativeDateTo

-RelativeDateTo <String>
Specifies a relative date until which history items should be returned, e.g.

* -1s, -2s: one second ago, two seconds ago
* -1m, -2m: one minute ago, two minutes ago
* -1h, -2h: one hour ago, two hours ago
* -1d, -2d: one day ago, two days ago
* -1w, -2w: one week ago, two weeks ago
* -1M, -2M: one month ago, two months ago
* -1y, -2y: one year ago, two years ago

Optionally a time offset can be specified, e.g. -1d+02:00, as otherwise midnight UTC is assumed.
Alternatively a timezone offset can be added, e.g. by using -1d+TZ, that is calculated by the cmdlet
for the timezone that is specified with the -Timezone parameter.

This parameter takes precedence over the -DateFrom parameter.

Required?false
Position?11
Default value
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

Timezone

-Timezone <TimeZoneInfo>
Specifies the timezone to which dates should be converted in the history information.
A timezone can e.g. be specified like this:

Get-JSTaskHistory -Timezone (Get-Timezone -Id 'GMT Standard Time')

All dates in JobScheduler are UTC and can be converted e.g. to the local time zone like this:

Get-JSTaskHistory -Timezone (Get-Timezone)

Default: Dates are returned in UTC.

Required?false
Position?12
Default value(Get-Timezone -Id 'UTC')
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

TaskId

-TaskId <Int32[]>

Required?false
Position?13
Default value
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

Limit

-Limit <Int32>
Specifies the max. number of history items for task executions to be returned.
The default value is 10000, for an unlimited number of items the value -1 can be specified.

Required?false
Position?14
Default value0
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

Successful

-Successful <SwitchParameter>
Returns history information for successfully completed tasks.

Required?false
Position?named
Default valueFalse
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

Failed

-Failed <SwitchParameter>
Returns history information for failed tasks.

Required?false
Position?named
Default valueFalse
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

Incomplete

-Incomplete <SwitchParameter>
Specifies that history information for running tasks should be returned.

Required?false
Position?named
Default valueFalse
Accept pipeline input?true (ByPropertyName)
Accept wildcard characters?false

about_JobScheduler

EXAMPLES

-------------------------- EXAMPLE 1 --------------------------

PS > $items = Get-JobSchedulerTaskHistory

Returns today's task execution history for any jobs.

-------------------------- EXAMPLE 2 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -RegEx '^/sos'

Returns today's task execution history for any jobs from the /sos folder.

-------------------------- EXAMPLE 3 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -RegEx 'report'

Returns today's task execution history for jobs that contain the string 'report' in the job path.

-------------------------- EXAMPLE 4 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -Timezone (Get-Timezone)

Returns today's task execution history for any jobs with dates being converted to the local timezone.

-------------------------- EXAMPLE 5 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -Timezone (Get-Timezone -Id 'GMT Standard Time')

Returns today's task execution history for any jobs with dates being converted to the GMT timezone.

-------------------------- EXAMPLE 6 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -Job /sos/dailyplan/CreateDailyPlan

Returns today's task execution history for a given job.

-------------------------- EXAMPLE 7 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -JobChain /sos/dailyplan/CreateDailyPlan

Returns today's task execution history for jobs in the given job chain.

-------------------------- EXAMPLE 8 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -ExcludeJob /sos/dailyplan/CreateDailyPlan, /sos/housekeeping/scheduler_rotate_log

Returns today's task execution history for any jobs excluding the specified job paths.

-------------------------- EXAMPLE 9 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -Successful -DateFrom "2020-08-11 14:00:00Z"

Returns the task execution history for successfully completed jobs that started after the specified UTC date and time.

-------------------------- EXAMPLE 10 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -Failed -DateFrom (Get-Date -Hour 0 -Minute 0 -Second 0).AddDays(-7).ToUniversalTime()

Returns the task execution history for any failed jobs for the last seven days.

-------------------------- EXAMPLE 11 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -RelativeDateFrom -7d

Returns the task execution history for the last seven days. The history is reported starting from midnight UTC.

-------------------------- EXAMPLE 12 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -RelativeDateFrom -7d+01:00

Returns the task execution history for the last seven days. The history is reported starting from 1 hour after midnight UTC.

-------------------------- EXAMPLE 13 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -RelativeDateFrom -7d+TZ

Returns the task execution history for any jobs for the last seven days. The history is reported starting from midnight in the same timezone that is used with the -Timezone parameter.

-------------------------- EXAMPLE 14 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -RelativeDateFrom -1w

Returns the task execution history for the last week.

-------------------------- EXAMPLE 15 --------------------------

PS > $items = Get-JobSchedulerTaskHistory -Directory /sos -Recursive -Successful -Failed

Returns today's task execution history for any completed tasks from the "/sos" directory and any sub-folders recursively.

  • No labels