File Assets and dotAssets documentation for the dotCMS Content Management System

When creating files, you can choose to create files in two different ways, depending on how you plan to use the files. Each of these types of files are represented by a different Base Content Type, and has different advantages:

  • File Assets are files with a specific location within the Site Browser tree, and which can be accessed using a URL which references the location of the file within the tree. File Assets:
    • May be accessed via a URL based on either the location of the file within the Site Browser tree, or the Identifier of the file.
    • Can be managed via WebDAV, and can be used for File-based Containers and Scripted Custom Endpoints.
    • Can be displayed directly in menus (by setting the Show on Menu property).
  • dotAssets are files that are managed in a repository fashion, based on the type of the file, rather than being tied to a specific URL based on the Site Browser tree. dotAssets:
    • Are accessed via a URL based on the Identifier of the file.
    • Can only be displayed in menus using Menu Links.
    • Can be configured to manage files automatically based on the file MIME type.


Which type of file you choose will depend on how you plan to use files of that type. In general, files which are intended for access via a fixed URL are best implemented as File Assets, and files which are intended for use as internal assets (to be displayed on Pages but not downloaded individually) are best implemented as dotAssets.

Creating Multiple File Content Types

With both File Assets and dotAssets, you can create multiple different Content Types, and assign different files to different Content Types, based on the type of file, or how the files will be used. By default, File Asset Content Types have additional system fields that dotAsset Content Types don't have, but you may add any custom fields you wish to each Content Type, allowing you to have different fields appropriate for different types of files.

Automatic File Handling

Although only limited automated file handling is available for File Assets, full automatic file handling is available for dotAsset Content Types.

Default File Asset Content Type

Default File Asset Content Types may be assigned to each folder.

  • When you create a new file in a folder using the back-end console, you will be prompted for the File Asset Content Type to use for the new file, and the default Content Type for the folder will be selected by default, but may be changed.
  • When you upload a file to the folder using other methods (such as WebDAV), the new file will be automatically assigned the default File Asset Content Type specified for the folder.

Automatic Assignment of dotAsset Content Types

Each dotAsset Content Type is managed almost as a separate repository. In addition to manual assignment of files to specific dotAsset Content Types, you can also configure your dotAsset Content Types so different file types are automatically assigned to the appropriate Content Type, based on the file type (as determined by the MIME type of the uploaded file).

Setting the Acceptable File Types

Each dotAsset Content Type contains a Binary field named “Asset”. By default, this field has no restrictions on what types of files can be uploaded, or the maximum file size; however you may restrict both the file types which may be uploaded and the maximum size of uploaded files by adding Field Variables to the “Asset” field:

  1. Open the Content Types Tool (Content Model -> Content Types).
  2. Click the dotAsset Content Type to edit it.
  3. Edit the “Asset” field.
  4. Select the “FIELD VARIABLES” tab.
  5. Click the “+” button to add a new Field Variable.
  6. To restrict the types of files which can be uploaded, add a field variable with the following values:
    • Key: accept
    • Value: A list of the MIME types to accept, separated by commas.
  7. To limit the maximum size of files which can be uploaded, add a field variable with the following values:
    • Key: maxFileLength
    • Value: The maximum size (in bytes) to allow.

Automatic Content Type Assignment

When you upload a file using a method that does not specify the specific Content Type to use, dotCMS will automatically upload the file as a dotAsset, and will choose the specific dotAsset Content Type to use based on the MIME types specified in the accept field variable for each dotAsset Content Type.

For example, consider the following three dotAsset Content Types:

Content TypeValue of the accept Field Variable
Documentapplication/pdf,application/rtf,text/plain
Imageimage/*
Videovideo/*

When you drag-and-drop a PDF file into the dotCMS back-end interface, dotCMS will compare the MIME type of the file (application/pdf) with the accepted MIME types for each of the dotAsset Content Types, and automatically assign the uploaded file to the Document Content Type.

Resolving Conflicts

When more than one dotAsset Content Type can accept the MIME type of the uploaded file, dotCMS automatically resolves the conflict by selecting the dotAsset Content Type with the most restrictive value for the accept field variable. For example, consider the following three dotAsset Content Types:

Content TypeValue of the accept Field Variable
Audioaudio/*
PCM Audioaudio/pcm
Uncompressed Audioaudio/wav,audio/pcm,audio/aiff

If you drop a PCM audio file into the dotCMS back-end interface, the file could potentially be assigned to any of these Content Types. However, the most restrictive Content Type (PCM Audio) accepts only PCM files, so dotCMS will automatically assign the dropped file to this Content Type.

Troubleshooting Conflicts

In most cases, simply knowing that the more specific specification will be used will be enough to understand which Content Type will be selected. However, if you have a large number of dotAsset Content Types with overlapping accept specifications, you may need to carefully review your accepted file types to ensure dropped files are assigned to the Content Types you expect. The following specifies the rules used to automatically assign the Content Type, in order of priority (the lower the number, the higher the priority):

  1. Exact match: An exact match on the MIME type or file extension for a Content Type on the specific Site the file is uploaded to, AND that the uploading user has permission for.
    • An exact match on the Site will be prioritized over an exact match on the System Host.
  2. Wildcard match: A match for a wildcard (for example, audio/*).
    • A wildcard match on the Site will be prioritized over a wildcard match on the System Host.
  3. Content Types with no file type restrictions: Any Content Type which does not have an accept field variable at all, or which has the accept field variable set to the global wildcard (*/*)
    • An unrestriced Content Type on the Site will be prioritized over an unrestricted Content Type on the System Host.

If more than one Content Type matches with equal priority, the Content Type chosen will be the one with the first variable name in alphabetical sort order.