Implement a Custom File Upload Preprocessor

Info: Available in brXM 14.4.0 and later.

Overview

You can preprocess images and assets uploaded by CMS users before they are stored in the repository. For example, you might need to sanitize metadata in PDF files before publication.

Bloomreach Content allows you to implement custom file upload preprocessors in Java and configure them for use during file uploads.

Implementation Steps

1. Implement the IUploadPreProcessor Interface

Create a Java class that implements the org.hippoecm.frontend.plugins.yui.upload.model.IUploadPreProcessor interface. Deploy this class as part of your CMS application.

The process method receives an org.hippoecm.frontend.plugins.yui.upload.model.UploadedFile instance representing the uploaded file. You can read and modify the file in your implementation.

public class MyFileUploadPreprocessor implements IUploadPreProcessor {

    private static final long serialVersionUID = 1L;

    @Override
    public void process(UploadedFile uploadedFile) {
        // implement preprocessing here
    }

}

See Example: Set PDF Author for a complete implementation.

2. Configure the File Upload Preprocessor Service

Before registering your custom preprocessor, configure the file upload preprocessor service in the JCR repository:

/hippo:configuration/hippo:frontend/cms/cms-services/fileUploadPreProcessorService:
  jcr:primaryType: frontend:plugin
  plugin.class: org.hippoecm.frontend.plugins.yui.upload.processor.DefaultFileUploadPreProcessorPlugin
  pre.processor.id: service.upload.pre.processor
  /preProcessors:
    jcr:primaryType: frontend:pluginconfig

Configuration properties:

Property name	Type	Description
`plugin.class`	String	Fully qualified class name of the service. Use `org.hippoecm.frontend.plugins.yui.upload.processor.DefaultFileUploadPreProcessorPlugin`.
`pre.processor.id`	String	Unique identifier for the service. Use the default `service.upload.pre.processor` unless you need multiple services.

The preProcessors node is the parent for your preprocessor configuration nodes.

3. Register Preprocessor Implementations

Add your custom preprocessor configuration under the preProcessors node:

/hippo:configuration/hippo:frontend/cms/cms-services/fileUploadPreProcessorService/preProcessors/myfileuploadpreprocessor:
  jcr:primaryType: frontend:pluginconfig
  className: org.example.MyFileUploadPreProcessor

Configuration property:

Property name	Type	Description
`className`	String	Fully qualified class name implementing the `IUploadPreProcessor` interface.

You can register multiple preprocessors by adding additional configuration nodes.

Example: Set PDF Author

The following example sets the author metadata on uploaded PDF files. This implementation uses Apache PDFBox.

package org.hippoecm.frontend.plugins.yui.upload.preprocessors;

import java.io.File;
import java.io.IOException;

import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.PDDocumentInformation;
import org.hippoecm.frontend.plugins.yui.upload.model.IUploadPreProcessor;
import org.hippoecm.frontend.plugins.yui.upload.model.UploadedFile;

public class AuthorFileUploadPreProcessor implements IUploadPreProcessor {
    @Override
    public void process(final UploadedFile uploadedFile) {

        String mimeType = uploadedFile.getContentType();

        PDDocument pdDocument = null;
        if(mimeType.equals("application/pdf")) {
            try {
                File file = uploadedFile.getFile();
                pdDocument = PDDocument.load(file);
                PDDocumentInformation info = pdDocument.getDocumentInformation();
                info.setAuthor("Processed by BRXM author");

                pdDocument.save(file);
            } catch (IOException e) {
                // do nothing
            } finally {
                try {
                    if (pdDocument != null) {
                        pdDocument.close();
                    }
                } catch (IOException e) {
                    // do nothing
                }
            }
        }
    }
}

Configuration for this preprocessor:

/hippo:configuration/hippo:frontend/cms/cms-services/fileUploadPreProcessorService:
  jcr:primaryType: frontend:plugin
  plugin.class: org.hippoecm.frontend.plugins.yui.upload.processor.DefaultFileUploadPreProcessorPlugin
  pre.processor.id: service.upload.pre.processor
  /preProcessors:
    jcr:primaryType: frontend:pluginconfig
    /pdf-author:
      jcr:primaryType: frontend:pluginconfig
      className: org.hippoecm.frontend.plugins.yui.upload.preprocessors.AuthorFileUploadPreProcessor

Configure Different Preprocessor Services for Different Upload Types

By default, configured preprocessors apply to all uploaded files. You can also configure separate preprocessor services for specific upload types:

Images uploaded through the Images gallery in the Content application
Assets uploaded through the Assets gallery in the Content application
Images uploaded via the image picker in image and rich text fields
Files uploaded to embedded resource fields in documents

To do this, create a preprocessor service with a unique pre.processor.id:

/hippo:configuration/hippo:frontend/cms/cms-services/imagepreprocessorservice:
  jcr:primaryType: frontend:plugin
  plugin.class: org.hippoecm.frontend.plugins.yui.upload.processor.DefaultFileUploadPreProcessorPlugin
  pre.processor.id: image.preprocessor.id
  /preProcessors:
    jcr:primaryType: frontend:pluginconfig
    /image-preprocessor:
      jcr:primaryType: frontend:pluginconfig
      className: org.example.ImageUploadPreprocessor

Set the pre.processor.id property to a unique value (e.g., image.preprocessor.id). This value must be different from the default and any other configured service IDs.

Configure preprocessors as child nodes of the preProcessors node as shown above.

Link Preprocessor Services to Upload Types

To associate a preprocessor service with a specific upload type, add the matching pre.processor.id property to the relevant configuration node:

/hippo:configuration/hippo:workflows/gallery/image-gallery/frontend:renderer
For images uploaded through the Images gallery in the Content application.
/hippo:configuration/hippo:workflows/gallery/asset-gallery/frontend:renderer
For assets uploaded through the Assets gallery in the Content application.
/hippo:namespaces/hippogallerypicker/imagelink/editor:templates/_default_/root
For images uploaded via the image picker in image and rich text fields.
/hippo:namespaces/hippo/resource/editor:templates/default/upload
For files uploaded to embedded resource fields in documents.

Example configuration for image gallery uploads:

/hippo:configuration/hippo:workflows/gallery/image-gallery/frontend:renderer:
  jcr:primaryType: frontend:plugin
  fileupload.maxItems: '25'
  gallery.processor.id: service.gallery.processor
  gallery.thumbnail.size: 60
  option.label: add-image
  option.text: add-image-label
  plugin.class: org.hippoecm.frontend.plugins.gallery.GalleryWorkflowPlugin
  pre.processor.id: my.preprocessor.id
  validator.id: service.gallery.image.validation

Behavior:

If an upload method has a pre.processor.id property, only the corresponding preprocessor service is applied to files uploaded by that method.
If no pre.processor.id is configured, only the default preprocessor (service.upload.pre.processor) is applied.

Verification

Upload a file using the configured method.
Confirm that the custom preprocessor modifies the file as expected (for example, check the PDF author metadata).

Troubleshooting

If the preprocessor does not run, verify that the class is deployed and the configuration paths and class names are correct.
Ensure that the pre.processor.id values match between the service and the upload method configuration.
Check logs for errors during file upload processing.