1. App Builder User's Guide
  2. Creating Applications
  3. Creating a Working Copy to Merge, Refresh, or Compare
  4. About Working Copies

5.9.1 About Working Copies

Learn about Working Copies.

A Working Copy enables developers to create a special copy of an application, make changes in the copy, and then merge those changes back into the main development application (or Main application). Similarly, you can also merge changes from the Main application back into the Working Copy. During the export process, you can view a comparison (or diff) of the Working Copy and the Main application and then select which changes to merge.

A common use case for this feature is when you want to test some changes on a page first and then merge them back into the Main application later.

About the Comparison Process

When you compare a Working Copy to the Main application, a split YAML export is taken of both applications and a checksum is generated on the individual files. The working copy is exported with original IDs to ensure that the IDs are the same between both applications. The checksums are then compared to identify the differences between the two applications.

Note:

The YAML export of both applications is performed in a background job. Therefore, your database must have JOB_QUEUE_PROCESSES enabled (that is, JOB_QUEUE_PROCESSES must have a value greater than zero). If the job queue is disabled you will see no progress in the progress bar. Please be aware that for multi-tennant databases the CDB JOB_QUEUE_PROCESSES setting can override the PDB setting so both should be checked. To learn more about JOB_QUEUE_PROCESSES, see Controlling the Number of Concurrent Jobs in Oracle APEX Installation Guide.

When comparing a Working Copy to the Main application, use the MAIN_APP_ID substitution string to identify the main application ID if the current application is a working copy.

About the Merge Process

The merge process takes a subset of pages and shared components from a Working Copy and imports them back into the Main application. If the page or shared component exists, it is replaced. Therefore, changes in your Main application that are not in your Working Copy will be overwritten by the Working Copy merge.

Unsupported Component Types

Working Copies do not support the automatic merging of the following component types:

  • Translations
  • Themes
  • Theme Templates
  • Supporting Objects
  • Application Properties
  • Workspace-level components (such as App Groups, Credentials, and Remote Servers)

For unsupported component types, Oracle suggests developers merge the working Working Copy, delete it, and then manually apply the additions or changes for the unsupported component types.

Limitations of Working Copies

Limitations of Working Copies include:

  • You cannot create a Working Copy of a Working Copy.

  • Deleted working copy pages or Shared Components must be manually deleted in the Main application.

  • Components listed as Missing may have been removed in the Working Copy or may only exist in the Main application.

  • When a working copy is created all automations are set to disabled. If automations are enabled in the Main application, they will show up in the differences report during a compare or merge.

    If an application contains automations, Oracle recommends deselecting the automations before merging or re-enabling automations manually after merging.

Known Issues for Working Copies

The known issues for Working Copies include:

  • Server Error message - If you are running APEX on Oracle Database release 19c and using the working copy feature, when you choose the actions Merge into Main, Refresh from Main, or Compare Changes, you may get a "Server Error" message that is caused by an underlying ORA-00600 error message. For example:

    ORA-00600: internal error code, arguments: [qjsnplsDecDomRefCnt:noValP], [], [], [], [], [], [], [], [], [], [], []

    The fix for this error is to upgrade to Oracle Database release 19.16 or higher.

  • ORA-00001 error during merge - The Working Copy feature raises an ORA-00001 unique constraint error when attempting to merge changes for component names that are not unique. It is important to coordinate the naming of shared components across working copies and the main application to avoid this error occurring.

Parent topic: Creating a Working Copy to Merge, Refresh, or Compare