Starting with Oracle APEX 23.2, you can create a Working Copy of an application to fix a bug, add a feature and then selectively merge your changes back into the Main application. Similarly, you can also refresh changes from the Main application into the Working Copy. During the merge or refresh process, you can view a comparison (or diff) of the Working Copy and the Main application and then select which changes to merge. You can create as many working copies as you like, so multiple developers can contribute and merge changes to a single application.
When you compare a Working Copy to the Main application, a 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.
The merge process takes a selected set 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. Therefore, it is important that the developer reviews the individual changes in any page or component that is listed as “Changed” between the Working Copy and the Main application to ensure that the developer’s own changes are the only ones present between the two. The integrated diff viewer makes this task easy.
Let’s explore the Application Working Copy feature in a simple example.
Pat is the development manager of a small team that builds HR solutions. Mark and Grace who are the developers in the team are tasked to work on an HR App. Pat periodically exports this app and checks the team’s progress into GitHub source control. In APEX Team Development, Pat creates tickets to track new feature development and bug fix status and assigns them to Mark and Grace. To work on their assigned tasks of application updates, Mark and Grace will first create working copies. They work on their respective working copies as long as needed. When Mark is complete with his changes, he will merge them back into the Main application. At any time, Grace can refresh her Working Copy from the Main application to pick up any changes other team members have made while she is working on her working copy. When Grace is ready, she will selectively choose which changes to be merged. If Grace has still some more changes to be made in the app, she will keep her Working Copy around and rename it as HR – Grace WIP for clarity.
For example, ticket #2 is assigned to Mark to perform the following tasks:
- Add pages to list, create, update, and delete departments
- Add a list of values (LOV) to pick up a department
- Change the Home page chart title to Compensation and X axis to “All Associates”
Mark will now create a working copy of the Main app named HR – 0002 based on the ticket number he’s working on. To create a working copy of an app, simply navigate to the application home page and under the Tasks sidebar, click Create Working Copy. Enter a name for the working copy, and a short description and then click Create Working Copy.
The application badge now shows HR – 0002 indicating the name Mark chose for the Working Copy he is using to work on ticket #2.
After making the requested application updates in his Working Copy, Mark will now merge these changes into the Main app. From the Working Copy drop-down menu, select Merge into Main.
App Builder exports the Main application and Working Copy and compares the two versions. The Merge Project Name into Main dialog appears summarizing what has been changed, added, or is missing. To view a Diff of the changes, click the Compare Changes icon for any component or page.
The View Differences window appears.
In this example, Mark notices the changes made to the labels and then will click Next to confirm the changes.
The Merge Project Name into Main dialog includes two options:
- Backup target app first
- Delete Working Copy after merge
Mark wants to delete the Working Copy after the merge as he doesn’t need it again. After choosing the appropriate options, Mark will click Confirm Merge. Mark’s changes are now part of the Main App.
In Team Development, Pat assigned Ticket #3 to Grace to add Employee pages and also make some changes to the chart on the Home page. Grace started working at the same time as Mark did on her ticket tasks and named her Working Copy HR-0003 accordingly. Since Mark finished and merged before her, Grace wants to pull Mark’s changes (merged into the Main app) into her Working Copy. She wants to review the diffs and select the changes to pull into her Working Copy.
Refreshing a Working Copy exports the changes from the Main application into the Working Copy. To refresh a working copy with changes from the Main, on the application home page, under the Tasks sidebar, click Refresh Working Copy. App Builder exports changes from the Main application to the Working Copy and compares the two versions. The Refresh Name from Main dialog appears summarizing what has been changed, added, or is missing. You can selectively choose the changes to be pulled into your working copy and click Next. Finally, click Confirm Refresh.
Now, Grace will review her assigned ticket, make the updates in her application Working Copy and then select a subset of her changes to merge back to the Main app. Since one of the last-minute changes Pat asked her to make wasn’t yet ready to merge, Grace will not delete the Working Copy after the merge. She will rename the Working Copy to HR – Grace WIP.
To rename a working copy, from the Main application, navigate to Working Copies and then select the working copy name. Then select View Working Copy Details.
Enter a name for Working Copy Name, a short description and click Apply Changes.
Now, Mark and Grace’s changes will be part of the next Main application export that Pat checks into the GitHub source control.
The Working Copy, Diff and Merge capabilities introduced in Oracle APEX 23.2 simplify collaborative application development without disturbing the Main application. Watch this video to learn about how this new feature enables developers to work on different aspects of the same app in parallel. To learn more about Oracle APEX 23.2 New Features, visit the What’s New page.