Call an External Application From Nuxeo

This chapter will focus on having Nuxeo calls an external application to trigger processing, send data or retrieve data.

Challenges

Security

The goal is to handle:

Authentication
- How do we present a credential to the external application?
Identity propagation
- Do we want to use a service account or not?

Nuxeo provides several authentication protocols:

OAuth2
Basic Authentication
Any kind of custom token

Handling Errors

The goal is to handle:

Exceptions in the external application
Availability of the external application
By extension, we may also need to address retry and back-off policies.

For interactive integration, the right approach is probably to let the exceptions and errors bubble. If needed, Nuxeo integrates the failsafe library. For asynchronous/batch integration, the Nuxeo infrastructure already provides patterns to do automatic retries.

Result Handling

The goal is to handle asynchronous requests and callback/resume.

On the Nuxeo side, the standard way to address that is to:

Store the call context inside the key/value store
Expose a callback endpoint that will restore the context from the key/value store
Store the final result into the transient store

In addition, all steps of the calls can be tracked inside the Audit Log.

Interactive/API level integration

The idea here is, to extend or hook onto the Nuxeo API so that the call to the external service is executed when a Nuxeo API is called.

Possible Implementations

Automation Scripting

Automation scripting allows deploying JavaScript code that wraps Automation Operations.

Interesting operations are:

Call external HTTP Service
- Blob.PostToURL
- HTTP.Call from nuxeo-labs-operations
- Use the automation HTTPHelper
Add a log entry
- Audit.LogEvent

Current limitations:

No direct support for OAuth Service providers
No API to access the transient store or the key/value store

Custom Java Operation

The idea is to build a custom Automation Operation that will:

Contain the java logic to handle the remote call
Expose an API for the rest of the platform including the client-side

Interesting APIs and services:

HTTP Client libraries:
- Jersey HTTP Client
- Apache HttpCore
- Google HTTP Client
OAuth2ServiceProvider
KeyValueStore
TransientStore

Java Service

Concepts

A service wrapper allows you to:

Expose a native Nuxeo service
Bring consistency
Implement unit tests
Leverage extension point system to configure calls to external service
Access Existing Nuxeo Services through OAuth Service Providers registration and the Transient Store / Blob Store

Associated gains:

Easier to use from the pure Java code (Listener, Enricher, etc.)
Leverage extension point system

API Integration

Two options are possible:

Automation API
- Automation Script or Automation Operation are exposed as part of the command API (RPC)
Enrichers and adapters
- Integrate result of calls to external service into existing Nuxeo API result

Event Driven approach

The idea is to trigger the call to the external service via an event

Possible Implementation

Native Nuxeo Integration

Event Listener
- Synchronous or asynchronous Java class
Work
- Asynchronous batch
Computation
- Stream processing

Kafka Integration

Concepts

Leverage nuxeo-stream API or even directly Kafka API:

Leverage events or messages published by Nuxeo in Kafka
Deploy a Kafka Consumer/Producer:
- Only depends on Kafka API
  - Read or write messages to communicate with Nuxeo

Code Sample for the Kafka Integration

You can check the nuxeo-external-service-sample GitHub repository, which contains a sample code to manage communication between a Nuxeo Server and an external service using nuxeo-stream (Kafka).