Using dotCMS as a Document Management System (DMS)

$URLMapContent.title

Using dotCMS as a Document Management System (DMS) Posted: 06.04.2012

A Document Management System allows users to organize and manage electronic documents. It provides the ability to access, modify and centrally store these documents. It is also capable of keeping track of all changes (versions), by different users.

In this blog post we will discuss how to implement a Document Management System using dotCMS and utilize Files as Content.

Let’s get started!

Creating a Document File Type

As of dotCMS 2.0, files have become a Content type, lending files additional benefits, such as:

  • Versioning
  • Additional Custom Fields
  • Tags and Categories
  • Metadata
  • File Field Search (stored in lucene)
  • Custom Defined Workflows

First, we will need to create a new File Type called Document. Click on Structures, and then on Add New Structure. On the next page, select File as your Structure Type.

Add additional fields to the newly created Document structure such as: Description, Publish Date, Author and taxonomy such as the Topic category and a Tag field.

In dotCMS, you can create many different categories and associate them with a file type. To add new categories go to Structures → Categories. Once created, they will be available for use on the Document structure.

Adding Documents to the Repository

To upload Documents to the central repository, go to Website Browser and right click on a folder: “New → Image or File”

Documents can also be uploaded using WebDav. To upload files using WebDav, make sure there are not required fields on the Document structure.

All uploaded Documents can be viewed and searched on the Content tab.

Since dotCMS 2.0, when a new file is uploaded, its metadata is extracted and stored in the content as additional fields. These fields can then be accessed by dynamic widget code (Velocity), to either search file fields and/or display their metadata.

Creating the DMS Widgets

Widgets are pieces of HTML/Velocity code which create dynamic displays of content. For the DMS we will be creating the following simple widgets:

  • Document Listing
  • Document Search
  • Document Detail

Click here for more information on how to create a simple widget.

Now let's see how the Widgets on the Demo site’s Resources section are designed to work.

The Document Listing Widget pulls file content from the central repository and displays it on a listing page. It uses the search parameters to filter the results, if any are passed.

The entire code for this Widget can be found on the demo site on the shared host under: /vtl/widgets/full-site/document-listing.vtl

Let’s go over some of the important sections of the widget’s code in more detail:

  1. Retrieve all request parameters: search keyword, categories, tags and file extension. These are all set on the Document Search Widget
  2. Split the Categories, if any, and create a categories lucene query on $catVar
  3. Split the Tags, if any, and create a tags lucene query on $tagVar
  4. Based on the file extension selected, if any, create a metadata lucene query on variable $extVar. This query uses the metadata contentType field.
  5. If "ALL" is selected, it uses the new keyword _all to search in lucene.
  6. It creates the complete lucene query on the variable $_qk
  7. Uses the variables pageNumber and numberToPull to return the results paginated
  8. Once the query is created, it calls the $dotcontent api to pull the results respecting pagination and ordering the results by modified date.
    #set($mypagelist = $dotcontent.pullPerPage("${_qk}",${pageNumber},${numberToPull},"modDate desc"))
  9. The returned results on $mypagelist are looped through and the following fields are displayed on the page: image or icon, title, author, publish date, and a shortened description.
  10. The widget displays at the end links with pagination tools to allow movement to the previous and next pages of results, if any are returned.

The Document Search Widget displays a search box with options to search for All, Image, Video or Document. It also displays a list of all Topics (categories), and Tags used in the Documents stored in the system.

When a Topic or Tag is selected, the filters are all maintained to refine the search. Filters can be cleared after they have been selected.

The entire code for this Widget can be found on the demo site on the shared host under: /vtl/widgets/full-site/document-search.vtl.

Let’s go over the widget’s code in detail:

  1. Retrieve all request parameters: search keyword, categories, tags and file extension.
  2. If either a category, tag, file type or search keyword has been entered, the widget displays the filters. It also allows the user to Clear all filters selected.
  3. Displays a keyword search box with options to search on All files, images, videos or documents (based on metadata content type)
  4. Displays all categories associated with the Document by key using: $categories.getChildrenCategoriesByKey("topic")
  5. Displays all tags saved on the Document file type using: #set($tagCloudStructures = $webapi.splitString("Document", ","))
    #set($tagsCount = $macro.getTagsCount($tagCloudStructures, 99, $ignoredTags, $request))

The Document Detail Widget displays the Document’s fields on the page based on a variable id passed in the request. In dotCMS 2.0, File Types don’t allow users to set a URL Map Pattern and Detail Page to have SEO friendly URLs as provided in Content Types, however, this feature will be implemented in an upcoming version.

The code for this Widget can be found on the demo site on the shared host under: /vtl/widgets/full-site/document-detail.vtl.

This widget uses the $dotcontent api to find the requested document based on id:


#set ($content = $dotcontent.find($request.getParameter("id")))

The following fields are displayed:

  • Metadata Content Type
  • Based on the Metadata’s content type displays either an image, a video player, an mp4 player, or a link to download the document.
  • Description
  • Publish Date
  • Categories
  • Tags
  • Metadata

Once all the Widgets have been created, all that is left to do is to add them on the html pages. For our example we created two pages under /resources/: index.dot and document-detail.dot.

Some improvements that can be made to our demo examples are: to do the search on the Document Listing using AJAX (to make this demo easier to understand we decided to use a simpler approach and reload the page whenever the search is executed) and also to provide a way for frontend users to upload documents to the Document Management System (users can register on the frontend or just login based on your requirements).

As of the 2.0 version, dotCMS can now also be used as a Document Management System, by allowing users to create different File Structure Types, add custom fields, and extract the file’s metadata when its uploaded.

Email me if you have any questions or feedback about this post.



New report from Digital Clarity Group notes that a majority of digital marketing teams don’t or can’t use all the software capabilities they have, creating “shelfware” or “underused” software. Gain fresh perspective on the challenges facing digital marketers. Download Now.