Server

Call Nuxeo From an External Application

Updated: March 18, 2024

Goal

Accelerate the implementation of Nuxeo Platform features surfacing into an external application by providing clear guidelines on which API to use and what to pay attention to.

Here are some examples:

  • Nuxeo Salesforce Connector
  • Nuxeo Outlook Connector

General Recommendations

  • Use the default Nuxeo automation operations. You can get the list of all default operation in Nuxeo Explorer. Indeed, the external application should make as few as possible assumptions about the Nuxeo side. Using automation operations is a good way to do that. On the other hand, the logic that has nothing to do with Nuxeo should be in the external app.
  • Use REST API operation. The REST API documentation is versioned and available in the Nuxeo Documentation website.
  • Use the supported Nuxeo clients: Java, Javascript, Python, .NET and PHP. More information on the Client SDKs section

Main Considerations

Server side API

Several approaches exists:

  • Call Nuxeo REST API
    • Using the Java / Python / Javascript clients
    • Raw REST API
  • Handle asynchronous processing

Challenges to address:

  • Authentication
  • Handling errors and availability
  • Asynchronous and Callback system

Client side API

Approaches:

  • Nuxeo Javascript Client
  • Reusable UI blocks (Using WebComponents or Nuxeo Elements)

Here are the links of the most useful documentation pages:

Hyland University
Don't forget to take the developer learning plan, available in Hyland University (Home > Getting Started > Learning Plans)

Typical Features Set of an Integration

Authentication

  • Replace the default basic authentication with one of the Nuxeo supported authentication protocols
  • Understand the authentication chain principles
Feature Guidelines
Connect to Nuxeo Use OAuth 2 Authentication protocol.

Browsing

  • Understand hidden in navigation and folderish facets
Feature Guidelines
Navigate the folder structure Use the tree_children page provider to implement the browsing capability.
Display thumbnails
  • If you need to display a listing with thumbnails, use the thumbnail enricher in the previous request to the tree_children page provider. That way you don't need to do as many queries as there are thumbnails to display. You get the thumbnail URL for each document within one call.
  • Also, use the @rendition web adapter with the thumbnail attribute value.
Implement sort and filter Defined in the page provider definition
Implement lazy scrolling If using the Nuxeo UI element nuxeo-data-table, then paginable attribute must be set to true (default value).

Implement a Breadcrumb

Feature Guidelines
Get all parents for a given document. Use the breadcrumb content enricher.

Document Management

Feature Guidelines
Create a document with metadata
  • Use the Document ID endpoint
  • Use the Document.Create automation operation
Display first name, last name, email
  • Use extended fields (fetch.document=dc:creator for example) so as to get all the information on the tree_children call.
  • Use the userprofile web adapter to get DOB, phone number and avatar of current user.
Version management
  • Use the Document.Version automation operation.
  • Use the X-Versioning-Option HTTP header with major or minor value to version a document with the PUT method on the Document ID./li>

File Management

Feature Guidelines
Import files
Download the file Use the Nuxeo REST API Web Adapter @blob (/api/v1/id/{docId}/@blob/{xpath})
Update the file of a document Use the batch upload endpoint and a PUT method on the Document ID endpoint
Handle additional attachment
  • Make sure your document type has the files schema (to have attachments)
  • Use the batch upload endpoint and a PUT method on the Document ID endpoint, on the file:files XPATH
  • Use the BlobHolder.AttachOnCurrentDocument automation operation
  • Leverage aggregates
  • Leverage quick filters
  • Saved searches
Feature Guidelines
Perform standard searches Use default Nuxeo advanced search page provider default_search
Highlight search results Use the highlight enricher

Previewing Content

  • Choose the correct rendition depending on the mime type
Feature Guidelines
Use the Nuxeo element to display the document preview. Use the nuxeo-document-viewer element as it adapts the suitable viewer according to the mime-type of the file (PDF viewer for Office documents, HTML5 viewer for videos, etc.).

Display Metadata

  • Content enrichers to add more information on a single document request
Feature Guidelines
Use special HTTP header to retrieve the metadata you need. Use the properties HTTP header.
View properties with a UI element. Use the metadata layout element to display the document metadata of your document type, defined in Nuxeo Studio.

Edit Metadata

Feature Guidelines
Edit properties with the REST API
  • Use PUT method on the Document ID endpoint.
  • Use the Document.SetProperties automation operation.
Edit properties with a UI element. Use the edit layout element to edit visually the document metadata of your document type, defined in Nuxeo Studio.

Display Document History

Feature Guidelines
View the document history with the REST API Use the @audit web adapter or use the DOCUMENT_HISTORY_PROVIDER page provider
View the document history with a UI element. Use the Nuxeo UI Element nuxeo-document-history.html to display the document history.

Display Conversions

Feature Guidelines
Display the rendition you need. Use the @rendition web adapter.

Going Further

In some cases, you may also need to add your custom Java code to your plugin, to add a new REST API endpoint , a new listener, a new callback API etc. To do so, please refer to the Nuxeo CLI documentation.