Introduction
- The Fork Instruction allows orders to be forked and joined to enable parallel processing in a workflow.
- The Fork Instruction allows creation of a number of parallel branches which process further instructions and jobs.
- Branches can include any number of instructions and jobs.
- Branches can include nested Fork Instructions which are limited to 15 levels.
- When an order enters a Fork Instruction then a child order is created for each branch.
- Each child order will pass the nodes in its branch independently of parallel child orders.
- Child orders can return results to parent orders by passing variables.
- Note that child orders take the role of parent orders in nested Fork Instructions.
- While child orders are running, the parent order waits for its child orders to be completed, i.e. to arrive at the Join Instruction. The parent order therefore is assigned the WAITING state, see JS7 - Order State Transitions.
- The Fork Instructions offers two variants:
- JS7 - ForkList-Join Instruction: Branches are created dynamically from variable sets.
- JS7 - ForkList-Join Instruction for Agent Clusters: Branches are created dynamically for all Subagents in a Subagent Cluster.
Feature Video
This video explains how to create parallel jobs which an be nested and joined in a workflow.
Workflow Instruction: Fork/Join
Simple Fork/Join
Download Workflow Example (.json upload): pdwFork.json
Explanation:
- The Fork Instruction is used for two parallel branches, the names of the branches can be specified.
- After the child orders for both branches have arrived with the Join Instruction then the parent order will continue with the next node.
- The Join If Failed property determines the behavior in the event of failed child orders:
- If checked then failed child orders terminate immediately and cause the parent order to adopt the FAILED state.
- If not checked then failed child orders will be halted and allow user intervention to resume execution from a node of the child order's branch.
Nested Fork/Join
Download Workflow Example (upload .json): pwdForkNested.json
The Workflows view for the above workflow will display parallel child orders like this:
Explanation:
- The Workflows view shows three levels of orders: the parent order sitting with the initial Fork Instruction and two levels of child orders passing their respective branches.
- As soon as the child orders are completed then the parent order continues.
Passing Variables from Fork Branches
Jobs in branches of a Fork Instruction can pass results to the parent order by use of variables, see JS7 - Order Variables:
By default such variables are available to subsequent nodes in the same branch only as they are confined to child order scope.
In addition, the Fork Instruction allows the specification of the child order variables which are to be passed to the parent order.
Download Workflow Example (upload .json): pdwForkReturnValues.json
Explanation:
- Each branch of a Fork Instruction allows pairs of names and values for variables that are passed to the parent order to be specified:
- For the parent order a variable with the given name and value is created.
- Variable names have to be unique across branches, i.e. no two branches can return the same variable names.
- Users are free to choose variable names for the parent order and assign variable values of the child order or constant values.
- The Join Instruction adds any variables created within branches to the parent order.
Error Handling
Job Errors
Parent orders are not exposed to job errors as any instructions and jobs within the Fork Instruction are executed by child orders. Instead a parent order adopts the final state of its child orders.
- If all child orders are completed successfully then the parent order will proceed with the next instruction following the Fork Instruction.
- If one or more child orders leave their branch with an unsuccessful outcome then the parent order will adopt the FAILED state and will remain with the Fork Instruction.
The following options apply to error handling with child orders:
- Default behavior: If a job in a child order's branch fails then the child order is assigned the FAILED state and remains with the offending job node. Such child orders require user intervention to resume execution. When resuming a child order then it can restart from the same or from any previous or later node in the child order's branch. This includes the option to move a child order to the branch end.
- Note that resuming a child order from its branch end will not modify its unsuccessful outcome that is inherited by the parent order.
- Alternative behavior:
- If a job in a child order's branch fails then the child order terminates immediately and the parent order is put to the FAILED state. This behavior can be activated by use of the Join if Failed flag of the Fork Instruction.
- Use of the JS7 - Try-Catch Instruction allows recovery of an order from a failed job by:
- proceeding in the child order's branch using an empty Catch Instruction or
- executing other instructions and jobs included with the Catch Instruction.
- Use of the JS7 - Finish Instruction allows child orders to leave the current branch:
- with a successful outcome independently of the fact that a previously executed job failed,
- with an unsuccessful outcome which will be adopted by the parent order and put the parent order in the FAILED state.
User Intervention
Parent Order Interventions
While child orders are running, the parent order will wait for its child orders to be completed, i.e. to arrive at the Join Instruction. The parent order therefore is assigned the WAITING state, see JS7 - Order State Transitions.
- If the parent order is suspended then child orders will continue to run. After joining child orders in the Join Instruction the parent order is put in a SUSPENDED state with the node following the Fork / Join Instruction.
- If the parent order is cancelled then child orders will continue to run. After joining child orders in the Join Instruction the parent order's cancellation will become effective and it will make the parent order leave the workflow with an unsuccessful outcome.
Suspending / Cancelling Child Orders
Child orders can be suspended or cancelled both individually and from bulk operations:
- If a child order is suspended then it is set to the SUSPENDED state. As a result the child order completes its current instruction and stops at the next node. It remains in this state until it is either resumed or cancelled at a later point. If the operation suspending an order is used with the force option then the job that is currently executed by the child order will be forcibly terminated and the orders will be suspended at the next node.
- Child orders can be cancelled, however - they will not leave the workflow but will leave their current branch and jump to the Join Instruction. Should child orders not be intended to pass the remaining instructions in a branch, then they can be resumed from the Join Instruction. The cancel operation allows the child order to complete its current node unless the force option is used that will forcibly terminate a running job executed by the order.
- Note that child orders can take the role of parent orders in nested Fork Instructions.
Note that any operations suspending or cancelling child orders work asynchronously as the jobs which are executed for child orders could be used with Agents on different servers. Therefore any bulk operation to suspend/cancel all child orders boil down to an individual operation and result per child order.
Resuming Child Orders
Child orders can be resumed if they are in a SUSPENDED or FAILED state.
- Child orders can be resumed from the current node.
- Child orders can be resumed from any previous or later node within their branch.
- For example, the child order can be dragged & dropped to one of the nodes within its branch:
- Child orders cannot be resumed from nodes in nested instructions configured with the branch and they cannot be resumed to a node outside of the branch.
- Child orders can be resumed to the end of the branch, indicating that no further instructions and jobs in the branch should be executed.
- For example, the child order can be dragged & dropped to the Join node of the Fork Instruction.
- In this situation the child order is assigned its previous outcome of being successful or unsuccessful.
- For example, a FAILED child order that is resumed from the end of its branch carries an unsuccessful outcome that is inherited by its parent order causing the parent order to be put in the FAILED state.
- Users who want to force successful execution of a failed child order should resume the child order from a job node that will be executed successfully.
- For example, the child order can be dragged & dropped to the Join node of the Fork Instruction.
- For example, the child order can be dragged & dropped to one of the nodes within its branch:
Resources
- JS7 - ForkList-Join Instruction
- JS7 - ForkList-Join Instruction for Agent Clusters
- JS7 - How To - Error Handling