Integration-Patterns.md

The goal is to identify the different types of integrations between Nxueo and external applications. The hope if to be able to extract some integration pattern and provide associated sample code and documentation

the first use case would be to have something we can use to drive the IRM spkides (see spikes listed UI Workshop and API Workshop)

Calling an external application from within Nuxeo

This chapter will focus on having Nuxeo call an external application to trigger a processing, send data or retrive data.

Server side integration

Challenges to address:

Security

The goals is to handle:

• Authentication : how do we present credential to the external application
• Identity propagation : do we want to use a service account or not

On the Nuxeo Side:

• basic auth
• OAuth2 support / Cloud Services
• 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 execptions and errors bubble.

If needed Nuxeo integrate the failsafe library 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:

• store the callcontext inside the KVStore
• expose a callback endpoint that will restore the context from the KVStore
• 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

Here the idea 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 to deploy JavaScript glue code that wrap Automation Operations.

Interesting operations

• 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 TranscientStore or the KVStore (?)

Custom Java operation

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

• contain the java logic to handle the remote call
• expose a 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

Same as the Opereation but packaged as a Nuxeo Service.

Associated gains:

• easier to use from the pure java code
  • i.e. Listener, Enricher ...
• leverage extension point system

API Integration

• Automation API
  • Autmation Script or Automation Operation are exposed as part of the command API (RPC)
• Enricher
  • integrate result of call 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
  • sync or async java class
• Work
  • async batch
• Computation
  • stream processing

Kafka Integration

Leverage nuxeo-stream API or even directly Kafka API

• leverage events or messages published by Nxueo in Kafka
• deploy a Kafka Consumer/Producer
  • only depend on Kafka API
  • read or write messages to communicate with Nuxeo

Event and CallBack system

Define a model for Async / Callback system

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

I think that it would make sense to extract a standard code sample for implementing such a flow:

• standard structure in KVStore
  • call ID
  • Context info
    • user
    • target document/documents
    • info needed to resume processing after callback
• standard structure in Transient Store
  • blobs and result
• standard callback endpoint
  • check KV to resume context
  • store result in Transicent Store
  • resume processing
    • Listener?
    • Work?
    • Computation?

Client side

Integrate an external application inside Nuxeo UI on the front-end side

Possible Approaches

• Direct JS
  • custom JS to call external API
• Custom web component
• IFrame / Popup integration

Challenges to address:

• Authentication
  • OAuth integration?
• handling errors and availability
• Async and Return code
  • SSE ? WebWorker ?
• UI/UX

Calling Nuxeo from within a external Application

Server side API

Call Nuxeo API from within an external application on the server side

Possible Approaches:

• call Nuxeo REST API
  • java / python / js clients
  • raw REST API
• handling Async Processing
  • @Async adapter
  • BAF

Challenges to address:

• Authentication
• handling errors and availability
• Async and Callback system

Client side API

Approaches:

• nuxeo.js client
• reusable UI blocks
  • WebComponents
  • File Picker & reusable Popup?