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.

Application Locks and Working Copies

An application lock gives the lock owner exclusive access to edit the locked application in App Builder. The lock applies only to that application. Locking a main application does not lock its working copies.

When an application is locked, only the lock owner can edit or unlock it in App Builder. Other developers and workspace administrators are directed to the Application Locked page. If the locked application has working copies, that page includes links to those working copies.

For more information on locking an application, see Locking and Unlocking an Application.

Tip: To lock an application, unlock an application, or create a working copy programmatically, see the APEX_APPLICATION_ADMIN package in Oracle APEX API Reference:

• CREATE_WORKING_COPY
• LOCK_APPLICATION
• UNLOCK_APPLICATION

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