1.3 Upgrading from a Previous Oracle Application Express Release

Upgrading Oracle Application Express creates new database objects in a new schema and migrates the application metadata to the new release.

If you have Oracle Application Express release 18.2x or ealier, following any of the installation scenarios in this guide upgrades your Oracle Application Express instance to release 19.1 and creates Oracle Application Express 19.1 database objects in a new schema and migrates the application metadata to the new release.

• About Release Numbering Convention
  New releases of Oracle Application Express correlate to the calendar year.
• Sample Upgrade Scenarios
  Common upgrade scenarios include upgrading from prior release and installing an Oracle Database release which include Oracle Application Express.
• Determining Your Oracle Application Express Release Version
  You can view the release version of Oracle Application Express on the workspace home page.
• About Determining the Version of Oracle REST Data Services
  You can view the version of Oracle REST Data Services on the About Application Express page.
• About Installing the Oracle Application Express Release Included with the Oracle Database
  Learn about the Oracle Application Express release included with the Oracle Database release.
• About Upgrading Existing Applications
  If you install a new release of Oracle Application Express, the installation process updates existing applications to the latest release.
• About Specifying an Application Compatibility Mode
  You can specify the compatibility mode in the application definition within each application.
• 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.
• 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.
• About Reverting to a Previous Release
  You can revert to a previous release of Oracle Application Express.

See Also:

• "Understanding the Installation Process"

• "Maximizing Uptime During an Application Express Upgrade"

1.3.1 About Release Numbering Convention

New releases of Oracle Application Express correlate to the calendar year.

This convention was introduced in 2018 with Application Express 18.1 and 18.2.

Additionally, Application Express now only offers full releases and no longer provides patch set releases (such as 5.1.1). Eliminating patch set releases reduces downtime when updating existing installations. Application Express architecture also enables developers to revert releases if necessary.

Patch set exceptions (PSEs) may still be delivered for major defects. To learn more about PSEs, visit the Oracle Application Express Known Issues page.

1.3.2 Sample Upgrade Scenarios

Common upgrade scenarios include upgrading from prior release and installing an Oracle Database release which include Oracle Application Express.

Table 1-1 lists common upgrade scenarios.

Table 1-1 Sample Upgrade Scenarios

Upgrade Scenarios	Action
Upgrade from a prior Oracle Application Express release	Download the latest files from the Downloads page.
You install Oracle Database which include Oracle Application Express.	Download the latest files from the Downloads page.

1.3.3 Determining Your Oracle Application Express Release Version

You can view the release version of Oracle Application Express on the workspace home page.

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.3.4 About Determining the Version of Oracle REST Data Services

You can view the version of Oracle REST Data Services on the About Application Express page.

To access the About Application Express page, go to the Help menu and then select About. Under the CGI Environment section, find APEX_LISTENER_VERSION. If APEX_LISTENER_VERSION does not appear, then your Oracle Application Express instance is not using ORDS as its web listener.

See Also:

"Determining Your Oracle Application Express Release Version"

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

Learn about the Oracle Application Express release included with the Oracle Database release.

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 2 (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.

• Oracle Database 18c - Oracle Application Express Release 5.1.

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 with the database, do not alter any Oracle Application Express files in the Oracle home directory (for example, /u01/app/oracle/product/18.0.0/dbhome_1/apex) .

1.3.6 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 App Builder User’s Guide

1.3.7 About Specifying an Application Compatibility Mode

You can specify the compatibility mode in the application definition within each application.

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, 5.0, 5.1/18.1, 18.2 and 19.1.

See Also:

• "Compatibility Mode" in Oracle Application Express Release Notes

• "Editing the Application Attributes in Oracle Application Express App Builder User’s Guide

• "Properties" in Oracle Application Express App Builder User’s Guide

1.3.8 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.3.9 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.3.10 About Reverting to a Previous Release

You can revert to a previous release of Oracle Application Express.

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"