Introduction

• The ForkList Instruction is the dynamic version of the JS7 - Fork-Join Instruction.
• Technically it implements the Fork / Join operation, however, it allows a number of branches to be created dynamically from order variables:
  • The ForkList Instruction expects an order to provide a Variable Set that is implemented as a list (array) of values. The list can include any number of name/value pairs (variables).
  • The ForkList Instruction is designed as a single branch when configuring the workflow with the Configuration View of the JOC Cockpit user interface. Depending on the number of entries provided with a ForkList Variable Set carried by an order the Agent will dynamically create branches for each entry of the Variable Set.
• The underlying use case suggests that users want to execute the same workflow in parallel for each element of a Variable Set.
• 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.
• A variant of this instruction is available with the JS7 - ForkList-Join Instruction for Agent Clusters

Workflow Instruction: ForkList

The workflow editor is used to add a ForkList Instruction as shown:

Explanation:

• The ForkList Instruction is assigned a Variable Set countries that is of type List.
  • Assignment is available when displaying workflow properties and when selecting the ForkList Instruction in the editor panel.
  • The Variable Set makes use of one or more variables, the example uses the countryCode variable with type String.
  • Any number of variables can be added to a Variable Set.
• When an order is added to this workflow then it has to provide the countries Variable Set populated with country codes.
• For each element of the Variable Set, i.e. for each country code, JS7 will dynamically create a branch with the ForkList Instruction.
  • Child orders are created for each branch running in parallel.
  • The handling of child orders is the same as for the Fork Instruction.
• A workflow can include any number of ForkList Instructions.
  • ForkList Instructions can be nested and a branch can include, for example, Fork Instructions, Resource Lock Instructions etc.
  • More than one ForkList Instruction can use the same Variable Set.
• The Join If Failed property determines the behavior in case 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 an node of the child order's branch.

Adding Orders to a Workflow with ForkList Instructions

When adding an order to a workflow that includes a ForkList Instruction then the popup window offers to add any number of elements to the countries Variable Set.

Explanation:

• From this example a single order enters the workflow and is split into three child orders for each country when meeting the ForkList Instruction.
• Jobs in forked branches are running in parallel, i.e. jobs for the three countries specified are parallelized.

Adding Schedules to a Workflow with ForkList Instructions

When creating a schedule for a workflow that includes a ForkList Instruction then users can specify the countries Variable Set like this.

Explanation:

• This example adds three elements to the countries Variable Set and specifies the country codes.
• Jobs in forked branches of the workflow are executed in parallel for each country specified.
• It is an option to add a second Variable Set that will result in a second order being created by the schedule.

Error Handling

Error handling applies to parent orders and to child orders:

• A parent order inherits the successful or unsuccessful outcome of its child orders:
  • As long as any child orders are passing in branches of the ForkList Instruction the parent order will be in a WAITING state.
  • If one or more child orders leave their branches with an unsuccessful outcome then the parent order will be put in the FAILED state.
• The following options apply to error handling with child orders:
  
  • Default: If a job in a child order's branch fails then the child order is assigned the FAILED state. Such child orders require user intervention to resume execution. When resuming a child order, it can be resumed from the same or from any previous or later node in the child order's branch. This includes the option of moving a child order to the branch end.
    • Note that resuming a child order from its branch end will not modify its unsuccessful outcome. This will be adopted by the parent order which will then 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 has been executed successfully or should switch to using the JS7 - Try-Catch Instruction.
  • 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 is activated by use of the Join if Failed flag of the Fork Instruction.
• 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 kill option is used. This will kill a running job executed by the order.
• For details about error handling see JS7 - Fork-Join Instruction.

Resources

• JS7 - Fork-Join Instruction
• JS7 - ForkList-Join Instruction for Agent Clusters
• JS7 - Order State Transitions
• JS7 - How To - Error Handling