Skip to main content

Cache purge configuration

When content is changed in Sitecore, it is likely the corresponding cache is Akamai must be purged. Uniform enables:

  • Sitecore users to purge Akamai cache manually
  • Sitecore to automatically purge Akamai cache when publishing is completed.

Both of these options require that Sitecore is able to use the Fast Purge v3 API in Akamai.

note

Customizing the cache purge process can give you greater control over when and how the process runs. Details are available on the customize Akamai cache purge page.

Create API client#

When an API client is created in Akamai, credentials are generated that Sitecore will use to make calls to Akamai to purge cache.

caution

You must have administrator access to Akamai Control Panel in order to add an API client.

  1. In Akamai Control Center, open the left menu and navigate to ACCOUNT ADMIN > Identity * access.

  2. Click New API client for me.

  3. Click Advanced.

  4. Enter the following values:

    • Name: Sitecore cache purge
    • Description: API client Sitecore uses to purge cache

  5. For the APIs field, select Select APIs.

  6. Click Clear API selection.

  7. For the row CCU APIs, select READ-WRITE.

  8. Click Submit.

  9. Click Manage purge options.

  10. Select the following values:

    • Purge by CP codes
    • All current and new CP codes

  11. Click Submit.

  12. Click Create API client.

  13. Credentials are displayed. These values are needed in the next section.

    caution

    Do not close this window without first copying the values displayed. Some of the details displayed cannot be retrieved later.

Add API client to Sitecore#

You must configure Sitecore to associate the API client with your Sitecore site. This can be configured in a couple of different ways.

Content Editor#

note

If you prefer to use a Sitecore config file to store the Akamai API client settings, skip this section.

  1. In Content Editor, navigate to sitecore > System > Uniform > Site Configurations.

  2. If a Site Configuration item for your site already exists, select it. Otherwise, create a new item using the template Site Configuration. Set the item name to match your Sitecore site. Select the new item.

  3. If a Configuration item already exists under the Site Configuration item for your site, select it. Otherwise, create a new item using the template Configuration.

  4. Create a new item using the template Configure: Akamai Purge Service....

  5. For the field Method, select the Akamai purge method you want to use. The following values are supported:

    • delete
    • invalidate

  6. For the field ClientToken, enter the credential value client_token.

  7. For the field AccessToken, enter the credential value access_token.

  8. For the field Secret, enter the credential value client_secret.

  9. For the field ApiUrl, enter the credential value host, but add https:// in front of the value. The following is an example of what the value should look like:

    https://akab-0000000000000000-0000000000000000.luna.akamaiapis.net

  10. For the field Network, specify the Akamai network whose cache you want to be purged when the purge functionality is triggered in Sitecore. The following options are supported:

    • staging
    • production

    These options correspond to the networks configured in the Akamai Property Manager.

  11. For the field HostNames, enter the Hostname(s) from the Akamai Property Manager. If you have multiple hostnames, add each host name on its own line in the multi-line text box.

  12. For the tag cpCodes, enter the CP Code(s) from the Akamai Property Manager. If you have multiple CP codes, add each CP code on its own line in the multi-line text box. They will only be used when full site purge is required.

Config file#

note

If you followed the steps in the previous section to configure the API client using Content Editor, you should skip this section.

  1. In Sitecore, create the following config patch file:

    <configuration xmlns:env="http://www.sitecore.net/xmlconfig/env/" xmlns:set="http://www.sitecore.net/xmlconfig/set/">  <sitecore>    <uniform>      <siteConfigurations>        <siteConfiguration name="">
          <site inherits="your-site-name" />
          <deployment>                  <deploymentService ref="uniform/services/nopDeploymentService" />          </deployment>
          <purge>            <purgeService set:ref="uniform/services/akamaiPurgeService">              <method></method>              <clientToken></clientToken>              <accessToken></accessToken>              <secret></secret>              <apiUrl></apiUrl>              <network></network>              <hostNames hint="list:AddHostName">                <hostName></hostName>              </hostNames>              <cpCodes hint="list:AddCpCode">                <cpCode></cpCode>              </cpCodes>            </purgeService>          </purge>        </siteConfiguration>      </siteConfigurations>    </uniform>  </sitecore></configuration>

  2. For the tag site, set the attribute inherits to be the Sitecore site name.

  3. For the tag siteConfiguration, set the attribute name to be the Sitecore site name.

  4. For the tag method, enter the Akamai purge method you want to use. The following values are supported:

    • delete
    • invalidate

  5. For the tag clientToken, enter the credential value client_token.

  6. For the tag accessToken, enter the credential value access_token.

  7. For the tag secret, enter the credential value client_secret.

  8. For the tag apiUrl, enter the credential value host, but add https:// in front of the value. The following is an example of what the value should look like:

    https://akab-0000000000000000-0000000000000000.luna.akamaiapis.net

  9. For the tag network, specify the Akamai network whose cache you want to be purged when the purge functionality is triggered in Sitecore. The following options are supported:

    • staging
    • production

    These options correspond to the networks configured in the Akamai Property Manager.

  10. For the tag hostNames, enter the Hostname(s) from the Akamai Property Manager.

  11. For the tag cpCodes, enter the CP Code(s) from the Akamai Property Manager.

    note

    This value is optional. It is only used for full-site purge operations. Full-site purge means the cache for an entire Akamai property is purged. For more information, see the Akamai reference section.

  12. Deploy the config file to your Sitecore instance.

Enable automated purge#

Uniform can send cache-purge instructions to Akamai when Sitecore publishing tasks are finished. This is called "automated purge". This functionality is disabled by default. Complete the following steps to enable automated purge:

  1. In Content Editor, navigate to sitecore > System > Uniform > Akamai > Settings.
  2. Tick the checkbox Clear Akamai cache on publish.
  3. Save the item.
note

For more information on how automated purge works, see the Akamai reference section.

Configure media handling#

Sitecore is responsible for generating URLs for images and other media files stored in the Sitecore Media Library. The specific approach you must take to ensure media files are handled properly depends on your site.

The following questions should be considered when developing a plan for handling media files:

  • After an image is added, is it every updated?
  • Are images used in multiple sites?
  • Are images added to rich-text fields? If so, how are they added?
  • Are images used in fields on items that represent pages?
  • Are images used in fields on items that are connected to pages using renderings?
  • Do you have components that load images from folders? If so, how is this implemented (e.g. the folder is a data source, or the component is hard-coded to reference a specific folder)?
  • Are images used outside of Sitecore? If so, how are they used?
caution

The options below are not recommendations. The specific approach you take to handling images should be based on your site's requirements. The questions above can help you understand what those requirements are.

Version-specific URLs#

If images are cached in Akamai, when an image is updated, the image in the cache is no longer valid. Determining the URL for the image and then purging that URL from the cache is one approach. Another option is to generate version-specific URLs for an image so that when an image is updated, it gets a unique URL.

In this case, when a new image version is available, any page that links to the image will have new URLs. This means the URLs for the pages that use the image must be purged from the cache, not the URL for the image itself.

Enabling version-specific URLs#

Sitecore supports this functionality. In a Sitecore config file, add the following settings:

<setting name="Media.AlwaysAppendRevision" value="true" /><setting name="Media.Cacheability" value="Public" />
note

For more information on these settings, see the Sitecore product documentation.