Using Triggers

You need to understand the concepts of states to get a clear understanding of when process-related triggers and actions fire, see the States section for more information on the 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 following trigger-points are available:

• Before Definition Change - before the definition of an object is changed
• Before Process On Change - when a non-maintenance process changes its status until it reaches status Queued (except for the transition LockWait > Queued); it does not fire for status Canceled
• Before Process On Change Maintenance - when a maintenance process changes its status, same as Before Process On Change
• Before Process Pre Running - before the PreRunningAction code is executed
• Before Process Post Running - before the PostRunningAction code is executed
• Before Process User Change - before the process or Chain is modified
• Before User Message Operation - when a user interacts with a user message (This only fires for processes of type UserMessage)
• On File Content Access - when a user accesses output

Note: The Before Definition Change trigger-point does not apply to any change to a process, 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.

Tabs and Fields

RedwoodScript

The code you write must be valid RedwoodScript; note that 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.

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

By default, RedwoodScript is based on Java 11; you set the /configuration/javatoolkit/SourceVersion and /configuration/javatoolkit/TargetVersionregistry entries to your desired version and can use all the features of the version you specify.

Trigger Logging

Triggers log to files using the Java logging mechanism. If you set the log level above the log level of the Redwood Server installation, the log entries will also be logged to the default trace file of Redwood Server; its location depends on your application server. On Redwood Platform, triggers log to <install_dir>/j2ee/cluster/server1/log/scheduler/triggers/ and the default trace file is <install_dir>/j2ee/cluster/server1/logs/scheduler.log.

The five trigger points listed below, when executed, generate a separate log file that is accessible by selecting the Monitoring > Processes section in the navigation bar. From there, the process preview pane lists the run-time details of the currently selected process. The trigger-related log file name is located under the preview pane's Files heading. The trigger points and the log file name they generate are listed below.

• Before Process On Change - stdonchange.log
• Before Process On Change Maintenance - stdonchange.log
• Before Process Pre Running - stdprerunning.log
• Before Process Post Running - stdpostrunning.log
• Before Process User Change - onbeforeuserjobchange.log

The two trigger points listed below, when executed, generate a separate log file that is accessible from the Scripting > Triggers section of the navigation bar, providing the Trigger Log Level field is not set "None". Select the desired trigger, then click on the Actions button, then select Download Log. The trigger points and the log file name they generate are listed below.

• Before Definition Change - BeforeDefinitionChange.<Partition_name>.<Trigger_name>.log
• On File Content Access - OnJobFileContentAccess.<Partition_name>.<Trigger_name>.log

These two trigger points also allow for log file rollover. You specify the maximum number of files ( Max Backup Files ) and the maximum of each file ( Max Log Size ). As soon as a log file reaches the maximum size, a new file is created provided the maximum number of individual log files has not been reached. When maximum number of log files has been reached and all files are the maximum size, the oldest is overwritten. This allows you to control the maximum space the trigger logs will use on your system.

The final trigger point listed below, when executed, writes only to the default trace file, if the log level is high enough.

• Before User Message Operation - scheduler.log

Trigger Scope

Triggers fire for all objects that share the same partition as the trigger. There are special System Wide triggers (for example, System_SystemWide_BeforeDefinitionChange), which fire for all objects in all partitions. Note that the partition of a process is derived from the Queue; for example, the partition of a process that ran on the GLOBAL.System Queue is thus GLOBAL. This means that the following triggers only fire for processes that ran on a Queue that is in the same partition as the trigger:

• Before Process On Change
• Before Process On Change Maintenance
• Before Process Pre Running
• Before Process Post Running
• Before Process User Change

Trigger Executions

The Before Process On Change and Before Process On Change Maintenance triggers fire at least twice, once when switching from New to Scheduled and again from Scheduled to Queued. Other process-related triggers might fire several times depending on your code. Note that you can create endless loops in triggers, and that these can have severe consequences as many processes can be affected. Test your triggers well and always start by excluding as many processes as possible as early as possible.

When you set a new Queue on a process in a Before Process Pre Running trigger, the trigger will fire again for the change to the new Queue. This can be dangerous, especially if you do not ensure the trigger will not change the Queue the second time the code executes for that process. You can end up in an endless loop.

Warning: When you create or modify objects in your trigger code, these changes might fire the trigger and you potentially end up in an endless loop; you need to ensure that you ignore any changes made by the trigger in your trigger code.

Context Menu

Triggers support the following context menu options.

Note: For generally applicable object context menu options, see Object Context Menu.

Process-Related Trigger Execution

Process-related triggers fire at specific times during the life-cycle of a process. The trigger points are named after the Process Definition actions they precede; for example, Before Process Definition On Change fires immediately before a On Change action on a Process Definition, if specified. If a file search is configured on the Process Definition, that always fires first, followed by any Before Process Post Running triggers, followed by any Post Running actions, if specified.

Note that triggers fire even if no actions are specified on the Process Definition. Note, also, that no trigger points fire for status Canceled.

Before Process Definition On Change and Before Process Definition On Change Maintenance

These triggers fire for the following status changes:

• New -> Scheduled
• New -> Held
• Held -> Scheduled
• Scheduled -> Held
• Scheduled -> EventWait
• EventWait -> Scheduled
• Scheduled -> Queued

Before Process Definition Pre Running

These triggers fire before the process is set to status Running and, if applicable, any pre running action on the Process Definition.

Before Process Definition Post Running

These triggers fire before process is set to a final status, except Canceled. The final statuses this trigger point fires before are Completed, Error, Killed, and Unknown.

Before On User Message Operation

These triggers only fire for user message processes.

• when a user message is created, forwarded, delegated, and replied to
• an attachment is added (before being uploaded) and uploaded

Before Process User Change

This trigger fires when a user attempts to save a modified process or Chain, or when the job is created in a user session, including when a job is resubmitted or in a recurrence. For example, a user attempts to change the Queue of a process using the Submit Wizard. This action fires immediately after the user has chosen Submit, before the process has been persisted to the database. It allows you to veto certain specific modifications to processes or chains.

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()

Before Definition Change

This trigger fires before changes made by users are persisted to the database. You use it to ensure that a user has filled in all fields, for example. See the example below to force users to specify applications for objects that can have applications.

Note: The Before Definition Change trigger-point does not apply to any change to a process, 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.

Warning: When you create or modify objects in your trigger code, these changes might fire the trigger and you potentially end up in an endless loop; you need to ensure that you ignore any changes made by the trigger in your trigger code.

Before Process On Change and Before Process On Change Maintenance

These triggers fire before a process gets status Queued for each status change and allow you to interact with the process. It does not fire when a process reaches or leaves status LockWait nor does it fire for status Canceled.

Before Process Pre Running

This trigger fires when a process is about to leave status Queued and allows you to interact with the process; this is the last trigger point at which you can prevent the process from starting. The process pre-running action code is executed immediately after this trigger code, if specified on the Process Definition. Note that the pre-running action of the Process Definition can also prevent the process from running.

Before Process Post Running

This trigger fires when a process is about to leave status Running and before the PostRunningAction code on the process is executed.

On Process File Content Access

This trigger fires as a user attempts to open output. When you throw an exception (to prevent the user from accessing the process file), you can send a message to the user. If the message starts with <HTML>, then the message will be sent in HTML.

System Wide Triggers

For each of the trigger-points a System Wide trigger can be defined. This must be defined in the GLOBAL partition and have a name matching the trigger point type, prefixed with System_SystemWide_; note that the System_ prefix is reserved for system-specific and system-wide objects.

The complete list of System Wide triggers are:

• System_SystemWide_BeforeDefinitionChange
• System_SystemWide_BeforeJobOnChange
• System_SystemWide_BeforeJobOnChangeMaintenance
• System_SystemWide_BeforeJobPreRunning
• System_SystemWide_BeforeJobPostRunning
• System_SystemWide_OnJobFileContentAccess

Finding Triggers

You can search for triggers using filters and the Search Triggers box on the Triggers 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 as well as 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: No spaces should be entered before or after the colon (:).

See the Advanced Object Search for more information.

The following table illustrates the available prefixes for triggers:

Security

The privileges available in the Security tab are as follows.

For more information, see Security Tab.

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

Before Process On Change

Before Process Pre Running

Before Process Post Running

Values

Note: A process has the same partition as the Queue it ran in.

Example

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

See the Trigger Examples topic for more examples of triggers.

import java.text.MessageFormat;
import com.redwood.scheduler.api.model.JobDefinition;
{
  Object o = jcsTriggerContext.getSchedulerEntity();
  if (o instanceof JobDefinition)
  {
    JobDefinition jDefinition = ((JobDefinition) o);
    if ( jDefinition.getParentApplication() == null)
    {
      String message = jDefinition.getName() + " has no application!";
      jcsOutLog.info(message);
      throw new RuntimeException(message);
    }
  }
}

See Also

• Trigger Examples
• Granting and Revoking System Privileges
• Granting or Revoking Object Privileges

OnBeforeJobUserChange OnUserMessageOperation PreRunning PostRunning