Live documentation - Nuxeo Platform Explorer


Tue 19 April 2016 By Mike Obrebski

Outside of developing and maintaining the Nuxeo Platform, a major goal of our company is to provide advice, support and tools for our customers to maximize the ease of development and clarity of the system. This includes extensive documentation, the Studio configuration application, the Nuxeo IDE, and some additional useful tools, which I’d like to discuss in this blog.

These tools serve as runtime documentation, important when looking to identify specific areas for extending, re-configuring or adding to achieve a particular functional goal. I find that these are often under-utilized but offer a important value.

For the purposes of this post, I’ll assume you are already familiar enough with the Nuxeo Platform architecture and concepts, and have experience with some degree of Nuxeo development and customization.

Modularity of the Nuxeo Platform


As you know, the Nuxeo Platform is highly extensible at it’s core, based on the OSGI model. The system consists of a large set of bundles deployed as jar files, which includes components. These functional groupings of code and configurations further include services, extension points and contributions to these XPs. These components define the platform.

The UI layer built within the JSF/Seam framework includes JSF templates, tags and seam beans. To allow UI configuration, the Nuxeo Platform further defines Widgets, Layouts and Actions. It also provides an extensive set of operations and a REST/Command API to expose all server side capabilites to external clients.

As you can see this great flexibilty, extensibility and open nature of the system can create a challenge when it comes to understanding all the complexity. Documentation is a good place to start to understand the concepts, but the Nuxeo Platform is not static. We need a way to see a live/active view of the system and all the aforementioned components. These tools include Platform Explorer, API Playground and the Dev Mode of the Nuxeo UI.

Today, we’ll focus on the Nuxeo Platform Explorer.

Nuxeo Platform Explorer


One of the most valuable tools at a Nuxeo developer’s disposal is the Nuxeo Platform Explorer. It is a dynamic documentation system, which at server startup time, builds a complete picture of every deployed modular object and organizes for convenient reference. As Javadoc is to a Java developer, the Explorer is to a Nuxeo developer and an invaluable reference.

The Explorer is deployed as a Nuxeo Package onto an instance and available for browsing through the Admin section of your server or in a whole page format at: http://localhost:8080/nuxeo/site/distribution
Explorer Package

We also provide for more convenience and public access to a deployment of explorer for every standard release package version at: Nuxeo Platform Explorer

Let’s look at the wealth of information available here.

The first thing we notice is the Bundle Groups, containing Bundles (corresponding to all the jar files in the ../nxserver/bundles directory of your server, which then contain Components (by name and groupings). Each Component contains some combination services, exposed extension points, and contributions to other extension points.

This structure describes the whole Nuxeo server deployment, and any customizatons will connect to some extension point here. This is a good point to start to find the appropriate extension point if you have some ideas on what you want to do.

In addition there are sections for Operations, REST API definition, as well as UI related Seam Beans which we'll cover in my next blog when exploring JSF and UI.

Extension Points


Let’s suppose, I’d like to schedule a recurring event to check for Documents past a certain creation date and change their status to Archived, send notifications, move locations, and follow any other custom business process.

Knowing general concepts based on Studio and other documentation, I know there is probably some extension point for contributing a recurring event call. I search extension points or components for something starting with “schedule”.

I find what I’m looking for at: Extension point - schedule
Schedule XP

Here, we see the documentation describing the extension point and the format for making a contribution to add our own.

We can also browse other contributions from other components in already deployed jars as examples to get an idea of what’s currently scheduled on our server.

From this we know how to deploy our own schedule definition, either in Studio or our own bundle from IDE. We can also browse for an Event extension point to see if any of these scheduled events were added to the Audit log using: Extension point - event

Next we need to add in a custom event listener to execute when our event is fired. We look for some words about “Listeners”. There are a few, so we look at a few to find the correct one based on descriptions: Extension point - listener

Now we know what options there are for configuration and that we need to specify our own Java implementation class. To dig further, knowing the component package name, we can switch to Javadoc, and narrow down to find the appropriate interface called EventListener: Package org.nuxeo.ecm.core.event

Using Explorer and not always knowing the exact point we are looking for, we can browse to find the correct XP, description, other examples, related items, and package names to give us the direction we need to extend the Nuxeo system, as well as getting an understanding of how everything works together. Of course you'd combine that with other documentation and examples, but this gives the definitive reference.

I'd suggest spending some time browsing this to get a feel of how the extension system works because eventually, complexity turns to a well organized powerful set of patterns.

REST API and API Playground


Another very useful section of the Platform Explorer is the REST API section whose link takes us to the API Documentation
Explorer - API Documentation

API Documentation

A related location the API Playground is also available: API Playground

A particularly useful aspect of these is that beyond documentation you can run actual API calls from here to any of your servers to test and validate. It's usually very convenient to test out calls and different parameter values, without having to write any client code.

UI and Extension Points


A previous post, The UI Dev Mode Will Tell You Everything!, introduced the UI Development mode as a tool to identify and describe all the Widgets, Actions, Layouts and templates which make up the UI. With this information you can go into the Explorer to see the complete definitions and build on them.

In my next blog, I'll discuss how to take advantage of these tools to understand and customize the UI.


Tagged: Insight, Nuxeo Platform, REST API