flow_globals Runtime Context API

flow_globals Runtime Context API

The flow_globals package provides the runtime execution context for a workflow step.

This package is primarily used inside PL/SQL Script Tasks, Service Tasks, Send Tasks, and Business Rule Tasks that execute PL/SQL code. It gives your code access to the current step context, task input parameters, task output parameters, and a small number of workflow-specific exceptions.

Unlike flow_api_pkg or flow_process_vars, flow_globals is not normally called as a standalone application API. In most cases, you use it only from code that is already running inside a workflow step.

For practical usage examples, see Configure a PL/SQL Script Task.

Public Runtime Variables

These package variables are populated by the engine for the currently executing step.

Variable	Type	Meaning
process_id	flow_processes.prcs_id%type	The current process instance id
subflow_id	flow_subflows.sbfl_id%type	The current subflow id
step_key	flow_subflows.sbfl_step_key%type	The current step key
scope	flow_subflows.sbfl_scope%type	The current variable scope
rest_call	boolean	Indicates that the current call originated from the REST interface
loop_counter	flow_subflows.sbfl_loop_counter%type	Iteration counter for iterated tasks and subprocesses
input_parameters	flow_subflows.sbfl_task_input_parameters%type	JSON input parameters for the current task
output_parameters	flow_subflows.sbfl_task_output_parameters%type	JSON output parameters collected during the current task

In normal user code, process_id, subflow_id, step_key, scope, loop_counter, and the parameter helper functions are the most useful items.

Workflow Exceptions

The package exposes two workflow-specific exceptions that can be raised from a PL/SQL Script Task.

throw_bpmn_error_event

throw_bpmn_error_event exception;
pragma EXCEPTION_INIT(throw_bpmn_error_event, -20101);

Raise this exception when you want the Script Task to throw a BPMN Error Event that can be caught by an Error Boundary Event.

raise flow_globals.throw_bpmn_error_event;

request_stop_engine

request_stop_engine exception;
pragma EXCEPTION_INIT(request_stop_engine, -20003);

Raise this exception when you want the engine to stop processing the current step and place the process into error handling.

raise flow_globals.request_stop_engine;

For narrative examples of both exceptions, see Configure a PL/SQL Script Task.

BUSINESS_REF Convenience Functions

BUSINESS_REF is a built-in process variable. The flow_globals package provides two convenience functions to access it from the current runtime context.

Function business_ref using scope

function business_ref
(pi_scope flow_subflows.sbfl_scope%type default 0)
return flow_process_variables.prov_var_vc2%type;

Returns the BUSINESS_REF value for the current process instance and the specified scope.

Function business_ref using subflow id

function business_ref
(pi_sbfl_id flow_subflows.sbfl_id%type)
return flow_process_variables.prov_var_vc2%type;

Returns the BUSINESS_REF value for the scope associated with the supplied subflow.

Example

declare
  l_business_ref varchar2(4000);
begin
  l_business_ref := flow_globals.business_ref();
end;

See also Process Variables and Process Variable System API.

Task Parameter Helper Functions

These functions are the main user-facing part of flow_globals for tasks that use input and output parameters.

Function input_parameter

function input_parameter
( pi_parameter_name in varchar2
) return varchar2;

Returns the named input parameter from the current task’s input parameter JSON.

If the input parameter JSON is null, invalid, or does not contain that parameter, the function returns null.

Example

declare
  l_case_id  varchar2(100);
begin
  l_case_id := flow_globals.input_parameter(pi_parameter_name => 'case_id');
end;

Procedure set_output_parameter

procedure set_output_parameter
( pi_parameter_name in varchar2
, pi_value          in varchar2
);

Adds or updates a single output parameter value in the current task output JSON.

Example

begin
  flow_globals.set_output_parameter('result', 'Validation completed successfully.');
end;

Procedure set_output_parameter_object

procedure set_output_parameter_object
( pi_parameter_name  in varchar2
, pi_key1            in varchar2 default null
, pi_value1          in varchar2 default null
, pi_key2            in varchar2 default null
, pi_value2          in varchar2 default null
, pi_key3            in varchar2 default null
, pi_value3          in varchar2 default null
, pi_key4            in varchar2 default null
, pi_value4          in varchar2 default null
, pi_key5            in varchar2 default null
, pi_value5          in varchar2 default null
, pi_key6            in varchar2 default null
, pi_value6          in varchar2 default null
);

Creates or updates a nested JSON object inside the current task output parameters.

This is especially useful when you want to return a structured object such as mainOutputs from a task.

Example

begin
  flow_globals.set_output_parameter_object
  ( pi_parameter_name => 'mainOutputs'
  , pi_key1           => 'status'
  , pi_value1         => 'LOCATED'
  , pi_key2           => 'airport'
  , pi_value2         => 'LHR'
  );
end;

Function get_output_parameters

function get_output_parameters
return flow_subflows.sbfl_task_output_parameters%type;

Returns the complete output parameter JSON currently collected for the executing task.

This is usually used by the engine, but can also be useful in advanced PL/SQL task code.

Advanced Engine-Managed Context Procedures

The package also exposes procedures and functions that are used internally by the engine to manage execution context and step state.

These include:

• set_context()
• set_step_error() / get_step_error()
• set_is_recursive_step() / get_is_recursive_step()
• set_is_async_session() / get_is_async_session()
• set_call_origin() / unset_call_origin()

These routines are primarily engine-managed and should not normally be called from user task code unless you are working on engine internals or highly specialized extensions.

Recommended Usage

Use flow_globals when your PL/SQL task code needs access to the current execution context.

• Use flow_globals.process_id, subflow_id, step_key, and scope to identify the current step context.
• Use input_parameter() to read task input parameters.
• Use set_output_parameter() and set_output_parameter_object() to return task outputs.
• Use business_ref() when you need the current process business reference inside task code.
• Use flow_process_vars for persistent process state that must live beyond the current step.

For the practical task-development view of this package, see Configure a PL/SQL Script Task.