Job Specification and Status

A Job Specification is a detailed set of instructions that tells the IPF Persistent Scheduler how to run a specific job. It includes several key components, each with a specific purpose. A job can have different status’ depending on where it is in its lifecycle:

Job Specification

It consists of the following parts:

Name Mandatory? Description

Name	Mandatory?	Description
`jobSpecificationKey`	Yes	A unique identifier for this job
`jobRequestor`	Yes	A unique identifier for the requestor (a requestor can have multiple jobs)
`schedulingSpecification`	No	The cron expression for a recurrent job.
`singleSchedule`	No	The exact time to schedule a one-time job (to millisecond precision).
`triggerCommand`	Yes	The `Command` to send to the `SchedulingHelper` at the scheduled time(s)
`triggerIdentifier`	Yes	Identifier to pass alongside the `triggerCommand` when invoking `SchedulingHelper` at the scheduled time(s)
`failureCommand`	No	If configured, when a failed execution is detected, the `SchedulingHelper` that supports this command will be invoked.
`failureIdentifier`	No	Identifier to pass alongside the `failureCommand` when invoking the `SchedulingHelper` after a failure
`calendar`	No	Calendar to use for this job (see Calendars)
`zoneId`	No	A time-zone id, such as `Europe/Paris`, used to override the default system time zone when scheduling a task. If omitted, the system default is used. List of zone ids.
`lateExecutionThreshold`	No	Duration threshold for late execution handling. If the job starts after the planned time plus this threshold, `lateExecute(…)` is invoked instead of `execute(…)`.
`deleteTime`	No	Used for Time-To-Live index (TTL Indexes). One-time jobs that have been executed successfully. One-time jobs that have failed execution. All jobs that have been cancelled. All these jobs will be updated with a "delete time" and will no longer be available when querying them in the database. It will allow us to quickly retrieve the latest job specifications and filter out (in case of rehydration) the jobs that have been excluded.
`processingContext`	No	A Processing Context for this job. If you chose to provide a Processing Context, values for `processingEntity`, `clientRequestId` and `unitOfWorkId` must be included.

jobSpecificationKey

Yes

A unique identifier for this job

jobRequestor

Yes

A unique identifier for the requestor (a requestor can have multiple jobs)

schedulingSpecification

The cron expression for a recurrent job.

singleSchedule

The exact time to schedule a one-time job (to millisecond precision).

triggerCommand

Yes

The Command to send to the SchedulingHelper at the scheduled time(s)

triggerIdentifier

Yes

Identifier to pass alongside the triggerCommand when invoking SchedulingHelper at the scheduled time(s)

failureCommand

If configured, when a failed execution is detected, the SchedulingHelper that supports this command will be invoked.

failureIdentifier

Identifier to pass alongside the failureCommand when invoking the SchedulingHelper after a failure

calendar

Calendar to use for this job (see Calendars)

zoneId

A time-zone id, such as Europe/Paris, used to override the default system time zone when scheduling a task. If omitted, the system default is used. List of zone ids.

lateExecutionThreshold

Duration threshold for late execution handling. If the job starts after the planned time plus this threshold, lateExecute(…) is invoked instead of execute(…).

deleteTime

Used for Time-To-Live index (TTL Indexes). One-time jobs that have been executed successfully. One-time jobs that have failed execution. All jobs that have been cancelled. All these jobs will be updated with a "delete time" and will no longer be available when querying them in the database. It will allow us to quickly retrieve the latest job specifications and filter out (in case of rehydration) the jobs that have been excluded.

processingContext

A Processing Context for this job. If you chose to provide a Processing Context, values for processingEntity, clientRequestId and unitOfWorkId must be included.

A valid job specification MUST specify exactly one of schedulingSpecification (for a cron-based recurrent job) or singleSchedule (for a one-time job at a specific instant). Setting both will result in failure.

Job Execution Status

The JobExecutionStatus collection is linked to the JobSpecification collection by the jobSpecificationId field.

The JobExecutionStatus collection is going to change more frequently, because the status of a job changes more frequently than its specification.

It contains the jobSpecificationId, the executionStatus the updatedTime and the deleteTime. It is an append only collection and in order to get the current job execution status we just need to order by updatedTime and get the latest more recent entry.

Similarly to the JobSpecification collection, the deleteTime field is used for TTL (Time-To-Live) index. In addition, for recurrent jobs, when a job is triggered, the previous entry will be marked for deletion. Only the most recent entry is worth keeping.

Status definitions

The different statuses are:

SCHEDULED: Is scheduled to run (and may have run in the past)
TRIGGERED: Has already run and will not run again
CANCELED: Was previously SCHEDULED but was not triggred
FAILED: Failed to execute