Task Parameters

Task Parameters

Task parameters define the inputs and outputs for a single workflow step. They let you describe what information a task or event needs when it starts, and what information it produces when it finishes.

Parameters are step-local. They are valid only while that workflow step is being processed. They are not a second copy of the process variable system, and they are not intended to hold long-lived process state.

Screenshots of the modeler configuration can be added here later.

What are Task Parameters?

Task parameters are a structured contract on a workflow step.

• Input parameters define the values a step needs before it executes.
• Output parameters define the values a step returns when it completes.

Parameters can be defined on supported tasks and events. In current usage, input parameters are used on start events and task-like steps. Output parameters are primarily used on task-like steps.

Typical uses include:

• passing selected process values into a script or service task
• collecting user input for a generated form or interactive step
• describing the output contract of a task so later workflow logic can use it
• making a task reusable by defining a clear input/output interface

Parameters and Process Variables

Task parameters and process variables are related, but they are not the same thing.

Process Variables

Process variables are the persistent state of a process instance.

• They belong to the process instance.
• They can live for the whole life of the workflow.
• They are scoped, stored, and can be read by later steps.
• They are the right place for business state that must survive from one step to the next.

See Process Variables for more information.

Task Parameters

Task parameters belong to a single step execution.

• They belong to the task or event definition, not to the whole process.
• Input parameters are resolved just before the step runs.
• Output parameters are created by the step and are available to the engine immediately after the step runs.
• They are the right place for a task contract: “what this step needs” and “what this step returns”.

In practice, input parameters will often be populated from process variables, and output parameters will often be copied into process variables after the task completes. But the parameter itself is not the process variable.

Defining Parameters in the Process Diagram

Parameters are defined on the BPMN object in the process diagram and stored in the object attributes JSON.

An input parameter definition typically includes:

• name
• type
• required
• description
• default when appropriate
• source describing where the value comes from
• apexRendering hints for generated user input forms, where applicable. See below.

An output parameter definition typically includes:

• name
• type
• required
• description

Input Parameter Sources

Current input parameter source types include:

• static - use a fixed value from the model
• processVariable - get the value from a process variable
• userInput - collect the value from the user - (this is only available for tasks inside an Adhoc Sub Process, for Start Events, and for UserTasks using the auto-forms subtype).

This gives you a single parameter definition that describes both:

• the schema of the parameter
• how its value is obtained at runtime

User Input layout instructions

Any parameters that are specifed as userInput for Adhoc SubProcesses, User Tasks, or Start Events are collected by an automatically generated APEX form. The form uses the ORACLE-APEX-JSON-REGION region plugin from Uwe Simon to dynamically generate an APEX region at runtime containing the required parameters.

The region makes default decisions about the APEX page item type and its settings - but these can be over-ridden if you want by specifying explicit instructions on how the APEX page item should be configured. This allows you to decide whether a text item is created on the APEX page as, for example, a text item, a text box, or a select list. You can also specify common properties such as the display title, help text, item size, CSS class, etc.

A list of the APEX layout instructions and their details is available here.

When Parameters are Set

The timing matters because parameters are part of step execution.

Input Parameters

Input parameters are set after the before-task variable expressions have run.

That means the sequence is:

1. before-task variable expressions run.
2. Input parameters are resolved from their sources.
3. The step executes using those input parameters.

This is useful because a before-task variable expression can prepare or update process variables first, and the input parameter can then read the final value.

Output Parameters

Output parameters are created before the after-task variable expressions run.

That means the sequence is:

1. The step executes and creates its output parameters.
2. The output parameters are available to the engine.
3. after-task variable expressions run.

This is important because the after-task variable expressions can copy or transform task outputs into process variables for later workflow steps.

Accessing Parameters in a PL/SQL Script

For PL/SQL script tasks, input parameters are exposed inside the running step through flow_globals.

Reading Input Parameters

Use flow_globals.input_parameter to get an input parameter by name.

declare
  l_case_id      varchar2(100);
  l_priority     varchar2(30);
  l_airport_code varchar2(10);
begin
  l_case_id := flow_globals.input_parameter(pi_parameter_name => 'case_id');
  l_priority := flow_globals.input_parameter(pi_parameter_name => 'priority');
  l_airport_code := flow_globals.input_parameter(pi_parameter_name => 'airport_code');

  -- task logic here
  null;
end;

For top-level scalar values, this gives the script a simple way to read the input contract of the task. Arrays and objects remain JSON-shaped data and should be handled accordingly in the script.

Setting Output Parameters

If a PL/SQL script task needs to return output parameters, use flow_globals.set_output_parameter.

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

These output parameters are then available before the after-task variable expressions run, so those expressions can map the outputs into process variables or use them in later logic.

Using JSON Path Expressions with Task Parameters

Task parameters work particularly well with the jsonPath variable expression type.

This allows you to declaratively copy selected values from task input or output parameter JSON into process variables without having to write PL/SQL.

Typical use cases include:

• copying one returned value from task output into a scalar process variable
• copying the complete task output JSON into a JSON process variable
• extracting one input parameter value after the task completes for later workflow logic

Examples:

• read $.result from taskOutput into a varchar2 process variable
• read $.mainOutputs.status from taskOutput into a varchar2 process variable
• read $ from taskOutput into a JSON process variable to keep the full returned document

See Variable Expressions for the full details of JSON Path Expressions, including source-type rules and type conversion behavior.

Migrating Older BPMN Diagrams

BPMN diagrams created with Flows for APEX v25.1 or earlier do not contain input or output parameters, but will still work with Flows for APEX v261 and later. Use of parameters is not required - but we would recommend that you start to use them as you develop BPMN models using Flows for APEX v26.1 and later.

Use of parameters is required to use the following new featutes of Flows for APEX v26.1 onwards:

• Tasks inside an Adhoc Sub Process (Enterprise Edition)
• Start Events (if you want to auto-generate a form to collect any starting parameters from the originator)
• User Tasks of type Auto-form.

For the broader runtime model and usage patterns of tasks inside an AHSP, see Adhoc Sub Processes, Adhoc Sub Process Concepts, and Using Manual Adhoc Sub Processes.

Summary

Use task parameters when you want a clean, explicit contract on a workflow step.

• Use process variables for long-lived process state.
• Use input parameters for the values a step needs right now.
• Use output parameters for the values a step returns right now.
• Use variable expressions to move data between step-local parameters and persistent process variables.