23.4 Isolating Changes with Working Copies

Use working copies to build, test, and merge isolated APEX changes safely.

When several developers work on the same APEX app, coordination matters. APEX is multi-user by design: team members can build or edit different parts of an app at once. To prevent conflicts, APEX offers page locking. For example, if you’re editing Page 5, you can lock it so others can’t change it until you’re done. But for larger or riskier changes, or when developing a new feature in isolation, Working Copies provide a safer path.

A Working Copy is a clone of the main application within the same workspace, a personal sandbox for each developer. At any time, a team member can create one to experiment, fix a bug, or build a new feature without affecting the main app. It’s like creating a temporary branch, similar in spirit to branching code in Git, but entirely within APEX. The working copy starts identical to the main application. From there, you make changes in your copy while others continue working on the main app or their own.

Working copies enable parallel development without conflict. For example, Alice creates a working copy to redesign report pages while Bob fixes bugs in the main app. Alice can make extensive changes safely in her copy. APEX lets you compare your working copy with the main app, or another working copy, to see what’s different. It’s an effective way to review changes in isolation. If others update the main app while you’re working, you can refresh your copy to pull in those changes and keep your sandbox current.

When you’re satisfied with your changes, you can either merge your working copy into the main app or discard it. Merging applies all changes to the main definition, typically when a feature or fix is complete and tested. If the work was experimental, simply delete the working copy with no impact on the main app. It’s a safe playground for development.

Working copies merge or refresh at the page and component level. If two copies modify different pages, they can merge cleanly. But if both change the same page, a conflict may occur. To prevent this, lock any page you’re modifying in a working copy. For example, before Alice edits Page 42 in her working copy, she locks Page 42 in the main app with a note like “Working on new report UI.” The lock signals to others not to touch that page until she’s done, and prevents them from doing so in the main application. After merging her changes, she can unlock it. Together, working copies and page locks let teams develop in parallel, isolated when needed, yet merging back into a single shared application.

In addition to using App Builder, developers can also work on a working copy using APEXlang. Since it is editable using external tools, it is ideal for use with code editors, AI coding agents, and diff/merge tools. A developer can export her working copy to APEXlang, work on it externally, then import the APEXlang working copy app back into App Builder. The final merge back into the main application of new or changed pages and components can use normal working copy functionality.

If working copy conflicts prevent a merge in App Builder, export the main application and working copy to APEXlang. Resolve the conflict manually using your favorite external tools. Then, validate the updated main application using apex validate. When it passes validation, import the merged APEXlang result to overwrite the main application. Finally, delete the conflicted working copy.

Working copies let teams build features or fixes in isolation without requiring separate environments per developer or complex branching. The approach suits small teams and fast iterations, keeping all work within the familiar App Builder while providing useful separation. Many developers use it to sandbox big changes, prototype freely, review differences, and merge into the main app only when ready.

For more information, see Creating a Working Copy to Merge, Refresh, or Compare in Oracle APEX App Builder User’s Guide.

Tip:

A working copy has a different application id from the main application, but APEX knows they are related. If application logic depends the value of the main application ID, use MAIN_APP_ID instead of APP_ID as a substitution or bind variable. It always evaluates to the ID of the main application.