Replacing Files and Naming Assets

This article covers how to replace a file in Assets so that every page and content item that uses it shows the new version, and which characters you can use in the name of a file you upload.

Replace a file in place

To replace a file, upload the new file with exactly the same name, into the same folder.

1. Go to Assets and open the folder that holds the file you want to replace.
2. Click Upload and add the new file. Its file name must match the existing file's name.
3. Click Upload. Agility finds that a file with that name is already in the folder, and the dialog changes to This file already exists (or Some files already exist if you added several files).
4. Click Replace to overwrite the existing file with the new one, or Skip to keep the existing file.

A file with the same name in a different folder is a different file. Uploading there adds a new file and leaves the original alone.

What happens when you replace a file

• The URL stays the same. Every page, component and content item that uses the file shows the new version. You don't need to edit or republish them.
• The new file is live straight away. Assets have no draft or publish step. See Assets go live when you upload them.
• Agility clears the CDN cache for that file, so the CDN serves the new version right away. A browser that already downloaded the old file may keep showing its saved copy until that copy expires. A hard refresh in the browser loads the new file.

Before you replace a file, check where it's used. See Finding Where an Asset Is Used.

If you want to keep the old file (to switch back to it, or because the change should wait for a launch), upload the new file under a different name instead, and point your content at it when you're ready.

Characters you can use in file names

Agility won't upload a file whose name contains:

• Characters outside the basic English (ASCII) character set, such as accented letters, non-Latin scripts and emoji.
• Any of these characters: # $ & ? %

If you add a file like this, the upload dialog shows Some files contain characters in their name that are not URL-safe and won't be uploaded. The other files still upload. Rename the file on your computer and upload it again.

All other characters are allowed, including spaces, capital letters, hyphens, underscores, brackets and dots. By default Agility keeps the file name exactly as you uploaded it.

File names become part of the file's URL, so names made of lowercase letters, numbers and hyphens (for example team-photo-2026.jpg) give the cleanest URLs.

Convert Uploaded Media Files to Lower Case

An administrator can turn on Convert Uploaded Media Files to Lower Case in Global Configuration. When it's on, Agility changes the name of each file as you upload it:

• Spaces become hyphens.
• Any character other than a letter, number, hyphen, underscore or dot is removed.
• The name is converted to lowercase.

For example, Team Photo (2026).JPG is saved as team-photo-2026.jpg. The setting only affects new uploads. Files already in Assets keep their names.

When you replace a file with this setting on, Agility compares the converted name, so Logo.PNG replaces an existing logo.png in the same folder.

Renaming a file

You can also rename a file in Assets. Renaming can break existing links to the file, so check where it's used first. See Finding Where an Asset Is Used.

Related articles

• Introduction to Assets
• Adding an Asset
• Finding Where an Asset Is Used
• Editing Images