Working with Chain Definitions

For a general discussion of Chain Definitions, see About Chain Definitions.

For information about the Chain Definition Editor, see Chain Definition Editor Reference.

Creating Chain Definitions

For information about basic chain editing, see Creating a Basic Chain Definition.

Tip: You can also edit Chain Definitions with RedwoodScript.

Warning: Be careful if you need to edit a Chain Definition that is currently scheduled for execution. The updated Chain Definition will affect all processes that have not reached the Dispatched status at modification time.

Deleting Chain Definitions

You can delete a Chain Definition only if no other objects relate to it. For example, if the Chain Definition is referred to in another Chain Definition, the Chain Definition cannot be deleted until that reference has been deleted. You can see a Chain Definition's related objects under Related Objects in the Detail View.

Tip: You cannot delete a Chain Definition if one of its processes is running.

Choosing a Queue

In general, when you set a Queue for a Chain, that Queue is used for all Process Definitions that do not have an assigned Queue.

If a Chain contains a Process Definition of one of the following types, and that Process Definition does not have an assigned Queue, and the Chain's Queue is not valid for the Process Definition, RunMyJobs determines the Queue to use as follows:

  • SAPR3, OraApps, OraOHI, and Publish: The default Queue of the specified remote system is used.
  • JDBC and AS400: The Queue is looked up in the following order:
    1. The first Queue that is assigned only to the Process Server in question (and no others) is used.
    2. The first Queue that is assigned to the Process Server in question (even if it serves other Process Servers) is used.

The above Queue selection mechanism requires the system constraints to be set on the definitions. These constraints are automatically created when you create the Process Definitions, but it is possible to manually delete constraints. If you manually delete such a constraint, you will be able to submit the Chain, and any Process Definition with an invalid Queue will reach Error status.

Tip: If a Chain contains a Process Definition with an invalid Queue, you cannot submit the Chain.

Chain Definition Messages

By default, several of the internal Chain components create process notes under certain circumstances to store processing and/or error messages. You can overrule this to create Operator Messages instead by adding the following registry entry and setting its Value to OperatorMessage:

/configuration/jcs/JobChainMessageLocation

Sub-Chain Names

If you specify a name for a Chain, and then add sub-Chains, the Chain name is used as the default name for child-Chains, with a suffix of _<n> (where <n> is a number).

Final Status for Chains

By default, the final status of a Chain is set to the final status of the last Step that reached a final state, unless that Step's final state is Disabled, Skipped, or Ignored (in which case the Chain's final state is set to Completed). If you want the final state of a Chain to be the same as the final status of the last Step even if it is Disabled, Skipped, or Ignored, you can achieve this in two ways.

  • In the Documentation tab, enter @useLastExecutedStepStatus=true or @useLastExecutedStepStatus=false.

  • Set the /configuration/jcs/jobchain/useLastExecutedStepStatusregistry entry to true.

The first option takes precedence over the second.

Chain Processes have the following context menu actions.

Action Description
Show Chain diagram Displays a diagram of the Chain with related objects.
Submit Submits the Chain Definition. This action is available only for top-level Chain Definitions, not for sub-Chains.
Cancel non-final state chains Cancels Chains that have not reached a final state.
Delete final state chains Deletes Chain Definitions that have reached a final state.
Monitor related processes Displays the Process Monitor with a temporary filter displaying Chains and Chain Processes for the Chain Definition.
Reset Statistics Resets the runtime statistics for the Chain.
Edit Lets you edit the Chain Definition.
Edit Submit form Lets you edit the submit form for the Chain.
Expand all Expands the entire tree of the Chain Definition.
New Creates a new Chain Definition.

Easy Restart

If no Status Handler overrules the default behavior:

  • If all processes in a Step reach status Completed, Skipped, or Ignored, processing continues with next Step. If there is no next Step, the status of the Chain is set to Completed.
  • If Easy Restart is enabled on the Chain Definition, and a process in a Step reaches any final status other than Completed, Skipped, or Ignored, the Step is set to Console status and the Chain is set to Waiting status. All remaining Steps and Chain Processes are set to Skipped status, and no Status Handlers are called for those Steps or Chain Processes.
  • If Easy Restart is disabled on the Chain Definition, and a process in a Step reaches any final status other than Completed, Skipped, or Ignored, both the Step and the Chain are set to Error status. All remaining Steps and Chain Processes are set to Skipped status, and no Status Handlers are called for those Steps or Chain Processes.

Easy Restart is enabled by default when you create a new Chain Definitions with the standard Chain editor. It has no effect on the basic HTML Chain editor and no effect on RedwoodScript scripts. Its value is false by default in Chain Definitions created with previous versions of the Chain editor. When Easy Restart is enabled, default Status Handlers are no longer editable.

Chains and Restart Behavior

A Step's restart behavior is only evaluated at the end of the Step. When a Step is skipped (for example, due to a precondition), the restart behavior is not evaluated. In such situations, you can put the precondition on the Chain Definition, so the Chain goes to status Skipped rather than the Step. This can be an issue if you use stepIterations < n preconditions, where n is a number.

The following substitution parameters are specifically tailored for use in preconditions in Chains that have calls that are supposed to restart. When a call restarts, the preconditions are evaluated before the Chain Process is persisted, so you cannot access properties directly.

  • stepJobId, stepUniqueId: Step and call preconditions.
  • callJobId, callUniqueId: Call preconditions.

Infinite Loops

You can cause infinite loops when you use Step-level Status Handlers and preconditions. If you have a precondition on a Step that returns false in combination with the Otherwise Status Handler for Restart Step, for example, the Step will be restarted but not run (because it will be Skipped by then). However, the Otherwise Status Handler will fire again, restarting the Step. This process will be repeated until an operator kills the Chain. Other combinations of Otherwise Status Handlers and preconditions can have similar behaviors.

To avoid infinite loops in these situations, put Status Handlers on Chain Processes instead of on Steps.

Ignoring Chain Processes

By default, a Step waits for all its children, because all Chain Processes have StepWaitingOnJob set to true by default. The Step also sets its status according to the status of its children, because all Chain Processes have ignoreStatus set to false, by default. You can set the flags individually for a Chain Process note that when ignoreStatus is set to true, the Step will still wait for the Chain Process.

Maximum Restarts

The Maximum Starts value (Process Status tab) determines how often the system may run a process. The value is decremented after the initial run and with each automatic restart. In other words, a Maximum Starts value of 4 will restart the process 3 times and the total number of runs will be 4. When an operator intervenes using an action on a Process Definition or an Operator Message, for example, then the value is reset to the value of the Process Definition.

Note: The Maximum Starts property on a Step behaves slightly differently as the initial run counts towards the value specified in Maximum Restarts; on Process Definitions, the initial run does not count towards the value specified in Maximum Restarts.