Grouping Logic and Background Execution

Group related page processes in an execution chain and offload longer-running tasks to the background.

Use an Execution Chain page process to group a sequence of child processes. Its server-side condition determines whether the children execute. They can be any kind of page process to execute code, invoke APIs and REST services, start workflows, print reports, send emails or push notification, load data, and more. Since chains can nest within chains, your logic becomes a self-documenting outline when you use clear, descriptive names.

Execution chains also improve user experience. Offload long-running work by adding child processes to a chain and enabling its Run in Background switch. The APEX runs the work in the background moves on to the next page process in the user session. Background jobs run in a distinct session, with a private copy of the page's session state. Do anything you need to, including processing user-uploaded files, reporting progress, and notifying users when complete.

You can limit background jobs per user and declaratively serialize them to avoid resource contention or to prevent multiple executions for the same context value. Workspace administrators set overall limits and can grant background jobs more resources when needed.

• Exploring Employee Excellence for HR Reps
  Preview the Employee Excellence page, where HR reps send welcome packets and start background award reviews.
• Outlining Logic Using Execution Chains
  Organize page processing logic into a clear outline using nested execution chains.
• Offloading Work to the Background
  Offload longer-running page processing to the background so users can keep working.
• Serializing Background Process Jobs
  Serialize background jobs by type or context value to prevent conflicting work.
• Understanding Cloned Session State
  Understand how background jobs use an isolated copy of the user’s session state.
• Reporting Background Progress
  Show users background job progress with the APEX_APPL_PAGE_BG_PROC_STATUS view.
• Loading Data in the Background
  Load uploaded data in the background and notify users when processing completes.
• Limiting and Throttling Background Jobs
  Limit or throttle background execution chain jobs at the chain, application, or workspace level.
• Adjusting Resources for Background Jobs
  Configure a custom job class when background process jobs need different resource limits.
• Debugging Background Processes
  Debug background execution chains by viewing jobs, session state, and failure details.

Preview the Employee Excellence page, where HR reps send welcome packets and start background award reviews.

HR reps like Susan at Woods Clinic strive to promote and reward staff success. She uses the Employee Excellence page below to start new hires off right with a Welcome Packet. It contains appropriate materials, tailored by role, on how to succeed at the company. Susan can also initiate an AI-assisted employee review to decide whether a staff member qualifies to receive an Employee Excellence Award. The figure shows Susan's view of the Employee Excellence page where she can search for an employee and send them a welcome packet or review them for an award.

The Review for Award process runs in the background so Susan can do other tasks while the system progresses the reviews without her involvement. If the recipient qualifies, they receive their award as an email attachment when the process completes without further input. Susan can return at any time to see the ongoing progress of any reviews she's initiated on the page as shown below. The figure shows Susan's view of the Employee Excellence page when there are ongoing award review processes running in the background. An Award Review Progress section of the page shows the progress of each review as a percent and a progress bar, as well as its current status.

Organize page processing logic into a clear outline using nested execution chains.

The Employee Excellence page uses execution chains to group and nest processing logic into a self-documenting outline.

• Setting Up Context After Submit
  Set hidden page items after submit so later processing steps can use the selected employee context.
• Making Processing Conditional
  Use an execution chain server-side condition to run child processes only in specific cases.
• Sequencing Child Processes
  Control child process order and move processes between execution chains.
• Nesting Execution Chains
  Nest execution chains to structure complex logic, adding conditions where needed.
• Choosing Descriptive Process Names
  Choose clear process names and conditions to make execution chains easier to understand and maintain.

Offload longer-running page processing to the background so users can keep working.

Enable one switch to offload longer-running page processing to the background so the user doesn't wait. Backgrounded execution chains can invoke APIs, engage AI services and machine learning, generate reports, send email and push notifications, and more. The Employee Excellence page's Review for Reward (in Background) chain combines all of these.

• Configuring Chain to Run in Background
  Configure an execution chain to run in the background and optionally associate it with a context value.
• Outlining the Award Review Process
  Outline a background award review with API calls, a qualification check, and conditional follow-up steps.
• Printing Personalized Certificate
  Generate a personalized PDF certificate in the background and store it temporarily for email delivery.
• Emailing User with Attachments
  Send an email with file attachments or inline images using Attachment SQL.
• Push Notifying User on Opted-in Devices
  Send push notifications to opted-in user devices from a native page process.

Serialize background jobs by type or context value to prevent conflicting work.

When you enable the Serialize switch for an execution chain that runs in the background, the APEX engine lets only one job of that type run at a time for any user of the system. This can be useful to avoid multiple background processes from modifying the same rows at the same time.

When you also configure a Context Value Item, the jobs serialize with respect to that context value. For example, the Employee Excellence page configures Context Value Item to come from Select One page item P34_EMPLOYEE_EMPNO. This means Susan or other HR reps can process the award reviews for employees 7876 (ADAMS) and 7499 (ALLEN) and 7698 (BLAKE) at the same time. The figure shows the Review for Reward (in Background) execution chain selected in the processing tree and highlights its Serialization properties and the configured error message a user would see if the job can't be scheduled.

However, if some HR rep tries to initiate an award review process for an employee already being actively processed by a background process job, it must either wait or give an error. As shown above, the Employee Excellence page configures the When Already Running property of the execution chain to Error and configures an Error Message. This means Susan's attempt to process BLAKE when that employee is already being processed, shows the error below. The figure shows Susan's view of the Employee Excellence page when she tries to initiate the award review process for BLAKE when one is already ongoing in the background for that employee.

Understand how background jobs use an isolated copy of the user’s session state.

The APEX engine simplifies background processing by cloning the user session state to the scheduled job and ensuring any session state changes it makes affect only its own private copy.

• Isolating Background Session State
  APEX gives each background job its own session state so its changes stay separate from the user session.
• Configuring Temporary File Handling
  Configure how a background execution chain handles temporary files from upload items.

Show users background job progress with the APEX_APPL_PAGE_BG_PROC_STATUS view.

The APEX_APPL_PAGE_BG_PROC_STATUS view lets you access the information and status of all background jobs, including the dynamic status message and percent complete details your own code sets to keep users informed.

• Reporting Background Process to Users
  Report background process status and progress from PL/SQL as each step completes.
• Accessing Background Process Status
  Use the APEX_APPL_PAGE_BG_PROC_STATUS view to show users the progress of background processes.
• Querying Progress of Background Process
  Query active background jobs to show status messages and percent complete.
• Showing Background Process Progress Bar
  Show background progress as a bar using the Percent Graph report column type.
• Stretching Classic Report's Last Column
  Apply a CSS class to make the last Classic Report column fill the remaining width.
• Clamping Text to a Fixed Number of Lines
  

Load uploaded data in the background and notify users when processing completes.

If appropriate, the execution chain can include Send Email or Send Push Notification child processes to notify the user that the data load has completed. Since the background job has access to a private copy of the user session state at the time the background job began, it can reference page item values like P34_EMPLOYEE_EMAIL and P34_EMPLOYEE_NAME as well as APP_USER when performing these kinds of notifications.

Limit or throttle background execution chain jobs at the chain, application, or workspace level.

For example, if the Woods HR application sets a Maximum Background Page Process Jobs to 4, then as shown below, employee award review processes wait their turn to be scheduled to stay within this limit. The figure shows Susan's view of the Employee Excellence page. The Award Review Progress section shows four executing background processes and four others with an hourglass emoji in their Progress and Status column indicating they are waiting to be scheduled for background execution.

Configure a custom job class when background process jobs need different resource limits.

APEX instance administrators who apply resource constraints to ensure a good service for all workspaces and applications can configure a distinct job class for background process jobs if necessary. A DBA user or one with APEX_ADMINISTRATOR_ROLE can execute the following PL/SQL to configure a custom background job process class. For example, this class might enable background jobs to use more resources for longer-running processing use cases.

-- Run as SYS or user with APEX_ADMINISTRATOR_ROLE
begin
   apex_instance_admin.set_parameter(
      p_parameter => 'BACKGROUND_PROCESS_JOB_CLASS',
      p_value     => 'CUSTOM_BG_PROC_CLASS'
   );
end;

Debug background execution chains by viewing jobs, session state, and failure details.

When using background execution chains, use the Debug Viewer and Monitor Activity pages to view background jobs, terminate them if needed, explore their session state, and investigate the cause of jobs that fail with an unexpected error.

• Reviewing App Background Processes
  Review and terminate application background processes from the Debug Viewer.
• Investigating Background Process Errors
  Investigate failed background jobs by reviewing their debug trace logs and error details.
• Viewing Background Process Session State
  View a background job’s working session to inspect its session state during debugging.

Set hidden page items after submit so later processing steps can use the selected employee context.

select ename, :G_DEMO_EMAIL
  into :P34_EMPLOYEE_ENAME, :P34_EMPLOYEE_EMAIL
  from eba_demo_emp
 where empno = :P34_EMPLOYEE_EMPNO

Various steps of the page processing logic below reference these hidden page item values, along with the value of the P34_EMPLOYEE_EMPNO Select One page item the user uses to pick an employee to process.

Use an execution chain server-side condition to run child processes only in specific cases.

In the Processing section shown below, the If Sending Welcome Packet... page process sets Type to Execution Chain and configures its Server-side Condition to run its child processes only when the P34_ACTION select list page item's value equals "WELCOME".

Control child process order and move processes between execution chains.

The If Sending Welcome Packet... execution chain's child processes execute in sequence. You can reorder a child process among other processes at the same level using drag and drop. You can also edit the value of its Sequence property shown below.

To change which execution chain a child process belongs to, just change its Execution Chain property to the new parent. Or set that to None to restore the process to the root level of the processing logic "tree".

In the If Sending Welcome Packet... chain, the Add General Notices child process executes first. It uses an Invoke API process to call the ADD_GENERAL_NOTICES procedure in the EBA_DEMO_WOODSHR_WELCOME package.

Nest execution chains to structure complex logic, adding conditions where needed.

eba_demo_woodshr_welcome.manages_others(:P34_EMPLOYEE_EMPNO)

If true, its child processes execute to include management awareness and team development materials pertinent only to mangers.

The figure shows the selected If User is Manager... child process selected in the processing tree. Its Execution Chain property identifies the containing If Sending Welcome Packet... chain, and its PL/SQL condition controls when its own child processes run.

Choose clear process names and conditions to make execution chains easier to understand and maintain.

It uses a native Send E-Mail process type and configures &P34_EMPLOYEE_EMAIL. as the recipient in the To property. Using the Attachment SQL below, it includes the zip file by querying the BLOB from the NOTICES_ZIP collection.

select blob001                      as contents,
       'woods_newhire_notices.zip'  as file_name,
       'application/zip'            as mime_type,
       null /* Normal Attachment */ as content_id
from apex_collections
where collection_name = 'NOTICES_ZIP'
fetch first row only

Configure an execution chain to run in the background and optionally associate it with a context value.

When you enable an execution chain's Run in Background switch, at runtime the APEX engine enqueues a background job to execute as soon as possible and proceeds to the next process in the list, if any. To learn the unique job execution ID the system assigns, provide the name of a page item for the Return ID into Item property. To associate a context value with the background job, as shown below, configure the name of a page item for the Context Value Item property.

For example, the Employee Excellence page ignores the job's execution id by leaving Return ID into Item property blank, and configures P34_EMPLOYEE_EMPNO to provide the context value. This means that each instance of the Review for Reward (in Background) job is linked to the employee ID it is processing.

Outline a background award review with API calls, a qualification check, and conditional follow-up steps.

As shown below, the Determine Award Qualification with ML Invoke API process maps its function result into the hidden page item P34_EMPLOYEE_REVIEW_RESULT.

Next, the If Qualified... execution chain's child processes only execute if its Server-side Condition is true. It's configured to check for P34_EMPLOYEE_REVIEW_RESULT equals "QUALIFIED". If true, it generates the certificate, emails it to the recipient, and sends a push notification to the recipient as well.

Generate a personalized PDF certificate in the background and store it temporarily for email delivery.

-- In package eba_demo_woodshr_reward
procedure generate_certificate(
    p_empno in number)
is
    l_certificate_pdf blob;
begin
    apex_background_process.set_status('Generating Certificate');
    -- Set application item referenced in Report Query to passed empno
    apex_session_state.set_value('G_EMPLOYEE_EXCELLENCE_EMPNO',p_empno);
    -- Generate the document using a report query by static id
    l_certificate_pdf := apex_print.generate_document(
                            p_application_id => V('APP_ID'),
                            p_report_query_static_id => 'emp_excellence_certificate');
    -- Create collection and add PDF blob for email attachment to it
    apex_collection.create_or_truncate_collection('EMP_EXCELLENCE_CERTIFICATE');
    apex_collection.add_member(
        p_collection_name => 'EMP_EXCELLENCE_CERTIFICATE',
        p_blob001         => l_certificate_pdf);
    apex_background_process.set_progress(p_totalwork => c_steps, p_sofar => 8);
    apex_background_process.set_status('Generating Certificate Completed');
end generate_certificate;

Send an email with file attachments or inline images using Attachment SQL.

The Email Certificate child process is a native Send Email type that delivers the Employee Excellence Award certificate to the recipient. It references the hidden P34_EMPLOYEE_EMAIL item in the To setting using substitution syntax. Notice it sends a simple email in plain text, foregoing the use of an email template and Body HTML. The Body Plain Text also uses substitution strings to personalize the text.

<img src="cid:company_logo" alt="Woods Clinic Logo">

When the email arrives in JONES' inbox, it looks like the figure below. JONES email client displays the attachment straight away so she can read the great news and the text of the award signed by Wendell Woods himself:

Send push notifications to opted-in user devices from a native page process.

The final child process notifies the Employee Excellence Award winner with a push notification. It uses a native Send Push Notification process type. Notice that here the To property uses the username (e.g. SMITH) instead of an email address.

APEX gives each background job its own session state so its changes stay separate from the user session.

From that moment, the background process has its own session state, separate from the user's. Each background process can read and write its own state as needed. However, changes in one background process do not affect the user session or any other background process.

Configure how a background execution chain handles temporary files from upload items.

When using Move or Copy, set the additional property Temporary File Items to a comma-separated list of File Upload or Image Upload items whose temporary files you want to affect. The background session works with the files in the same way as in the user session using the APEX_APPLICATION_TEMP_FILES table.

Report background process status and progress from PL/SQL as each step completes.

To report progress and current status of a background process, use SET_PROGRESS and SET_STATUS procedures in the APEX_BACKGROUND_PROCESS package. As shown below, your code sets the total amount of work as a number in some appropriate units. It also sets the work completed so far using another number in the same units.

The package code related to the Employee Excellence award review processing establishes a total of 9 units of TOTALWORK, and increments the SOFAR value as it completes each of the 9 different steps. The GATHER_PERFORMANCE_INFORMATION below accomplishes three of the nine total steps. At each step the code updates the current background process status and progress.

-- In package eba_demo_woodshr_reward
c_steps constant pls_integer := 9;

procedure gather_performance_information(
    p_empno in number)
is
begin
    apex_background_process.set_progress(p_totalwork => c_steps, p_sofar => 0);
    apex_background_process.set_status('Gathering Project Management Details');
    --     ⋮
    apex_background_process.set_progress(p_totalwork => c_steps, p_sofar=> 1);
    apex_background_process.set_status('Gathering 360 Feedback Information');
    --     ⋮
    apex_background_process.set_progress(p_totalwork => c_steps, p_sofar => 2);
    apex_background_process.set_status('Gathering Attendance Records');
    --     ⋮
    apex_background_process.set_progress(p_totalwork => c_steps, p_sofar => 3);
    apex_background_process.set_status('Gathering Completed');
end gather_performance_information;

Use the APEX_APPL_PAGE_BG_PROC_STATUS view to show users the progress of background processes.

If you configure an execution chain's Return ID into Item property, use the execution ID saved in the target page item to query this view by EXECUTION_ID to find that particular background job's status.

The figure shows how the dictionary view APEX_APPL_PAGE_BG_PROC_STATUS relates to two other views containing information about the page processes and sessions via the foreign key columns described above.

Query active background jobs to show status messages and percent complete.

The Employee Excellence page's Award Review Progress classic report region uses the following query to show the progress of all active background processes related to the page. It filters on the current page's process name: Review for Reward (in Background). Notice it only includes rows with STATUS_CODE values of ENQUEUED, SCHEDULED, and EXECUTING.

The query computes the percent complete by dividing the SOFAR value by the TOTALWORK. The PROGRESS select list column multiplies this ratio by 100 to display the value as a percentage. The PROGRESS_BAR column leaves the value as the decimal the Percent Graph report column type expects.

To show the employee name being processed, it joins the EBA_DEMO_EMP table using the CONTEXT_VALUE associated with each background process job.

select e.ename,
       case when bgp.sofar is not null and bgp.totalwork is not null
            then round(bgp.sofar/bgp.totalwork*100)||'%'
            else '⏳'
       end progress,
       nvl(round(bgp.sofar/bgp.totalwork*100),0) progress_bar,
       coalesce(bgp.status_message,'⏳') as status_message
  from apex_appl_page_bg_proc_status bgp
  join eba_demo_emp e
    on e.empno = to_number(bgp.context_value)
 where    bgp.process_name = 'Review for Reward (in Background)'
      and bgp.application_id = :APP_ID
      and bgp.page_id        = :APP_PAGE_ID
      /* Background Job is Waiting or Doing Work */
      and bgp.status_code in ( 'ENQUEUED','SCHEDULED', 'EXECUTING')

Show background progress as a bar using the Percent Graph report column type.

Use the report column type of Percent Graph to show a decimal value between 0 and 1 as a progress bar. If needed, configure custom background and foreground colors and an explicit bar width in the Appearance section. The figure shows the PROGRESS_BAR column of the Award Review Progress region selected in the component tree and highlights the column Type is set to Percent Graph as well as the available Appearance options.

Apply a CSS class to make the last Classic Report column fill the remaining width.

The Award Review Progress classic report in the Employee Excellence page shown below has the employee name being processed, and the percentage progress both as a percent and a bar graph. The Status column uses the rest of the horizontal space available in the page width.

As shown below, the report configures this behavior by applying a custom CSS class named stretch‑last‑column in the CSS Classes region property.

This stretch-last-column CSS class solves a common need in Classic Report regions: stretching the last column to use the remaining width. As explained in Configuring Application-Wide Style Rules, it's part of the Woods HR application's app.css file. The technique uses two CSS rules that override the browser’s default table layout.

First, it applies table-layout: fixed and width: 100% to the table. By default, browsers use automatic layout, sizing columns by content and space, often with unpredictable results. Fixed layout makes the table obey your width values and stretch across its container.

Next, it uses CSS selectors to handle columns with or without explicit Cell Width specified. The selector :not([data-col-width]) matches columns that lack a defined width. Those non-last columns get a fixed width (120px in this example) so they stay readable but don’t hog space. The last column gets width: auto, which under fixed layout means “use the rest.”

/* In app-wide CSS Static Application File app.css */
/* Generic stretch-last-column class for APEX Classic Reports */
.stretch-last-column .t-Report-report {
    width: 100% !important;
    table-layout: fixed;
}

/* Force table wrapper to full width */
.stretch-last-column .t-Report-tableWrap {
    width: 100%;
}

/*
 * Give all non-last columns without explicit widths a reasonable default
 * The key is using a percentage that works regardless of column count
 */
.stretch-last-column .t-Report-report th:not(:last-child):not([data-col-width]),
.stretch-last-column .t-Report-report td:not(:last-child):not([data-col-width]) {
    width: 120px; /* Fixed pixel width - adjust this value as needed */
}

/* Let the last column stretch to fill remaining space (unless it has explicit width) */
.stretch-last-column .t-Report-report th:last-child:not([data-col-width]),
.stretch-last-column .t-Report-report td:last-child:not([data-col-width]) {
    width: auto;
}

Universal Theme includes many pre-defined CSS classes to easily customize how pages look. Reference the complete set using the Reference section of the Universal Theme Reference Application online. One group in particular comes in handy for reports that display text of unpredictable length. The Status column of background processes falls in this category.

Regardless of text length, sometimes it's useful to limit a report column's display to a fixed number of lines. The line clamp classes are the solution. By applying the u-lineclamp-1 class to the STATUS_MESSAGE report column, the Award Review Progress region only display a single line of text. As shown below, set it on the CSS Classes property of the report column.

At runtime, if text in the Status column exceeds the "clamped" number of lines the browser automatically adds an ellipsis instead of word-wrapping onto more lines.

Review and terminate application background processes from the Debug Viewer.

Use Debug > View Debug from the Developer Toolbar to open the Debug Viewer page. As shown below, on its Session tab, choose Background Executions in the View select list and click (Set) to review background processes for the current application.

Notice you can see each job's status, Currently Executing status message, So far, Total work, and Context values. Recall that the Review for Reward (in Background) execution chain configures the employee ID to provide this context value, so the values shown represent the employee being reviewed for a Employee Excellence Award by each particular background process.

Use the Statuses checkboxes to refine the list to see the processes that interest you. By default, it shows jobs that have been enqueued, scheduled, or are executing.

Click the (Terminate) button in any row to abort that background job immediately.

Investigate failed background jobs by reviewing their debug trace logs and error details.

When a background job encounters an unexpected error, start with the Debug Viewer page's Session tab. Set View to Background Executions and click (Set). Then filter for jobs with a Failed status as shown below.

Then, on the Debug tab sort descending by Timestamp and drill into the debug trace log for the candidate process as shown below.

Any errors that occurred show as red dots on the debug trace timeline. As shown below, click the first red dot to jump to the relevant part of the debug trace log.

Review the error information. As shown below, the stack trace helps you see that line 43 of the EBA_DEMO_WOODSHR_REWARD package encountered a NO_DATA_FOUND exception during the execution of the Invoke API that calls PREDICT_AWARD_QUALIFICATION. With this info, you can more quickly identify the cause in your code.

When needed, you can enable debug mode and add additional APEX_DEBUG.INFO debugging messages into your code to add extra debugging context information to the logs to further narrow down the culprit.

View a background job’s working session to inspect its session state during debugging.

To view the session state of a background process, start by opening the Monitor Activity page from the "person with wrench" menu button in the App Builder as shown below. Then identify a user session like SUSAN's and click its session id link to drill down for more information.

On the Session Detail page, select the Background Processing tab as shown below to see all its scheduled and running jobs. To view the session state of a particular background job's session, just click on the appropriate session id link in the Work Session ID column.

This opens the Session Detail page for the background job's working session. From there, select the Session State Item Values tab. As shown below, you can then inspect the values of any session state that are not encrypted.

apex_debug.info('### DEBUGGING (%s) (%s)', expression1, expression2);