Managing Application Changes Safely with Working Copies in Oracle APEX

Introduction

In collaborative application development, managing change safely is critical, especially when working with live environments or production-grade logic. Oracle APEX offers a built-in feature called Working Copies, which helps developers implement and test changes without directly modifying the active version of an application.

Working Copies allow you to create an isolated, editable version of a deployed application. Developers can work on new features, apply bug fixes, or refactor components within this copy. Once the changes are verified, the working copy can be published to overwrite the active version, or discarded if the changes are no longer needed.

In Oracle APEX 24.1, Working Copies were enhanced with features that improve collaboration, prevent conflicts, and increase development safety. These capabilities remain fully supported and available in the latest release, Oracle APEX 24.2. You can consult the official documentation for more details on creating and managing working copies here.

This blog post explores how Working Copies function, when to use them, and how to incorporate them effectively into your APEX development workflow.

Let’s begin by understanding what a Working Copy is.

What is a Working Copy?

A Working Copy in Oracle APEX is an editable snapshot of a deployed application. It allows developers to make changes in isolation, without affecting the active or “runtime” version of the application that end users interact with.

When a working copy is created, Oracle APEX clones the application’s metadata: pages, shared components, processes, and logic. This cloned version becomes your development workspace, where you can test modifications, experiment with UI changes, or implement new features safely.

Unlike traditional version control, where changes are committed to a repository, working copies remain within the APEX environment. They are especially useful in team-based or multi-developer environments, where controlled change management is essential.

A working copy is not visible to application users. Its changes only take effect once the developer explicitly publishes the copy, replacing the live version. Alternatively, the copy can be discarded at any time if the changes are no longer desired.

This mechanism makes Working Copies ideal for safe, iterative development within Oracle APEX, eliminating the need for external tooling or branching systems.

Key Use Cases

Working Copies are especially valuable when maintaining applications in environments where stability, team collaboration, and controlled deployments are priorities. Below are the most common scenarios where using a working copy is highly recommended:

• 🛠️ Feature Development
  When introducing new features to an existing application, “Working Copies” enables you to prototype and validate logic without compromising production functionality.
• 🐞 Bug Fixing
  Small patches or corrections can be applied safely in a working copy, tested, and published once verified, without affecting ongoing application use.
• 👥 Collaborative Development
  In multi-developer teams, each developer can create their working copy, reducing the risk of overwriting changes made by others.
• 🔍 Code Review and Validation
  Working Copies serve as staging areas for QA review. A lead developer or reviewer can inspect changes before approving them for production.
• 🗂️ Version Control within APEX
  If external versioning tools aren’t in place, working copies provide a basic, internal alternative for version isolation and iterative deployment.

Creating a Working Copy

Creating a Working Copy in Oracle APEX is a straightforward process, but it plays a critical role in how safely you manage application changes. When you initiate a working copy, APEX duplicates the current state of your application into an isolated, editable version, leaving the live version untouched.

Steps to Create a Working Copy

To create a Working Copy in your application:

1. Go to the home page of your application.

2. Find Working Copy Tasks on the right sidebar.

   

3. Under Working Copy Tasks click the “Create Working Copy” option.

4. The “Create Working Copy” Wizard appears so that you can fill in the following information:

   • Working Copy Name: You can specify a short or descriptive label for the Working Copy (e.g. TSK_0001).
     A common best practice is to include the Jira or Ticket ID if you’re working under a task-tracking system (e.g., JIRA-1754-Add-ai-summary).

   • Working Copy Description: Optionally describe the purpose of the copy (e.g., “Add date of Birth for the Employee Details Form”)

     

5. Confirm and create.

Working Copy Scope

Unsupported Component Types in Working Copies

Working Copies in Oracle APEX provide a powerful mechanism for isolated development; however, not all component types are compatible with automated merging. The following elements are not included in the automatic synchronization between a Working Copy and the Main application:

• Translations

• Themes and Theme Templates

• Supporting Objects

• Application Properties

• Workspace-level components (e.g., App Groups, Credentials, Remote Servers)

For these components, Oracle recommends that once changes in the Working Copy are merged into Main, developers should manually replicate any modifications related to these unsupported components. As a best practice, delete the Working Copy afterwards to avoid confusion and ensure consistency between environments.

Available Working Copy Options

Oracle APEX provides a dedicated set of options to manage and maintain working copies effectively. These are accessible from the Working Copy menu and the Application home sidebar.

Working Copy Menu Options

• Switch to Main
  Quickly navigate back to the main (live) application.

• Working Copies
  View all existing working copies associated with the main app.

• Merge into Main
  Publish the changes made in the working copy by merging them into the live application.

• Refresh Working Copy
  Sync the working copy with recent changes made in the main application, ensuring alignment.

• Compare with Main
  Launch a side-by-side comparison tool to review the differences between the working copy and the main version.

• View/Edit Working Copy Details
  Update the name or description of the working copy as needed.

• Delete Working Copy
  Permanently remove the working copy (after confirmation).

Sidebar: Working Copy Tasks

The Application home page sidebar also includes quick-access links for commonly used actions:

• Merge to Main

• Refresh Working Copy

• Compare Changes

Additionally, you’ll find a direct link back to the Main Application to switch contexts with a single click.

Making Changes

Once your working copy is created, you can begin applying modifications just as you would in any standard APEX application, except your changes remain completely isolated from the runtime version.

This allows you to design, iterate, and validate logic with complete confidence that the live application will not be affected until you’re ready to publish.

A Practical Approach

We will explore a comprehensive practical case that covers various scenarios between a Working Copy and the Main version of the application. By analyzing the following situations, we will understand the best practices for managing changes, performing comparisons, and executing merges effectively:

Example 1: Modification in the Main that is not reflected in the Working Copy.

While working on TSK_0001, you decide to run a Compare Changes operation to check for any discrepancies between your working copy and the main application. To your surprise, APEX highlights a structural difference on Page 2 (Employee Form):

Upon inspection via the Diff button, you discover that someone has added a new item called B2_BIRTH_DATE (a Date Picker field capturing the employee’s birth date) directly in the Main application after your working copy had been created. This situation is common in collaborative environments where multiple developers are updating the same application concurrently.

In this case, your working copy is out of sync with the main app. If you were to continue working or attempt a merge without refreshing, you might:

• Overwrite the new field unintentionally, or

• Miss critical recent changes made by others

To avoid this, and once you have verified that the new field B2_BIRTH_DATE only exists in Main:

1. Go to the “Working Copy Tasks” submenu and click the “Refresh Working Copy” option.

2. After a few seconds, the summary of changes will appear (similar to the “Compare Changes” option).

   

3. Click on the “Next >” button.

   

4. Before “Confirming the Refresh”, we can check the “Backup target app first” option to create a copy of our current working copy just in case. Later on, if it is necessary, we can restore it.

5. Click on the “Confirm Refresh” button to apply changes.

What did the Refresh option?

• Pull all structural changes made in Main (after the working copy was created).

• Apply them to your working copy.

• Preserve your own changes (as long as there are no direct conflicts).

After the refresh, B2_BIRTH_DATE will be visible and usable within TSK_0001. You can now continue working on your feature branch without inconsistencies.

Example 2: A change in the Working Copy that doesn’t exist in the Main.

In our working copy TSK_0001, we decided to introduce a functional enhancement to Page 2 (Employee Form). Specifically, we added a new button labelled “Save”, intended to submit the form, allowing users to store the information introduced.

This button is only created and configured in TSK_0001. The Main application has not been modified since your working copy was created.

Once we have added the “Save” button to Page 2, we notice that there is a warning icon on the Page Designer toolbar (View changes in other copies). If you click on this icon, APEX will show us the page changes across working copies.

Next Step: Merge into Main

Once you confirm that the new button works as intended in the working copy and does not interfere with any runtime behaviour:

1. Navigate to the Working Copy Tasks submenu.

2. Select Merge into Main.

3. Review the merge summary (it will include the B2_SAVE button).

4. Confirm the operation.

APEX will automatically:

• Integrate the new button into the live Page 2 definition.

• Remove the working copy (unless you select to retain it).

After merging, APEX will redirect you to the Main app:

Example 3: Conflicting changes in Main and Working Copy.

In collaborative development environments, it’s common for different team members to work on separate Working Copies simultaneously. By the time you’re ready to merge your own changes, others may have already merged theirs into the Main application, introducing differences that now conflict with your local copy.

Let’s walk through such a scenario using Page 2 (Employee Form) as a reference point:

You’re working on the Working Copy: TSK_0001, and while you were developing your features, other team members finished their tasks and already merged their Working Copies into the Main application.

As a result:

– In Main (after merges from other Working Copies):

• The label of a field was updated from “Employee Name” to “Full Name”.

• The layout of the region was rearranged.

• The appearance of the “Back” button was changed.

– In Your Working Copy (TSK_0001):

• You added a validation logic on the Birth Date field.

• You added a new “Help” button.

• You added a dynamic action for the Birth Date field (Change event).

• You also updated the label of “Employee Name” to “Staff Name”, unaware of the previous update.

Comparing changes

If you decide to go straight to Merge into Main without first running a full comparison, Oracle APEX will still identify components with differences and display them in the merge wizard.

In our example, Page 2 will appear as a modified component, and by default, its checkbox will be selected, meaning its content from the Working Copy is ready to be merged into Main.

However, you should:

• Uncheck Page 2 from the merge list to avoid overwriting those changes.

  

• Click the Diff icon next to Page 2 to inspect the detailed differences between the Working Copy and Main.

• Take note of your own changes that are still relevant.

  

• Manually apply those adjustments in Main after validating that they don’t undo work previously merged by others.

This approach allows you to still proceed with merging other non-conflicting pages or components from your Working Copy while preserving the integrity of shared work done in the Main application.

Now, you can continue with the Merging into the Main process of the rest of the components.

Tips and Recommendations

This is a summary table of the key recommendations for using Working Copies in Oracle APEX:

Conclusion

Working Copies in Oracle APEX 24.1 provide a powerful and flexible mechanism for managing collaborative development, parallel workflows, and safer deployment of changes. By following a structured approach, along with the best practices outlined above, teams can avoid unnecessary conflicts, minimize manual rework, and maintain a clean and stable Main version of their applications.

Whether you’re managing a single project or coordinating across multiple developers, mastering the Working Copy lifecycle (from refreshing to merging) is key to streamlining your APEX development process.

If you or your team need guidance in implementing this approach effectively, feel free to reach out to us at hello@novoshore.com we’d be happy to help.