File Manager

The File Manager is used to create documents from simple binaries.

From a user perspective, the Nuxeo Platform offers many ways to capture a binary so as to make it a document with a binary property. It can be done from the browser's drag and drop, from the upload REST API, from WebDAV, from CMIS, from Nuxeo Drive, ...

Hyland University

Watch the related expert session on Hyland University:
File Manager Expert Session

The File Manager service is a traditional Nuxeo Platform service that offers some methods that help standardize what happens when a file is captured in the Platform, in regard to:

What document type should be created.
What is the property mapping logic.
How should the binary be processed (exploding a zip, doing some pre-persistence conversions).

Customising and Using the File Manager Service

The File Manager service has a plugin architecture, so that it is possible to contribute different policies depending on the MIME type of the file and the context. The default Nuxeo Platform use cases of the File Manager can be customised reading the documentation of the File Manager service extension point. There is also a helper for implementing binary unicity checks.

The File Manager can be called and used in your custom Java code with the standard service call pattern:

... fileManager = Framework.getService(FileManager.class);
FileImporterContext context = FileImporterContext.builder(coreSession, blob, parentPath)
    .overwrite(true)
    .fileName(fileName)
    .build();
DocumentModel createdDoc = fileManager.createDocument(context);

The File Manager relies on the FileImporterContext class that contains everything needed to create a document from a blob.

You can also use the FileManager.Import Automation operation, which provides a way to create in one REST call a document from a binary, or to create easily a document from a blob in an Automation chain.
There is also the FileManager.ImportWithProperties Automation operation, which provides a way to create in one REST call a document from a binary and set properties on it.

The versioning policies applied to the File Manager are the ones defined globally for the platform, see the Automatic Versioning section of the Versioning page.
Please note that if the file name of FileImporterContext is missing then it will be filled with the Blob's file name.

Implementing Your Own Plugin

Let's take a simple example where the document type depends on the parent folder type. In order to do that in a fully automated way, you'll need to implement your own plugin. For example, we have a folder type PurchaseOrderFolder which accepts only PurchaseOrder documents as children, and an InvoiceFolder which accepts only Invoice documents.

Write a class which extends org.nuxeo.ecm.platform.filemanager.service.extension.AbstractFileImporter.

public class SampleFilemanagerPlugin extends AbstractFileImporter {

    private static final long serialVersionUID = 1L;

    @Override
    public DocumentModel createOrUpdate(FileImporterContext context) throws NuxeoException {

        PathRef parentRef = new PathRef(context.getParentPath());
        DocumentModel parentDoc = session.getDocument(parentRef);
        DocumentModel doc = null;
        switch (parentDoc.getType()) {
        case "PurchaseOrderFolder":
            doc = createDocType(context, "PurchaseOrder");
            break;
        case "InvoiceFolder":
            doc = createDocType(context, "Invoice");
            break;
        default:
            break;
        }
        if (doc != null) {
            doc = session.createDocument(doc);
        }
        return doc;
    }

    protected DocumentModel createDocType(FileImporterContext context, String type) {
        Blob blob = context.getBlob();
        String fileName = context.getFileName();
        DocumentModel doc = session.createDocumentModel(path, fileName, type);
        doc.setPropertyValue("dc:title", fileName);
        doc.setPropertyValue("file:content", (Serializable) blob);
        return doc;
    }
}

The createdOrUpdate method returns either a DocumentModel object or null. If null is returned, then the File Manager service will try with the next plugin. Within this method, we have access to the destination path which enables us to determine the type of the folder and thus create a document with the relevant type.

Add a new contribution to the File Manager service.

 <component name="org.nuxeo.sample.filemanager">
     <extension target="org.nuxeo.ecm.platform.filemanager.service.FileManagerService" point="plugins">
         <plugin name="SampleImporter" class="org.nuxeo.sample.SampleFilemanagerPlugin" order="0">
             <filter>.*</filter>
         </plugin>
     </extension>
 </component>

That's it!