Customizing Jobs with Specific Actions

Actions allow you to interact with objects while these are doing something, the most common one being setting the final job status. With Actions you can change the status to Completed even if the job reached status Error. You may define a set of conditions that must be met for this change to take place. If you want to interact with jobs from many job definitions, it might be easier to use a trigger. See the Using Triggers and Using Actions sections of the documentation.

Note Note

Actions require RedwoodScript which in turn requires an Module.Scripting license key.

End of the note.

There are three different types of actions that fire at three different times in the life-cycle of a job. The following three actions are available:

On Change - When the status of a job changes but has not reached Queued (but does not fire when the status changes to Chained)
Pre Running - Before a job has started running
Post Running - After a job has completed

Post Running is the only action that allows changing the final status of a job, it is therefore the most used action. The other actions allow you to change the queue, start time or even hold the job if a set of defined conditions are met.

You need to understand the concepts of job states to get a clear understanding of when triggers and actions fire, see the Job States section for more information onthe subject.

All actions have a log file, which will be attached to the job if it is not empty. When an error occurs in an action, the job will go to status Error, this can be changed in status handlers.

The following illustrates the three Actions that are available and what they can be used for:

Since actions are dependent on the job state, you must be familiar with the various job states, see the Job States section for more information.

Note Note

You are not allowed to persist in any of these actions, that is done for you at the end.

End of the note.

On change

Any change before Queued and Dispatched
- Does not fire on Chained status
Can change scheduled start time, queue, or hold the job.

Pre running

During Queued, Dispatched, EventWait and LockWait
Can change scheduled start time, queue, or hold the job.

Post running

Any transition from Running into a final state:
- Error, Completed, Killed, Unknown, Canceled
Can change the final state.

All actions have access to the job changing status, the old and new statuses as well as a jcsSession. The changes that are allowed in the actions are action dependent. You cannot change the scheduled start time in a post-running action, for example, because the job has finished running.

The source of the actions is written in RedwoodScript which allows interacting with the repository. The above uses are only the most common - it is perfectly possible to submit another job in any of the actions or even cancel the job in question.

Contexts

The following predefined objects are available in job definition actions. These are defined in the Source Stub. You can reload the source tab from the context menu to display them.

Before Job On Change

Object	Class	Example Code
jcsOutLog	com.redwood.scheduler.infrastructure.logging.api.Logger	jcsOutLog.warning("This is a warning!");
jcsOnChangeContext	com.redwood.scheduler.api.scripting.variables.PreExecutingActionScriptObject	jcsOnChangeContext.setFailJobOnError(false);
jcsSession	com.redwood.scheduler.api.model.SchedulerSession	jcsSession.getUserName()
jcsJob	com.redwood.scheduler.api.model.Job	jcsJob.hold();
jcsOut	java.io.PrintWriter	jcsOut.println("This text will be printed to a specific output file on the job.");

Before Job Pre Running

Object	Class	Example Code
jcsOutLog	com.redwood.scheduler.infrastructure.logging.api.Logger	jcsOutLog.info("This is an informational message!")
jcsSession	com.redwood.scheduler.api.model.SchedulerSession	jcsSession.getQueueByName("UNIX_Generic");
jcsJob	com.redwood.scheduler.api.model.Job	jcsJob.hold();
jcsPreRunningContext	com.redwood.scheduler.api.scripting.variables.PreExecutingActionScriptObject
jcsOut	java.io.PrintWriter	jcsOut.println("This text will be printed to a specific output file on the job.");

Before Job Post Running

Object	Class	Example Code
jcsOutLog	com.redwood.scheduler.infrastructure.logging.api.Logger	jcsOutLog.debug("This is a debug message!")
jcsPostRunningContext	com.redwood.scheduler.api.scripting.variables.PostRunningActionScriptObject
jcsSession	com.redwood.scheduler.api.model.SchedulerSession
jcsJob	com.redwood.scheduler.api.model.Job	jcsJob.restart();
jcsOut	java.io.PrintWriter	jcsOut.println("This text will be printed to a specific output file on the job.");

Values

Tab	Field	Description	Default Value
Actions	Type	The type of action to create.
Actions	Enabled	Enable/disable action
Actions	Source	Source code of the actions in RedwoodScript

Example

A multi-step job chain has a job in the first step that may fail, but the rest of the chain must finish to clean up. The status of the job chain should be Completed if all steps Completed and Error when the first step went into error. The status handler on the first step for status Error is Continue. The following action is used to check if the first step reached status Error, and if so, throws a RuntimeException to force the job chain into status Error.

{

//Check if the first step failed, if it did,

//throw an exception to put the Jobchain job into Error

String stepName = "Run SystemBackup";

String statusName = "Error";

// Get an iterator over the child jobs of the job chain job

for (Iterator it = jcsJob.getChildJobs(); it.hasNext();)

{

Job myJob = (Job) it.next();

String realStepName = (String) myJob.getDescription();

String realStatus = (String) myJob.getStatus().name();

if (stepName.equals(realStepName) && statusName.equals(realStatus))

{

throw new RuntimeException();

}