By default, Vidispine names new files according to site-id-number**``.``**extension, all in one folder. This pattern can be overridden. This section describes three very different ways.

Using a tree structure for files

Putting all files in the same directory of a storage can cause degraded performance on some file systems. By setting the configuration property fileHierarchy, the naming convention is changed to site-id - number1 / number2 . extension. The number set in fileHierarchy controls the size of number2. Example:

fileHierarchy not set, or 0

fileHierarchy =100

fileHierarchy =1000







Note that the splitting into subdirectories is currently only done in one level, so no VX-4/72/32.mp4.

The configuration property may be changed at any time, but old files will not be renamed.

Storage name rules

A storage name rule dictates the filename that the file of a particular shape should have on a certain storage. Note that these rules doesn’t make sure a file is actually located on a storage, it just says what filename a file should have if it is located on that storage. Storage name rules are often used together with storage rules

Naming files on storage

The default naming convention of can be overridden on a per-storage basis by associating a JavaScript script to the storage.

The script will be invoked whenever a file needs to be created on the storage.

Setting the script

The JavaScript is stored as metadata filenameScript to the storage. That is, the code is set using PUT /storage/(storage-id}/metadata/filenameScript.

If using curl, use --data-binary instead of -d to make sure all new-line characters are kept.


In the execution context of the script, there is a variable named context, which has the following functions:


Returns a ShapeType (see Vidispine XSDs) object.

For example, to get the essence version, use context.getShape().getEssenceVersion(). Can return null.


Returns a java.util.Map<String,String>. Can be null.


Returns an ItemType, which is the same output as GET /item/(item-id)?content=metadata,shape,access,external. Can return null.


Returns a StorageType.


Returns a ComponentType. Can return null.


Returns the suggested extension for the file. Can return null.


Returns the file id of the file to be created.


Returns a java.util.Collection<String> of the shape tags of the shape the file belongs to.


Returns the original filename that was used when item was imported.


Returns the original filename that was used when component was created.


Most of the time this will return null, except when you want to split audio channels to separate files.


Returns the job id.


Returns the job type.


The script should return (last value) the file name of the file.

Existing file names

If the suggested file name is already in use on the Storage, the script will be called again, up to 10 times. The new invocations will run in the same context as the previous, so it is possible to store information, e.g. sequence numbers, to not repeat the same file name.


var l = "foobar-"+context.getStorage().getId()+"/"+context.getFileId();
if (context.getExtension() != null)
    l += "."+context.getExtension();