Deploying an Application

This section describes how to package an application built within Application Builder.

Topics:

This section contains the following topics:

About the Oracle Application Express Application Development Life Cycle

When developing applications using Application Builder, you need to find a balance between two dramatically different development methodologies:

Iterative, rapid application development
Planned, linear style development

The first approach offers so much flexibility that you run the risk of never completing your project. In contrast, the second approach can yield applications that do not meet the needs of end users even if they meet the stated requirements on paper.

System Development Life Cycle Methodologies to Consider

The system development life cycle (SDLC) is the overall process of developing software using a series of defined steps. There are a number of SDLC models that work well for developing applications in Oracle Application Express.
The SDLC waterfall is probably the best known model. In this methodology, the development process is broken down into the following stages:

Project Planning
Requirements Definition
Design
Development
Integration and Testing
Installation and Acceptance
Maintenance

This methodology is referred to as a waterfall because the output from one stage is the input for the next stage. One of the primary problems with this approach is that it is assumed that all requirements can be established in advance. Unfortunately, requirements often change and evolve during the development process.
The Oracle Application Express development environment enables developers to take a more iterative approach to development. Unlike many other development environments, creating prototypes is easy. With Oracle Application Express, developers can:

Use built-in wizards to quickly design an application user interface
Make protoypes available to users and gather feedback
Implement changes in real time, creating new prototypes instantly

Other methodologies that work well with Oracle Application Express include:

Spiral - This approach is actually a series of short waterfall cycles. Each waterfall cycle yields new requirements and enables the development team to create a robust series of prototypes.
Rapid application development (RAD) life cycle - This approach has a heavy emphasis on creating a prototype that closely resembles the final product. The prototype is an essential part of the requirements phase. One disadvantage of this model is that the emphasis on creating the prototype can cause scope creep; developers can lose sight of their initial goals in the attempt to create the perfect application.

Understanding the Packaging Process

To move an application from one Oracle Application Express instance to another, you need to move both the metadata and supporting objects used by the application as follows:

Move the application definition and all associated files. See "How to Move an Application to Another Development Instance".
Move the supporting objects. Review the Database Dependencies report to determine what objects to move. See "About the Database Object Dependencies Report" and "How to Create a Packaged Application".

This section contains the following topics:

Deployment Options to Consider

When you develop an application in Application Builder, you create the application within a specific workspace. Each workspace has a unique ID and name. A common scenario is to create the application in a development instance and then deploy it to a production instance.
During the deployment process, you need to decide whether you want to use the existing application ID, the existing workspace, the existing database, the existing Oracle HTTP Server, or create new ones. Deployment options to consider include:

Create Application Express End Users. The simplest way to deploy an application is to create Application Express end users and then send the URL and login information to users. This approach works well for applications with a small and tolerant user population. See "About Publishing the Application URL" and "Managing Application Express Users".
Use the same workspace and same schema. Export and then import the application and install it using a different application ID. This approach works well when there are few changes to the underlying objects, but frequent changes to the application functionality.
Use a different workspace and same schema. Export and then import the application into a different workspace. This is an effective way to prevent a production application from being modified by developers.
Use a different workspace and different schema. Export and then import the application into a different workspace and install it so that it uses a different schema. This new schema will need to have the database objects required by your application. See "About the Database Object Dependencies Report".
Use a different database with all its variations. Export and then import the application into a different Oracle Application Express instance and install it using a different schema and database.

Deciding Whether to Copy a Workspace

Deciding whether or not to copy an existing workspace is a matter of preference. Keep in mind that the production version must have access to all the appropriate objects. For example, you might want to copy a workspace in the following situations:

When the application subscribes to other Application Express objects within the workspace.
When the application relies on Oracle Application Express authentication. Copying the workspace automatically migrates all the required user data.

Deciding Whether to Copy a Database

When deciding whether or not to copy the database, remember that the schema against which the application runs must have access to the same objects as the development instance. The actual name of the schema is unimportant. You can change it during the import process.

About the Application ID

It is not necessary to have matching application IDs for a development version and production version of an application. In fact, as a best practice never hard code the application ID into your application. Instead, use the application alias (defined on the Edit Definition page), or use a built-in substitution string (such as APP_ID and APP_ALIAS). Using a substitution string is the better approach because it enables you to change the application ID without affecting any application functionality.

See Also:

"Name" for information about defining an application alias and "About Built-in Substitution Strings" for information about using APP_ID and APP_ALIAS

Deciding to Install a New HTTP Server

In order to run, Oracle Application Express must have access to either the embedded PL/SQL gateway or Oracle HTTP Server and mod_plsql. Installing a new HTTP server is another way to separate a development version and production version of an application. To learn more about HTTP server configuration options, see "Choosing a HTTP Server" in the appropriate installation guide for your operating environment. See "Related Documents".

How to Move an Application to Another Development Instance

Whether you want to move an application to another workspace or just make a copy of it, deploying involves the following steps:

Move the supporting database objects (if appropriate). Review the Database Dependencies report to determine what objects to move. See "About the Database Object Dependencies Report".
Package an application definition with its supporting objects to create a packaged application. See "How to Create a Packaged Application".
Import the exported files into the target Oracle Application Express instance. See "Importing Export Files".
Note that if the target instance is a different schema, you also need to export and import any required database objects.
Install the exported files from Export Repository. See "Installing Export Files".

You can import an application into your workspace regardless of the workspace in which it was developed. See "Deployment Options to Consider".

Tip:

You can also move the application definition and all supporting objects manually. See "Exporting an Application and Related Files".

About Managing Database Objects

Before you export an application and the appropriate related files, you need to determine if you also need to migrate the database objects referenced by the application. If you are unsure of which database objects to move, review the Database Object Dependencies report.

If the target schema is different from the schema used in the development environment, you need to migrate the database objects referenced by the application. In many cases, this process can be as simple as using Oracle database export and import utilities to copy the application schema from the development environment to target instance. The following are two common scenarios where this approach does not work:

When the object development schema refers to tablespaces to which the target instance schema does not have access
When the development instance schema has sample data that you do not want to migrate to the target instance schema

If a database administrator or an Oracle Application Express administrator is the person responsible for exporting Oracle Application Express applications, be sure to clearly communicate if he or she:

Should include all data when exporting your application
Should not include data from specific tables you identify

See Also:

"Loading Data" and "Unloading Data"

How to Create a Packaged Application

You can greatly simplify the steps needed to deploy an application by creating a packaged application on the Supporting Objects page.
Topics in this section include:

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 or not 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 need to create installation scripts that define your application's supporting objects (including database objects, images, and seed data) as well as any preinstallation validations. You define these objects as well as the installation and deinstallation scripts and the messages that display when the user installs or deinstalls on the Supporting Objects page.
Topics in this section include:

Accessing the Supporting Objects Page

You create a packaged application on the Supporting Objects page.
To access the Supporting Objects Page application:

On the Workspace home page, click the Application Builder icon.
Select the application.
The Application home page appears.
Click the Supporting Objects icon.
The Supporting Objects page appears.

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 sup_object_sum.gif follows

Description of sup_object_sum.gif follows

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 prior to 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 , , , ,  , <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 "About 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:

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.
Under Installation, click Installation scripts.
The Installation Scripts page appears.
Click Create.
At the bottom of the page, click Create Script to Install Files.
A list of available cascading style sheets, images, and static files appears.
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:

Create an access control list. See "Controlling Access to Applications, Pages, and Page Components".
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.
Under Installation, click Installation scripts.
The Installation Scripts page appears.
Click Create.
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.
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:

On the Workspace home page, click the Application Builder icon.
Select the application.
Click Supporting Objects.
The Supporting Objects page appears.
Click the Install Supporting Objects on the Tasks list.
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.
To exit the Preview Scripts page and continue, click Close.
From Install Supporting Objects, click Yes and click Next.
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:

On the Workspace home page, click the Application Builder icon.
Select an application.
Click Supporting Objects.
The Supporting Objects page appears.
On the Tasks list on the right side of the page, click Remove Supporting Object Installation.
Follow the on-screen instructions.

Upgrading a Packaged Application

You can define scripts to upgrade a previously published application on the Upgrade page.
Topics in this section include:

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:

On the Workspace home page, click the Application Builder icon.
Select an application.
Click Supporting Objects.
The Supporting Objects page appears.
Under Upgrade, click Upgrade Scripts.
To create a new 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.
Use the Detect Existing Supporting Objects section to determine if the appropriate objects are installed or need to be upgraded.
In Query to Detect Existing Supporting Objects, enter a query in the field provided that returns at least one row if the supporting objects exist.
This query determines whether or not the user who installs the packaged application is prompted to run the installation scripts or the upgrade scripts.
Follow the on-screen instructions.

Upgrading a 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 packaged application.
To upgrade a packaged application:

Import a new version of application to be upgraded (if applicable). See "Importing an Application or Page".
On the Workspace home page, click the Application Builder icon.
Select the application.
Click Supporting Objects.
The Supporting Objects page appears.
From the Tasks list, click Upgrade Supporting Objects.
Follow the on-screen instructions.

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.

See Also:

"Creating a Packaged Application".

To deinstall a packaged application:

On the Workspace home page, click the Application Builder icon.
Select the application.
Click Supporting Objects.
The Supporting Objects page appears.
Click Deinstall Supporting Objects.
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.
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:

On the Workspace home page, click the Application Builder icon.
Select the application.
Click Supporting Objects.
The Supporting Objects page appears.
On the Tasks list on the right side of the page, click View Install Summary.
A Summary page appears.

Exporting an Application and Related Files

You export and import application definitions and all associated files using the Workspace Users, Application, CSS, Images, Files, Themes, and User Interface Defaults tabs located at the top of the Export page. Note that it is not necessary to export a workspace unless you wish to migrate workspace users or replicate shared component subscriptions in the target instance.
Once you export an application and any related files, you need to import them into the target Oracle Application Express instance and then install them. As a general rule, always import the application first and then the related files. See "How to Move an Application to Another Development Instance".

Tip:

You can simplify the steps needed to deploy an application by creating a packaged application. See "How to Create a Packaged Application".

Topics in this section include:

Exporting an Application

When you export an application, Oracle Application Express generates a text file containing PL/SQL API calls.

See Also:

"Exporting Application Components"

To export an application:

Navigate to the Export page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Export and then click Next.
From Application, select the application to be exported.
From File Format, select how rows in the export file will be formatted:
- Choose UNIX to have the resulting file contain rows delimited by line feeds.
- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
From Build Status Override, select one of the following:
- Run Application Only - Developers can only run an application
- Run and Build Application - Developers can both run and edit an application
Selecting Run Application Only is an effective way to protect an application from modifications from other developers.

Tip:
If you select Run Application Only, you cannot set the argument p_trace to Yes. See "Using Build Options to Control Configuration". Also, the only way to change this setting after you import the application, is to log in to Oracle Application Express Administration Services. See "Changing Application Build Status SetDuring Deployment".
From Supporting Object Definitions, specify whether or not to include packaged installation scripts and configuration options. See "How to Create a Packaged Application".
From Export Comments, specify whether or not to export comments for this application. See "Adding Developer Comments".
Use the As of field to export your application as it was previously defined. Specify the number of minutes in the field provided.
This utility uses the DBMS_FLASHBACK package. Because the timestamp to System Change Number (SCN) mapping is refreshed approximately every five minutes, you may have to wait that amount of time to locate the version for which you are looking. The time undo information is retained and influenced by the startup parameter UNDO_RETENTION (the default is three hours). However, this only influences the size of the undo tablespace. While two databases can have the same UNDO_RETENTION parameter, you are able to go back further in time on a database with fewer transactions because it is not filling the undo tablespace, forcing older data to be archived.
Click Export Application.

In addition to exporting the actual application file, you may also need to export other related files such as cascading style sheets, images, and script files.

See Also:

"Enabling SQL Tracing and Using TKPROF"

Exporting Workspace Users

You can make an application available to other users by creating workspace users. When you export workspace users, Oracle Application Express creates an ASCII text SQL script of users and any defined user groups.
To export workspace users:

Navigate to the Export page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Export and then click Next.
On the Export page, click the Workspace Users tab.
From File Format, select how rows in the export file will be formatted:
- Choose UNIX to have the resulting file contain rows delimited by line feeds.
- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
Click Export Workspace Users.

See Also:

"Managing Application Express Users"

Exporting Application Components

You can export shared components or components of a page on the Component Export page. You can use this wizard to:

Export shared components or page components to another application or workspace
Back up a component before editing it
Create an export to function as a patch to another Oracle Application Express 2.2 instance

To export shared components or page components:

Navigate to the Component Export page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. From the Tasks list, click Component Export.
  The Component Export page appears.
Click the following tabs and select the components to be exported:
- Components displays shared application components and entire pages. Use the navigation bar at the top of the page to search for components. See "Working with Shared Components" and "Exporting Build Options or Build Option Status".
- Components by Page lists components of the selected page. Navigate to a specific page by making a selection from the Page. Click Check All to select all components.
- Application Attributes displays application attributes. Press CTRL or SHIFT to select multiple attributes. See "About the Edit Definition Page".
- Build Option Status displays available build options. Use this page to turn build options on and off. See "Exporting Build Options or Build Option Status".
Click Add to Export.
Click Next.
On Components to Export:
1. From File Format, select how rows in the export file will be formatted:
  - Choose UNIX to have the resulting file contain rows delimited by line feeds.
  - Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
2. Use the As of field to export a page as it was previously defined. Specify the number of minutes in the field provided.
  This utility uses the DBMS_FLASHBACK package. Because the timestamp to System Change Number (SCN) mapping is refreshed approximately every five minutes, you may have to wait that amount of time to locate the version for which you are looking. The time undo information is retained and influenced by the startup parameter UNDO_RETENTION (the default is three hours). However, this only influences the size of the undo tablespace. While two databases may have the same UNDO_RETENTION parameter, you are able to go back further in time on a database with fewer transactions because it is not filling the undo tablespace, forcing older data to be archived.
3. Click Export Components.

Exporting a Page in an Application

You can also export a specific page within an application by clicking the Export page icon on the Page Definition. When exporting a page, remember that exported pages can only be imported sucessfully if they have the same application ID and workspace ID.

To export a page in an application:

Navigate to the appropriate Page Definition. See "Accessing a Page Definition".
On the Page Definition, you can export a page in two ways:
- Click the Export Page icon, the down arrow in the upper right corner. See "Export Page Icon".
- From the View list, select Export and click Go.
The Export Page Wizard appears.
From Page, select the page to be exported.
From File Format, select how rows in the export file will be formatted:
- Choose UNIX to have the resulting file contain rows delimited by line feeds.
- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
Use the As of field to export a page as it was previously defined. Specify the number of minutes in the field provided.
This utility uses the DBMS_FLASHBACK package. Because the timestamp to System Change Number (SCN) mapping is refreshed approximately every five minutes, you may have to wait that amount of time to locate the version for which you are looking. The time undo information is retained and influenced by the startup parameter UNDO_RETENTION (the default is three hours). However, this only influences the size of the undo tablespace. While two databases may have the same UNDO_RETENTION parameter, you are able to go back further in time on a database with fewer transactions because it is not filling the undo tablespace, forcing older data to be archived.
Click Export Page.

Exporting Cascading Style Sheets

Use the Export Cascading Style Sheets utility to export uploaded cascading style sheets. Note that you can use this utility to export only uploaded cascading style sheets.
To export related cascading style sheets:

Navigate to the Export page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Export and then click Next.
Click the CSS tab at the top of the page.
On the Export Cascading Style Sheets page, select the following:
1. Style Sheets - Select the cascading style sheets to export.
2. File Format - Select how rows in the export file will be formatted:
  - Choose UNIX to have the resulting file contain rows delimited by line feeds.
  - Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
3. Click Export Style Sheets.

Exporting Images

Use the Export Images utility to export uploaded images. When you export images using this utility, the images are converted to a text document. Note that you can use this utility to export only uploaded images.
To export upload images:

Navigate to the Export page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Export and then click Next.
Click the Images tab at the top of the page.
On the Export Images page, select the following:
1. Export Images in Application - Select an application from which to export images.
  Be aware that selecting Workspace Images only exports those images in your repository that are not associated with a specific application. If all of your images are associated with specific applications, then the workspace image export file will be empty.
2. File Format - Select how rows in the export file will be formatted:
  - Choose UNIX to have the resulting file contain rows delimited by line feeds.
  - Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
Click Export Images.

Exporting Static Files

Use the Export Static Files utility to export static files you have imported. Note that you can use this utility to export only uploaded static files.
To export related static files:

Navigate to the Export page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Export and then click Next.
Click the Files tab at the top of the page.
On Export Static Files, select the following:
1. Static Files - Select the files to be exported.
2. File Format - Select how rows in the export file will be formatted:
  - Choose UNIX to have the resulting file contain rows delimited by line feeds.
  - Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
3. Click Export File(s).

About Importing into Another Oracle Application Express Instance

Note that you cannot use the Web interface described in this section to import exported static files into another Oracle Application Express instance. To import exported static files into another Oracle Application Express instance, use SQL*Plus while connected to the database. Note that you must export from and to a workspace having the same name and workspace ID.

Exporting Script Files

You can transfer selected scripts from your current Script Repository to a Script Repository in a different Workspace by using the Export and Import tasks.
To export script files:

On the Workspace home page, click the SQL Workshop icon.
Click SQL Scripts.
On the Tasks list, click Export.
Select the appropriate script files and click Add to Export.
Review the file name and click Export All.
Select the Remove check box to remove the script.

See Also:

"Using SQL Scripts"

Exporting Themes

Use the Export Theme utility to export themes from one Oracle Application Express development instance to a file.

See Also:

"Importing Themes"and"Managing Themes"

Exporting a Theme from the Export Page

To export an application theme from the Export page:

Navigate to the Export page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Export and click Next.
Click the Themes tab at the top of the page.
On the Export Application Theme page, select the following:
1. Export Theme - Select the theme to be exported.
2. File Format - Select how rows in the export file will be formatted:
  - Choose UNIX to have the resulting file contain rows delimited by line feeds.
  - Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
3. Click Export Theme.

Exporting a Theme from the Themes Page

To export an application theme from the Themes page:

On the Workspace home page, click the Application Builder icon.
Select an application.
On the Application home page, click Shared Components.
Under User Interface, select Themes.
The Themes page appears.
On the Tasks list, click Export Theme.
The Export page appears.
On the Export Theme page, select the following:
1. Export Theme - Select the theme to be exported.
2. File Format - Select how rows in the export file will be formatted:
  - Choose UNIX to have the resulting file contain rows delimited by line feeds.
  - Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
3. Click Export Theme.

Exporting User Interface Defaults

Exporting User Interface Defaults is useful when you plan to develop on a target system.
When you export User Interface Defaults, all User Interface Defaults for the selected schema are exported to a single SQL Command script. When prompted, save this file to your hard drive. The file contains an API call to create table hints by making calls to the application PL/SQL API. You can use this file to import User Interface Defaults to another database and Oracle Application Express instance.

Exporting User Interface Defaults from the Export Page

To export User Interface Defaults from the Export page:

Navigate to the Export page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Export and click Next.
Click the User Interface Defaults tab at the top of the page.
On the Export User Interface Defaults page, select the following:
1. Schema - Select the schema that owns the table associated with the User Interface Defaults.
2. File Format - Select how rows in the export file will be formatted:
  - Choose UNIX to have the resulting file contain rows delimited by line feeds.
  - Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
3. Click Export User Interface Defaults.

Exporting User Interface Defaults from the User Interface Defaults Page

To export User Interface Defaults from the User Interface Defaults page:

On the Workspace home page, click the Application Builder icon.
Select an application.
On the Application Builder home page, click Shared Components.
Under User Interface, select User Interface Defaults.
The User Interface Defaults page appears.
From the Tasks list, click Export.
On the Export User Interface Defaults page, select the following:
1. Schema - Select the schema that owns the table associated with the User Interface Defaults.
2. File Format - Select how rows in the export file will be formatted:
  - Choose UNIX to have the resulting file contain rows delimited by line feeds.
  - Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
3. Click Export User Interface Defaults.

Importing Export Files

Once you export an application and any related files, you need to import them into the target Oracle Application Express instance before you can install them. As a general rule, always import the application first and then the related files. See "How to Move an Application to Another Development Instance".

Tip:

You can simplify the steps needed to deploy an application by creating a packaged application. See "How to Create a Packaged Application".

Topics in this section include:

Importing an Application or Page

To import an Application or Page Export into a target Oracle Application Express instance:

Navigate to the Import page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Import and then click Next.
For Specify File, specify the following:
1. Import file - Click Browse and navigate to the file.
2. File Type - Select Application, Page, or Component Export.
3. Verify that File Character Set is correct.
4. Click Next.
Once you import a file, you have the option to install it.
To install an imported file, click Next.
The Install Application wizard appears.
In the Install Application wizard, specify the following:
1. Parse As Schema - Select a schema.
  This is the schema against which all of the application's SQL and PL/SQL will be parsed.
2. Build Status - Select one of the following:
  - Run Application Only - Users can only run an application.
  - Run and Build Application - Users can run an application and developers can both run and edit an application.
  Selecting Run Application Only is an effective way to protect an application from modifications from other developers.
  
  Tip:
  If you select Run Application Only, the only way to change this setting after you import the application is to log in to Oracle Application Express Administration Services. See "Changing Application Build Status SetDuring Deployment".
3. Install As Application - Select one of the following:
  - Auto Assign New Application ID
  - Reuse Application ID From Export File
  - Change Application ID
  Use these options to avoid application ID conflicts. These options come in handy when you need to have two versions of the same application in the same instance. For example, you might be migrating an application to a production instance and still need to maintain the development version.
4. Click Install.
  If you are installing a packaged application (that is, one for which you have defined Supporting Objects), the installer prompts you to install the packaged installation scripts. Follow the on-screen instructions.

See Also:

"How to Create a Packaged Application"

Importing Cascading Style Sheets

After you import an application into the target Oracle Application Express instance, you need to import all related files.
To import a CSS Export file:

Navigate to the Import page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Import and then click Next.
For Specify File, select the following:
1. Import file - Click Browse and navigate to the file.
2. File Type - Select CSS Export.
3. File Character Set - Verify that File Character Set is correct.
4. Click Next.
Once you import a file, you have the option to install it.
To install an imported file, click Next.
Click Install CSS.

Importing Static Files

After you import an application into the target Oracle Application Express instance, you need to import all related files.
To import a static file:

Navigate to the Import page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Import and click Next.
For Specify File, select the following:
1. Import file - Click Browse and navigate to the file.
2. File Type - Select File Export.
3. File Character Set - Verify that File Character Set is correct.
4. Click Next.
Once you import a file, you have the option to install it.
To install an imported file, click Next.
Click Install Static Files.

See Also:

"Exporting Static Files"

Importing Images

After you import an application into the target Oracle Application Express instance, you need to import all related files.
To import an Image Export file:

Navigate to the Import page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Import and click Next.
On Import Definition, select the following:
1. Import file - Click Browse and navigate to the file.
2. File Type - Select Image Export.
3. File Character Set - Verify that File Character Set is correct.
4. Click Next.
Once you import a file, you have the option to install it.
To install an imported file, click Next.
Click Install Image.

Importing Themes

After you import an application into the target Oracle Application Express instance, you need to import all related files.
To import a Theme Export file:

Navigate to the Import page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Import and click Next.
On Import Definition, select the following:
1. Import file - Click Browse and navigate to the file.
2. File Type - Select Theme Export.
3. File Character Set - Verify that File Character Set is correct.
4. Click Next.
Once you import a file, you have the option to install it.
To install an imported file, click Next.
Click Install Theme.

Importing User Interface Defaults

User Interface Defaults enables you to assign default user interface properties to a table, column, or view within a specified schema.
After you import an application into the target Oracle Application Express instance, you need to import all related files.
To import User Interface Defaults:

Navigate to the Import page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application home page, click Export/Import.
4. On the Export/Import page, click Import and then click Next.
Select an application.
On Import Definition, select the following:
1. Import file - Click Browse and navigate to the file.
2. File Type - Select User Interface Defaults.
3. File Character Set - Verify that File Character Set is correct.
4. Click Next.
Once you import a file, you have the option to install it.
To install an imported file, click Next.
Click Install User Interface Defaults.

Installing Export Files

After you import an application and any related files into the target Oracle Application Express instance, the files are stored in the Export Repository. Next, you need to install them.
You can install export files in the following ways:

After you import the export file, click the Install button and follow the on-screen instructions.
Import the export files into Application Builder and then install the files from the Export Repository.
Install the export files from SQL*Plus.

Tip:

You can simplify the steps needed to deploy an application by creating a packaged application. See "How to Create a Packaged Application".

Topics in this section include:

Accessing the Export Repository

When you import an application and any related files into a target Oracle Application Express instance, the files are stored in the Export Repository.
To access the Export Repository:

On the Workspace home page, click the Application Builder icon.
Select an application.
On the Tasks list, click Manage Export Repository.
The Export Repository appears.

Tip:

You can also access the Export Repository by clicking Export Repository on the Tasks list on either the Application home or Application Builder home pages.

Installing an Application Export from the Export Repository

After you import an application export into an Oracle Application Express instance, you must install it before it can become active or available in Application Builder.
To install an application export from the Export Repository:

Navigate to the Export Repository:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Tasks list, click Manage Export Repository.
  The Export Repository appears.
Select an application export and click Install in the Action column.
Specify the following:
1. Parse As Schema - Select a schema.
  This is the schema against which all of the application's SQL and PL/SQL will be parsed.
2. Build Status - Select one of the following:
  - Run Application Only
  - Run and Build Application
  Select Run Application Only to run the application in the target instance and make it inaccessible to developers.
  
  Tip:
  If you select Run Application Only, the only way to change this setting after you import the application is to log in to Oracle Application Express Administration Services. See "Changing Application Build Status SetDuring Deployment".
3. Install As Application - Select one of the following:
  - Reuse Application ID from Export File
  - Auto Assign New Application ID
  - Change Application ID
  Use these options to avoid application ID conflicts. Use these options when you need to have two versions of the same application in the same instance. For example, you might be migrating an application to a production instance and still need to maintain the development version.
4. Click Install.

About Installing a Packaged Application

If you are installing a packaged application, the installer prompts you to install the packaged installation scripts. Follow the on-screen instructions.

See Also:

"How to Create a Packaged Application"

Installing Other Files from the Export Repository

After you import files into an Oracle Application Express instance, you must install them before they can become active or available in Application Builder.
To install files stored in the Export Repository:

Navigate to the Export Repository.
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Tasks list, click Manage Export Repository.
  The Export Repository appears.
Select the file to be installed and click Install in the Action column.
Follow the on-screen instructions and click the Install button.

Deleting Files from the Export Repository

You can delete a file from the Export Repository.
To delete a file from the Export Repository:

Navigate to the Export Repository.
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Tasks list, click Manage Export Repository.
  The Export Repository appears.
Select the file to be deleted and click Delete Checked.

Installing Export Files from SQL*Plus

You can also install export files from SQL*Plus. Note there are two restrictions:

The export file must originate from the same user database account as the one into which you are installing.
If the export file is an application, the application ID will be overwritten. Therefore, the target workspace must own the ID of the application being installed.
If the export file contains Supporting Object scripts, the scripts are not run when the application is installed. You can either log in to the Application Builder to install Supporting Objects, or copy the installation scripts to a standalone SQL*Plus script and run them from there.

Topics in this section include:

Verifying If Source and Target Workspace IDs Are Identical

You can verify that the source and target workspaces are identical by running a query in SQL Command Processor.
To verify that the source and target workspaces are identical:

Log in to the source workspace.
Click the SQL Workshop icon on the Workspace home page.
Click SQL Commands.
Enter the following in the SQL editor pane and click Run:
```
SELECT &WORKSPACE_ID. FROM DUAL
```
Note the workspace ID.
Log in to the target workspace.
Repeat steps 2 through 5 to verify the workspace IDs match.

Using SQL*Plus to Install Export Files

To install Oracle Application Express export files from SQL*Plus:

Log in to SQL*Plus.
Run the export file.
For example, if your export file is names f144.sql by default, you would type @f144 at the command prompt.

About Publishing the Application URL

Once you have deployed your application, loaded data, and created users, you can publish your production URL.
You can determine the URL to your application by positioning the mouse over the Run icon on the Application home page. The URL displays in the status bar at the bottom of the page.
The Run icon gets its value from the Home link attribute on the Edit Security Attributes page. This link is only referenced by this icon and by applications that do not use the Oracle Application Express Login API. Consider the following example:

http://apex.oracle.com/pls/apex/f?p=11563:1:3397731373043366363

Where:

apex.oracle.com is the URL of the server.
pls is the indicator to use the mod_plsql cartridge.
apex is the database access descriptor (DAD) name. The DAD describes how Oracle HTTP Server connects to the database server so that it can fulfill an HTTP request. The default value is apex.
f?p= is a prefix used by Oracle Application Express.
11563 is the application being called.
1 is the page within the application to be displayed.
3397731373043366363 is the session number.

To run this example application, you would use the URL:

http://apex.oracle.com/pls/apex/f?p=11563:1

When users log in, they receive unique session numbers.

Using Build Options to Control Configuration

Build options enable you to conditionally display specific functionality within an application.
Build options have two possible values: INCLUDE and EXCLUDE. If you specify an attribute as being included, then the Application Express engine considers it part of the application definition at run time. Conversely, if you specify an attribute as being excluded, then the Application Express engine treats it as if it did not exist.
Topics in this section include:

Creating Build Options

You create a build option for an application on the Build Options page.
To create a build option:

On the Workspace home page, click the Application Builder icon.
Select an application.
On the Application Builder home page, click Shared Components.
Under Application, click Build Options.
To create a new build option, click Create.
Follow the on-screen instructions.

About the Build Options Page

Once you create a build option, it appears on the Build Options page. You control how the Build Options page displays by making a selection from the View list. Available options include:

Icons (the default) displays each build option as a large icon. To edit a build option, click the appropriate icon.
Details displays each build option as a line in a report. Each line includes the application ID, build option name, status, and a link to the Build Option Utilization report. To edit a build option, click the appropriate name.

Managing Build Options

Build options have two possible values: INCLUDE and EXCLUDE. If you specify an attribute as being included, then the Application Express engine considers it part of the application definition at run time. Conversely, if you specify an attribute as being excluded, then the Application Express engine treats it as if it did not exist.
To include or exclude a build option:

On the Workspace home page, click the Application Builder icon.
Select an application.
On the Application Builder home page, click Shared Components.
Under Application, click Build Options.
Select the appropriate build option.
The Create/Edit Build Option page appears.
For Status, select either INCLUDE or EXCLUDE.

Selecting a Build Option

Once you create a build option, you can select it for a page, a component (report, chart, or form), a specific page control (button, item, list of value), and another shared component (breadcrumb, list, or tab). You apply build options to a page, component, page control, or shared component by navigating to the appropriate attributes page. Most attributes pages contain a Configuration section where you can select defined build options.

See Also:

"Editing Page Attributes"

Exporting Build Options or Build Option Status

You can export build options or build option status on the Component Export page. Exporting build option status is an effective way to toggle build options on or off within another environment. For example, you can use this feature to deploy a production application with a hidden feature.
To accomplish this, you associate the components of the hidden feature with a build option having the status of EXCLUDE. After deployment, you can enable the hidden feature by changing the status of the build option to INCLUDE and then exporting the Build Option Status.
Once you apply the Build Options Status to the production instance, the new feature appears.

To export build options or build option status:

Navigate to the Component Export page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. From the Tasks list, click Component Export.
  The Component Export page appears.
Select the build options to be exported:
1. Click the Components tab and select the build options to be exported.
2. Click Add to Export.
Select Build Option Status to be exported:
1. Click the Build Options Status tab and select the build options to be exported.
2. Click Add to Export.
Click Next.
On Components to Export:
1. From File Format, select how rows in the export file will be formatted:
  - Choose UNIX to have the resulting file contain rows delimited by line feeds.
  - Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.
2. Use the As of field to export a page as it was previously defined. Specify the number of minutes in the field provided.
  This utility uses the DBMS_FLASHBACK package. Because the timestamp to System Change Number (SCN) mapping is refreshed approximately every five minutes, you may have to wait that amount of time to locate the version for which you are looking. The time undo information is retained and influenced by the startup parameter UNDO_RETENTION (the default is three hours). However, this only influences the size of the undo tablespace. While two databases may have the same UNDO_RETENTION parameter, you are able to go back further in time on a database with fewer transactions because it is not filling the undo tablespace, forcing older data to be archived.
3. Click Export Components.

Viewing the Build Option Utilization Report

Once you create a build option, a Utilization tab appears on the Build Options page. This report details build option utilization in the current application.

Note:

The Utilization tab only appears on the Build Options page after you create a build option.

To view the Build Option Utilization report:

Navigate to the Build Options page:
1. Navigate to the Workspace home page.
2. Click the Application Builder icon.
3. Select an application.
4. On the Application Builder home page, click Shared Components.
5. Under Application, click Build Options.
  The Build Options page appears.
On the Build Options page, click Utilization.
The Build Option Utilization report appears.
Select a build option and click Go.

Tuesday, 16 October 2012