Dispatcher Flush UI: An In Depth Review


Joey and Peter did a podcast introducing ACS AEM Commons, and within that podcast they talked about one of their favorite features: Dispatcher Flush UI. I thought I would take some time to outline a little bit more about this incredibly useful AEM feature.

What is it?
Dispatcher cache can often confuse authors, especially in content-heavy sites. Traditionally, authors publish pages and rely on the flush agents on the publish servers to automatically flush the cache of that page, but this process can leave a lot of gaps. What if the author does not want to actually push the content out to the dispatcher? What do you do when a content change affects a group of related pages? Or, you might find yourself occasionally needing to flush the dispatcher cache on demand. While you certainly COULD visit each and every page that is affected by a change and manually activate it, triggering a flush, people have often found the need for a better answer. ACS AEM Commons provides the Dispatcher Flush UI feature that allows privileged users to set up pages to hold paths that can be flushed at the push of a button, without the involvement of the Operations team.

How it works
The Flush UI tool creates a new type of page, in the /etc tree, under the “miscadmin” (or “Tools”) panel of the Classic UI. Who exactly should be allowed to create these Flush UI pages will differ from project to project and can be managed through user permissions, but suffice it to say, users with the appropriate permissions can create a page and use the built-in pathfield component to add references to any number of paths within their JCR. Once the page is defined, users can visit this page and hit a clearly labelled button, causing all referenced paths to be activated (and subsequently flushed) in a single batch. Since the authors use the Flush UI in the authoring environment, the author server needs to have dispatcher flush agents available. The ACS AEM Commons page provides specifics for the configuration.

Why it’s good
In addition to the use cases described in “What is it?”, the Dispatcher Flush UI feature has useful applications in the development process. Dispatchers can more easily stay in sync with quickly changing development environments without disabling cache altogether. Multiple Flush UI pages can be set up, each controlling different sections of cache. It is particularly helpful in flushing clientlibs (if you are not using the Versioned Clientlibs feature) and networks of pages related by dynamic content.

How to do it
First, a Dispatcher Flush replication agent must be created to service this feature on the authoring environment. Active flush agents usually reside on publish environments and get triggered when the publish server receives a replication request. We need ours on the author environment, so when an author hits the “Flush Paths” button, there is something there to send the request. The Ignore Default option designates the flush agent as outside of the normal replication flow, ensuring it is not called by other processes.

Let’s make a flush page to invalidate the main clientlibs.
The Flush UI page can be created through the /miscadmin/tools section of AEM. There is a folder set up by ACS to hold flush pages under /etc/acs-commons/dispatcher-flush. The page is created like any other and uses the “Dispatcher Flush” page template.
The properties on the node point to ACS resources.
The flush page holds a dialog with configurable path fields that you can point to whichever resource you want to flush and how you want to flush them. The flush method can be Invalidate Cache or Delete Cache. We will point our paths to the CSS and JavaScript generated by the main clientlibs. Note that we have minification off in this example. And also note that the paths are not necessarily in the author JCR. It is the dispatcher that cares about these paths. The pathfield’s browse and autocomplete capabilities will not help you find things like compiled clientlibs, servlet paths, or selectors.
The configuration node looks how you would expect: resources pointing to ACS components and the paths held in a String[].
Once configured, the flush method, paths, and agent are displayed and there is a big red button to push to do it.
If these pages are useful, you might consider adding them to your build process to make them available across all stages of your development process. Pages are quick to create and the paths are easy to modify, but it can be helpful to have pre-configured pages that point to a set of pages that need frequent flushing.

Audience Impact (authors, devs, admins)

  • Developers drive the decision of which items should be flushable by whom
  • Admins create the Flush UI pages and set up the permissions
  • Authors use the result and trigger the cache flush from the interface created by the admins and devs.

Example application
One of our Adobe Experience Manager implementation customers had many of their content pages that were actually aggregations of content imported from third-party systems. When bulk updates were made to that third-party system, no one wanted to sit down and click “activate” on a few thousand pages; nor did we particularly relish the idea of having to manually flush the cache at the customer’s whim.

Instead, we created a Flush UI page that listed all these aggregate pages, and provided the authoring team the ability to trigger the flush event when they felt it was appropriate, as they were often the first group aware of changes in the third-party system that needed to be reflected on the site.

If you found this interesting then check out this page about ACS AEM Commons which contains other posts where we talk other things related to ACS AEM Commons. And if you have any question then feel free to send us an email to [email protected].