REST API

Content Enricher

 

Extract from the course "Working with the REST API" on Nuxeo University

Pluggable Context

It is sometimes useful to optimize the number of requests you send to the server. For that reason we provide a mechanism for requesting more information on the answer, simply by specifying the context you want in the request header.

For example, it is some times useful to get the children of a document while requesting that document. Or its parents. Or its open related workflow tasks. The Nuxeo Platform provides you with several content enrichers out of the box for the most common use cases, and you can contribute your own if needed.

How To Call a Content Enricher

Content enrichers can be called by sending the proper header(s) in your request. The header you need to call depends on the entity-type being enriched by the enricher. Hence, enrichers enriching documents can be called using the header:

X-NXenrichers.document: enricherName

If you want to call an enricher enriching a user for instance, you would do it through a slightly different header:

X-NXenrichers.user: enricherName

Several enrichers can be called in a single request by specifying a comma separated list in the header, or by sending several headers:

X-NXenrichers.document: enricher1,enricher2,enricher3

is equivalent to sending:

X-NXenrichers.document: enricher1
X-NXenrichers.document: enricher2
X-NXenrichers.document: enricher3

and combination would work.

The enrichers can be called the same way by passing GET parameters.

http://NUXEO_SERVER/nuxeo/site/api/v1/path/default-domain/workspaces?enrichers.document=enricher1,enricher2
http://NUXEO_SERVER/nuxeo/site/api/v1/path/default-domain/workspaces?enrichers.document=enricher1&enrichers.document=enricher2

Default Content Enrichers

Thumbnail

When specifying X-NXenrichers.document: thumbnail, the JSON payload of the document REST calls response that contains the related attached file thumbnail of the document:

Call Example

Request URL:
http://localhost:8080/nuxeo/api/v1/id/4246ca87-c076-4bf4-b62b-0bab9dd21102
 Request Method:
 GET
 Request Headersview source
 ...
 Content-type:
 application/json+nxentity
 X-NXenrichers.document:
 thumbnail
 X-NXproperties:
 dublincore

JSON Response Example

{
    "entity-type": "document",
    "repository": "default",
    "uid": "4246ca87-c076-4bf4-b62b-0bab9dd21102",
    "path": "/default-domain/workspaces/Marketing/photo.jpg",
    "type": "Picture",
    "state": "project",
    "parentRef": "036f99ec-a500-4a1e-9d89-e8eb656a0ff7",
    "isCheckedOut": true,
    "changeToken": "1426696491000",
    "title": "photo.jpg",
    "lastModified": "2015-03-18T16:34:51.00Z",
    "properties":
    {
        "dc:description": "",
        ...
    },
    "facets":
    [
        "Versionable",
        ...
    ],
    "contextParameters":
    {
        "thumbnail":
        {
            "url": "http://localhost:8080/nuxeo/nxthumb/default/4246ca87-c076-4bf4-b62b-0bab9dd21102/thumb:thumbnail/Small_photo.jpg"
        }
    }
}

More details about the thumbnail enricher: http://community.nuxeo.com/api/nuxeo/release-7.10/javadoc/org/nuxeo/ecm/platform/ui/web/io/ThumbnailJsonEnricher.html

ACLs

When specifying X-NXenrichers.document: acls, the JSON payload of the document REST calls response that contains all related ACLs of the document:

Call Example

Request URL:
http://localhost:8080/nuxeo/api/v1/id/036f99ec-a500-4a1e-9d89-e8eb656a0ff7
Request Method:
GET
Request Headers
...
Content-type:
application/json+nxentity
X-NXenrichers.document:
acls
X-NXproperties:
dublincore

JSON Response Example

{
    "entity-type": "document",
    "repository": "default",
    "uid": "036f99ec-a500-4a1e-9d89-e8eb656a0ff7",
    "path": "/default-domain/workspaces/Marketing",
    "type": "Workspace",
    "state": "project",
    "parentRef": "02d7b1d5-791a-4939-ae6e-aaa75c05bd2c",
    "isCheckedOut": true,
    "changeToken": "1426695969000",
    "title": "Marketing",
    "lastModified": "2015-03-18T16:26:09.00Z",
    "properties":
    {
        "dc:description": "",
        ...
    },
    "facets":
    [
        "Folderish",
        ...
    ],
    "contextParameters":
    {
        "acls":
        [
            {
                "name": "local",
                "aces":
                [
                    {
                        "username": "jsmith",
                        "permission": "ReadWrite",
                        "granted": true
                    }
                ]
            },
            {
                "name": "inherited",
                "aces":
                [
                    {
                        "username": "jdoe",
                        "permission": "Everything",
                        "granted": true
                    },
                    {
                        "username": "Administrator",
                        "permission": "Everything",
                        "granted": true
                    },
                    {
                        "username": "members",
                        "permission": "Read",
                        "granted": true
                    }
                ]
            }
        ]
    }
}

More details about the acls enricher: http://community.nuxeo.com/api/nuxeo/release-7.10/javadoc/org/nuxeo/ecm/permissions/ACLJsonEnricher.html

Preview

When specifying X-NXenrichers.document: preview, the JSON payload of the document REST calls response that contains the related attached file preview of the document:

Call Example

Request URL:
http://localhost:18090/api/v1/repo/test/path/folder_1/photo.jpg
 Request Method:
 GET
 Request Headersview source
 ...
 Content-type:
 application/json+nxentity
 X-NXenrichers.document:
 preview
 X-NXproperties:
 dublincore

JSON Response Example

{
    "entity-type": "document",
    "repository": "default",
    "uid": "4246ca87-c076-4bf4-b62b-0bab9dd21102",
    "path": "/default-domain/workspaces/Marketing/photo.jpg",
    "type": "Picture",
    "state": "project",
    "parentRef": "036f99ec-a500-4a1e-9d89-e8eb656a0ff7",
    "isCheckedOut": true,
    "changeToken": "1426696491000",
    "title": "photo.jpg",
    "lastModified": "2015-03-18T16:34:51.00Z",
    "properties":
    {
        "dc:description": "",
        ...
    },
    "facets":
    [
        "Versionable",
        ...
    ],
    "contextParameters":
    {
        "preview":
        {
            "url": "http://localhost:8080/nuxeo/restAPI/preview/default/4246ca87-c076-4bf4-b62b-0bab9dd21102/default/"
        }
    }
}

More details about the preview enricher: http://community.nuxeo.com/api/nuxeo/release-7.10/javadoc/org/nuxeo/ecm/platform/preview/io/PreviewJsonEnricher.html

Call Example

Request URL:
http://localhost:8080/nuxeo/api/v1/id/4246ca87-c076-4bf4-b62b-0bab9dd21102
 Request Method:
 GET
 Request Headersview source
 ...
 Content-type:
 application/json+nxentity
 X-NXenrichers.document:
 breadcrumb
 X-NXproperties:
 dublincore

JSON Response Example

{
    "entity-type": "document",
    "repository": "default",
    "uid": "4246ca87-c076-4bf4-b62b-0bab9dd21102",
    "path": "/default-domain/workspaces/Marketing/IMG_20141004_132816.jpg",
    "type": "Picture",
    "state": "project",
    "parentRef": "036f99ec-a500-4a1e-9d89-e8eb656a0ff7",
    "isCheckedOut": true,
    "changeToken": "1426696491000",
    "title": "IMG_20141004_132816.jpg",
    "lastModified": "2015-03-18T16:34:51.00Z",
    "properties":
    {
        "dc:description": "",
       ...
    },
    "facets":
    [
        "Versionable",
        ...
    ],
    "contextParameters":
    {
        "breadcrumb":
        {
            "entity-type": "documents",
            "entries":
            [
                {
                    "entity-type": "document",
                    "repository": "default",
                    "uid": "42bbc2f6-13bd-4eb1-8c35-07342358f5f8",
                    "path": "/default-domain",
                    "type": "Domain",
                    "state": "project",
                    "parentRef": "22288b40-7879-4665-b01e-b9bacb132506",
                    "isCheckedOut": true,
                    "changeToken": "1426694633000",
                    "title": "Default domain",
                    "lastModified": "2015-03-18T16:03:53.00Z",
                    "facets":
                    [
                        "Folderish",
                        ...
                    ]
                },
                {
                    "entity-type": "document",
                    ...
                },
                {
                    "entity-type": "document",
                    ...
                },
                {
                    "entity-type": "document",
                    ...
                    ]
                }
            ]
        }
    }
}

More details about the breadcrumb enricher: http://community.nuxeo.com/api/nuxeo/release-7.10/javadoc/org/nuxeo/ecm/core/io/marshallers/json/enrichers/BreadcrumbJsonEnricher.html

Other Enrichers

Additional enrichers are:

Contributing Your Own Content Enricher

Adding a content enricher is done by providing a Java class and a XML contribution. You can enrich a Nuxeo Document Model or any kind of specific object returned.

Document Model Content Enricher

Here is a sample to get you started, that provides a document's parent id, title and description.

<?xml version="1.0" encoding="UTF-8"?>
<component name="org.nuxeo.sample.enrichers.parentDocEnricher">
<!-- Start copying here if you declare the enricher in Nuxeo Studio -->
<extension target="org.nuxeo.ecm.core.io.MarshallerRegistry" point="marshallers">
  <register class="org.nuxeo.university.enrichers.ParentDocEnricher" enable="true" />
</extension>
<!-- Stop copying here if you declare the enricher in Nuxeo Studio -->
</component>

package org.nuxeo.sample.enrichers;

import static org.nuxeo.ecm.core.io.registry.reflect.Instantiations.SINGLETON;
import static org.nuxeo.ecm.core.io.registry.reflect.Priorities.REFERENCE;

import java.io.IOException;

import org.codehaus.jackson.JsonGenerator;
import org.codehaus.jackson.map.ObjectMapper;
import org.codehaus.jackson.node.ObjectNode;
import org.nuxeo.ecm.core.api.CoreSession;
import org.nuxeo.ecm.core.api.DocumentModel;

// The class will be instanciated as a singleton
// Priority defines which marshaller will be used in case of conflict. Priority is an integer.
// The higher the number, the more priority you get: 10 > 1 for instance.
@Setup(mode = SINGLETON, priority = REFERENCE)
public class ParentDocEnricher extends AbstractJsonEnricher<DocumentModel> { // You could also enrich a user or anything else

    // The enricher will be called using X-NXenrichers.document: name (name being parentDoc here)
    // If you were enriching a user, you would call it using X-NXenrichers.user: name (X-NXenrichers.entity-type)
    public static final String NAME = "parentDoc";

    public ParentDocEnricher() {
        super(NAME);
    }

    // Method that will be called when the enricher is asked for
    @Override
    public void write(JsonGenerator jg, DocumentModel doc) throws IOException {
      // We use the Jackson library to generate Json
      ObjectNode parentDocJsonObject = addParentDocAsJson(doc);
      jg.writeFieldName(NAME);
      jg.writeObject(parentDocJsonObject);
    }

    private ObjectNode addParentDocAsJson(DocumentModel doc) {
      ObjectMapper o = new ObjectMapper();

      // First create the parent document's Json object content
      CoreSession session = doc.getCoreSession();
      DocumentModel parentDoc = session.getDocument(doc.getParentRef());

      ObjectNode parentObject = o.createObjectNode();
      parentObject.put("id", parentDoc.getRef().toString());
      parentObject.put("title", parentDoc.getTitle());
      parentObject.put("description", parentDoc.getPropertyValue("dc:description").toString());

      return parentObject;
    }
}

Specific Object Content Enricher

Here is a sample to get you started with a content enricher for the object org.nuxeo.ecm.platform.audit.api.LogEntry:

<?xml version="1.0" encoding="UTF-8"?>
<component name="org.nuxeo.sample.enrichers.logEntryEnricher">
<!-- Start copying here if you declare the enricher in Nuxeo Studio -->
<extension target="org.nuxeo.ecm.core.io.MarshallerRegistry"
           point="marshallers">
  <register class="org.nuxeo.sample.enrichers.LogEntryEnricher" enable="true" />
</extension>
<!-- Stop copying here if you declare the enricher in Nuxeo Studio -->
</component>
package org.nuxeo.sample.enrichers;
import static org.nuxeo.ecm.core.io.registry.reflect.Instantiations.SINGLETON;
import static org.nuxeo.ecm.core.io.registry.reflect.Priorities.REFERENCE;

import java.io.IOException;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.GregorianCalendar;

import org.codehaus.jackson.JsonGenerator;
import org.nuxeo.ecm.core.api.CoreInstance;
import org.nuxeo.ecm.core.api.CoreSession;
import org.nuxeo.ecm.core.api.DocumentModel;
import org.nuxeo.ecm.core.api.IdRef;
import org.nuxeo.ecm.core.api.NuxeoPrincipal;
import org.nuxeo.ecm.core.io.marshallers.json.enrichers.AbstractJsonEnricher;
import org.nuxeo.ecm.core.io.registry.reflect.Setup;
import org.nuxeo.ecm.platform.audit.api.LogEntry;
import org.nuxeo.ecm.platform.usermanager.UserManager;
import org.nuxeo.runtime.api.Framework;

import com.google.common.base.Strings;

@Setup(mode = SINGLETON, priority = REFERENCE)
public class LogEntryEnricher extends AbstractJsonEnricher<LogEntry> {

    public static final String NAME = "sfLogEntry";

    public LogEntryEnricher() {
        super(NAME);
    }

    @Override
    public void write(JsonGenerator jsonGenerator, LogEntry logEntry) throws IOException {
        CoreSession session = CoreInstance.openCoreSession(logEntry.getRepositoryId());
        DocumentModel targetDocument = session.getDocument(new IdRef(logEntry.getDocUUID()));
        Date creationDate = ((GregorianCalendar) targetDocument.getPropertyValue("dc:created")).getTime();
        Date modificationDate = ((GregorianCalendar) targetDocument.getPropertyValue("dc:modified")).getTime();

        jsonGenerator.writeObjectFieldStart(NAME);
        jsonGenerator.writeObjectField("contact", getPrincipalName(logEntry));
        jsonGenerator.writeObjectField("creation", new SimpleDateFormat("yyyy-MM-dd").format(creationDate));
        jsonGenerator.writeObjectField("modification", new SimpleDateFormat("yyyy-MM-dd").format(modificationDate));
        jsonGenerator.writeEndObject();
    }

    protected String getPrincipalName(LogEntry logEntry) {
        UserManager userManager = Framework.getLocalService(UserManager.class);
        NuxeoPrincipal principal = userManager.getPrincipal(logEntry.getPrincipalName());
        String firstName = principal.getFirstName();
        String lastName = principal.getLastName();
        if (Strings.isNullOrEmpty(firstName) && Strings.isNullOrEmpty(lastName)) {
            return principal.getName();
        } else {
            return firstName + " " + lastName;
        }
    }
}

REST Request Header

Don't forget to set the proper header to use this enricher:

X-NXenrichers.logEntry = sfLogEntry

4 months ago manonlumeau Relocated assets to fit new URL structure for 710 - fix
3 years ago Manon Lumeau 43
3 years ago Bertrand Chauvin 42
3 years ago Bertrand Chauvin 41
4 years ago Manon Lumeau 40 | Fix links to 7.10
4 years ago Thomas Roger 39
4 years ago Vladimir Pasquier 38
4 years ago Vladimir Pasquier 37
4 years ago Manon Lumeau 36
4 years ago Bertrand Chauvin 35
4 years ago Bertrand Chauvin 34 | Added video
4 years ago Nicolas Chapurlat 33
4 years ago Nicolas Chapurlat 32
4 years ago Benoit Delbosc 31 | Fix header format
4 years ago Vladimir Pasquier 30
4 years ago Solen Guitter 29 | Format
4 years ago Bertrand Chauvin 28 | Added how to call enrichers section
4 years ago Bertrand Chauvin 26 | Fixed contributing your enricher section
4 years ago Bertrand Chauvin 27 | Fixed typo
4 years ago Bertrand Chauvin 25 | Fixed formatting and unneeded text
4 years ago Bertrand Chauvin 24 | Added how to contribute an enricher, fixed XML
4 years ago Thomas Roger 23
4 years ago Thomas Roger 22
4 years ago Solen Guitter 21 | Add links to javadoc, and children and permission enrichers in additional enrichers sections
4 years ago Solen Guitter 20 | Update response examples from 7.2, add breadcrumb enricher
4 years ago Solen Guitter 19 | Replacing deprecated headers X-NXContext-Category and X-NXDocumentProperties by X-NXenrichers.document and X-NXproperties
4 years ago Solen Guitter 18 | typo
5 years ago Solen Guitter 17
5 years ago Nelson Silva 16
5 years ago Nelson Silva 15 | Add parameters and vocabulary enricher
5 years ago Manon Lumeau 14
5 years ago Vladimir Pasquier 13
5 years ago Vladimir Pasquier 12 | Add preview content enricher
5 years ago Solen Guitter 11 | Formatting
5 years ago Vladimir Pasquier 10
5 years ago Solen Guitter 9 | formatting
5 years ago Vincent Dutat 8
5 years ago Vincent Dutat 7
5 years ago Vladimir Pasquier 6 | little update on content enrich
5 years ago Vladimir Pasquier 5 | renaming rest contrib into content enrich
5 years ago Vladimir Pasquier 4
5 years ago Vladimir Pasquier 3
5 years ago Vladimir Pasquier 2 | Rest Contributors
5 years ago Alain Escaffre 1
History: Created by Alain Escaffre

We'd love to hear your thoughts!

All fields required