A business process instance typically runs for some extended period of time, and might require multiple users to perform many individual tasks, often across different application sessions. This is typically longer than a single APEX session.
Executing a process typically requires the process to have its own variable system that allows the process to manage process state for the duration of the business process instance, and which is separate from the data stored in the underlying objects that the process acts on.
The Flows for APEX Process variable system is a flexible, persistent process variable system that allows you to create and use variables for the lifetime of your process instance.
All process variables are accessed through the setters and getters provided in the
The process variable system allows you to create process variables identified by an arbitrary name and the process_ID of their process instance.
Process variables are typed, and are based on Oracle datatypes. Allowed types are
timestamp with time zone
There is a function
flow_process_vars.get_var_type() that returns the type of a process variable.
From Flows for APEX v22.2+, process variable names are case-independant. So the variables
MYVAR, and ‘myvar` all represent the same variable.
Process variables are defined within the scope of a single diagram.
If your process instance uses bpmn:callActivities and calls models contained on a separate diagram, information on process variable scoping system and how to access a process variable by scope is included on this page. (Add link to Call activities and Process Variable Scoping Concepts page).
Flows for APEX instances contains one built-in process variable that is created for every instance called BUSINESS_REF. A process instance typically needs to know the identity of its subject - typically the primary ID or business no of the main object this process works on. BUSINESS_REF should be used for this purpose. BUSINESS_REF is typed as a varchar2.
For example, an order handling process instance would typically need to have a unique identifier / primary key of the order that it is working on. Each instance of the process would typically be working on a separate order.
Setting and Getting Process Variables.
Process Variables can be accessed via the following interfaces:
- via the flow_process_vars PL/SQL API, which allows you to set, get, and delete a process variable.
- from an APEX application, using the Flows for APEX Process Variable Plugin (manage-flow-instance-variables ).
- from a BPMN model, where each process step can set variables using declarative process variable expressions defined in the Flow diagram, before and after the process step.
Process variables are persistent for the duration of the flow instance, being stored inside the database until the process is deleted with a
flow_delete call or a
flow_reset (with the exception of built-in variables which are retained after a flow_reset).
Saving Process State - Page Items or Process Variables?
If a user is going from one process step to another, all inside APEX, you are able to transfer session state from one step to another using APEX Page Items. Flows for APEX makes APEX Page Items available in ScriptTasks, for example, if you specify in your model the option to use the APEX Engine to execute your scriptTask if you choose to bind-in the APEX variables.
However, some of your process steps might not take place in an APEX environment, and so might not have access to an APEX session. For example, any tasks that could follow a timer will be executed by the Oracle DBMS Scheduler – outside of an APEX session. In these steps, outside of an APEX session, APEX Page Items and other APEX are not available. Instead, Process Variables should be used to transfer state from one flow step to another.
When building applications in APEX, you can use the Flows for APEX manage flow instance variables plugin
- before the application step (at page load processing) to transfer process state from Process Variables to APEX Page Items
- after the application step (at page processing) to transfer process state from APEX Page Items back into Process Variables.
Accessing Process Variables in userTask APEX pages and in scriptTasks
Starting from v23.1, process variables can be accessed in tasks by either substitution or binding.
Process variables can be substituted into the APEX page call of a userTask. See doc. As with substitution in APEX, substitution replaces the &variable_name. reference in text with a varchar2 representation of the contents of the specified variable.
To prevent any confusion between APEX items and Flows for APEX process variables, substition strings in Flows for APEX are prefixed with
Process variables can be set or got inside a PL/SQL scriptTask or serviceTask procedure using the setters and getters above. See doc
Process variable contents can be substituted into the definition string for Timers. See doc
Process variables can be substituted into a gateway routing expression, using the
&F4A$var_name. syntax, or bound using bind syntax
Your application can set and get process variables by calling the appropriate setters and getters, as required.
Starting from Flows for APEX v23.1, process variables can also be bound into SQL and PL/SQL statements, expressions and function bodies. A process variable can be accessed using
:F4A$var_name bind syntax. Process variables of type
timestamp with time zone can be bound into SQL and PL/SQL statements, returning values true to their type specification - so, unlike in APEX itself, you do not need to convert variables to varchar2 format before binding them.