Server

Call an External Application From Nuxeo

Updated: December 2, 2024

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:

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

service-wrapper
service-wrapper

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

    automation-rest-api.png
    automation-rest-api.png

Event Driven approach

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

streams-intro
streams-intro

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).

Event and CallBack System

Define a model for Async / Callback system

Review complete flow based on how it currently works for AWS Lambda

Client-side

Here are the possible approaches to integrate an external application inside Nuxeo UI on the front-end side:

  • Direct JavaScript
    • Custom JavaScript to call external API
  • Custom Web components
  • IFrame / Popup integration

Challenges to address:

  • Authentication
    • OAuth integration
  • Handling errors and availability
  • Async and Return code
    • SSE, WebWorker..
  • UI/UX

training
Test the Nuxeo API with the Nuxeo Javascript Client