1 Oracle Application Express Installation Overview

This document describes how to install Oracle Application Express in a on-premises (or local) installation. How you sign in and access Oracle Application Express depends upon your user role and where Oracle Application Express resides. Oracle Application Express may reside in a local on-premises Oracle Database or in an Oracle Cloud Service.

Note:

If you are accessing Oracle Application Express in the Oracle Database Cloud, see the corresponding Using Guide for the Cloud Service hosting Oracle Application Express. To learn more, see the Cloud Documentation Platform and Infrastruture page: 
http://docs.oracle.com/cloud/latest/?tab=3

1.1 Understanding the Installation Process

This section provides an overview of the Oracle Application Express installation process.

See Also:

"Upgrading from a Previous Oracle Application Express Release"

1.1.1 About Planning Your Installation

The installation process involves the following steps:

  1. Plan your installation: During the planning phase, you should determine whether to install a full development environment or runtime environment. A full development environment provides complete access to the Application Builder development environment to develop applications. A runtime environment is an appropriate choice for production implementations in which you want to run applications that cannot be modified.

    You should also determine which Web listener to use. Available options include the Oracle REST Data Services, Embedded PL/SQL Gateway, or Oracle HTTP Server and mod_plsql.

  2. Verify installation requirements: "Oracle Application Express Installation Requirements" describes the minimum requirements that your system must meet before you install the software.

  3. Install the software: The required installation steps depend upon which Web listener you decide to use.

See also:

"About the Oracle Application Express Runtime Environment," "Choosing a Web Listener," and "Oracle Application Express Installation Requirements"

1.1.2 About Patch Sets and Point Releases

Patch sets are a mechanism for delivering fully tested and integrated product fixes. Patch sets provide bug fixes only. Patch sets typically do not include new functionality and they do not require certification on the target system. Patch sets include all of the libraries that have been rebuilt to implement the bug fixes in the set. All of the fixes in the patch set have been tested and are certified to work with each other.

In between major product releases, Oracle may offer a point release. A point release (for example Oracle Application Express release 4.2.5) includes bug fixes and incorporates all current patch sets. Typically, point releases do not introduce new functionality.

See Also:

"Upgrading from a Previous Oracle Application Express Release" and "Downloading and Installing Patches"

1.1.3 About Oracle Application Express Schemas

The Application Express engine consists of a large number of Oracle tables and thousands of lines of PL/SQL programs residing within their own version specific schema. For each release of Oracle Application Express, this schema has a unique name as described in Table 1-1.

Table 1-1 Oracle Application Express Release and Schema

Oracle Application Express Release Schema Name

Oracle Application Express release 5.0.x

APEX_050000

Oracle Application Express release 4.2.x

APEX_040200

Oracle Application Express release 4.1.x

APEX_040100

Oracle Application Express release 3.1.x and earlier

FLOWS_xxxxxx

1.1.4 About the Installation Process

Whether you are installing Oracle Application Express for the first time or updating from previous release, you use the same installation procedure and the same installation scripts. The installation script checks for the latest existing Oracle Application Express schema and automatically copies the instance metadata, workspaces, and applications from the previous schema into the current schema. The original schema associated with the previous release is left completely unaltered. Following best practices, Oracle recommends that you create new tablespaces for a new release of Oracle Application Express and follow the appropriate installation instructions as outlined in this document.

1.1.5 About Accessing Oracle Application Express

Note:

This information does not apply to Oracle Database Cloud Service (Database Schema).

How you sign in and access Oracle Application Express depends upon your user role.

  • Instance administrators are superusers that manage an entire hosted instance using a separate application called Oracle Application Express Administration Services. Instance administrators manage workspace provisioning, configure features and instance settings, and manage security.

  • Workspace administrators can perform administrator tasks specific to a workspace such as configuring workspace preferences, managing user accounts, monitoring workspace activity, and viewing log files.

  • Developers are users who sign in to a workspace and create and edit applications.

  • End users can only run existing database or Websheet applications.

If you are a developer, an administrator must grant you access to shared work area called a workspace. If you are an Instance administrator, you must sign in to Oracle Application Express Administration Services, determine whether to specify a provisioning mode, create a workspace, and then sign in to that workspace.

About Specifying a Provisioning Mode

An Instance administrator determines how the process of provisioning (or creating) a workspace works for a specific Oracle Application Express instance. To determine how provisioning works, an Instance Administrator selects one of the following options on the Instance Settings page:

  • Manual - In this mode, an Instance administrator creates new workspaces and notifies the Workspace administrator of the login icon.

  • Request - Users request workspaces directly in a self-service fashion. Users click a link on the login page to access a request form. After the workspace request has been granted, users are automatically emailed the appropriate login information.

  • Request with Email Verification - In this mode, users request workspaces directly by clicking a link on the login page to access a request form. Each user receives an initial email containing a verification link. Clicking this link validates the user's email address and then the request is processed. Then another email is sent to the user containing login credentials (that is, the workspace name, username, and password).

About Creating Workspaces and Users

Before you can develop or install applications, an administrator must create a workspace and add Oracle Application Express users. To learn more contact your administrator, or see the ”Creating a Workspace and Adding Oracle Application Express Users” section for your Web listener in this document.

See Also:

"Creating Workspaces" and "Managing Workspace and Change Requests" in Oracle Application Express Administration Guide

1.1.6 Signing In When Workspace Requests Is Enabled

Note:

This information does not apply to Oracle Database Cloud Service (Database Schema).

If your administrator has enabled workspace requests, signing in to a workspace requires the following steps. First, you request a workspace using a link on the Sign In page. Second, your administrator approves the request and the system send you an email with your sign in credentials. Third, you sign in to your workspace.

Tip:

Before users can request a workspace or change their passwords, an Oracle Application Express administrator must configure Oracle Application Express environment preferences.

1.1.6.1 Requesting a Workspace from the Sign In Page

Note:

Before a user can request a workspace from the Sign In page, your Oracle Application Express administrator must configure Oracle Application Express to support workspace requests. To learn more, see "Creating Workspaces" in Oracle Application Express Administration Guide

To request a workspace:

  1. In a web browser, navigate to the Oracle Application Express Sign In page.

    The Sign In page appears.

  2. Under Workspace, click Request a Workspace.

    The Request Service Wizard appears.

  3. Select the type of workspace. Options include:

    • Application Development

    • Packaged Apps Only

  4. Follow the on-screen instructions.

1.1.6.2 Signing In To a Workspace

After an Oracle Application Express administrator approves a workspace request, an e-mail arrives with your login credentials (the workspace name, user name, and password).

Note that if your administrator selected Email Verification as the automated method for handling new workspace requests, you might first receive an email containing a verification link. This step ensures that your email is a valid one before the workspace request is approved.

To sign in to Oracle Application Express:

  1. In a web browser, navigate to the Oracle Application Express Login page provided in your workspace request email.

  2. On the Sign In page:

    • In the Workspace field, enter the name of your workspace.

    • In the Username field, enter your user name.

    • In the Password field, enter your case-sensitive password.

  3. Click Sign In.

    The workspace home page appears.

Tip:

Depending on your setup, you might be required to change your password when you sign in for the first time.

See Also:

"Creating Workspaces" in Oracle Application Express Administration Guide

1.1.6.3 Signing Out of a Workspace

To sign out of an Oracle Application Express workspace:

  • Select the Account Menu in the upper right corner of the window and click Sign out.

1.1.6.4 Recovering Your Workspace Name

If you cannot remember your workspace name, you can request a list of all workspace names associated with your email address.

To find your workspace name:

  1. In a web browser, navigate to the Oracle Application Express Sign In page.

  2. On the Sign In page, click Reset Password.

  3. Click Find My Workspace.

  4. Enter your email address and click Find Workspace.

    You will receive an email listing all workspaces associated with the email address you provided.

1.1.6.5 Resetting Your Password from the Sign In Page

Tip:

To reset your password from the Sign In page, you must provide your email address and workspace name.

To reset your password from the Sign In Page:

  1. Under Sign in, click Reset Password.

  2. Enter your email address and workspace name, and click Reset Password.

    You will receive an email containing new passwords for all accounts associated with the email address and workspace name you provided.

  3. On the Sign In page, enter your workspace, username, and the new password and click Sign In.

    Tip:

    Passwords are case sensitive. Do not copy and paste the new password.

  4. On Change Password, enter:

    1. Current Password - Enter the current password provided by the email.

    2. New Password - Enter your new password.

    3. Confirm Password - Enter your new password again.

    4. Click Apply Changes.

1.2 Upgrading from a Previous Oracle Application Express Release

If you have release 1.5.x, 1.6.x, 2.0.x, 2.2.x, 3.0.x, 3.1.x, 3.2.x, 4.0x, 4.1x or 4.2.x of Oracle Application Express, following any of the installation scenarios in this guide upgrades your Oracle Application Express instance to release 5.0 and creates Oracle Application Express 5.0 database objects in a new schema and migrates the application metadata to the new release. This section describes other information relevant to the upgrade process.

See Also:

"Understanding the Installation Process"

1.2.1 Sample Upgrade Scenarios

Both Patch sets and point releases are available for download from My Oracle Support. Table 1-2 lists common upgrade scenarios.

Table 1-2 Sample Upgrade Scenarios

Upgrade Scenarios Action

Upgrade from a prior Oracle Application Express release

Download the latest files from the Downloads page.

Upgrade from a major Oracle Application Express to point release.

Download the point release from My Oracle Support.

You install Oracle Database 12c which includes Oracle Application Express release 4.2 by default.

Download the latest files from the Downloads page.

1.2.2 Determining Your Oracle Application Express Release Version

To determine which release of Oracle Application Express you are currently running:

  1. Sign in to Oracle Application Express.

    The Workspace home page appears.

    The current release version displays in bottom right corner.

  2. To view the About Application Express page:

    • Locate the Help menu at the top of the page.

    • From the Help menu, select About.

      The About Application Express page appears.

1.2.3 About Installing the Application Express Release Included with the Oracle Database

Oracle Application Express is included with the following Oracle Database releases:

  • Oracle Database 11g Release 1 (11.1) - Oracle Application Express Release 3.0.

  • Oracle Database 11g Release 1 (11.2) - Oracle Application Express Release 3.2.

  • Oracle Database 12c Release 1 (12.1) - Oracle Application Express Release 4.2.

  • Oracle Database 12c Release 2 (12.2) - Oracle Application Express Release 5.0.

The Oracle Database releases less frequently than Oracle Application Express. Therefore, Oracle recommends updating to the latest Oracle Application Express release available on Oracle Technology Network. To learn more, see the installation instructions for the appropriate Web Listener in your environment.

Note:

If upgrading Oracle Application Express from a release that ships from the database do not alter any Oracle Application Express files in the Oracle home directory (for example: dbhome_1).

1.2.4 About Upgrading Existing Applications

If you install a new release of Oracle Application Express, the installation process updates existing applications to the latest release. The upgrade process is designed to not alter the application user interface or application components. As a result, application components that may impact the user interface are left untouched by the upgrade process. It is the developer's responsibility to manually review these components and update them, or leave them as is. Examples of components which may impact existing functionality include new features added to interactive reports, charts, certain validations, and so on.

Tip:

Charts that use custom XML must be updated manually otherwise the custom XML will be lost.

See Also:

"Running Advisor to Check Application Integrity" in Oracle Application Express Application Builder User's Guide

1.2.5 About Specifying an Application Compatibility Mode

Within each application, you can also specify the Compatibility Mode in the Application Definition. Changing the application Compatibility Mode changes certain runtime behaviors. Compatibility Mode options include Pre 4.1, 4.1, 4.2, and 5.0.

See Also:

"Compatibility Mode" in Oracle Application Express Release Notes and "Editing the Application Attributes" and "Properties" in Oracle Application Express Application Builder User's Guide

1.2.6 About Testing Requirements

Determining the appropriate amount of regression testing when upgrading Oracle Application Express depends upon the complexity, size, and number of applications you are upgrading. You should include the majority of complex pages, particularly those that incorporate significant JavaScript or extensive PL/SQL computations or processes. Developers should ensure pages which they manually update based on the Upgrade Application or Advisor are also included in regression tests. Not all remaining pages have to be included in regression testing. Oracle recommends you include a good representation of different page types includes reports, charts, and forms. An application should always be included in regression testing if its compatibility mode was modified post-upgrade.

While regression testing of upgraded applications is imperative to minimize risk of disrupting the end users, it is important that testing is not drawn out for an extended period. As a general rule:

  • Step 1: Upgrade your development environment first. Allow developers to review the applications and make initial updates as needed.

  • Step 2: Upgrade your QA/Test environment.

  • Step 3: Upgrade applications from development are built into this environment.

  • Step 4: Upgrade your production environment.

  • Step 5: Build upgraded applications into this environment.

1.2.7 About Cleaning Up Your Environment

Following the successful upgrade of all of the environments to the latest release of Oracle Application Express, you should clean-up the environments. Once you start developing with the newer release, the Oracle Application Express schema associated with the prior release can be deleted.

If you installed the prior release into a separate tablespace, you can simply drop the specific tablespace. Oracle recommends leaving the older Oracle Application Express schema(s) for a few weeks and then remove them from the development, test, and production environments. This cleanup process releases disk space and ensures that no one accesses an outdated schema using tools such as SQL Developer or SQL*Plus.

1.2.8 About Reverting to a Previous Release

Because Oracle Application Express creates a new schema for each major release, reverting back to a prior release is a relatively simple process. If you revert to a prior release, any modifications made in the current Oracle Application Express instance are lost. The main task is to switch the public synonyms and grants to point at the previous schema instead of the new schema.

See Also:

"Reverting to a Previous Release After a Failed Upgrade Installation"

1.3 Choosing a Web Listener

In order to run, Oracle Application Express must have access to Oracle REST Data Services, Oracle HTTP Server and mod_plsql, or the Embedded PL/SQL Gateway.

1.3.1 About Choosing a Web Listener

Oracle Application Express uses a simple architecture where pages are dynamically generated using metadata stored within the Oracle Database. There is no code generation or file based compilation. Once fully installed, a Uniform Resource Locator (URL) is defined for both developers and end users to access Oracle Application Express. Users require only a Web browser and the required URL. No additional client software is required.

Description of apex-arch-1876607.png follows
Description of the illustration ''apex-arch-1876607.png''

The Web Listener functions as a communications broker between the Web browser and the Oracle Application Express objects in the Oracle database by mapping browser requests into database stored procedure calls. You have a choice of three Web Listeners.

See Also:

"Choosing a Web Listener" and "Web Listener Requirements"

1.3.2 About Oracle REST Data Services

Oracle REST Data Services (formerly Oracle Application Express Listener) is Java-based, can be installed into any supported J2EE compliant Web Server, and is the preferred option for use with Oracle Application Express. It is a free tool that is fully supported against Oracle WebLogic Server, Oracle Glassfish Server, and Apache Tomcat. Oracle REST Data Services is part of the reference architecture used to operate the Oracle Database Cloud Service.

Note:

There are licensing costs associated with Oracle WebLogic Server and Oracle Glassfish Enterprise edition. Oracle Glassfish Community edition is a no cost option.

Using Oracle REST Data Services creates an architecture which consists of:

  • A web browser

  • Oracle REST Data Services

  • Oracle Database containing Oracle Application Express

The major advantage of this architecture is the separation of the mid-tier and the database tier.

Tip:

This architecture is appropriate for Oracle Real Application Clusters (Oracle RAC) environments. See "Selecting a Web Listener in an Oracle RAC Environment."

See Also:

"Web Listener Requirements", "About Configuring Oracle REST Data Services with Oracle Application Express" in Oracle Application Express Application Builder User's Guide, and "Installing Application Express and Configuring Oracle REST Data Services"

1.3.3 About Oracle HTTP Server with mod_plsql

Note:

mod_plsql is deprecated as of Oracle HTTP Server 12c (12.1.3). For more information, see My Oracle Support Note 1576588.1. Oracle recommends using Oracle REST Data Services instead. See "About Oracle REST Data Services."

The Oracle HTTP Server (Apache) with mod_plsql can be placed on the same physical machine as the database, or on a separate physical machine. If Oracle HTTP Server is installed on the same physical machine as the database then the Oracle HTTP Server is included as part of the limited-use license included with the Oracle Database license. Otherwise, you must obtain a separate Oracle HTTP Server license.

Using Oracle HTTP Server (Apache) with mod_plsql creates an architecture which consists of:

  • a Web browser

  • Oracle HTTP Server with mod_plsql

  • Oracle Database containing Oracle Application Express

This architecture separates the mid-tier and the database tier.

Tip:

This architecture is appropriate for Oracle Real Application Clusters (Oracle RAC) environments. See "Selecting a Web Listener in an Oracle RAC Environment."

See Also:

"Web Listener Requirements," "About Configuring Oracle HTTP Server with mod_plsql with Oracle Application Express" in Oracle Application Express Application Builder User's Guide, and "Installing Application Express and Configuring Oracle HTTP Server"

Where Images Are Stored When Using Oracle HTTP Server

In an Oracle HTTP Server or Oracle Application Server configuration, images are stored on the file system in the location referenced by the alias /i/. If you are upgrading Oracle Application Express from a prior release, you can locate the images directory on the file system, by reviewing the following files and searching for the text alias /i/:

  • Oracle HTTP Server distributed Oracle9i Release 2—see the httpd.conf file.

  • Oracle Application Server 10g—see the marvel.conf or dads.conf files.

  • Oracle HTTP Server distributed with Oracle Database 11g or 12c —see the marvel.conf or dads.conf files.

Specific examples for locating the text alias /i/ can be found in "Copying the Images Directory."

1.3.4 About the Embedded PL/SQL Gateway

Oracle XML DB Protocol Server with the Embedded PL/SQL Gateway installs with Oracle Database. It provides the Oracle database with a Web server and also the necessary infrastructure to create dynamic applications. The Embedded PL/SQL Gateway runs in the Oracle XML DB Protocol server in the Oracle database and includes the core features of mod_plsql.

The Embedded PL/SQL Gateway consists of a simple two tier architecture: a Web browser and an Oracle database containing the Embedded PL/SQL Gateway and Oracle Application Express.

Advantages of the Embedded PL/SQL Gateway include:

  • Ease of configuration

  • Included in the database

  • No separate server installation

See Also:

"Web Listener Requirements" and "About Security Considerations When Using the Embedded PL/SQL gateway"

Where Images Are Stored When Using the Embedded PL/SQL Gateway

When running Oracle Application Express with the Embedded PL/SQL Gateway, images are stored directly in the database within the Oracle XML DB repository. You can access images by using the WebDAV feature of Oracle XML DB or by using FTP. To learn more, see "Using Protocols to Access the Repository" in Oracle XML DB Developer's Guide.

1.3.5 Comparing Web Listener Options

Table 1-3, "Web Listener Comparisons"compares Web Listener options for Oracle Application Express.

Table 1-3 Web Listener Comparisons

Capabilities Oracle REST Data Services Oracle HTTP Server with mod_plsql Embedded PL/SQL Gateway

Image location

File system

File system

Within the database

Configuration options

GUI interface (Release 2.0.3 or later); Administration pages

Database Access Descriptor (DAD)

Database initialization parameters

Connection Pool settings

JDBC parameters

Min/MaxSpareServers; MaxClients

SHARED_SERVERS; MAX_SHARED_SERVERS

Emit RESTful Web Services

Yes (Release 2.0.3 or later)

No

No

Support multi-databases

Yes, including Oracle RAC

Yes, including Oracle RAC

No

Virus scan files

Yes, with integration of ICAP server

No

No

PDF printing

Yes, included FOP support

No

No

Environment recommendations

All

All

Development only

1.3.6 About Security Considerations When Using the Embedded PL/SQL gateway

The Embedded PL/SQL Gateway runs in the database as part of the Oracle XML DB HTTP listener. The Oracle XML DB HTTP listener and Embedded PL/SQL Gateway provides the equivalent core features of Oracle HTTP Server and mod_plsql. Because the HTTP Listener runs in the same database where Oracle Application Express is installed, it is not possible to separate the HTTP listener from the database. For this reason, Oracle does not recommend the Embedded PL/SQL Gateway for applications that run on the Internet. Additionally, the Embedded PL/SQL Gateway does not provide the same flexibility of configuration and detailed logging as Oracle REST Data Services or Oracle HTTP Server.

1.3.7 Selecting a Web Listener in an Oracle RAC Environment

When running Oracle Application Express in an Oracle Real Application Clusters (Oracle RAC) environment, Oracle recommends that you use Oracle REST Data Services or Oracle HTTP Server with mod_plsql. Oracle REST Data Services or Oracle HTTP Server with mod_plsql permit you to specify a connection in the service name format, so that one HTTP Server can access all nodes.

Oracle recommends that you do not select the Embedded PL/SQL Gateway option for Oracle RAC installations. Because the Embedded PL/SQL Gateway uses an HTTP Server built into the database instance, it does not take advantage of the Oracle RAC shared architecture.

1.4 About the Oracle Application Express Runtime Environment

As with any software development life cycle, Oracle strongly recommends that you have different environments for development, testing/QA, and production. For testing and production instances, Oracle Application Express supports the ability to install just a runtime version of Oracle Application Express. This runtime environment minimizes the installed footprint and privileges and improves application security since in a runtime instance developers cannot inadvertently update a production application.

An Oracle Application Express runtime environment enables you to run production applications, but it does not provide a Web interface for administration. A runtime environment only includes the packages necessary to run your application, making it a more hardened environment. You administer the Oracle Application Express runtime environment using SQL*Plus or SQL Developer and the APEX_INSTANCE_ADMIN API. To learn more see, "About the Advantages of the Application Express Runtime Environment" in Oracle Application Express Application Builder User's Guide.

Scripts are provided to remove or add the developer interface from an existing instance. To learn more, see one of the following for the corresponding type of installation: