16.4 How to Create a Custom Packaged Application

16.4.1 How Creating a Custom Packaged Application Simplifies Deployment

From a developer'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 custom 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 many advantages:

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

• Provides 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".

• Provides users and developers with an easy way to upgrade a previously released custom packaged application. See "Upgrading a Custom 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.

16.4.2 Creating a Custom Packaged Application

To create a custom 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.

Topics:

• Accessing the Supporting Objects Page

• About the Supporting Objects Page

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

To specify whether to include supporting objects with an application export, select Yes or No from the Include in Export list and click Apply.

Description of the illustration sup_object_sum.gif

The rest of the page is divided into three categories.

16.4.2.2.1 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 custom 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 custom 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.

• Messages. Enables you to define messages that display when the user installs or deinstalls the application. Supported HTML tags include <b>, <i>, <u>, <p>, <br>, <hr>, <ul>, <ol>, <li>, and <pre>.

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

16.4.2.2.2 Upgrade

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

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

• Upgrade Message. Enables you to define messages that display when the user upgrades the application. Supported HTML tags include <b>, <i>, <u>, <p>, <br>, <hr>, <ul>, <ol>, <li>, and <pre>.

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

16.4.2.2.3 Deinstallation

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

• Deinstallation Script. 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.

• Deinstallation Message. Allows you to define messages that display when the user deinstalls the application. Supported HTML tags include <b>, <i>, <u>, <p>, <br>, <hr>, <ul>, <ol>, <li>, and <pre>.

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

16.4.3 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 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. Follow the on-screen instructions.

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

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

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

16.4.4 Adding an Access Control List to a Custom 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 custom 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.

16.4.5 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 custom 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.

16.4.6 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 custom 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.

16.4.7 Upgrading a Custom Packaged Application

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

Topics:

• Defining an Upgrade Script

• Upgrading a Custom Packaged Application

16.4.8 Deinstalling Supporting Objects

Once you create or install a custom 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 custom 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. From the Tasks list, 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.

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