3.12.11.1.9 Installing an Application

Install an APEX application into a target environment by 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.

• Installing an Application When Target Environment Mirrors the Source
  Learn about installing an application when the target environment mirrors the source.
• Installing an Application When Target Environment Differs From Source
  Learn about installing an application when the target environment differs from the source.

3.12.11.1.9.1 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.

3.12.11.1.9.2 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