Installing an Application

Install an APEX application into a target environment by installing an APEXlang export or running a SQL script.

Note that you can handle special cases by first configuring installation context information and then running the SQL script. This topic explains both scenarios.

About the APEX_APPLICATION_INSTALL API

Oracle APEX provides two ways to import an application into an APEX instance:

Uploading an application export file by using the web interface of APEX.
Execution of the application export file as a SQL script, typically in the command-line utility SQLcl.

Using the file upload capability of the web interface of APEX, developers can import an application with a different application ID, different workspace ID and different parsing schema. But when importing an application by using a command-line tool like SQLcl, changing these attributes (application ID, workspace ID, parsing schema) can be done by using the APEX_APPLICATION_INSTALL API.

To view the install log, enter the following from the command-line tool, so the server outputs are displayed:

set serveroutput on unlimited

As more and more APEX customers create applications which are meant to be deployed by using command-line utilities or by using a non-web-based installer, they are faced with this challenge of how to import their application into an arbitrary workspace on any APEX instance.

Another common scenario is in a training class when installing an application into 50 different workspaces that all use the same application export file. Today, customers work around this by adding their own global variables to an application export file and then varying the values of these globals at installation time. However, this manual modification of the application export file (usually done with a post-export sed or awk script) should not be necessary.

Application Express 4.0 and higher includes the APEX_APPLICATION_INSTALL API. This PL/SQL API provides many methods to set application attributes during the APEX application installation process. All export files in Application Express 4.0 and higher contain references to the values set by the APEX_APPLICATION_INSTALL API. However, the methods in this API are only used to override the default application installation behavior.

See Also: APEX_APPLICATION_INSTALL in Oracle APEX API Reference

Installing an Application from an APEXlang Export

Learn about installing an APEXlang application export.

Tip: Importing an APEXlang export requires a version of Oracle SQLcl that supports the apex import command. Before importing, download and install the latest version of Oracle SQLcl. See Downloading and Installing SQLcl.

To install an application from an APEXlang export, run the apex import command.

Consider the following examples:

Install an application from an APEXlang ZIP export:
```
apex import -input myapp.zip
```
Install an application from a directory containing an APEXlang application:
```
apex import -input path-to-folder/myapp
```

Note: To display all options for the apex import command, run help apex import in SQLcl.

Importing Selected Files from an APEXlang Application

To import selected files from an APEXlang application, run the apex import command with -files option, where the files specified are relative to the current folder. APEX can import multiple files using space as a separator.

Consider the following examples:

importing a single file from an APEXlang application:

apex import -input test-app/ -files test-app/pages/p00001-home.apx

or

-- when you are in the APEXlang application directory test-app
apex import -files pages/p00001-home.apx

importing multiple files from an APEXlang application

apex import -input test-app/ -files test-app/pages/p00001-home.apx test-app/shared-components/lovs/lov-countries.apx

or

-- when you are in the APEXlang application directory test-app
apex import -files pages/p00001-home.apx shared-components/lovs/lov-countries.apx

importing Static Application files

apex import -input test-app/ -files test-app/shared-components/static-files/app-logo.png

or

-- when you are in the APEXlang application directory test-app
apex import -files shared-components/static-files/app-logo.png

Note:

Selected files import:

is intended for development environments only. For production environments, always use a full application import.
expects the application already exists in the target APEX environment. If the application does not exist, then it throws an error.
is not supported for the following component type files:
- Themes
- Templates
- Plug-ins
- Workspace components
is not supported across different APEX versions. The APEXlang application version should match the target APEX environment version.

Installing an Application When Target Environment Mirrors the Source

Learn about installing an application when the target environment mirrors the source.

You export an APEX application from a source environment as a single SQL file or a set of individual SQL files split into subdirectories. To install the export into a target environment that uses the same workspace name, workspace ID, workspace schema name, and application Alias, simply run the SQL script created by the export procedure.

The application being installed overwrites the application of the same ID in the target environment. If the application export was a partial export containing only selected components, then only those components are overwritten in the target environment.

If the export was a single SQL file, such as f1234.sql, then run that script to install the application. If instead the export used the -split option to create a directory, such as f1234 which containing individual component SQL files organized into subdirectories, then run the ./f1234/install.sql script to install the application. If you used the -split option to export a partial set of components, then run the ./f1234/install_component.sql script.

Installing an Application When Target Environment Differs From Source

Learn about installing an application when the target environment differs from the source.

If the target environment into which you need to import does not use the same workspace name, workspace ID, workspace schema name, and application Alias, then installing the application requires a SQL script that performs the following additional steps as shown in the following example:

REM First setup the installation context in the target environment
begin
    -- Add necessary calls to apex_application_install package procedures here
end;
/
REM Then install the application by running its exported SQL script
REM For "split" export run @f1234/install.sql
REM or @f1234/install_component.sql instead
@f1234.sql

Setting Up the Installation Context

The installation context includes:

Workspace name (for example, TARGET_WORKSPACE)
Application ID (for example, 5678)
Workspace schema (for example, HRAPP_PROD)
Application alias (for example, hrapp, used in friendly URLs)

If the name or ID of the target workspace is different than the workspace from which the application was exported, then you need to add a call to the set_workspace() procedure to the anonymous block in your installation script:

apex_application_install.set_workspace('TARGET_WORKSPACE');

Similarly, other calls to apex_application_install package procedures are only required when their value in the target environment differs from the corresponding value in the source environment from which the application was exported.

To set a specific application ID in the target environment, add a call to set_application_id() as shown below, along with the additional call to generate_offset().

apex_application_install.set_application_id(5678);
apex_application_install.generate_offset();

To generate an available application ID instead of supplying a specific one, add a call to generate_application_id instead of calling set_application_id.

apex_application_install.generate_application_id;
apex_application_install.generate_offset;

To set the name of the workspace schema for the application to be installed, add a call to set_schema() as shown here:

apex_application_install.set_schema('HRAPP_PROD');

To set the application alias (used in friendly URLs), add a call to set_application_alias() procedure as shown here:

apex_application_install.set_application_alias('hrapp');

Running the SQL Script to Install an Application

This section includes a complete example of an installation script for single-file and “split” exports.

This example assumes you have previously exported an application with ID 1234 to a single file named f1234.sql. This example also shows the SQL script you would run using SQLcl to install the APEX application into a target environment with workspace HRAPP_PROD, using application ID 5678, workspace schema HRAPP_PROD, and application alias hrapp.

REM First setup the installation context in the target environment
begin
    apex_application_install.set_workspace('TARGET_WORKSPACE');
    apex_application_install.set_application_id(5678);
    apex_application_install.generate_offset();
    apex_application_install.set_schema('HRAPP_PROD');
    apex_application_install.set_application_alias('hrapp');
end;
/
REM Then install the application by running its exported SQL script
REM For "split" export run @f1234/install.sql
REM or @f1234/install_component.sql instead
@f1234.sql