Introduction

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. To handle the ambiguity that could be caused by, for example, calling the same Call activity multiple times in a process or from BPMN loops and multi-instances, process variables are scoped.

All process variables are accessed through the setters and getters provided in the flow_process_vars package.

The process variable system allows you to create process variables identified by an arbitrary name and the process_ID of their process instance.

Data Types

Process variables are typed, and are based on Oracle datatypes. Allowed types are

  • varchar2
  • number
  • date
  • clob
  • timestamp with time zone
  • JSON element 🆕(New in all editions of v24.1)

There is a function flow_process_vars.get_var_type() that returns the type of a process variable.

Naming

From Flows for APEX v22.2+, process variable names are case-independant. So the variables myVar, MYVAR, and myvar all represent the same variable.

Scope

Process variables are generally defined within the scope of a single diagram.

Call Activities. 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.

Loops and Iterations. 🆕(Enterprise Edition ony). Tasks or subProcesses that loop or iterate also use scoping to keep identically named process variables separate in each loop or iteration.

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 APEX Human Tasks (Approval Tasks and Action 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.

The following pseudo variables are relevant to BPMN loops and Iteration completion conditions 🆕. (Flows for APEX Enterprise Edition). `

Pseudo Variable Description Available
loop_counter the loop or iteration counter (1-n) Available in Completion Conditions.
Also available as flow_globals.loop_counter
total_instances total number of iterations / loops Only for Completion Conditions
active_instances number currently active iterations / loops Only for Completion Conditions
completed_instances number of completed iterations / loops Only for Completion Conditions
terminated_instances number of terminated iterations / loops Only for Completion Conditions

loop_counter is also accessible as a flow_global in variable expressions and in PL/SQL script tasks, across editions. If the current task is the child of an iteration or loop, it will return the loop_counter for its closest parent iteration or loop. If a task is not iterated, it returns null.

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.

JSON typed Process Variables🆕 - New in v24.1

The JSON-typed process variable is stored in Oracle as a CLOB with an IS JSON constraint, allowing Oracle 19c compatibility but ensuring that the JSON is valid and that it is stored efficiently in OSON format. At some later version, when Oracle 23ai adoption is widespread, we will migrate this to a native JSON column.

A JSON process variable can be set or get in either CLOB format (to get a character representation of the JSON) using get_var_json and set_var, or as a json_element_ttyped JSON object usingget_var_json_element.

Persistence

Process variables persistfor the duration of the flow instance, being stored inside the database until the process instance 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 might be 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, it is good practice to use Flows for APEx process variables to transfer state from one step to another for several reasons; some of your process steps might not take place in an APEX environment, and so might not have access to an APEX session, and eoorors or a session restart would cause APEX Page Items to be lost, whereas process variables are still available. 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.

Process variable plugin configuration.

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, where 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.

Substitution

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 places where settings (page calls, timers, priorities, task assignment, etc.) are allowed, or where 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 :F4A$myvar.

Binding

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 date, number, 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 set or get inside a PL/SQL scriptTask or serviceTask procedure using the setters and getters above. See doc

Your application can set and get process variables by calling the appropriate setters and getters, as required.