Gateways
General
In Flows for APEX, BPMN diagrams should use explicit Gateway objects to control process flow. Flows for APEX supports the following BPMN Gateway objects:
- Exclusive Gateways - where 1 forward path is chosen out of several possible options.
- Parallel Gateways - where several forward paths are defined and ALL execute, creating multiple parallel flows. At the end of a parallel section, the flows wait for each other at a closing Parallel Gateway before continuing as a single forward path.
- Inclusive Gateway - where one or more forward paths are chosen to operate in parallel. At the end of a parallel section, the flows wait for each other at a second, closing Inclusive Gateway before the process continues forward on a single path.
- Event-based Gateway - where the forward process flow continues down one of several paths, depending on which path an Event occurs on first. These are covered in more details in the Events documentation.
Flows for APEX does not currently support the BPMN Complex Gateway type.
Explicit Gateway Definitions Only
Except for certain exceptions described below, sequence flows that cause flows to split or change direction must be implicitly modeled with Gateway objects.
Implicit process flow splits, or flow control decisions using flow conditions, are not supported. These process structures can easily be modeled using the gateway types that are available.
Exclusive Gateways (XOR)
With an Exclusive Gateway, a decision made by the process or by a user allows only one of the possible forward paths to proceed.
As there is only one route taken forward from an Exclusive Gateway, a split section can recombine without requiring a closing Exclusive Gateway. However, it is generally better style and clearer if a closing Exclusive Gateway is used to end the optional sections of your diagram.
Controlling the Forward Path at an Exclusive Gateway (Changed in v22.2).
When a subflow reaches an exclusive gateway, the flow engine chooses the forward path as follows:
- If a Gateway Routing Variable is provided, it will take the path specified in the Gateway Routing Variable. See ‘Specifying a Routing Variable’ below.
- If no Gateway Routing Variable is defined, we then look at the Gateway Routing Expressions defined on each of the possible forward paths, in increasing sequence order. See ‘Specifying a Routing Expression’ below.
- If none of the forward path expressions evaluate to ‘true’, the Default Path is chosen (if one is defined). See ‘Default Paths on Exclusive Gateways’ below.
- If no routing is provided, and no default is specified, an error is signaled.
As a general recommendation, from v22.2 onwards, you wil probably find it easiest to use Gateway Routing Expressions to define conditions for each of the forward paths, in conjunction with a Default Path.
Specifying a Gateway Routing Variable for an Exclusive Gateway (from v21.1)
An exclusive gateway will look for its routing instruction in a process variable named
The routing instruction should be the bpmn_id of the required forward path (sequenceFlow).
For example, in the progress diagram below, the exclusive gateway ‘Choose B or C?’ has a bpmn_id of Gateway_0j0mpc0. So in a process step before reaching the gateway, your application would need to set the process variable Gateway_0j0mpc0:route.
Assuming for the sale of this example that you want to take ‘B Route’ so that the process goes next to task B, the variable needs to have a varchar2 value set to the bpmn_id of ‘B Route’, which is ‘Flow_B’. You can set these variables using the set_var procedure in flow_process_vars package.
Variable : Gateway_0j0mpc0:route
Value : Flow_B ----(varchar2)
There are several ways to set up the process variable to contain your routing instruction:
- you could set the process variable as part of your processing in an earlier step. For example, if an earlier task has a manager approve or reject a document, the process step in the application could set up the routing instruction for a following gateway based on the approval decision. In v5, adding this would be implemented by including a PL/SQL
set_var()call in APEX page processing; from v21.1, this can be done declaratively using the Flows for APEX manage flow instance variables plugin. - you could have a scriptTask step that runs automatically before the gateway to set the routing instruction.
- you could use a process variable expression defined in BPMN model to set the variable based on a function or a SQL query, etc., defined to execute in the pre-split processing of the gateway. (from v21.1).
Specifying a Gateway Routing Expression for an Exclusive Gateway (New in v22.2)
Instead of setting a Gateway Routing Variable, you can now use Gateway Routing Expressions on each sequence flow forward from the gateway to specify whether the forward path should be taken, or not. A Gateway Routing Expression is set on each forward path from the gateway. The Gateway Routing Expression is a PL/SQL Expression or a PL/SQL Function Body that evaluates to a boolean (true/false) result. The Gateway Routing Expressions are evaluated in increasing Sequence order.
.
For an Exclusive Gateway, each forward route is evaluated, in Sequence order, until a routing expression evaluates to true - when the gateway takes that path. For an Inclusive Gateway, all forward paths are evaluated, and all paths that evaluate to true are taken.
The Gateway Routing Expression can be either a PL/SQL expression, or a PL/SQL Function Body. The Routing expression can contain references to process variables, using either substitution syntax &F4A$myvar. or bind syntax :F4A$Myvar. Bind syntax can be used to bind varchar2-typed process variables, number-typed process variables, and date-typed process variables. If a date-typed process variable is bound, the value actuallly bound will be a varchar2 representation of te date, using the standard Flows for APEX default date format mask of ‘YYYY-MM-DD-HH24:MI:SS’.
For example, if the process variables DateA, DateB and DateC all exist and are of type ‘Date’, you could write an gateway routing expression on a forward path using bind syntax, as follows:
to_date(:F4A$DateB,'YYYY-MM-DD HH24:MI:SS') between to_date(:F4A$DateA,'YYYY-MM-DD HH24:MI:SS')
and to_date(:F4A$DateC,'YYYY-MM-DD HH24:MI:SS')
Default Paths on Exclusive Gateways
Note that the diagram above contains a small tick mark on the path from the exclusive gateway to task C1. This denotes that this is the default path. If the conditions for path A ( sales > 2000 ) and path B ( sales < 50 ) are not met, the gateway will choose the default path. Processing continues on task C1 on path C.
Parallel Gateways (AND)
At a Parallel Gateway, all forward paths proceed in parallel with their own subflow. The incoming subflow is halted with status of ‘split’.
Adding a second Parallel Gateway causes the parallel workflows to merge and re-synchronize. In the diagram above, Path A, Path B and Path C all wait at the Merging Parallel Gateway until all three paths have completed, before a single path proceeds to task D.
A parallel workflow does not have to re-merge and re-synchronize. You can have all of the forward paths proceed to their own process end events, so shown in this diagram.
Note, however, that merging and synchronization has to occur either for all of the parallel flows, or for none of them. Having 2 of the forward paths re-merge, but one continue to it’s own end – as shown in the diagram below - is not supported.
A parallel workflow that merges should usually be merged with an explicit merge / re-synchronize gateway. The following scenario shows an implicit merger, without a closing Parallel Gateway. If you created this workflow, note that all of the parallel paths will continue to execute Task D and then end. So D would be executed 3 times. While you might have a business process where this is the desired behavior, this is likely to be unusual!
It’s usually fairly easy to re-write process structure to create balanced gateway pairs, without impact on the actual business process. The following example takes a nested pair of gateways that are unbalanced, and rewrites them as two balanced pairs of Parallel Gateways to achieve the same process workflow that can be handled by Flows for APEX.
A merging Parallel Gateway can also be used to merge, synchronize, and then re-split the flow – as in the following diagram.
Flows for APEX does not support a standalone parallel gateway as a merging event. Merging can only be done for workflows that were earlier split by an equal Parallel Gateway.
Inclusive Gateways (OR)
An Inclusive Gateway allows one or more of the possible forward paths to occur, in parallel. In many ways, this can be thought of as a cross between the Exclusive Gateway and the Parallel Gateway functionality. With an Inclusive Gateway, a decision made by the process or by a user allows one or more of the possible forward paths to proceed.
In this example, the business process of a manufacturer allows goods to be shipped by air, by sea, and to have additional consumer packaging added. One, two, or all three of these options can be chosen. The processes merge / re-synchronize at the matching closing Inclusive Gateway, labelled “ABC Merge”, before proceeding to task E.
Like with Parallel Gateways, Inclusive Gateways must either:
- occur in a balanced pair, where all of the options start at one opening Inclusive Gateway and then all end at a matching closing / merging Inclusive Gateway, or
- start with an Inclusive Gateway, and then all of the optional parallel paths proceed to their own end events.
At the merging / closing Inclusive Gateway, all routes that were started must complete at the gateway before the single forward path commences. This re-synchronizes the overall process before it continues.
If no closing gateway is included, all routes must proceed to their own end events, as in the diagram below.
Starting from v21.1, an Inclusive Gateway can now act, simultaneously, as both a Merging / Closing gateway and an Opening Gateway, in the same way that a Parallel Gateway does. Some experts advise that this is not good BPMN practice as users can get confused by the concept, and so the BPMN Modeler will give you a warning if you include this in your diagram. But it works!
Controlling the Forward Path at an Inclusive Gateway (Changed in v22.2).
When a subflow reaches an exclusive gateway, the flow engine chooses the forward path as follows:
- If a Gateway Routing Variable is provided, it will take the paths specified by the variable. See ‘Specifying a Gateway Routing Variable’ below.
- If no gateway Routing Variable is found, we look at Gateway Routing Expressions on each of the possible forward paths to determine whether that path should be taken. See ‘Specifying a Gateway Routing Expression’ below.
- Failing that, the Default Path is chosen. See ‘Default Paths on Inclusive Gateways’ below.
- If no routing is provided, and no default is specified, an error is signaled.
As a general recommendation, from v22.2 onwards, you wil probably find it easiest to use Gateway Routing Expressions to define conditions for each of the forward paths, in conjunction with default paths.
Specifying Gateway Routing Variables for an Inclusive Gateway
An exclusive gateway will look for its routing instruction in a process variable named
The routing instruction should be the bpmn_id of the required forward path (sequenceFlow). If more than one paths are required, these should be colon : separated.
For example, in the progress diagram below, the exclusive gateway ‘Choose B or C?’ has a bpmn_id of Gateway_0tkydca. So in a process step before reaching the gateway, your application would need to set the process variable Gateway_0tkydca:route.
Assuming for the sake of this example that you want to take routes B and D, so that the process starts 2 parallel forward routes going next to tasks B and D, the variable needs to have a varchar2 value set to the bpmn_id of ‘B Route’ and ‘D Route’, which is Flow_05d0ha9:Flow_0zhby4b. You can set these variables using the set_var procedure in flow_process_vars package.
Variable : Gateway_0tkydca:route
Value : Flow_05d0ha9:Flow_0zhby4b ----(varchar2)
Typically you would set these routing instructions into a variable as part of an earlier Task step, or you might have a scriptTask that sets it based on a database query. If it is a user decision, you would create an APEX Page for the user to review some information and make a decision. If the routing can be looked up or calculated, a scriptTask could run a PL/SQL procedure that does the appropriate query and processing to make the decision. You can also set these using a ‘before split’ variable expression on the gateway itself.
Specifying a Gateway Routing Expression for an Inclusive Gateway (New in v22.2)
Instead of setting a Gateway Routing Variable, you can now use Gateway Routing Expressions on each sequence flow forward from the gateway to specify whether the forward path should be used, or not. A Gateway Routing Expression is set on each forward path from the gateway. The Gateway Routing Expression is a PL/SQL Expression or a PL/SQL Function Body that evaluates to a boolean (true/false) result. The Gateway Routing Expressions are evaluated in increasing Sequence order.
For an Exclusive Gateway, each forward route is evaluated, in Sequence order, until a routing expression evaluates to true - when the gateway takes that path. For an Inclusive Gateway, all forward paths are evaluated, and all paths that evaluate to true are taken.
The Gateway Routing Expression can be either a PL/SQL expression, or a PL/SQL Function Body. The Routing expression can contain references to process variables, using either substitution syntax &F4A$myvar. or bind syntax :F4A$Myvar. Substitution syntax can be used with varchar2-typed process variables. Bind syntax can be used to bind varchar2-typed process variables, number-typed process variables, and date-typed process variables. If a date-typed process variable is bound, the value actuallly bound will be a varchar2 representation of te date, using the standard Flows for APEX default date format mask of ‘YYYY-MM-DD-HH24:MI:SS’.
For example, if the process variables DateA, DateB and DateC all exist and are of type ‘Date’, you could write an gateway routing expression on a forward path using bind syntax, as follows:
to_date(:F4A$DateB,'YYYY-MM-DD HH24:MI:SS') between to_date(:F4A$DateA,'YYYY-MM-DD HH24:MI:SS')
and to_date(:F4A$DateC,'YYYY-MM-DD HH24:MI:SS')
If you use Gateway Routing Expressions on a specific gateway, you must put conditions on all non-default forward paths of the gateway.
Default Paths on Inclusive Gateways
Like Exclusive Gateways, Inclusive Gateways can also have a single default path which is enabled if no other path is chosen.
Adding a condition to the default path is optional. Note that this changes the behavior – and this is a frequent source of confusion to designers. The following example shows two Inclusive Gateways having forward paths A,B,C and D,E, F.
| Var1 Value | Path A | Path B | Path C |
|---|---|---|---|
| A |  |
||
| B | |
||
| AB | |
|
|
| C | |
||
| X | |
||
| AC | |
||
| ABC | |
|
| Var2 Value | Path D | Path E | Path F |
|---|---|---|---|
| D | |
||
| E | |
||
| DE | |
|
|
| F | |
||
| X | |
||
| DF | |
|
|
| DEF | |
|
|