You are not looking at the latest version of the documentation. Check it out there.

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.

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

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 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_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.

Persistence

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.

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

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 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 :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.