Replace URL-based media files (Media Entity File Replace module)

Replace URL-based media files (Media Entity File Replace module)

This document explains the GovCMS Media Entity File Replace module, which allows a URL-based media file to be replaced with an updated version. This module was added to the GovCMS distribution in February 2020.

This document contains the following sections:

  • About the Media Entity File Replace module
  • When did the module become available?
  • What workarounds does this module replace?
  • Who can enable this module?
  • Who can use the functionality provided by this module?
  • Potential caching issue
  • More information

About the Media Entity File Replace module

The Media Entity File Replace module allows a media file to be replaced while retaining the existing URL to the file.

Examples: Word documents and PDFs.

It is useful when a GovCMS website contains media files for end users and those files are managed using the Media module.

This module operates on the media entity level, which means that the existing source media file can be overwritten in the Edit form, retaining the same file name and URL. Figure 1 shows the Edit screen.

Figure 1

edit document sample_pdf.pdf

End users can access the latest version of the media file without knowing the direct file URL. This eliminates errors associated with users accessing a media file using an absolute reference.

Examples: Browser bookmarks and Google crawl.

When did the module become available?

The Media Entity File Replace module was added to the GovCMS distribution on 26 February 2020, as part of a GovCMS D8 (Drupal 8) release.

See: https://www.drupal.org/project/govcms8/releases/8.x-1.1.

What workarounds does this module replace?

Previously, replacing a media file involved removing the existing file from the file widget and uploading the new version using the same file name. However, this method appends the file name with a number, instead of overwriting it. In practice, the process of uploading a replacement media file required that the site be configured to automatically delete unused files during cron runs and involved:

  • deleting the media file
  • waiting for the next cron run to delete the unused media file
  • uploading the new media file using the same file name.

Who can enable this module?

Who can enable this module depends on whether your organisation signed up to the Software as a Service (SaaS) or Platform as a Service (PaaS) service offering.

If you are a SaaS customer, the GovCMS Service Desk can enable the module for you:

If you are a PaaS customer, you can enable the module.

Who can use the functionality provided by this module?

This functionality provided by this module can be used by GovCMS users who have one of the following roles:

  • Content Editor
  • Content Approver
  • Site Builder
  • Site Editor
  • Site Administrator.

Potential caching issue

All non-HTML files are cached, including by Akamai, for a predefined period. The duration partly depends on whether a website’s default cache control settings for origin have been modified. If your website:

  • has not defined site-specific cache control settings for origin, non-HTML files are cached for one day
  • has defined site-specific cache control settings for origin, then non-HTML files are cached according to the website’s settings.

This means that the updated file may not be available immediately after it is uploaded. When you are validating that the new file is available and can be downloaded, ensure that you test using multiple devices.

Example: Using a computer-based browser and a smart phone-based browser.

If your testing finds that the older version of the media file is downloading, follow the existing procedure for clearing the Akamai cache:

  • Create a GovCMS service desk support ticket (https://www.govcms.support/).
  • Include the following information:
    • an appropriate level of business impact
    • the date/time you uploaded the new version
    • the link you are using to download the file
    • details on what's changed in the latest version so that we can compare it to previous versions.

More information

See: For more information, including instructions for using the module, see https://www.drupal.org/project/media_entity_file_replace.