Steps

Chain steps are executed in sequence. They contain chain processes that are executed in parallel. Steps may also have precondition functions that control whether they are executed or not. Steps also define their own status handling that controls what happens when a chain process goes into a final status that is not Completed.

The attributes of a step are:

• Name - name of the step.
• Description - description of the step.
• Documentation - comment of the step.
• Maximum Restarts - maximum number of runs, including initial run; used in conjunction with Status Handlers; note that this is different from the behavior on process definitions.
• Restart Delay Amount - amount of Restart Delay Units to wait before restarting the step; used in conjunction with Status Handlers.
• Restart Delay Units - unit of Restart Delay Amount; used in conjunction with Status Handlers.
• Precondition - start condition (as an expression that should evaluate to true if the step should run).
  • Time Window - time window to check.
  • Time Window Status - the status of the time window.
  • Time Zone - time zone to use for the check.
  • Expression - REL expression to evaluate, when no time window was provided.
• Status Handlers - the actions to take when all chain processes have reached a final status.

Chain Process Scheduling Parameters

• Default Queue - the queue that should be used by default
• Priority - the default priority of the job
• Hold On Submit - the default value for the scheduling parameter Hold on Submit which defines the status of the chain process after the submit. Can be true, false (the default), or =<expression> in chain processes, which should be a boolean Redwood Expression Language expression. When a chain process is submitted on hold, human intervention is required to start it.
• Start Time - the start time of the chain process.
• Time Window - the time window that specifies the start time of the chain process.
• Ignore Status - the final status of this chain process is ignored when evaluating the status of the step. For example, when a chain process with Ignore Status enabled reaches status Error and all other chain processes in this step reach status Completed, the step will be set to Completed.
• Wait For Completion - wait for this chain process to reach a final status. If this is set to false, the step will both ignore the status and not wait for this chain process to reach a final status.

Restart

If the process definition of the chain process has a restart behavior configured on the process definition, this will be used in the chain. You can specify a restart behavior on the chain definition as well.

Preconditions

Steps have a single, optional precondition function. A step with no precondition always executes. A step with a precondition only executes if the precondition returns true. The Restart Behavior is only evaluated at the end of the step. When a step is skipped, due to a precondition, for example, the restart behavior is not evaluated, since the step does not run, thus does not finish. Therefore you have to put the precondition on the chain processes, so the chain processes go to Skipped and not the step. This can be an issue if you use stepIterations < n preconditions, where n is a number, for example.

The precondition is either an expression in Redwood Expression Language or a built-in expression which checks whether a specified time window is open or closed.

note

Preconditions may be executed before the chain is persisted, or, saved to the database. This can occur in chains when the step reaches status Console and is restarted; it has the effect that it is not possible to access itself or any other chain process in the same chain.

Status Handlers

Final status handlers of steps control the behavior of the step when all chain processes in that step reach a final status. When this is the case, the step status handlers are evaluated. If the step does not define a matching handler, then the chain definition handlers are consulted. Status handlers do not fire for manual actions on upper-most process of the chain, when an operator cancels or kills the chain for example. At most one status handler fires for each iteration of a step.

note

Step-level Status Handlers are not evaluated for disabled or skipped steps. If you want to use a precondition and Status Handlers (to match Otherwise), set the precondition on all Chain processes of the step instead of on the step.

Status handlers are evaluated as follows:

• A Completed handler triggers only if all chain processes in the step have the status Completed, Skipped, or Ignored.
• Otherwise, a Canceled handler triggers when there is at least one chain process with the status Canceled.
• Otherwise, an Error handler triggers when there is at least one chain process with the status Error.
• Otherwise, a Killed handler triggers when there is at least one chain process with the status Killed.
• Otherwise, an Unknown handler triggers when there is at least one chain process with the status Unknown.
• Finally, if no other handler is triggered, an 'Otherwise' handler will trigger.

If no status handler overrules the default, the default setting is followed.

The default setting is as follows:

• If all chain processes of the step reached status Completed, Skipped, or Ignored, continue with next step or if this is the last step set the chain to Completed.
• With Easy Restart enabled on the chain definition, if any of the chain processes of that step reached any other final state than Completed, Skipped, or Ignored, set the step to Console, the parent chain will remain in status Waiting.
• With Easy Restart disabled, the default behavior is to set both step and chain to status Error when any chain processes of that step reached any other final state than Completed, Skipped, or Ignored.

All remaining steps and chain processes in the chain will be set to Skipped, and no status handlers will be 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 either the basic HTML chain editor or RedwoodScript. 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.

To customize the behavior, the following actions are available:

• Status - The status the chain, step or chain process must reach.
• Action - The action to take when the step reaches a given status can be:
  • None - Use the default action. (default)
  • Goto - Go to another step within the chain or to the end
  • Location - Can be set to any step in the chain or end of chain, which sets the status of the chain to Completed
  • Raise Error - Raise an error by returning the Return Code
  • Message - The error message to show when the action is set to Raise Error
  • Error Return Code - the error code to raise when the action is set to Raise Error
  • Request Restart - Send operator message to choose a restart option and put the chain process to status Console
  • Restart Step - Restart the current step
  • Restart Step Master - Restart the latest version of current step
  • Restart Step Delayed - Restart the current step after a delay
  • Restart Step Delayed Master - Restart the latest version of current step after a delay
  • Restart Failed Chain Processes - Restart the chain processes that reached status Error
  • Restart Failed Chain Processes Master - Restart the latest version of the Chain Processes that reached status Error
  • Restart Chain - Restart the current chain
  • Restart Chain Master - Restart the latest version of the chain
  • Continue - Continue with the processing of the chain as if the step had reached status Completed

The default processing order of status handlers is as follows:

1. Killed => On Killed status handler.
2. Canceled => On Cancel status handler.
3. Error => On Error status handler.
4. Unknown => On Unknown status handler.
5. Otherwise is always last.

The order of the status handlers can be changed via scripting, please note that any status handler coming after Otherwise will be ignored. When the chain process already has reached status Skipped and previous iterations in the same chain never reached Completed, you use the Otherwise status handler to dictate further processing.

note

Status handlers do not fire for manual actions performed on the upper-most process of a chain such as operators that cancel or kill a whole chain.

Request Restart

The available options of Request Restart operator messages vary depending on the version of the chain definition the chain uses.

The following table lists the available slider combinations of Request Restart operator messages for chains of current chain definitions:

Slider Positions	Description of Consequences
Action: Abort Chain Chain Status: Completed	Choosing Ok will cause the chain to stop executing, and set the status of the chain to Completed.
Action: Abort Chain Chain Status: Error	Choosing Ok will cause the chain to stop executing, and set the status of the chain to Error.
Action: ContinueHandle as if: Completed	Choosing Ok will cause the step to be reprocessed as if all processes had gone to status Completed.
Action: ContinueHandle as if: Error	Choosing Ok will cause the step to be reprocessed as if some processes had gone to status Error.
Action: RestartRestart: Chain from StartWhen: Restart Immediately	Choosing Ok will restart the step immediately. All processes from the step will be restarted, including those that finished in status Completed.
Action: RestartRestart: Chain from StartWhen: Hold Restarted Step	Choosing Ok will cause the chain to restart from the first step. This first step will be Held to allow for further modifications, this step must be released before execution will continue.
Action: RestartRestart: Entire StepWhen: Restart Immediately	Choosing Ok will restart the step immediately. All processes from the step will be restarted, including those in status Completed.
Action: RestartRestart: Entire StepWhen: Hold Restarted Step	Choosing Ok will cause the step to be restarted, and set to status Held to allow for further modifications, this step must be released before execution will continue. All processes from the step will be restarted, including those in status Completed.
Action: RestartRestart: Errored Processes in StepWhen: Restart Immediately	Choosing Ok will restart the step immediately. Only processes that finished in status Error from the previous run are restarted, all other processes in the step are set to status Skipped.
Action: RestartRestart: Errored Processes in StepWhen: Hold Restarted Step	Choosing Ok will restart and hold the step, allowing for further modifications. This step must be released before execution will continue. Only processes that finished in status Error in the previous run will be restarted.

The following table lists the available slider combinations of Request Restart operator messages for chains of old chain definitions (You modified the chain or any process definitions it calls since submittal):

Slider Positions	Description of Consequences
Action: Abort Chain Chain Status: Completed	Choosing Ok will cause the chain to stop executing, and set the status of the chain to Completed.
Action: Abort Chain Chain Status: Error	Choosing Ok will cause the chain to stop executing, and set the status of the chain to Error.
Action: ContinueHandle as if: Completed	Choosing Ok will cause the step to be reprocessed as if all processes had gone to status Completed.
Action: ContinueHandle as if: Error	Choosing Ok will cause the step to be reprocessed as if some processes had gone to status Error.
Action: RestartRestart: Chain from StartWhen: Restart ImmediatelyDefinition: Use Old Definitions	Choosing Ok will restart the step immediately. The processes will be restarted using the definitions that were current when the chain was submitted. All processes from the step will be restarted, including those that finished in status Completed.
Action: RestartRestart: Chain from StartWhen: Restart ImmediatelyDefinition: Use Updated Definitions	Choosing Ok will restart the step immediately. All processes from the step will be restarted using new definitions, including those in status Completed.
Action: RestartRestart: Chain from StartWhen: Hold Restarted StepDefinition: Use Old Definitions	Choosing Ok will cause the chain to restart from the first step. This first step will be set to status Held to allow for further modifications, this step must be released before execution will continue. The processes will be restarted using the definitions that were current when the chain was submitted.
Action: RestartRestart: Chain from StartWhen: Hold Restarted StepDefinition: Use Updated Definitions	Choosing Ok will cause the chain to restart from the first step. This first step will be set to status Held to allow for further modifications, this step must be released before execution will continue. The processes will be restarted using the new definitions.
Action: RestartRestart: Entire StepWhen: Restart ImmediatelyDefinition: Use Old Definitions	Choosing Ok will restart the step immediately. All processes from the step will be restarted, using the definition that was current when the chain was submitted, including those in status Completed.
Action: RestartRestart: Entire StepWhen: Restart ImmediatelyDefinition: Use Updated Definitions	Choosing Ok will restart the step immediately. All processes from the step will be restarted using new definitions, including those in status Completed.
Action: RestartRestart: Entire StepWhen: Hold Restarted StepDefinition: Use Old Definitions	Choosing Ok will restart and hold the step, allowing for further modifications. This step must be released before execution will continue. All processes from the step will be restarted, using the definition that was current when the chain was submitted, including those in status Completed.
Action: RestartRestart: Entire StepWhen: Hold Restarted StepDefinition: Use Updated Definitions	Choosing Ok will cause the step to be restarted, and set to status Held to allow for further modifications, this step must be released before execution will continue. All processes from the step will be restarted using new definitions, including those in status Completed.
Action: RestartRestart: Errored Processes in StepWhen: Restart ImmediatelyDefinition: Use Old Definitions	Choosing Ok will restart the step immediately. Only processes that finished in status Error from the previous run are restarted, using the definition that was current when the chain was submitted, all other processes in the step are set to status Skipped.
Action: RestartRestart: Errored Processes in StepWhen: Restart ImmediatelyDefinition: Use Updated Definitions	Choosing Ok will restart the step immediately. Only processes that finished in status Error from the previous run are restarted, using the new definition, all other processes in the step are set to status Skipped.
Action: RestartRestart: Errored Processes in StepWhen: Hold Restarted StepDefinition: Use Old Definitions	Choosing Ok will restart and hold the step, allowing for further modifications. This step must be released before execution will continue. The processes will be restarted using the definitions that were current when the chain was submitted. Only processes that finished in status Error in the previous run will be restarted.
Action: RestartRestart: Errored Processes in StepWhen: Hold Restarted StepDefinition: Use Updated Definitions	Choosing Ok will restart and hold the step, allowing for further modifications. This step must be released before execution will continue. The processes will be restarted using the new definitions. Only processes that finished in status Error in the previous run will be restarted.

Infinite Loops

You can cause infinite loops when you use step-level Status Handlers and preconditions. If you have a precondition on the 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 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, you should have the status handler on the process definition(s) instead of on the step.

Ignoring Chain Processes

A step waits for all its children as all Chain processes have StepWaitingOnJob set to true, by default. The step also sets its status according to the status of its children as all Chain processes have ignoreStatus set to false, by default. You 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 Restarts value is used to determine how often the system may run this particular process; the value is decremented after the initial run and each automatic restart. This means that a Maximum Restarts 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 Restarts 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.

See Also

• Configuration Entries

JobChain