How to Create a Packaged Application

How a Packaged Application Simplifies Deployment

From a user's perspective, importing and installing an application is a complicated process. First, you create the target database objects and seed data. Second, you import and install the application definition and all related files, including images, themes, and any other required static files.

Creating a packaged application using the Supporting Objects utility greatly simplifies this process. Instead of performing numerous steps to create the database objects and then import and install the application and all supporting files, you can define the supporting objects so that the application and supporting files can be migrated in a few easy steps.

After users import and install the application definition, a wizard guides them through a few simple configuration steps. Then, the wizard asks whether to install the supporting application objects. Users have the option of installing the supporting application objects then or doing it later.

From a developer's perspective, this feature has a number of advantages:

• Ensures that the supporting objects are created in the correct order.

• Provides users with an automated process for deploying an application quickly using very few steps.

• Gives users the option to install supporting application objects when they import and install the application definition or at a later time. See "Installing Supporting Objects".

• Enables users and developers with a convenient method for removing the application definition, supporting files, and all database objects. See "Deinstalling Supporting Objects".

• Enables users and developers with an easy way to upgrade a previously released packaged application. See "Upgrading a Packaged Application".

Plus, you can also take advantage of the Deinstall and Install features to quickly edit the underlying database objects that support an application. For example, you can deinstall and remove all database objects, edit the underlying database object creation scripts, and reinstall to create the redefined application objects.

Creating a Packaged Application

To create a packaged application, you must create installation scripts that define your application's supporting objects (including database objects, images, and seed data) and any preinstallation validations. You define these objects and the installation and deinstallation scripts and the messages that display when the user installs or deinstalls on the Supporting Objects page.

This section contains the following topics:

• Accessing the Supporting Objects Page

• About the Supporting Objects Page

About the Supporting Objects Page

The top of the Supporting Objects page displays the application name and indicates current selections for the following: Check for Objects, Verify System Privileges, Required Free KB, Prompt for License, Substitutions, Build Options, Validations, Installation Scripts, Upgrade Scripts, Deinstallation Script, and Include in Export.

Description of the illustration sup_object_sum.gif

The rest of the page is divided into four categories.

Installation

Use the links under Installation to define the following types of information:

• Prerequisites. Defines built-in checks required before installing the application, including required free disk space, required system privileges, and schema object restrictions.

• Application substitution strings. Lists static substitution strings defined for the application. You can define static substitution strings for phrases or labels that occur in many places within an application. See "Substitutions".

  When packaging an application, you can include prompts for substitution strings which users can specify when they install the packaged application.

• Build Options. Lists build options defined for this application. You can use build options to conditionally display specific functionality within an application. See "Using Build Options to Control Configuration" and "Exporting Build Options or Build Option Status".

  When packaging an application, you can include prompts for specific build options which display when the application is installed.

• Pre-installation Validations. Lists validations defined for the packaged application. Similar to normal page validations, these validations prevent a user from installing database objects if the user-defined conditions are not satisfied. To create a new validation, click Create and follow the on-screen instructions.

• Installation Scripts. Enables a you to define multiple installation scripts that install supporting objects for the application. To create a new script, click Create and follow the on-screen instructions. To edit an existing script, click the Edit icon.

Message

Use the links under Message to define message to display when the user installs or deinstalls the application. Supported HTML tags include <b>, <i>, <u>, <p>, <br>, <hr>, <ul>, <ol>, <li>, and <pre>. Available message types include:

• Welcome

• License

• Application Substitutions

• Build Options

• Validations

• Confirmation

• Post Installation

• Upgrade

• Deinstallation

Note that when these messages display, only a limited set of HTML tags are recognized in order to prevent a cross site-scripting (XSS) attack. See "Understanding Cross-Site Scripting Protection".

Upgrade

Click Upgrade scripts to define scripts to upgrade database objects, images, and seed data when upgrading an existing application. See "Upgrading a Packaged Application".

Deinstallation

Click Deinstallation script to define a script to drop database objects and static files created by the installation scripts. To edit an existing script, click the Edit icon.

Adding Installation Scripts for an Image, Cascading Style Sheet, or Static File

You can create installation scripts for images, cascading style sheets, and static files you have previously uploaded for your application or workspace on the Installation Scripts page. Oracle Application Express uses the name of the file you select as the name for each new script. It also adds corresponding API calls to the end of the deinstallation script (or creates one if one does not already exist), which removes the selected files when the application's supporting objects are deinstalled.

To create installation scripts for an image, cascading style sheet, or static file:

1. Navigate to the Supporting Objects page:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select the application.

      The Application home page appears.

   3. Click Supporting Objects.

      The Supporting Objects page appears.

2. Under Installation, click Installation scripts.

   The Installation Scripts page appears.

3. Click Create.

4. At the bottom of the page, click Create Script to Install Files.

   A list of available cascading style sheets, images, and static files appears.

5. Select the files to include with your packaged application and click Create Script.

Adding an Access Control List to a Packaged Application

You can control access to an application, individual pages, or page components by creating an access control list.

To add an access control list of a packaged application:

1. Create an access control list. See "Controlling Access to Applications, Pages, and Page Components".

2. Navigate to the Supporting Objects page:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select the application.

      The Application home page appears.

   3. Click Supporting Objects.

      The Supporting Objects page appears.

3. Under Installation, click Installation scripts.

   The Installation Scripts page appears.

4. Click Create.

5. At the bottom of the page, click Create Scripts for Access Control Tables.

   If Access Control tables are defined, the Create Script page displays the tables to be included.

6. Click Create Script.

Installing Supporting Objects

After you edit your supporting objects and create the appropriate scripts, you can run your installation scripts by clicking Install Supporting Objects on the Tasks list.

End users can also use this feature if they elect to not install the packaged application (or supporting objects) after they import and install the application definition.

To install supporting objects:

1. On the Workspace home page, click the Application Builder icon.

2. Select the application.

3. Click Supporting Objects.

   The Supporting Objects page appears.

4. Click the Install Supporting Objects on the Tasks list.

5. To view details about the installation script before running it, click Preview Installation Script.

   The Preview Scripts page appears listing summary information, prerequisites, and the actual scripts to be run.

6. To exit the Preview Scripts page and continue, click Close.

7. From Install Supporting Objects, click Yes and click Next.

8. Follow the on-screen instructions.

Deleting Supporting Objects Scripts, Messages, and Installation Options

You can delete the metadata that defines supporting object scripts, messages, and installation options associated with a packaged application by clicking Remove Supporting Object Installation on the Tasks list on the Supporting Objects page.

To delete the metadata that defines supporting object scripts, messages, and installation options:

1. On the Workspace home page, click the Application Builder icon.

2. Select an application.

3. Click Supporting Objects.

   The Supporting Objects page appears.

4. On the Tasks list on the right side of the page, click Remove Supporting Object Installation.

5. Follow the on-screen instructions.

Upgrading a Packaged Application

You can define scripts to upgrade a previously published application on the Upgrade page.

This section contains the following topics:

• Defining an Upgrade Script

• Upgrading a Packaged Application

Deinstalling Supporting Objects

Once you create or install a packaged application, you can deinstall it by either:

• Clicking the Deinstall Supporting Objects on the Supporting Objects page

• Clicking Delete this Application on the Application home page

When you deinstall an application, you have the option of removing the current application definition and running the deinstallation script defined in the Supporting Objects.

To deinstall a packaged application:

1. On the Workspace home page, click the Application Builder icon.

2. Select the application.

3. Click Supporting Objects.

   The Supporting Objects page appears.

4. Click Deinstall Supporting Objects.

5. Select a deinstallation option:

   • Remove Application Definition removes the current application definition.

   • Deinstall Database Objects runs the deinstallation script defined in the deployment attributes for this application.

6. Follow the on-screen instructions.

Viewing an Install Summary

You can view a log of recent installation and deinstallation by clicking View Install Summary on the Tasks list on the Supporting Objects page. Note that this log only displays results from the most recent installation or deinstallation that occurred during the current Application Express session.

To view the Install Summary:

1. On the Workspace home page, click the Application Builder icon.

2. Select the application.

3. Click Supporting Objects.

   The Supporting Objects page appears.

4. On the Tasks list on the right side of the page, click View Install Summary.

   A Summary page appears.