Knowledge Base

Working With Custom Hooks: OnUpload

This custom hook can help you keep your asset tree clean and organized - and ensure your team adheres to standards.

When a user uploads a physical file (such as a pdf, image, or video) the CMS creates an asset item in the Asset Tree to store metadata, settings, and taxonomy details about the file. The asset is automatically given the name of the file that was uploaded and can be changed by the user once it is in the Asset Tree. The URL for accessing the file is generated based on the location of the film in the Asset Tree. 

Administrators can control settings in the CMS that limit the type of assets end-users can upload. This can be done by setting restrictions on asset folders or by restricting security access to the schema that controls the file extension.

With this custom hook you are given the file that is being uploaded, the asset that is created from that file, and the user account that is uploading the asset.

This action can be triggered using the following methods:

  • Uploading an asset through the right-click context menu, the toolbar on an asset folder, or through the pop-up dialogue from the asset field in the edit form.
  • Triggering a script that uploads a file.


As always, avoid uploading a file with a script in the upload hook to prevent infinite loops.

Users might be uploading a large number of files to the CMS and too much scripting could slow down their ability to upload smoothly. If you plan to do a lot of massaging with scripts on these hooks you might consider fixing the items after they are uploaded with an automated task or custom tab instead, which can run during slower working times for the CMS.

Accessing the file stream and trying to work on contents of the file can be time consuming, so be judicious with your use of this ability.


Clean up asset names to match internal standards

There are often thousands of assets that go into the production of a website. These files need to be easy to find, which means they have to be effectively organized. Logical, well-planned naming conventions is one of the best ways to achieve this goal.

The following script updates the name of an asset to align with pre-determined naming conventions as a user attempts to upload it. In this example, we are updating the name of assets to ensure that they do not have any special characters or spaces, and that dashes are replaced with underscores, and that any repeated spaces, underscores, or dashes result in a single underscore.

First, make sure that the asset being uploaded exists and an error didn’t occur before trying anything else. Set a variable to contain your working name as you alter it. Then replace the spaces and dashes with underscores. Strip out the special characters with a regular expression. Normalize down any repeated underscores to just a single one. Then, run a function to strip any leading or trailing underscores in case the user had started or ended their file name with a space or dash. Finally, set the asset name to your variable name and save the asset.

public void OnNewAsset(IAssetItem asset, Stream file, IUserWriteSession session)


  if (asset != null)


                                  int outVar;

                                  //Replace spaces and dashes with _

                                  var tempName = Regex.Replace(asset.Name, " ", "_");

                                  tempName = Regex.Replace(tempName, "-", "_");

                                  //Remove special charactes besides letters and _

                                  tempName = Regex.Replace(tempName, @"[^0-9a-zA-Z_]+", "");

                                  //Replace multiple _ with one _

                                  tempName = Regex.Replace(tempName, @"_+", "_");

                                  //Remove last and first _

                                  tempName = ReplaceFirst(tempName, "_", "");

                                  tempName = ReplaceLast(tempName, "_", "");


                                  var newAssetName = tempName;


                                  asset.Name = newAssetName;




//Custom Functions for replacing First and Last instances of any string you give it and will replace with given string

                 public static string ReplaceFirst(string Source, string Find, string Replace)


                          int Place = Source.IndexOf(Find);

                          string result = Source.Remove(Place, Find.Length).Insert(Place, Replace);

                          return result;



                 public static string ReplaceLast(string Source, string Find, string Replace)


                          int Place = Source.LastIndexOf(Find);

                          string result = Source.Remove(Place, Find.Length).Insert(Place, Replace);

                          return result;


This script could be enhanced in the following ways: 

You could take this script further by considering other types of naming conventions you want to put in place. For example, you might locate the date from the file itself and append it to the file name or update the asset metadata with the username of the person who uploaded it. Both are potentially good ways to make an asset easier to find and use in the CMS.

  • Published: January 4, 2023
  • LAST UPDATED: September 18, 2023
  • Comments: 0

Please login to comment


There are no comments yet.