Skip to main content

Cache purge

The purpose of using Akamai as a CDN is to reduce the need for a Sitecore CD instance to handle visitor requests. The first time a page is requested, Akamai must request the page from the origin (i.e. Sitecore CD instance). But all subsequent requests for the page can be handled by Akamai CDN.

The following diagram illustrates the logic that results in a personalized page being delivered to a visitor.

Uniform provides the ability to purge entries from the Akamai cache. This is necessary when content in Sitecore changes. By purging the pages in Akamai cache, Akamai is forced to retrieve the latest content from Sitecore.

Akamai API client#

In order to purge entries from the Akamai cache, Uniform must make API calls to Akamai. This requires the following be in place:

  • An API client must be configured in Akamai.
  • Settings for the API client must be added to Sitecore.

Details on how to determine these settings and add them to Sitecore are available in the installation instructions.

An API client is the collection of settings that Uniform uses to make API calls to Akamai. The settings can be broken down into the following categories:

Connectivity#

Connectivity settings are used to establish the connection between Uniform and Akamai. These values are generated by Akamai during the installation process. These settings include:

  • Access token
  • API URL
  • Client secret
  • Client token

Selection#

Uniform uses selection settings to identify which parts of the Akamai cache to purge. These settings include:

  • Network - In Akamai, a property has separate settings for staging and production. This setting identifies which of those networks cache purge instructions are sent to.
  • Host names - When Uniform sends to Akamai a list of URLs to purge, it also sends one-or-more host names so that Akamai can locate the appropriate cache entries.
  • CP codes - In Akamai, each property is represented by a CP code. This setting identifies the Akamai property that is associated with the API client. CP codes are used during full-site cache purge.

API client resolution#

When cache purge is triggered, a Sitecore item is identified as the root item.

The Sitecore site that the root item is a part of is determined. The first API client assigned to the Sitecore site is used. If no API client is assigned to the Sitecore site, an error is thrown.

note

If the cache purge was triggered manually, the error message is displayed. If the purge was triggered by publishing, the error is written to the Sitecore log.

Cache purge operations#

A cache purge operation represents the act of purging entries from the Akamai cache. There are two kinds of cache purge operations.

Full-site purge#

Purging all URLs for a site is called "full-site purge".

How is full-site purge triggered?#

Full site purge is triggered in the following ways:

  • "Publish site" command is triggered
  • Automated purge for an item based on the template "Uniform Site Item"
  • Manual purge for an item based on the template "Uniform Site Item"
note

Triggers that involve publishing require the setting "Clear Akamai cache on publish" be enabled.

How are cache entries selected?#

The cache entries that are purged depend on whether CP codes are specified on the API client:

  • CP codes specified - All cache entries associated with the specified CP codes are purged.
  • No CP codes specified - Dependent pages are resolved for the root item of the Sitecore site and its descendants.

Item purge#

Purging the URLs for a site based on the "root item" is called "item purge".

How is item purge triggered?#

Item purge is triggered in the following ways:

  • Automated purge for a content item.
  • Automated purge for a media item.
  • Manual purge for a content item.
  • Manual purge for a media item.
note

Triggers that involve publishing require the setting "Clear Akamai cache on publish" be enabled.

How are cache entries selected?#

The specific URLs that are purged are determined by the process that resolves dependent pages.

Dependent pages#

When cache purge is triggered for an item, Uniform Optimize must determine the URLs related to that item in order to send the appropriate purge instructions to Akamai.

Imagine that you have changed an item that represents a banner that appears on multiple pages on your site. Those pages are called "dependent pages", because they depend on the banner item. Uniform Optimize must resolve the URLs for the dependent pages, because those are the URLs that must be purged from the Akamai cahche.

Dependent pages are resolved by the pipeline getPurgeItems. The result of this pipeline running is a collection of items. The URLs for these items are sent to Akamai to be purged.

By default, the following items are added to the collection:

  • Root item - The root item is provided in the args passed to the pipeline. This item represents the item that was published or was selected to be purged.
  • Descendants - The pipeline args includes a property "clear cache option". If this is set to "clear item branch cache", the descendants of the root item are included.
note

Related items are not included out-of-the-box. If you need related items to be included, you must add a custom pipeline processor that implements the required functionality.

You can add processors to this pipeline to include additional items based on your site design and information architecture.

Triggering cache purge#

Manual#

Akamai cache can be purged manually from Sitecore Content Editor. Buttons are available in the "Uniform" ribbon. Depending on the item selected in Content Editor, different cache purge commands are available:

Page#

Page cache purge is available when the selected item is identified as a page in the Uniform Map Service.

When page cache purge is triggered, the following URLs are purged:

  • URL that corresponds to the selected item
  • URLs for dependent pages of the selected item

Tree#

Page cache purge is available when the selected item is identified as a page in the Uniform Map Service.

When tree cache purge is triggered, the following URLs are purged:

  • URL that corresponds to the selected item
  • URLs for dependent pages of the selected item
  • URLs of pages that are descendants of the selected item
  • URLs for dependent pages of the descendants of the selected item

Site#

Site cache purge is available when the selected item is a Uniform Site Configuration item.

When site cache purge is triggered, all URLs are purged for the site. This is accomplished by using the CP codes assigned to the site.

Automated#

Automated cache purge is triggered by the Uniform deploy process. The Uniform deploy process is triggered by publishing.