You are not looking at the latest version of the documentation. Check it out there.
You are looking at draft pre-release documentation for the next release of Flows for APEX. Product features documented here may not be released or may have different behavior to that documented here. You should not make any purchase decisions based on this draft documentation..

Async Tasks and Background Execution

Introduction

Understanding how workflow sessions work in Flows for APEX is important for both developers designing workflows and administrators managing instances. When a workflow executes, it runs within a workflow session - a context that determines how and where the workflow processing occurs.

This page explains the different types of workflow sessions, when background execution is used, and how you can control async execution behavior using the new Async Before and Async After flags. 🆕

Workflow Sessions and Execution Contexts

A Flows for APEX workflow instance can execute in different types of sessions, depending on how the workflow was triggered and the configuration of individual tasks.

Types of Workflow Sessions

Workflows in Flows for APEX can be started and continued from the following session types:

1. User Session (APEX Application)

The most common execution context is a user session, where a workflow runs as part of an APEX application session. This occurs when:

  • A user starts a workflow from an APEX application, including restarting it from a task in their Task List.
  • A user completes a userTask and steps the workflow forward (via flow_complete_step)
  • Any APEX page interaction that processes workflow steps

In a user session:

  • The workflow runs in the context of the current APEX session
  • The user’s APEX session ID and username are available
  • Process Variables and APEX Page Items are both accessible
  • Processing happens synchronously in response to user actions
  • The user’s browser waits for the workflow to reach a natural break point

Best Practice: User sessions should be used for interactive workflows where immediate feedback to the user is required.

2. DBMS Scheduler Job Session

When a Timer Event fires in a workflow, the timer is executed by the Oracle DBMS_Scheduler in a background database job. This creates a background session that is not associated with any APEX user session.

Timer events that trigger background sessions include:

  • Timer Start Events
  • Timer Intermediate Catch Events
  • Timer Boundary Events

In a DBMS Scheduler session:

  • No APEX session context exists naturally from the DBMS Scheduler.
  • APEX Page Items are not available
  • Process Variables remain available
  • The workflow runs asynchronously from any user interaction
  • An APEX session will be created for task processing (see Background Task Session Configuration)

For more information about timer configuration and execution, see About Timers and Scheduling.

3. Incoming Message Flow Session (EE Only)

In Flows for APEX Enterprise Edition, incoming messages received via Oracle Advanced Queuing (AQ) create an async background session to process the message.

When a Message Catch Event or Receive Task receives a message:

  • The message is dequeued from the AQ queue
  • An async background session processes the message
  • No APEX session context exists initially
  • An APEX session will be created if needed for task processing

For more information about MessageFlow, see Understanding Message Flow and Message Flow - Message Design.

Editions: MessageFlow via AQ is available only in the Flows for APEX Enterprise Edition.

4. Async Session Following Async Before/After Flags (EE Only) 🆕

In Flows for APEX Enterprise Edition (from v26.1), you can explicitly push long-running Script Tasks or Service Tasks into a background async session by setting the Async Before or Async After flag on the task definition.

This allows you to:

  • Offload long-running processing from the user’s session
  • Improve user experience by not making users wait for lengthy operations
  • Continue processing workflow steps in the background

For details on configuring these flags, see Async Before and Async After Flags.

Editions: Async Before and Async After flags are available only in the Flows for APEX Enterprise Edition v26.1 and later.

Natural Break Points in Workflow Execution

Regardless of which type of session starts or continues a workflow, the workflow engine always processes steps until it reaches a natural break point.

What is a Natural Break Point?

A natural break point is a point in the workflow where processing must pause to wait for external input or a future event. Natural break points include:

  • User Tasks - waiting for a user to complete a task (APEX Page Task, Human Task, Simple Form)
  • Receive Tasks and Message Catch Events - waiting for an incoming message
  • Timer Catch Events - waiting for a timer to fire
  • Manual Tasks - waiting for manual work to be completed outside the system
  • Merging Gateways - waiting for other paths to be completed so that the gateway can complete.

Continuous Processing Until Break Point

When a workflow session begins (from any of the four session types above), the workflow engine:

  1. Starts processing from the current step
  2. Automatically executes any Script Tasks, Service Tasks, and passes through Gateways
  3. Continues processing subsequent steps
  4. Only stops when it reaches a natural break point

Example: If a user completes a User Task that is followed by three Script Tasks and a Gateway before reaching another User Task, all four intermediate steps (3 scripts + gateway) are executed as part of a single database transaction before pausing at the next User Task.

This continuous processing ensures:

  • Efficient execution with minimal session set-up/tear-downs.
  • Transactional integrity across related steps (see Transaction Model)
  • Predictable workflow progression

Background Execution and Session Management

When Background Sessions Are Created

Background execution (via DBMS_Scheduler or AQ) automatically occurs in these scenarios:

  1. Timer Events fire - Always creates a DBMS_Scheduler job
  2. Messages arrive via AQ (EE only) - Always processes in async session
  3. Async Before flag is set (EE only) 🆕 - Explicitly pushes task to background
  4. Async After flag is set (EE only) 🆕 - Explicitly pushes continuation to background

APEX Session Creation for Background Tasks

When a background session processes tasks that require an APEX session context (such as calling APEX APIs or executing page processing), Flows for APEX automatically creates a temporary APEX session.

The APEX session creation behavior is configured at the System Configuration, Process diagram or Instance level using the Background Task Session configuration.

Configuration options:

  • Business Administrator User - Session created using the configured admin username

This allows background tasks to:

  • Call APEX APIs that require a session context
  • Access workspace-specific resources
  • Execute APEX page processing logic
  • Maintain security context for auditing

For configuration details, see Configure Participants and Processes.

Controlling Async Execution with Task Flags (EE Only) 🆕

Async Before and Async After

Flows for APEX Enterprise Edition v26.1 introduces two flags that allow you to control when and how tasks are pushed into background async execution:

  • Async Before - The task itself starts execution in an async background session
  • Async After - The task completes normally, but continuation to the next step(s) happens in an async background session

These flags are available on:

  • Script Tasks
  • Service Tasks
  • Send Tasks (when implemented with PL/SQL)
  • Business Rule Tasks

When to Use Async Flags

Use Async Before when:

  • The task performs long-running processing (e.g., bulk data processing, external API calls)
  • You want to immediately free the user’s session rather than making them wait
  • The task doesn’t need to return immediate results to the user

Use Async After when:

  • The task itself should complete in the user’s session (e.g., to capture immediate results)
  • Subsequent processing can happen in the background
  • You want to provide immediate feedback to the user while continuing workflow processing asynchronously

How Async Flags Work

When an Async Before flag is set:

  1. The Pre-Task Phase completes and commits
  2. A background job is scheduled to execute the task
  3. Control returns immediately to the calling context
  4. The task executes asynchronously in a background session
  5. Upon task completion, processing continues to the next step(s) until a natural break point

When an Async After flag is set:

  1. The task executes normally in the current session
  2. The task completes and the Post-Task Phase begins
  3. Before moving to the next step, a background job is scheduled
  4. Control returns immediately to the calling context
  5. The workflow continues asynchronously from the next step until reaching a natural break point

For configuration instructions and examples, see Async Before and Async After Flags in Script Tasks.

Visibility in Instance Timeline

Background and async execution is clearly visible in the Instance Timeline view within the Flows for APEX application. Sessions running async are designated with special indicators that help you understand when and how tasks executed in the background.

The Instance Timeline shows:

  • When a task switched from user session to background execution
  • DBMS_Scheduler job execution details
  • AQ message processing events
  • Async Before and Async After task execution

Screenshot placeholder: Instance Timeline showing async session designation will be added here

This visibility helps both developers and administrators:

  • Debug workflow execution paths
  • Understand performance characteristics
  • Identify tasks running in background sessions
  • Troubleshoot timing-related issues

Async Behavior After Rewind (EE Only)

When using the Rewind functionality in Flows for APEX Enterprise Edition, async execution behavior changes temporarily to facilitate debugging and controlled restart.

Foreground Execution After Rewind

After a process instance has been rewound and execution is resumed:

  • Tasks that would normally run in an async session (timer-triggered, message-triggered, or async flag-set tasks) will run in the foreground session of the user issuing the Resume command
  • This foreground execution continues until:
    • Another explicit Async Before or Async After flag is encountered, OR
    • A natural break point is reached

Why This Happens

This behavior ensures that:

  • Administrators can observe immediate execution results after rewind
  • Debugging is easier with synchronous, visible execution
  • Any corrections or adjustments take effect immediately
  • No background jobs are inadvertently triggered during recovery

Resuming Normal Async Behavior

Once the rewound instance encounters:

  • A new task with an Async Before or Async After flag, OR
  • A timer event fires (creating a DBMS_Scheduler session), OR
  • A message arrives via AQ (creating an async session)

…then normal async behavior resumes for subsequent processing.

For more information about Rewind, see Rewinding a Process.

Editions: Rewind functionality is available only in the Flows for APEX Enterprise Edition.

Transaction Boundaries and Async Execution

Understanding how async execution interacts with database transactions is critical for designing reliable workflows.

Transaction Phases and Commits

Each workflow step executes in a three-phase transaction model:

  1. Pre-Task Phase - Setup and preparation
  2. Main Task Phase - Task execution
  3. Post-Task Phase - Completion and advancement

For async tasks and background execution:

  • The Pre-Task Phase commits before async execution begins (when using Async Before)
  • The Post-Task Phase commits before async continuation (when using Async After)
  • Background sessions create their own transaction boundaries
  • Each background execution processes until the next natural break point, then commits

For detailed information about transaction phases and commit behavior, see Transaction Model.

Impact on Error Handling

Async execution affects error handling:

  • Errors in user sessions can be immediately displayed to users
  • Errors in background sessions are logged to the instance and require monitoring
  • Failed background tasks can be restarted or rewound as needed
  • Transaction rollback only affects the session where the error occurred

Best Practices

For Developers

  1. Use Process Variables, not Page Items - Background tasks (and step restarts after a step error) cannot access APEX Page Items. Always use Process Variables to pass data between steps.

  2. Design for Async-Capable Tasks - When designing Script Tasks or Service Tasks that might run in background sessions:
    • Don’t assume APEX session context
    • Don’t reference page items directly
    • Make code restartable and idempotent where possible

  3. Choose the Right Async Flag - Select Async Before vs. Async After based on whether the task itself or just the continuation should be async.

  4. Consider User Experience - Use async execution to keep the user interface responsive for long-running operations.

  5. Test Background Execution - Test workflows with timers, messages, and async flags to ensure proper behavior in background sessions.

For Administrators

  1. Configure Background Sessions - Set up appropriate Background Task Session configuration for processes that need APEX context.

  2. Monitor Async Execution - Use the Instance Timeline to monitor background execution and identify performance issues.

  3. Plan for Background Job Capacity - Ensure adequate DBMS_Scheduler resources for timer-based and async workflows.

  4. Configure AQ Appropriately (EE only) - For MessageFlow, ensure AQ queues and subscribers are properly configured.

  5. Understand Rewind Behavior (EE Only) - When using Rewind, remember that initial execution after resume happens in the foreground.

Updated: