Standard Decorators

Introduction

To store documents in the UDM using Document.save, you will first need to store content types with their decorators, using the ContentType package. The documents to be saved will be validated, and only stored in the database if they comply with the defined content type. Which decorators to use is an important decision, because it influences the degree of re-usability of the connector you are building; more use of standard decorators generally means better re-usability.

This document provides a list of standard decorators that can be used in any migration project. While it is not mandatory to use these decorators, a lot of robots make use of them. It is advised to always first look to use standard decorators before inventing your own.

Most fields in the standard decorators are required. If you have no way of providing the required information for every document, please do not fill the field with fake information, but rather consider using a custom decorator as fake information may break other robots that depend on accurate data.

List of all standard decorators

file

The file decorator is used to describe a physical (downloadable) file. 

var file = {
     "name" : {
          "type": "STRING",
          "required" : true
     },
     "extension" : {
          "type": "STRING",
          "required": true
     },
     "rawExtension" : {
          "type": "STRING",
          "required": false
     },
     "path" : {
          "type" : "STRING",
          "required" : true
     },
     "size": {
          "type" : "NUMBER",
          "required": true
     }
}; 

The "name" field holds the full name + extension of the file.

Together with the "name" field and the "path" field, the "extension" field is indispensable when it comes to migrating a file. It is also useful for file analysis. A report can be generated to give an overview of the number of files with a particular extension.

The "extension" field is required and holds the extension of the file. In projects where extensions are validated against a set of business rules the field "extension" should be filled with an empty string (indicating the extension is empty) when the extension was found invalid, and the field "rawExtension" should be used to store what might have been the extension.

The "path" field gives the physical location of the file on the file system or as a link where it can be downloaded. It serves to seperate concerns between the virtual location as is indicated using the parent decorator vs the actual location where it can be obtained.

The "size" field can also be used for file analysis. Based on this field, a decision can be made on whether to migrate or not files that are very large and rarely accessed.

hash

The hash decorator is an addition to the file decorator. It has been created as a separate decorator because the hash of a file is not always needed in a migration.

var hash = {
     "md5" : {
          "type" : "STRING",
          "required": true
     }
};

The "md5" field contains the hash of the file content. The field is useful for identifying file duplicates.

mimeType

The mimeType decorator comes also as an addition to the file decorator.

It has been created as a separate decorator because the media type of a file is also not always needed in a migration. Moreover, it may even not be available.

var mimeType = {
     "type" : {
          "type" : "STRING",
          "required" : true
     }
};

The "type" field gives the media type of the file. Along with the extension, the media type offers some extra information about the file type. Sometimes the extension alone is not enough for a system to know how to handle a file. In that case storing also the MIME type of a file would be required.

document

The document decorator is valid for all files and folders, but also for other content types. A content type which is not a file or a folder, can still be a document.

var document = {
    "title" : {
          "type" : "STRING",
          "required" : true
     },
     "author" : {
          "type" : "STRING",
          "required" : true
     }
};

To be able to import a document into a target system, both the "title" field and the "author" field are required. When a formal document title cannot be extracted from the system, it is good practice to just enter the filename.

created

The created decorator is an addition to the document decorator. This decorator shows when and by who the document has been created. This kind of metadata is usually desired to be migrated to the target system. Because it's not always available, this information is separated from the modified decorator. 

var created = {
    "date" : {
          "type" : "DATE",
          "required" : true,
     },
     "by" : {
          "type" : "STRING",
          "required" : false,
     }
}

 The "date" fields holds the date on which the document was created. The optional field "by" contains the name of the user who created the document.

modified

The modified decorator is an addition to the document decorator. This decorator shows when and by who the document has been modified. This kind of metadata is usually desired to be migrated to the target system. Because it's not always available, this information is separated from the  created decorator. 

var modified = {
     "date" : {
          "type" : "DATE",
          "required" : true
     },
     "by" : {
          "type" : "STRING",
          "required" : false
     }
};

The "date" fields holds the date on which the document was modified. The optional field "by" contains the name of the user who created the document.

parent

The parent decorator is an addition to the file and folder decorators. It describes where the entry fits in the content repository structure.

var parent = {
     "id" : {
          "type" : "STRING",
          "required" : true
     },
     "path" : {
          "type" : "STRING",
          "required" : true
     }
};

The "id" field is a reference to the ID of the parent entry. This ID was generated by MongoDB when the parent was saved to the database, and returned by the function Document.save. The record representing the parent of a document can be easily found in the database by using this field for the child. 

The "path" field gives the full path of the parent. The parent path helps to easily reconstruct the folder hierarchy when migrating to a target system. 

folder

The folder decorator is to be used with all migration documents that are folders.

var folder = {
     "name": {
          "type": "STRING",
          "required": true
     },
     "path" : {
         "type": "STRING",
          "required": true
     }
};

The "name" field gives the name of the folder. The "path" field gives the location of the folder on the file system. 

Both fields are necessary to be able to migrate a folder to a target system. 

folderStatistics

The folderStatistics decorator is an addition to the folder decorator.

It has been created as a separate decorator because knowing the number of files and folders is not always relevant in a migration.

var folderStatistics = {
      "folderCount" : {
          "type" : "NUMBER",
          "required" : true
     },
     "fileCount" : {
          "type" : "NUMBER",
          "required" : true
     }
};

The "folderCount" represents the number of folders located in the folder tree. The "fileCount" represents the number of files located in the folder tree. 

Both fields are useful for analysis. A report can be generated to compute statistics on the folder hierarchy. 

permissions

The permissions decorator contains the security definitions for the system from which the content is being extracted. 

This decorator is an addition to the document decorator, since a migration of permissions is not always required.

var permissions = {
    "users" : {
        "type" : "LIST",
        "required" : true
    },
     
    "groups" : {
        "type" : "LIST",
        "required" : true
    }
};

The decorator is split into two fields: a "users" field and a "groups" field. Both fields are of type LIST, since a document might have permissions for more than one user or more than one group.

audit

The audit decorator contains the history of all events associated to the document. 

This decorator is also an addition to the document decorator. Not all migrations require a migration of history events. Therefore, this decorator is created separately from the document decorator.

var audit = {
    "events" : {
        "type" : "LIST",
        "required" : true
    }
};

The "events" field provides a list of all document events which occurred in the past. For example, when and who has added a new document version, when and who has changed the document permissions, when and who has moved the document, etc.

Include the library robot

A library robot has been added to this article. It makes all standard decorators ready for usage immediately with one function call. Put this robot (with its folders) in the root folder of your project and add the following code to your own robot: 

use ContentType;

include com.xillio.contenttypes.StandardDecorators;
// (any code here)
var standardDecorators = getStandardDecorators();
// now, for instance, you can save the content type 'file' with two standard decorators like this:
ContentType.save("file",[standardDecorators.file,standardDecorators.hash]);

 Improving this list

This list of standard decorators will be maintained while new projects are coming along. If you, the reader, believe that certain standard decorators should be improved or added, please let us know by entering a ticket with the buttons below.