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, use, and maintain 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 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..
Built-In Variables and Pseudo-Variables
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.
BUSINESS_REF serves the same function as
APEX$TASK_PK in APEX Workflow and Approval Tasks.
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.
In addition, the pseudo variable
PROCESS_PRIORITY is also available to see the current priority settings for the process instance.
Setting and Getting Process Variables.
Process Variables can be accessed via the following interfaces:
- via the
flow_process_varsPL/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).
Logging and Audit
If you want to log changes to process variables for logging, audit, or long term archive purposes, this is possible by setting logging into
full mode. See Configuring Event Logging.
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.
Accessing Process Variables Inside your APEX Application
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 using PL/SQL in userTask APEX pages and in scriptTasks
Starting from v23.1, process variables can be accessed in tasks by either substitution or binding. In general, were you have choice, binding is better.
To prevent any confusion between APEX items and Flows for APEX process variables, Flows for APEX process variable names are prefixed with
F4A$ when then are substituted or bound into an expression, like
&F4A$VariableName. for substitution, or
:F4A$variableName for binding.
As with substitution in APEX, substitution replaces the &variable_name. reference with a varchar2 representation of the contents of the specified variable.
Process variables can be substituted into the APEX page call of a userTask. See doc, as well as into most placd where settings (page calls, timers, priorities, task assignment, etc.) are allowed, or wher SQL or PL/SQL is used.
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
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.
Setting and Getting Process Variables in PL/SQL
Process variables can be
get inside a PL/SQL scriptTask
or serviceTask procedure using the setters and getters above.
Your application can set and get process variables by calling the appropriate setters and getters, as required.