Delete and replace files in media assets

Video creator
Salsa Digital

Disclaimer: The content in this video remains relevant to Drupal 10 customers. An updated version of this training video is in the works and will be available soon.



Welcome to the GovCMS Content Administration Training series. Hi, I’m Ivan from Salsa Digital and in this video,  you’ll learn how to delete assets and replace files. We’ll cover the following two topics:

  • How to delete media assets and discuss deleting physical files
  • How to replace files in a media asset

Delete files

So we know how to upload files and create media assets. But let’s look at how you can delete media assets and the current limitations with deleting physical files. To demonstrate how to delete media assets, let’s upload an image.

Click on Add media then Image.  And I’ll upload a file named delete-file and I’ll enter that as the name and alternative text.

At this point, we’ve uploaded a file and created an asset. And if we go into the asset we can see the file. And if we open the files tab in another browser, we can see the physical file and you can see it’s used in two places, but this is just the number of revisions. Because if we click on the link, you can see it’s part of the “delete file” media asset.

Let’s leave this tab open and go back to the Media tab and now we’ll delete the asset we just created. 

You can delete an asset by clicking on delete from the operations column, or we can edit the asset and click on the delete button. Let’s go ahead and delete. And you can see the asset is now gone.

Now if we go to the Files tab and refresh the page, you can see that the “Used in” column is now “0 places” because the file is no longer attached to the media asset. The asset itself has been deleted. But the physical file will still be accessible because GovCMS has been configured to never delete the files.

The way GovCMS, or technically Drupal, deletes a file works like this: if a file is no longer used and the “Used in” says “0 places”, the status of the file will be changed from Permanent to Temporary. Then around six  hours later Drupal will delete the file.

Now this file deletion, sometime in the future, causes a lot of problems. Because an editor could delete an asset but the file could still be linked directly from an email newsletter. And also you don’t want files just randomly deleting. So in GovCMS this file garbage collection or cleanup or whatever you want to call it has been disabled. Now for most other files, it’s perfectly fine to leave them there on the server. 

But if you need a file deleted which is out-of-date or has misleading information, then you need to create a ticket on the GovCMS service desk and they will need to manually delete the files.

I understand submitting a ticket to delete files is not ideal, we are working on a solution to make this process easier in the future.

Replacing files

At this point, you know how to manage assets, how to create and delete them, but now let’s look at how you can replace the uploaded file in a media asset.

To demonstrate, let’s go ahead and create a media asset for a PDF report. Click on Add media, then File. I’ll enter “Report 2019” into name and I’ll select the PDF file. Then click on Save.

You can see the report file here and if we click on it, we can go directly to the file by clicking on the file name.

Just a side note, how the PDF gets displayed on your computer could be different. I’m using Firefox in this recording and it displays the PDF in a popup window. But it may look a bit different on your computer. 

Now take note of the path, this path here (“sites/default/files/2020-06”), this is just standard GovCMS. When you upload a file, it’ll save it into “sites/default/files” and then it’ll put the file in a folder with the year then a dash then the month — this is the year and month when it was uploaded. And then you have the actual file name (“report-2019.pdf”).

You can copy this URL, put it in your email newsletter or give it to someone and they’ll be able to access the file directly.

But what if you want to replace this file with a new version? Let’s see what happens. Click on Remove, and I’ll select the new version, take note of version 2 and click on Upload. Then click on Save.

Let’s go back to the report and click on the file name and you’ll notice that the file name has changed, there’s an _0 in the name. The full URL to the file has changed.

Drupal, which GovCMS is built on, will add a number to the filename and increment it, because a file with the same name, report-2019, already exists. It hasn’t replaced or deleted the old file. Now this can cause problems if you’ve linked directly to the file in an email newsletter for example. Because you haven’t technically replaced the old file, it’s still there.

But lucky for us, there is a solution. So if your media edit page looks like what’s on screen, it means the functionality to replace files hasn’t been set up. All you need to do is create a GovCMS service desk ticket and ask for “Media Entity File Replace” and they’ll be able to set it up on your site. So let me go ahead and get it set up on this site.

Let me refresh and now we see this replace file functionality. And most importantly we have this option: “Overwrite original file”. That’s exactly what we want. Let’s forget this media file and create another called “report 2020”.

So I’ll go to Content, Media, Add media, then File. I’ll select report-2020 version 1, and the filename is “report-2020”, and I’ll add “Report 2020” into Name. Then I’ll click on Save. Then go back in and if we click on the file name, we see report 2020 version 1.

Now let’s go ahead and replace the file. Click on Choose file and I’ll select version 2, and also make sure “Overwrite original file” is checked. Then click on Save. Then go back in and click on the file. If you still see the old version, that’s because it has been cached locally, so just do a hard refresh (Ctrl+F5 if you’re on Windows or Command+r if you’re on a Mac) and we should see version 2 of the file, but the filename has stayed the same.

So now we won’t have broken links or old, out-of-date content. Chances are this functionality may not be set up on your site. And if you don’t see this “Replace file” field set then it’s definitely not set up on your site. All you need to do is create a ticket on the GovCMS service desk and ask for “Media Entity File Replace”. And they’ll be more than happy to set it up for you.


Let’s now recap what we covered in this video. First, you learnt how to delete a media asset and the current limitations with deleting physical files. Then we looked at how to replace existing files in a media asset.