HOWTO: Create and Use Document Facets

Updated: May 27, 2021

Document facets can be attached dynamically to implement specific business logic.

Nuxeo University


Enabling a facet on a Nuxeo document adds additional functionality. Facets can be used to attach a schema to a document. It can be interpreted by Nuxeo Web UI to display additional data or views of the document, like:

  • Folderish: Can be a parent to specified document types.
  • NXTag: Can be tagged, includes the tag schema.
  • Picture/Video: Changes how the document is displayed to show document conversions, multimedia information extraction.
  • etc.

Use Case

We will create a new facet, entitled ValidityFacet, which is applied to any approved document. The facet is linked to a custom schema called validity which provided information about the validity period of a document.

Create the Validity Schema

  1. In Studio Modeler, create a new external schema in Configuration > Content Model > Schemas, called validity.
  2. Add two Date properties: ValidityStartFrom and ValidityEndsIn.

Create the Facet to the Studio Registry

The next step is about registering the new built-in document facet.

  1. In Studio Modeler, navigate to Settings > Registries > Document Facets.
  2. Add the new facet using the example provided in the upper section:
  "facets": [
      "id": "ValidityFacet",
      "description": "Facet applied to all new validated document"

At this step, you should see the ValidityFacet checkbox in the Definition screen of your document type.

In Studio Modeler, create an XML Extension in Configuration > Advanced Settings > XML Extensions to associate the facet with the schema previously created:

<extension point="doctype" target="org.nuxeo.ecm.core.schema.TypeService">
  <facet name="ValidityFacet">
    <schema name="validity" />

Add Business Logic

Nuxeo Studio exposes the Document.AddFacet automation operation so that you can add the facet dynamically:

  • You can execute it from an Event Handler (Like On Document Created event with some criteria, like the document location, or the document lifecycle state in our example).
  • You can also trigger this operation from a button, created in Nuxeo Studio Designer.

Design Your Visual Element

There is no default UI component for the facet, so it needs to be created manually, either from the UI > Layout Blocks menu, or directly in the Resources tab.

Then, you can add the following condition in your elements and layouts to display or not the facet information:

<template is="dom-if" if="[[hasFacet(document, 'ValidityFacet')]]">
  <!-- Code of the UI element displaying the facet information -->

We'd love to hear your thoughts!

All fields required