ODA Update From IBM Connect: The Awesome New Functionality of ODA

  |   Blog   |   3 Comments

At the end of my OpenNTF Domino API session with Stephan Wissel at IBM Connect, I showed a demo of some experimental new functionality in ODA. Hopefully those who saw it were impressed with the power and potential, especially because part of it reproduced the Watson Workspace notifications integration that the Sapho product showed in the OGS, but this was built with open source over lunch before the session.

First, I need to give some background.

For a few years now, there has been functionality in ODA for EventListeners. This was powerful functionality that allows code to be assigned to the Database and run whenever the respective events were triggered. The key elements are:

  • A class implementing IDominoListener that was passed to the addListener method of the relevant Database.
  • The class contains an ArrayList of org.openntf.domino.ext.Database.Events.
  • A boolean eventHappened method that runs code based on whether the event passed in is the relevant Event in the ArrayList.

This was powerful functionality, but was limited because it couldn’t be triggered from outside of ODA code and required the class to be passed to the addListener method every time the database was accessed.

In October last year Stephan Wissel had been working on using ODA in a branch of Verse On Premises and asked whether it was possible to intercept the change of read / unread on a server, to avoid regularly checking the underlying document for whether the user had opened it, and so automatically marked it unread. Nathan was fully acquainted with it, because he had made been involved in some fixes for DOTS in DOTS Extended. Basically, what he then realised was that a whole host of events are published to a MessageQueue in Domino called MQ$DOTS…and have been for years! Moreover, these events are published to the MessageQueue wherever in Domino they occur – XPages, Notes Client, server, even (I suppose) via external programs as long as they’re interacting with the server. To quote Nathan from the Slack chat:

and… just to reiterate… this is lotus.notes.internal.MessageQueue. This is not NAPI or anything in the XPages stack. This is in notes.jar. And it doesn’t use lotus.notes packages; it uses lotus.domino

Basically, subscribe to that MQ$DOTS MessageQueue and code can intercept a variety of events no matter how they are triggered, and the code had already been written by Nathan in DOTS Extended. Why DOTS and not DOTS Extended? Apparently, the Java code in DOTS doesn’t queue messages from the C API, so if a tasklet is busy, it just drops the message. Also, the extended version includes the username in alll events, and obviously knowing who performed some action is rather important.

Just to put this in context, here are a few ideas that were kicked around in the chat:

We can add a PostDocumentDelete event in Java that runs in the XPages JVM NO MATTER WHERE THE DOCUMENT IS DELETED FROM

so you can have some Java code that runs whenever a document is updated within a specific NSF

or you could have some that runs whenever a document is updated in ANY NSF

You could write a Java bean, stick it in ApplicationScope, and tell Xots to notify it whenever any document is opened in your application

so you could have something in the UI that says “who else is reading this right now?”

So you can show recently updated documents by any user from any process – XPages, Formula Agent, Scheduled LotusScript Agent, button hack etc?


There are two steps required:

  1. Adding the DOTS extension to the <domino> folder on the server. For Windows 64-bit this is ndotsExtMgr2.dll (the one in 1.0 release may be corrupt, I got a recompiled version from Ulrich), for other platforms it will be the relevant extension.
  2. Adding to the notes.ini “EXTMGR_ADDINS=ndotsExtMgr2.dll” (or the relevant extension). Then restart the server.

There are a few limitations at the moment:

  1. I currently got security exceptions when trying to run the code within the NSF. There may be ways round that, but I haven’t investigated further yet. The code is still experimental and – believe me – there are a lot of events passed to the MessageQueue even for a dev server.
  2. If something other than Domino tries to subscribe to the MessageQueue, it crashes the server. This happened for me when running CrossWorlds against the server and when running code from Eclipse in the “two-headed beast” approach in ODA tests.
  3. If the Open Social Component is also running on the server, the parsing of the Message Queue fails with some messages. These seem to be when loading plugins, possibly because it misses some elements and those messages weren’t addressed by DOTS extended.

Next time I’ll go through some sample code I’ve used while working on this and the code for the demo I did at IBM Connect.

AUTHOR - Paul Withers

Paul Withers has been an IBM Champion since 2011, has been an OpenNTF Board Member since 2013, has worked with XPages since 2009, co-authored XPages Extension Library and was technical editor for Mastering XPages 2nd Edition. He is one of the developers on OpenNTF Domino API as well as contributor to a variety of other OpenNTF projects.

  • Cameron Gregor | Mar 27, 2017 at 1:46 am

    Last week I finished a proof-of-concept based on listening to the ‘Note Updated’ event using DOTS, and then I was pretty disappointed to find that DOTS only half-heartedly listened to events.

    I’m giving the ODA Xots version a go this week, thanks for your help setting it up! and thanks to Nathan (I Assume?) for the creative work he has done restructuring this for use these Events within XPages runtime!

  • Stephan H. Wissel | Mar 28, 2017 at 2:33 am

    We could write a tiny plugin that forwards the Domino events to a MQ(TT) broker 😉

  • Michael Bourak | Mar 29, 2017 at 11:40 am

    Are those event use for other goal that billing ? (I imagine that’s their main use ?)

Post A Comment