Using Triggers

The following trigger-points are available:

Before Definition Change - before the definition of an object is changed
Before Job On Change - when a job changes its status
Before Job Pre Running - before the PreRunningAction code is executed
Before Job Post Running - before the PostRunningAction code is executed

Note Note

The Before Definition Change trigger-point does not apply to any change to a job, operator message, event or alert. It does not apply to changes in queue status or process server status, for example or to changes made by the system.

End of the note.

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.

You can have multiple triggers for one trigger point, the sequence in which the triggers are executed inside a trigger-point are defined in the Execution Order field.

The code you write must be valid RedwoodScript, however only a subset of Java classes are available for use in triggers. You import your own class from your library for use in a trigger. Redwood recommends to store as much of the code as possible in a library, especially if you plan on reusing it in other triggers or actions.

Triggers have their own log files. These are used only when enabled and accessible via the context menu.

Note Note

You must never persist a session in your trigger code, that is done for you at a later point.

End of the note.

Actions

Triggers support the following actions:

Action	Description
Export	Export the trigger into a CAR file
Edit	Edit the trigger
Edit Security	Edit the security of the trigger
Delete	Delete the trigger
Duplicate	Make a copy of the trigger to create a similar one
Expand All	Expand all triggers in the current filter
New	Create a new filter
Filter > New Filter	Create a new trigger filter
Filter > Edit Filter	Edit current trigger filter
Filter > Delete	Delete current trigger filter

Writing Trigger Code

When you write trigger code, you have the choice between creating your own class and writing directly between curly brackets {}.

If you choose to surround your method with curly brackets, it will be added to the execute() method of the stub class.

Your own class must:

inherit from the stub
must implement a public void execute()

Finding Triggers

You can search for triggers using filters and the Search Triggers box on the Trggers tab. This box is known as the intelliSearch box and located under your username on the top right-hand side of the user interface. Filters allow you to specify a list of objects with static criteria. IntelliSearch allows you to specify complex queries in a simple way using prefixes. Prefixes are used to specify which property you are searching in and have short and long syntaxes. For example, if you want to display all triggers with the term trigger in the comment, you would use the search criteria as follows:

c:trigger

You can search more than one property, as follows:

c:trigger n:JV

Note Note

No spaces should be entered before or after the colon (:).

End of the note.

See the Advanced Object Search for more information.

The following table illustrates the available prefixes for triggers:

Prefixes	Description
n, name	searches the name property
c, com, comment	searches the comment property
d, desc, description	searches the description property
a, app, application	searches the application property

Security

Privilege	Description
Trigger.Create	Create triggers
Trigger.Delete	Delete triggers
Trigger.Edit	Edit triggers
Trigger.View	Access triggers

You can grant privileges on two levels, Access and Admin; a privilege granted on Admin level allows the grantee to grant the privilege to other users. These privileges can be granted system-wide, per partition or isolation group.

If you have the security module, which requires the Module.Security license key, you have an additional Security tab on the trigger. It allows you to specify which users can access, edit, and delete the trigger.

Contexts

For each trigger point, a set of objects are predefined in the context for you to use. Once you have chosen your trigger-point, you can refresh the Stub Source from the context menu to display the list of predefined objects with their classes (so that you can use the API documentation to lookup the available methods). The objects jcsOut and jcsOutLog write to the same file, the latter uses the Redwood Logging Syntax, which allows you to specify a severity (info, warning, error, fatal, debug) and includes a time-stamp.

The following tables illustrate the predefined objects, their classes as well as a simple example.

Before Definition Change

Object	Class	Example Code
jcsOutLog	com.redwood.scheduler.infrastructure.logging.api.Logger	jcsOutLog.fatal("This is a fatal error message!");
jcsTriggerContext	com.redwood.scheduler.api.scripting.variables.TriggerScriptObject	jcsTriggerContext.getSchedulerEntity();

Before Job On Change

Object	Class	Example Code
jcsOutLog	com.redwood.scheduler.infrastructure.logging.api.Logger	jcsOutLog.warn("This is a warning and gets printed to the stdonchangelog file on the job.");
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	String strNewStatus = jcsPreRunningContext.getNewStatus();
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	jcsSession.getSchedulerEntity()
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

Field	Description
Partition	The partition of the trigger, this also defines the scope of the trigger as it will only effect trigger-points of objects that are in the partition of the trigger.
Name	The name of the trigger
Application	The application the trigger resides in
Description	A description of the trigger
Comment	The comment for the trigger, helpful for other users to understand your trigger
Enabled	Only enabled triggers will have effect
Execution Order	The order at which the triggers are executed for one same trigger-point
Library	Your library of classes to use within the trigger
Log File Enabled	Should the trigger actions be logged? This is helpful for troubleshooting your trigger
Source	The source code of the trigger
Stub Source	The source stub, which contains the stub code with predefined objects

Example

This example trigger checks if job definitions or job chains have an application, and throws an exception when this is not the case. This trigger allows you to force users to put job definitions and job chains in applications.

import java.text.MessageFormat;

import com.redwood.scheduler.api.model.JobDefinition;

{

Object o = jcsTriggerContext.getSchedulerEntity();

if (o instanceof JobDefinition)

{

JobDefinition jobDef = ((JobDefinition) o);

if ( jobDef.getParentApplication() == null)

{

String msg = MessageFormat.format("{0} has no application!", new Object[] {jobDef.getName()});

jcsOutLog.info(msg);

throw new RuntimeException(msg);

}