23.5 How to Create a Custom Packaged Application

You can greatly simplify the steps needed to deploy an application by creating a custom packaged application on the Supporting Objects page.

Topics:

See Also:

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

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

  • Provides users and developers with an easy way to upgrade a previously released 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.

See Also:

23.5.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:

23.5.2.1 Accessing the Supporting Objects Page

You create a custom packaged application on the Supporting Objects page.

To access the Supporting Objects Page application:

  1. On the Workspace home page, click the App Builder icon.
  2. Select the application.

    The Application home page appears.

  3. Click the Supporting Objects icon.

    The Supporting Objects page appears.

23.5.2.2 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, and Include in Export. To learn more about these options, see field-level Help.

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

Description of GUID-E300DE55-A43E-449B-B9E2-A3A92A8AE1DF-default.png follows
Description of the illustration GUID-E300DE55-A43E-449B-B9E2-A3A92A8AE1DF-default.png

The rest of the page is divided into the following categories: Installation, Upgrade, and Deinstallation.

Topics:

See Also:

"Viewing Field-Level Help"

23.5.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, such as 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.

    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.

    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. To prevent another developer from editing a script, click the Lock icon. If the script is locked, the Lock icon appears as a closed padlock. If the script is unlocked, the Lock icon appears as an open padlock.

  • 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 Also:

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

  • 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 Also:

23.5.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 Also:

"Understanding Cross-Site Scripting Protection"

23.5.3 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.
  2. Navigate to the Supporting Objects page:
    1. On the Workspace home page, click the App 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, expand the Tasks region and 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.

See Also:

"Controlling Access to Applications, Pages, and Page Components"

23.5.4 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 App 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, expand the Tasks region and 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.

23.5.5 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 App 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.

23.5.6 Upgrading a Custom Packaged Application

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

Topics:

23.5.6.1 Defining an Upgrade Script

You can use the Upgrade page to define scripts to upgrade database objects, images, and seed data when upgrading an existing application.

To create an upgrade script:

  1. On the Workspace home page, click the App Builder icon.
  2. Select an application.
  3. Click Supporting Objects.

    The Supporting Objects page appears.

  4. Under Upgrade, click Upgrade Scripts.
  5. Use the Detect Existing Supporting Objects section to determine if the appropriate objects are installed or must be upgraded.
  6. In Query to Detect Existing Supporting Objects, enter a query in the field that returns at least one row if the supporting objects exist.

    This query determines whether the user who installs the custom packaged application is prompted to run the installation scripts or the upgrade scripts.

  7. To create a script, click Create.

    Tip:

    To enable users to upgrade from various earlier versions of this application, you can add conditions to the upgrade scripts by going to the Script Properties page.

  8. To prevent another developer from editing a script, click the Lock icon.

    If the script is locked, the Lock icon appears as a closed padlock. If the script is unlocked, the Lock icon appears as an open padlock.

  9. To edit an existing script, click the Edit icon.
  10. Follow the on-screen instructions.

23.5.6.2 Upgrading a Custom Packaged Application

After you create your upgrade script, you can test it by clicking Upgrade Supporting Objects on Tasks list on the Supporting Object page.

End users can also use this feature to upgrade an existing custom packaged application.

To upgrade a custom packaged application:

  1. Import a new version of application to be upgraded (if applicable).
  2. On the Workspace home page, click the App Builder icon.
  3. Select the application.
  4. Click Supporting Objects.

    The Supporting Objects page appears.

  5. From the Tasks list, click Upgrade Supporting Objects.
  6. Follow the on-screen instructions.

See Also:

"Importing an Application, Page or Component Export"

23.5.7 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 App 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.

See Also:

"Creating a Custom Packaged Application"

23.5.8 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 App 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.