1. App Builder User's Guide
  2. Deploying an Application
  3. How to Create a Custom Application

25.4 How to Create a Custom Application

Simplify the steps needed to deploy an application by creating a custom application using the Supporting Objects utility.

See Also:

Parent topic: Deploying an Application

25.4.1 How Creating a Custom Application Simplifies Deployment

Learn about how creating a custom application simplifies the application deployment process.

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 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, creating a custom application has the following 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 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:

Parent topic: How to Create a Custom Application

25.4.2 Creating a Custom Application

Learn how to create a custom application.

To create a custom 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 manage installation, upgrade, and de-installation scripts and their associated messages on the Supporting Objects page.

Parent topic: How to Create a Custom Application

25.4.2.1 Accessing the Supporting Objects Utility

Create a custom application on the Supporting Objects utility page.

To access the Supporting Objects Page utility:

  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.

Parent topic: Creating a Custom Application

25.4.2.2 Supporting Objects Page

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

Description of sup_object_sum.png follows
Description of the illustration sup_object_sum.png

To specify whether to include supporting objects with an application export, find Include in Export at the top of the page, click either Yes or No. If you select Yes, a new page appears. From the Include Supporting Object Definitions in Export list, make a new selection and click Apply Changes.

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

  • Installation
    Learn about the links under Installation on the Supporting Objects page.
  • Upgrade
    Learn about the links under Upgrade on the Supporting Objects page.
  • Deinstallation
    Learn about the links under Deinstallation on the Supporting Objects page.

See Also:

Viewing Field-Level and Page Designer Help

Parent topic: Creating a Custom Application

25.4.2.2.1 Installation

Learn about the links under Installation on the Supporting Objects page.

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 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 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. Define multiple installation scripts that create the application's supporting database objects. 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.

    Note:

    The Data Package installation script type requires Oracle Database 18c and later.

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

25.4.2.2.2 Upgrade

Learn about the links under Upgrade on the Supporting Objects page.

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.

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

25.4.2.2.3 Deinstallation

Learn about the links under Deinstallation on the Supporting Objects page.

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.

25.4.3 Installing Supporting Objects

Learn how to install 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 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. From the Tasks list click the Install Supporting Objects.
    The Install Supporting Object dialog appears.
  5. To view details about the installation script before running it, click preview the installation details.

    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. Click Install Supporting Objects.
  8. Follow the on-screen instructions.

Parent topic: How to Create a Custom Application

25.4.4 Deleting Supporting Objects Scripts, Messages, and Installation Options

Learn about 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 application by clicking Remove All Supporting Objects 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 All Supporting Objects.
  5. Follow the on-screen instructions.

Parent topic: How to Create a Custom Application

25.4.5 Upgrading a Custom Application

Define scripts to upgrade a previously published application on the Upgrade page.

Parent topic: How to Create a Custom Application

25.4.5.1 Defining an Upgrade Script

Create an upgrade script 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 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.

Parent topic: Upgrading a Custom Application

25.4.5.2 Upgrading a Custom Application

Learn how to upgrade a custom 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 application.

To upgrade a custom 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 or Page Export

Parent topic: Upgrading a Custom Application

25.4.6 Deinstalling Supporting Objects

Learn how to deinstall supporting objects.

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

  • Clicking Deinstall Supporting Objects under Tasks on the Supporting Objects page.
  • Clicking Delete this Application on the Application home page.

To deinstall a custom 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. On Deinstall Supporting Objects:
    1. Select Deinstall Database Objects to run the deinstallation script defined in the deployment attributes for this application.

      Note:

      To preview the deinstallation script, expand the Tasks region and click Preview Deinstallation Script.
    2. Click Deinstall
  6. Follow the on-screen instructions.

See Also:

Creating a Custom Application

Parent topic: How to Create a Custom Application

25.4.7 Viewing an Install Summary

Viewing an Install Summary log.

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 Oracle APEX 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.

Parent topic: How to Create a Custom Application