Stay DRY by Using APEX Subscriptions
Table of contents
- Set Up a Master Application
- Establishing a Subscription
- Subscribing to an Existing Component
- Publishing Changes
- Breaking a Subscription
- What Happens Behind the Scenes
Developers are taught the DRY (Do not Repeat Yourself) principle. When I write PL/SQL code, I always think of how this code could be re-used in the future. This usually involves breaking large procedures and functions into smaller, more reusable procedures and functions.
On the APEX side, we deal with declarative components. APEX helps us keep to the DRY principle with some of these components by allowing us to maintain a "Master" copy of certain shared components. Other applications can then subscribe to these components. Subscriptions prevent us from manually duplicating these components in each application where they are used.
This post will cover various aspects of the APEX Shared Components Publish/Subscribe mechanism, including:
How to set up a "Master" Application
How to publish changes from the "Master" Application to subscribing Apps
How to refresh individual components from the "Master" Application
What happens when you deploy the "Master" Application and associated subscribing Apps
Throughout this post, I will refer to a Master Application (App ID 102) and a Subscribing Application (App ID 103). The Master Application will contain the master copy of the components we want to share. A Subscribing Application is any application with components that subscribe to the Master Application.
Throughout this post, I will use an example static List of Values called
PRIMARY_COLORS. The steps for subscribing, publishing, refreshing, un-subscribing, etc., are the same for other components that support subscriptions.
Set Up a Master Application
The "Master" Application is just a shell for components we want to share with other applications. I find it easier to maintain all subscribed components in one "Master" application than spread them around several applications.
There is nothing special about the components you define in the master application. There are, however, some considerations you need to keep in mind.
Make the App Unavailable
In most circumstances, the "Master" Application should not be runnable, and we must make sure it can never be run. We can prevent the application from being run by setting the
Application Definition property
If someone tries to run this application, they will be presented with the message you enter in the
Message for unavailable application property.
What Components are Supported
We also need to understand which components of an APEX application can be shared. The list of components that can be shared changes from release to release. For example, APEX 22.1 introduced Subscription Support for
Lists. At the time of writing, the following components can be subscribed to:
Lists (Includes Navigation Menu & Navigation Bar)
List of Values
Themes and Theme Templates
Note: REST Data Sources have an alternate mechanism for sharing REST Data Source definitions within a Workspace, called REST Source Catalogs.
Establishing a Subscription
The first thing you need to do is create a component that you want to share. I have created a new static List of Values in my Master Application called 'PRIMARY_COLORS'.
Then I navigate to my subscribing application and create a new List of Values.
Click 'Create' and complete the Wizard steps as follows:
- Copy the definition from the Master Application
- Elect to Copy the definition AND Subscribe to it.
List of Values created in Subscribing application
Reference Master List of Values Fromis set to the Master application
Next, navigate back to the same list of values in the Master Application:
You can see the Applications and list of values that subscribe to the list of values in the Master Application.
This list will grow as you reference this list of values in other subscribing applications. In the above example, two applications subscribe to the
PRIMARY_COLORSlist of values.
Subscribing to an Existing Component
You can also navigate to an existing component and establish a subscription to a component in the Master Application. In the screenshots below, I have created a LOV called
JD_PRIMARY_COLORS. I then link it to the LOV
PRIMARY_COLORS in the Master application. After applying my changes the LOV
JD_PRIMARY_COLORS is overwritten with the values of
PRIMARY_COLORS in the Master application.
There are two benefits to subscribing to a common definition of components. One is to avoid having to type in the definition twice. The more important benefit is that if you change the definition of the Master Component, you can publish the change to all subscribing applications at the same time.
There are two approaches to applying changes from the Master application to the Subscribing applications.
1 Publish from the Master App
Most of the time, you will change a component in the "Master" Application and push this change out to all of the Subscribing Apps.
Let's use the example of the
PRIMARY_COLORS List of Values. We can push out/ publish a change to all subscribing applications by clicking the
Publish LOV button.
2. Refresh from the Subscribing App
The second option is to navigate to the component in each Subscribing application and click the Refresh button. While it is sometimes helpful to do this, most of the time, you should be publishing your changes to all subscribing applications. If you do not then you can end up with the components being configured differently in each subscribing application. At that point, you may as well not be using subscriptions.
Let's use the example of the
PRIMARY_COLORS List of Values again. We can refresh the LOV in the subscribing application (App 103) by navigating to the LOV and clicking
Note: This will only refresh the LOV in application 103. Any other applications subscribed to the
PRIMARY_COLORS LOV in the Master application will not be refreshed.
Breaking a Subscription
You can break/unlink a subscription by setting the property
Reference Master List of Values From in the component in the subscribing application to
- no List of Values - and then apply your changes.
What Happens Behind the Scenes
When Establishing the Subscription
When you subscribe to a component in the Master application, APEX creates an exact copy of the component in the subscribing application. You may think that APEX would maintain a link to the component and not copy the entire component, but it does not. It is implemented this way so that you can migrate the subscribing application to another instance independently of the Master application.
When Publishing or Refreshing
When you Publish from the Master application or Refresh from the subscribing Application, APEX replaces the existing copy of the component in the subscribing application with a complete copy of the component from the Master application.
Updates in the Subscribing Application
What happens if I change a subscribed component in the subscribing application? You can do this and the change will work just fine. The next time you Publish from the Master application (or refresh from the subscribing application), however, your change will get wiped out with a copy of the component from the master application.
As we discovered earlier, when you subscribe to a component in the master application, APEX creates an exact copy of the component in the subscribing application. This means that you can deploy subscribing applications without worrying about the master application.
When you change a component in the master application, remember to Publish the component so changes are reflected in the subscribing applications.
Make sure that any changes you make to the master application component will not adversely impact any subscribing applications. For example, if you remove a LOV value for application 1, it may break application 2.
You do not need to deploy the Master Application to test or production. Each subscribing application contains a complete copy of any components that are subscribed from the master application.
When a subscribing component is copied, dependent components are also copied. For example, if you copy a List and the list items are associated with an Authorization Scheme, then the associated Authorization Scheme will be copied to the subscribing application also. Note: In this case, the Authorization Scheme is not subscribed to the Authorization Scheme in the master application. If the Authorization Scheme changes in the master application, then you need to update it in the subscribed application manually.
Make sure to name components clearly. For example, if you have a LOV containing order statuses which is called 'STATUSES' in the master application, it may not be clear what statuses the LOV refers to in the subscribing applications. In this example, it would be better to call the LOV 'ORDER_STATUSES'.
APEX Subscriptions can help prevent component duplication, improve consistency, and make it faster to make changes to multiple applications in one go. I encourage you to start using subscriptions in your next APEX project.
🔗 Read More
- [APEX Shorts](https://blog.cloudnueva.com/series/apex-shorts)
- [APEX Posts](https://blog.cloudnueva.com/tag/orclapex)