Call Nuxeo From an External Application

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
  • Using the Bulk Action Framework
  • Using the @Async adapter

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)

Links

Here are the links of the most useful documentation pages:

• Nuxeo REST API Web Adapter
• Nuxeo REST API Enrichers
• Nuxeo Extended Fields

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

• Understand batch upload endpoints and the file manager service.

Feature	Guidelines
Import files	Use the batch upload endpoint. Use the Blob.AttachOnDocument automation operation.
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

Search

• 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

• Discover the conversion service

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.