15.3.4 Understanding Background Page Processing

Background page processing enables developers to run a sequence of page processes that can execute in the foreground or in the background.

• About Background Page Processes
  Learn about background page processes.
• Creating a Background Page Page Process
  Create a background page process using the Execution Chain process type, which contains child processes executing one after the other. Execution chains can run in the background or in the foreground.
• Monitoring Currently Running Background Processes
  Monitor background processes by clicking Session on the Runtime Developer toolbar.

15.3.4.1 About Background Page Processes

Learn about background page processes.

The Execution Chain process type enables page processing to execute in the background so that users don't have to wait until processing finishes. Typical use cases are long running operations such as data loading or expensive data processing. An Execution Chain process type may contain one or multiple child processes, which do the actual processing, and are executed one after the other. An execution chain can run either in the background or in the foreground.

Creating a background page process involves the following general steps:

• In Page Designer, create a Execution Chain page process.
• To the Execution Chain process, add the child processes which do the actual processing (for example, Execute PL/SQL code, Data Loading, and so on).
• Edit the Execution Chain attributes and enable the Execute in Background switch.

Tip:

You can monitor background procecces programatically, using the APEX_BACKGROUND_PROCESS API. See APEX_BACKGROUND_PROCESS in Oracle APEX API Reference

About Reimporting an Application with Background Processes

Reimporting an application with background processes has a slightly different workflow compared to a standard Application Export. During the import, the wizard prompts you on how to handle existing background processes. See Reimporting an Application Containing Background Processes.

Configuring Limits for Concurrently Running Scheduler Jobs

Background page processing is actually executed by the database scheduler (DBMS_SCHEDULER). This means that the application's parsing schema must have the CREATE JOB privilege granted in order to run background page processing jobs.

You can configure limits for concurrently running background page processing jobs as follows. If a new background execution would exceed the configured limits, it will wait in a queued state until one of the running executions finishes and a slot becomes available.

• Instance level (as a default). Configure the Background Jobs attributes in Instance Settings. The instance level setting acts as a default for all workspaces and can be overridden at the workspace level.

  See Configuring Background Jobs in Oracle APEX Administration Guide

• Workspace level. Edit the Maximum Background Page Process Jobs attribute under Workspace Isolation. The workspace limit acts as a maximum for all applications within that workspace.

  See Configuring Workspace Isolation Attributes in Oracle APEX Administration Guide

• Application level. Edit the Application Definition, Maximum Background Page Process Jobs attribute. This limit is specific to this application. Use this setting to distribute the workspace limit across applications in that workspace. If you configure a higher value than the workspace limit, this limit will be ignored and the workspace limit will be used instead.

  Application level. Edit the Application Definition, Maximum Background Page Process Jobs attribute. See Properties.

15.3.4.2 Creating a Background Page Page Process

Create a background page process using the Execution Chain process type, which contains child processes executing one after the other. Execution chains can run in the background or in the foreground.

To create background page process using the Execution Chain process type:

1. View the page in Page Designer.
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.

      Page Designer appears.

Create Execution Chain page process:

2. In the Processing tab, locate the node where the process will occur. Right-click and select Create Process.

In the Property Editor, configure the Execution Chain process.

3. Under Identification:
   1. Identification, Name - Enter the name of the process for easy identification by developers.
   2. Identification, Type - Select Execution Chain.
   3. Identification, Execution Chain - This attribute enables support for nested execution chains. Use this attribute to define another execution chain as the parent for this chain. For this example, select None.
4. Under Settings:
   1. Settings, Execute in Background - Enable this option to execute this chain in the background.
   2. Settings, Serialize Executions - Specify whether to serialize executions of this execution chain. When enabled, all executions (from all APEX sessions) are serialized to avoid concurrent executions in the background. Use this setting when processes of this chain are likely to work on the same resources, for instance, performing DML on the same row in a table..
   3. Settings, Return Execution ID into Item - Choose a page item to return the execution ID into. Based on the execution ID, the current status of the background execution can be fetched.
   4. Settings, Temporary File Handling - Determine how to deal with temporary files, uploaded through a File Browse page item. Options include:
      • Ignore - Neither move nor copy temporary files to the working session for background execution. Choose this option if the background processes will not work with uploaded files.
      • Move - Move temporary files to the working session for background execution. Choose this option if access to temporary files is only needed by one background execution chain.
      • Copy - Copy temporary files to the working session for background execution. Choose this option if you have multiple background execution chains, and all of them require access to the temporary files.
   5. Settings, Executions Limit - If an execution limit is specified, Oracle APEX will raise an error message, if an application user requests more than the specified limit of background executions. For example, specifying the value 3, users see an error message when attempting to submit the fourth background execution. This attribute is useful to prevent users from submitting large amounts of background executions to the server.
5. Under Execution :
   1. Execution, Sequence - Specify the sequence for this computation. The sequence determines the order of execution.

      If two components have the same sequence value, then they may be executed in a different order when the application is exported and imported into another environment.

   2. Execution, Point - Select the point at which this process is executed.
   3. Execution, Run Process - Select the frequency that this process executes.
6. Under Success Message:
   • Success Message, Success Message - Enter the success message for this process.

     If the process runs and does not generate an error, then this process success message displays in the notification section of the resulting page displayed. If you are branching to another page using a URL redirect, you may need to check the preserve success message attribute.

     To learn more, select the attribute in the Property Editor and click the Help tab in the central pane.

7. Under Error:
   1. Error, Error Message - Enter the error message for this process.

      This message displays if an unhandled exception is raised. After any error processing stops, a rollback is issued and an error message displays.

   2. Error, Display Location - Select where this process error message displays, when the process fails to complete successfully.
8. Click Save.

Create one or more child process:

9. Create a child process:
   1. In the Processing tab, select the Execution Chain process, right-click and select Create Child Process.
      The new child process displays under Processes.
   2. In the Property Editor, configure the process attributes.

      To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the central pane.

   3. Click Save.
10. Repeat the previous step to create additional child processes.

15.3.4.3 Monitoring Currently Running Background Processes

Monitor background processes by clicking Session on the Runtime Developer toolbar.

Tip:

You can also view a Background Processing report for Active Sessions in Workspace Administration. From the Administration menu, select Monitor Activity and then Active Sessions. Select an active session and then Background Processing.

To monitor background processes:

1. Run the application as a developer.
2. Locate the Runtime Developer toolbar. By default, the Runtime Developer toolbar displays at the bottom of the page.
3. On the Runtime Developer toolbar, click Session and then View Session State.

   The Session page appears and displays the following information displays at the center of the page.

4. From View, select Background Executions and click Set.
   The Background Processing region appears displaying currently running background processes as shown in the following example.
   Description of the illustration background_processing.png
5. Statuses - Configure which background executions to include and click Go. Available Statuses include:
   • Submitted for Execution
   • Scheduler Job Created
   • Executing
   • Finished Successfully
   • Aborted
   • Failed
6. To abort a currently running background process, click Abort.