Graph – a closer look at the data


A graph database data is represented as ‘vertices’, sometimes called ‘nodes’. The relationships between vertices are represented by connections called ‘edges’. Graph databases also store metadata or ‘properties’ about vertices and edges.

Domino Explorer

If you look at the data in Domino Explorer after the source databases names.nsf and catalog.nsf are scanned you can group them in the same categories vertices and edges.

If you look further at the Graph related properties on the Vertices documents you notice that the next level of division is the Java class the vertex is added with to the Graph (Java object-type Vertex = graph.addVertex(id, Java.class).

Each class defines specific properties for the object and also the relation(s) to other Vertices. These Edges contain properties like label, direction (in/out).

Adjacency annotate getters and adders to represent a Vertex incident to an Edge. AdjacencyUnique extends this idea to ensure that there is only one instance of an Edge with a specific label between any two specific Vertices. This allows the user of the graph to call an “add” method and return the existing adjacency if it already exists.

So when and where are these relations defined? That depends on your code.

When you “like” a post on Twitter, the relation between you and the tweet is created when you click the “like” icon.

In Domino Explorer relations are created when you run the setup by selecting one of the “Start Scan” buttons.

Screen Shot 2016-05-23 at 13.46.55

Scan Databases

When you select to scan the databases the $ReplicaID view in the catalog.nsf is opened and for each entry found a Vertex is created using the DXDatabase class and committed to the Graph.

View allDbs = catalog.getView(“($ReplicaID)”);
DocumentCollection col = allDbs.getAllDocuments();
for (Document db : col) {
String replicaId = session.evaluate(“@Text(ReplicaID; \”*\”)”, db).elementAt(0).toString();
DXDatabase databaseVertex = graph.addVertex(replicaId, DXDatabase.class);
String dbTitle = db.getItemValueString(“Title”);

// ACL
scanAcl(graph, databaseVertex);

Then then Graph is “scanned” with the newly created vertex. Here the database ACL is collected and for each ACL entry a new vertex is created using a specific class. Also the relationship between the database and aclentry vertices is created:

DXACLEntry graphAclEntry = graph.addVertex(aclEntry.getName(), DXACLEntry.class);

The addAclEntry method is defined the DXDatabase class which the db object is created with:

@AdjacencyUnique(label = “hasAcl”, direction = Direction.IN)
public void addAclEntry(DXACLEntry ae);

If you look at the Vertex object in the Domino Explorer NSF you notice these properties for a DXDatabase Vertex object:

#Note-UNID 82753B9B92522221033D1650C7BE35D4
$$Key 85256714:00725208
_ODA_GraphType V
form DXDatabase
filePath AgentRunner.nsf
replicaId 85256714:00725208
server CN=dev1/O=quintessens
title Java AgentRunner


  • note-UNID is the document unique id
  • $$Key is the same as the replicaId of the (target) database (different for Vertices created with other class)
  • _ODA_GraphType, V stands for Vertex
  • form is the Java class the document is created with
  • _COUNT_OPEN_IN_hasAcl, counter. Not sure where it’s used for.
  • _OPEN_IN_hasAcl, for all Vertices empty

If you look at a DXACLEntry Vertex document notice the following properties:

#Note-UNID B9962995F0A05DCBAE35F07C64964A1C
$$Key -Default-
_ODA_GraphType V
form DXACLEntry
_COUNT_OPEN_IN_hasAcl 110
_OPEN_IN_hasAcl 110
level 6
name -Default-
_COUNT_OPEN_OUT_member 1

If you search through the Edges document you will find a document matching the note UNID’s above and carrying the label “hasLabel”:

Screen Shot 2016-05-23 at 15.00.21

and carrying the following properties:

Screen Shot 2016-05-23 at 15.01.06

Hereby the Graph db recognises a relationship between one Vertex of type DXDatabase and  another Vertex of type DXACLEntry.

Because this is not the only relationship the DXDatabase object has when the ACLService remote service is called, provided with the replicaID of the Database more than one matching relationship is returned under db.getAclEntries:

DXDatabase db = graph.getElement(replicaId, DXDatabase.class);
if (db != null) {
int count = 0;
Iterable<DXACLEntry> acl = db.getAclEntries();
for (DXACLEntry entry : acl) {
JsonJavaObject aclEntry = new JsonJavaObject();
aclEntry.put(“name”, entry.getName());
aclEntry.put(“level”, entry.getLevel());
aclEntry.put(“levelName”, ACL_LEVEL[entry.getLevel()]);
data.put(count, aclEntry);

Here for each found relationship the DXACLEntry object is collected from the Graph and properties from it placed in a JsonJavaObject, placed in an array and returned.


After taking this deeper look under the hood and analyzing the data I hope you have gained a bit more understanding of the Graph concepts and the implementation of it from it via OpenNTF’s Domino API in Domino Explorer.


Another Graph sample from Domino Explorer


In a previous post I dove into Domino Explorer, an XPages application that cans the Domino Directory and the Catalog by using the Graph capabilities in the OpenNTF Domino API.

In this post will describe another XPage in that application. Perhaps it helps to get a better picture on the Graph db and how to build an application around it using XPages, JavaScript, & Java.

Hopefully I will be ready writing before a European football final kicks off…


The xpage I discuss is allacl.xsp. Basically it displays at start a table with ACL entries for the entire catalog. When I click on an entry or row in the table I get presented a list of applications where the selected ACL entry resides in the ACL.

The result of the scenario above captured in the following screen:


As the image suggests the entry [Anonymous] resides in 4 applications. Let’s dive in a little deeper into the XPage to see how it’s done…

On document ready

The XPage contains a JS library whichs fires an AJAX call to collect the data for the DataTable object. The rest service resides on the XPage and is accessed via it’s pathinfo property. The restservice is bound to a custom servicebean which resides in the application.

The AJAX call does not provide a parameter to the restservice, so the java class will collect all the vertices of type DXACLEntry.class. For each vertice a JSONJavaObject containing name and level and placed in a JSONJAVAArray object. This array is placed in a JSONJavaObject and returned as a string to the restservice.

When the data is received in the DataTable object only the name property is placed.

The routing is visualized in the next image:


On row click

In the JS library for the DataTable object is also defined what should happen when a row in the table is clicked.

Here the name value for the selected row is used in a function that initiates a second DataTable object. Again a call is made to the same restservice. However now the name value is send as a parameter (“?name=” + name value).

The servicebean picks this parameter up (String name = request.getParameter(“name”)) and get’s all the vertices from the Graph with the provided name, matching the DXACLEntry (DXACLEntry aclEntry = graph.getElement(name, DXACLEntry.class)).

Similar as in the document ready event for each found DXACLEntry object a JSONJavaObject is created, now with some more properties (title,filepath, replicaId,server) and placed in a JSONJavaArray. This array is returned as a string to the restservice.

When the results are received by the DataTable object the four properties are displayed per column.



The scenario is that simple. The DataTable plugin is really a great plugin that does a lot for you and can save you multiple design elements (view controls) by defining in your code what you want in it as result and in which order.

Now let me enjoy my evening of football with a cold beer! Happy development =)



Exploring the Domino Explorer


We live in a connected world today and also the data in your IBM Notes/Domino platform is more connected that you perhaps realise:

I work work for company X at department Y and besides my assignment as “ICS product specialist” I perform in different roles, sometimes as developer, sometimes as a solution architect, sometimes as project manager etc. I own a range of devices to do my work, bought in by different suppliers under different conditions/contracts. Now a external project-leader (they claim they are the best) has became responsible for a new project (Z since it is the final project the company is ever going to run) and to make a huge impact the project-leader want to equip his team (which I have become member of) with the latest and greatest of devices to make our work most convenient and the impact of the project delivery as huge as possible. BUT of course he is unaware about the devices the team owns already and the lifetime of the contracts. He also does not want to make top management angry so he suggest to provide this team with devices just 1 configuration level below top management. So how does the project-leader require the information he need to know (a list of end of lifetime for the current devices the project team owns compared with the list of current devices top management owns) ?

All objects in the story above (organisation, departments, employees, devices, contracts, suppliers) are represented in Notes documents. By connecting them in a Graph DB new information can be gathered!


Lately I have been exploring Graph data modelling more closely. Mostly because I see many opportunities to connect/model unstructured data in fluid ways. Faster than relational datasources sometimes can.

For now I have been mainly looking at Neo4J because most Graph related education is focussed around this product. But for IBM customers you have IBM Graph (cloud only?) and since recent IBM Notes via the OpenNTF Domino API.

Graph need NoSQL

Graph needs NoSQL databases since NoSQL is capable of describing the variety of objects that are around in enterprise data. As it turns out Lotus Notes is around as one of the first NoSQL databases!

ODA & Tinkerpop

The OpenNTF Domino API has included Tinkerpop and an implementation to store content in a graph database structure.

This is great because as Domino developer you are concerned that your data is stored in an NSF. Probably you want to avoid the hassle of moving your data to another technology first and focus on developing applications directly.

Domino Explorer

Recently Oliver Busse has released Domino Explorer. It scans the Domino Directory and the Catalog application to show the capabilities of Graph in an XPages application. Getting the Notes data into a Graph data model is done via the OpenNTF Domino API.

In the next part of this post I will focus on how this is was implemented…

Document: Exploring the Domino Explorer

This document describes the setup of the Domino Explorer (DE) application (app) available on OpenNTF (link). The DE app demonstrates the Graph db capabilities via the OpenNTF Domino API (ODA) (link).

By exploring the architecture of the app better understanding of the Graph technology is aimed to achieve and how to implement it in XPages applications.


It is presumed that the reader of this document has advanced level of understanding of XPages technology, intermediate level of Java programming language, medium level of understanding of IBM Notes data and low level of the graph data model.

If not turn around or educate yourself on these topics😉

Graph glossary

The view design element “graph” group it’s containing documents into the two basic units in the Graph Data Model (Graph/GDM): Edges and Vertices.


Vertices (singular:vertex) are the objects in a graph.


Each edge has two (or in hypergraphs, more) vertices to which it is attached, called its endpoints. Edges may be directed or undirected; undirected edges are also called lines and directed edges are also called arcs or arrows.

IBM Notes data

When we translate this to IBM Notes data, vertices are mostly objects that contain values or properties (edge). E.g. a user is member of a group. An order has a date-stamp etcetera. With graph you can make queries to find different types of objects connected via shared properties e.g. A car-leasing company may have a fleet of rental-cars which may have present or past drivers.

General overview

Design elements in scope of the dissection

To have some sort of start we will start easy and give an overview of the design elements involved:

Design element Purpose Scope
Views Used to store documents that are used in the graph data model.
Documents are of type Edge or Vertex(Vertices).
XPages Used to initiate business logic and present the result to the user in a web interface. X
Custom controls Used to break parts of XPages into reusable pieces. X
Script libraries Client-side javascript libraries used to interact with the web presentation. X
Java Java classes that contain the business logic. X
Images Used to enhance the web presentation.
Style sheets CSS definitions used to enhance the web presentation.
Themes Use to set rules for the application regarding style, behaviour, resources
faces-config.xml Configuration file for the application, mostly used for registering managed beans.

For the rest of this document we will only focus on design elements that are marked with X under the Design elements will most likely be discussed in the logical order how the graph data model is implemented in the DE app.

Managed Beans

Managed Bean (link) is a regular Java Bean class registered by the XPages framework. Important beans registrered in the DE app for Graph are:

Bean name Class
config net.notesx.domex.controller.ConfigurationController
scanner net.notesx.domex.controller.ScannerController


The ConfigurationController class controls the configuration for the GDM. It  sets which databases are in scope for the GDM (Names.nsf, catalog.nsf).

It uses the:


Java class Usage
net.notesx.domex.graph.GraphHelper Setup of the Graph
net.notesx.domex.graph.Configuration Configuration of the Graph

DFramedTransactionalGraph<DGraph> configGraph = GraphHelper.getGraph();

Configuration configuration = configGraph.addVertex(“configuration”, Configuration.class);





In the code above the Graph db is loaded and the configuration added as a Vertex.

Configuration class

The configuration class contains the following properties:

  • $$Key (??? identifier for current configuration)
  • ApplicationName (name for the application, display only)
  • namesPath (location of the names.nsf)
  • catalogPath (location of the catalog.nsf)

GraphHelper class

The GraphHelper class sets up the Graph in the following order:

  • Setup an element store for configuration
  • Add the types (Vertices) to the element store
  • Create a configuration for the Graph
  • Add the element store to configuration and set the default element store (= filepath of current database)
  • Setup the Graph by using the configuration
  • Return it

// set element store for configuration

DElementStore configStore = new DElementStore();

Database currentDatabase = Factory.getSession(SessionType.CURRENT).getCurrentDatabase();


// setup the type



// create a graph config

DConfiguration config = new DConfiguration();

DGraph graph = new DGraph(config);

// add the config element store



// setup the graph

DFramedGraphFactory factory = new DFramedGraphFactory(config);

DFramedTransactionalGraph<DGraph> fg = (DFramedTransactionalGraph<DGraph>) factory.create(graph);

// return the graph

return fg;


This class adds the database, user and group objects to the Graph according the specified class for each object.

Important methods:

  • scanPeopleAndGroups
  • scanDatabases
  • scanAcl
  • scanMember


  • Get the path of the catalog db via the ConfigurationController class
  • Initiate the Graph datamodel via the GraphHelper class
  • Put all documents from View $ReplicaID into a document collection
  • For each document add a vertex to the graph using the DXDatabase class
    • Set properties for the vertex
    • Commit it to the Graph
    • Run the scanAcl method for the databaseVertex object


  • Get the name of the names db via the ConfigurationController class
  • Initiate the Graph datamodel via the GraphHelper class
  • Put all documents from View $VIMPeople into a document collection
  • For each document add a vertex to the graph using the DXUser class
    • Set properties for the vertex
    • Commit it to the Graph
  • Put all documents from View $VIMGroups into a document collection
  • For each document add a vertex to the graph using the DXGroup class
    • Set properties for the vertex
    • Commit it to the Graph
    • Run the scanMember class for the groupVertex object


  • For the given database (vertex object) get the database object
    • Grab the ACL
    • For each ACL entry add a vertex using the DXACLEntry class
      • Set properties for the vertex
      • Add the ACL entry vertex as an Edge to the DB vertex (the label “hasAcl” will be used)
      • Commit it to the Graph


  • For the given group (DXGroup class object):
    • For each member in groupmembers list:
      • Check if it contains a “/” ( This is a user)
        • Create a user object with the DXUser class from the Graph
        • If the user object is not null (in the Graph) add it to the group
      • If not (this is a group)
        • Create a group object with the DXGroup class from the Graph
        • If the group object is not null add it to the group
      • Set a property for the vertex
      • Commit it to the Graph

Other classes

DE contains more classes stored under several packages:

  • Common
  • Domex
    • Controller
    • Graph
    • Rest

Common package

Classes under the common package are used for setting properties for application e.g. navigation, page behaviour etc. They are out of scope for this document.

Domex \ controller package

Classes under the domex \ controller package are ConfigurationController and ScannerController and available as described earlier as managed beans.

Domex \ graph

Classes under the domex \ graph package are directly related to the Graph data model and describe the Graph data objects (vertexes):

  • Configuration
  • DXDatabase
  • DXACLEntry
  • DXGroup
  • DXUser

Each class describes the type of the object, the properties the object has and how to get & set them, the edges the object has and in which direction they go.

Annotation Description Example
@TypeValue Interface annotation for marking the Element property-value that may contain type information. @TypeValue(“DXACLEntry”)
@Property Property annotations are for getter and setters to manipulate the property value of an Element. @Property(“$$Key”)

public String getKey();


public void setName(String s);

@AdjacencyUnique Adjacency annotate getters and adders to represent a Vertex incident to an Edge. AdjacencyUnique extends this idea to ensure that there is only one instance of an Edge with a specific label between any two specific Vertices. This allows the user of the graph to call an “add” method and return the existing adjacency if it already exists. @AdjacencyUnique(label = “hasAcl”, direction = Direction.OUT)

public Iterable<DXDatabase> getDatabases();

Below is as example of the definition of the class:

package net.notesx.domex.graph;

import org.openntf.domino.graph2.annotations.AdjacencyUnique;

import org.openntf.domino.graph2.builtin.DVertexFrame;

import com.tinkerpop.blueprints.Direction;

import com.tinkerpop.frames.Property;

import com.tinkerpop.frames.modules.typedgraph.TypeValue;


public interface DXUser extends DVertexFrame {


public String getKey();


public String getUserName();


public void setUserName(String s);

@AdjacencyUnique(label=”member”, direction=Direction.OUT)

public Iterable<DXGroup> getMembershipInGroups();


The GraphHelper class is described earlier in this document and is used to setup the Graph.

Domex \ Rest package

The classes under the domex \ rest package create collections of json objects for the objects in the Graph data model. Some classes take in parameters, some don’t. Each class defines what type of graph object is in scope.

The way these classes are initiated is as follow:

  • On XPages rest service(s) of type customRestService are defined. The servicebean property directs to which class the service is bound to.
  • The XPage contains JavaScript libraries.
    • In a library can be defined which rest service should be called when the document is ready e.g. to build a collection of database objects.
    • In a library can be defined which rest service should be called when a link is being clicked e.g. a row in a data table control and if a parameter should be send (e.g. the replica Id of the database). Also is defined what should be done with the data returned from the rest service.


The design elements described above come together in the XPages design elements. We will demonstrate by describing an XPage.



Type Name Purpose
Custom Control _layoutBS3 Reusable layout for application.
JavaScript library alldbs.js Calling Rest Services.

On document ready: data

On click table row: acl

Rest service control Pathinfo: data Bound to Java class
Rest service control Pathinfo: acl Bound to Java class
HTML table datatable Placeholder for result from rest service under pathinfo data
Div acl Placeholder for result from rest service under pathinfo

XPage logic explained

On document ready:

  1. When the document is ready an AJAX call is made to the rest service under pathinfo data. This initiates Java class
  2. The class gets the Graph data model and collects all objects/vertexes of the type specified in the DXDatabase class.
  3. For each vertex a JsonJavaObject is created which is being filled by properties from the vertex.
  4. Each JSON object is a JSONJavaArray.
  5. The array returned to the rest service which returns it to the AJAX call.
  6. When the data is returned the HTML table is updated. Note that the table is of type datatable. This is a Bootstrap plugin. When the data is returned to the datatable object it knows how to update the content (rows and columns) of the table.

Below you find the process visualize:

Screen Shot 2016-05-16 at 11.09.02

When clicking a row:

  1. When the document is ready a listener is registered for each time a table row (TR) element is clicked.
  2. When such a TR is clicked an AJAX call is made to the rest service available under pathinfo acl. As data the replicaid value is send with the call. This value is stored in the data-set for each row.
  3. The AJAX call initiates class Here with the value of the given request parameter replicaid once again the Graph datamodel is opened and searched for the DXDatabase vertex that has a matching replicaid property.
  4. The returned vertex is bound to the DXDatabase class (name = db).
  5. If the DXDatabase is not null a collection is setup of type Iterable and filled with objects of type DXACLEntry for each item from the method db.getACLEntries.
  6. Then the collection is walked through and for each item a JSONJavaObject is created and filled with properties from the DXACLEntry object.
  7. The JSONJavaObject is placed in a JSONJavaArray. This array put as a string in a new JSONJavaObject which is returned to the rest service.
  8. The rest service returns the data back to the AJAX request.
  9. The AJAX request clear the DIV with id acl and fills it with the data received from the rest service. For each JSON object in the array a line with values is written in the DIV.

The process is visualized below:

Screen Shot 2016-05-16 at 11.11.07

The processes described above are the most basic types. The Graph is called for basic objects, not correlated.

As a result the following information is displayed on your screen:

Screen Shot 2016-05-16 at 11.17.13


Perhaps you are thinking: what the fuzz?! I can do something similar with document collections, perhaps showing a single category from a categorized column or perhaps create a jsonarray containing jsonjavaobjects and iterate through them and find a match.

Perhaps you can for THIS example. But I rather would avoid to create an unnecessary amount of design elements for it. Also in this example a very basic query is performed. Rethink the story in the beginning of this post. How are you gonna search your data under those conditions?

Also the combination to display your result data with the DataTables plugin you can build on the fly custom tables and reduce the amount of Notes views to a minimum.

In a future post I will describe more enhanced queries. Stay “connected”!

Links of interest



Stress testing with ODA Graph

I am very interested in Graph data modelling and with the Graph capabilities in OpenNTF Domino API I decided to setup some demo environments just to get my head around the subject and how you can implement it in XPages and use Notes data.

To my opinion reading Notes data in the Graph database structure can bring interesting new opportunities, far beyond what we can deliver with Views and Collections today.

Oliver Busse has provided a great starting point with his SUTOL demo application so I started with that one.

Besides the implementation and Graph capabilities I am also curious about performance.  So I run some tests on my working demo app. With the help with a simple agent I decided to be gentle and create a set of only 20.000 user documents.

The first test was about returning user profiles (nodes) matching certain properties (relations), presented in a repeat control. Below the list the time to load the filtered set is displayed.



When I compare the result with a normal view filter (by category or FT search) the results where a bit disappointing.

I also noted that navigating through the list was very slow (20 seconds or more returning a new set of rows of 10 documents). More than I expected I received timeouts.


The reason for this performance is still unknown. I guess there is no index created yet for the user node in the graph db structure. Why navigating through the list is so latent in performance is also a mysterie.

Nevertheless, my demo is up and running so expect more results on Graph in XPages with Notes data in the future on this blog.

Below are sampels of performance using the “traditional” FT search filter capacity in Notes. Notice the difference.



I would like to thank Oliver Busse for his guidance getting the demo app up and running and for explaining some basic concepts of the implementation.





Modernizing a Notes application


The quickest way of modernizing your application build on Notes is probably by keeping it on that sublime application platform and provide a new user-interface and updated business logic to it.

As a demonstratable example I would like to bring up my own Bildr project on OpenNTF.

A brief history

The application started initially as a web browser display only and create content via the Notes client application in the early 2000’s. From that the application was updated in a create content via the web browser too features.

Later the oneUI was implemented in a later step also utilizing the Application Layout control. With the Bootstrap4XPages plugin a responsive UI could be delivered a couple of years ago.

Nowadays the Application Layout control is no longer used but the Bootstrap responsive features and components are used further through the application.

The application still relies on XPages and Notes data (allthough used mainly in JSON format). The business logic resides mainly in Java Classes. With the separation of design and data the application could be hosted on Bluemix (not tested, please do).


Looking back at this application story I believe the application will change also in the future (or die) perhaps a challenge could be to have the data optional in a different source (e.g. MongoDB) or exchange XPages for Angular and run it on Node.js.

So if you have experience moving data from Notes to MongoDb, applying a similar ACL and Roles security model on your application I would be happy to hear your experiences.

Or if you are still on the Notes client only level and want to bring your application to a (mobile) browser I am happy to exchange ideas with you and learn from your situation.

New release

Why am I saying this? Today I uploaded a new version on OpenNTF and for many Notes developers who a) not have taken the XPages path yet b) unfamiliar with Java and JSON the application could be a great starter example.

Lately there are not that many (new, updated) projects (applications) available at OpenNTF so the chance to find a working demo to see and understand the code and data running are a bit scarce (I am sorry).

I remember in the days of Superhuman Software a quote about Notes and collaboration was “dare to share” so I would challenge more developers to do so. We can learn a lot from examples from others and I thank those people who (still) do and from which I can learn from!

I wish you a wonderful learning experience at IBMConnect 2016!



new release XPages OpenLog Logger and custom runtime error page


Good news for me! In an XPage application I wanted to provide an error logging function and preferably to OpenLog. I had problems with implementing the previous version of OpenLog logger but yesterday a new version is released on OpenNTF which took away that pain.

OpenLog logger

The OpenLog logger has some powerful features:

  • It can be used in your managed beans and other Java classes.
  • It can be used directly from SSJS with as little as openLogBean.addError(e,this);.
  • From SSJS all caught errors on the page are logged out together, at the end of the request.
  • Only two method names are used from SSJS, one to add an error, one to add an event, making it easy to pick up
  • From SSJS you only need to pass the information you wish. There is no need to pass nulls or empty strings.
  • From SSJS only one unique error per component is logged, regardless of how many times the error is encountered during the refresh lifecycle.
  • In SSJS, if you use a custom error page, uncaught errors will also be logged.
  • Uncaught errors will be logged for the page the error occurs on, not your custom error page.
  • You can define the OpenLog path and a variety of other variables without needing to change the code.
  • The functionality and code are available as an OSGi plugin (the best practice approach) but can also be included in individual NSFs.

Custom Runtime Error Page

In case you want to implement such functionality then I recommend you also take a look at how to define a custom run time error page. In my project I am using Bootstrap for UI look & feel, so I followed the steps Erick McCormick provides in this blog post.


In Erick’s post you will find that he uses Google’s code-prettify project. A nice feature is to ability to set a skin for the error message box. There are plenty of color themes available for the prettify project but if you use Bootstrap like I do you could try this theme.

A big thank you to the OpenLog logger project members and Erick!



Uninstalling Java extensions (“plugins”)


Yesterday I tried to install the OpenLog logger plugin in my development environment (Notes 9.0.x) to add some more common logging procedures to an Xapp (XPages application).

Unfortunately the installation failed and I received an error message ‘no accessible features found for this plugin’. The plugin was not available under application management so from there I could not undo the installation and deleting the plugin from the data\workspace… resulted in an error when starting up Designer.

So I feared a new setup of my development environment but luckily the first result after the query ‘lotus designer remove installed plugin’ was at help. I just repeat them here so I know I have stored it somewhere:

Complete guide to manually uninstalling “plugins” from Lotus IBM Notes

The complete steps to manually uninstalling a Java extension is therefore as follows:

  1. Close Lotus Notes
  2. Open the “features”-directory (<Notes data dir>\workspace\applications\eclipse\features)
  3. Locate the Eclipse features to uninstall.
  4. For each Eclipse feature you need to open it and edit the feature.xml file. Locate the <plugin>-tags and fine the names of the referenced plugins. Note that there might be more than one. Combining the plugin id and the plugin version will give the full filename of the plugin (<plugin id>_<plugin version>.jar).
  5. Delete the Eclipse features you’re uninstalling.
  6. Open the “plugins”-directory (<Notes data dir>\workspace\applications\eclipse\plugins).
  7. Delete the plugin JAR-file(s) you recorded in the step above.
  8. Open the directory containing the platform.xml file (<Notes data dir>\workspace\.config\org.eclipse.update).
  9. Edit platform.xml and go to the end of the file.
  10. Remove each entry you see for the features you deleted in the step above.
  11. Save and close the file.
  12. Since Lotus Notes also keeps a record of which Java extensions to load it’s best to start Notes with some parameters to make it recompute the Java extension registry: notes.exe -RPARAMS -clean

Good news

I posted the problems I experienced on the OpenNTF project page and Paul Withers answered he is working on a newer version of the plugin. Hopefully that one will work brilliantly in Notes 9 clients…

Using the language bean from XPages Toolkit for Internationalization


You have people who tend to tick around where they live and work and you have people who tend to switch location now and then. Especially in Europe which is divided into many countries with many different languages, somehow operating under one flague,  you are sometimes amazed that organizations have not fully adapted to the trend of “travelling” co-workers.

different langiages

If you are lucky an application is presented bilingual but in a lot of occasions an application is presented either in English (when that is the official language of communication) or in a native language where the application is initiated and being used.

But what if that cross-border European co-worker enters the work floor?


Internationalization refers to the process whereby you prepare your application for users from varied geographies. There are two parts to this:

The need for localization is obvious; a German user wants to see an application in German and a French user in French, and so on. Localization involves making different language versions of all the application’s user interface available and ensuring the correct strings are used based on user preferences.

Support in XPages

In the IBM Notes and Domino Application Development wiki you can learn about the support for internationalization in XPages.

In this post I will describe how you can use the language bean that is part of the XPages Toolkit available in OpenNTF.

Sample application

In this post we will build a simple XPages UI which looks as followed:


In a combo-box you get presented a list with available language options. And based upon your selection values will be collected from a set of property files.

I will include a dropbox link to the sample application.


First: download & install the library. Beside the library there is also a sample application which comes in handy to borrow code from.

Java classes

The following files you will need:


Property files

The property files contain the actual string values. The amount of files depends on the number of languages you want to support. In our case 4: English (default), Swedish, German and Dutch. There will be three types of files: general, contacts and keywords.  That makes 12 (4*3) in total.


Here is what the files could look like. First the general poperties file:

AppTitle=Language Bean
NotAvailable=Not Available
SwitchLanguage=Choose Your Language
Header=Demo Language Bean
SubHeader=Register A Person

Which becomes in Swedish:

AppTitle=Språk Böna
NotAvailable=Inte Tillgänglig
SwitchLanguage=Välj Ditt Språk
Header=Demo Språk Böna
SubHeader=Registrera En person

The contacts properties files:

LastName=Last Name
FirstName=First Name

In German:


And at last the keywords properties file:


Which becomes in Dutch:


The properties files are “registrered” in the language bean via the following method:

public List<String> getPropertyFileNames() {
List<String> propertyFileNames = new ArrayList<String>();
return propertyFileNames;

Layout custom control

My demo app contains 2 pages which demonstrates the 2 options you have with the toolkit: use the language bean or the toolkit @formula.

<?xml version=”1.0″ encoding=”UTF-8″?>
<xp:view xmlns:xp=”; xmlns:xe=””&gt;
<xe:applicationLayout id=”applicationLayout1″><xp:this.facets>
<xp:panel xp:key=”LeftColumn”>
<xe:navigator id=”navigator1″>
<xe:pageTreeNode page=”/bean.xsp”>
<xe:pageTreeNode page=”/formula.xsp”>
<xp:callback facetName=”facet_1″ id=”callback1″></xp:callback>
<xe:simpleResponsiveConfiguration navbarText=”Language Bean”
label=”Kwintessential Notes” title=”Visit My Site”>
label=”XPages Toolkit” title=”Visit Project on OpenNTF”>

Bean XPage

I will spare you the  complete code for the Bean page. Check the download if you want the complete code.  The principle is simple. You collect the value via the following pattern

xptI18NBean.getValue(“[properties file].[key]”)

That could become something like:


Switching language

In order to switch language a combobox control is presented with the following code:

<xp:comboBox id=”cbSwitchLanguage” defaultValue=”#{javascript:xptI18NBean.getCurrentLanguage()}”>
<xp:eventHandler event=”onchange” submit=”true” refreshMode=”complete”>
<![CDATA[#{javascript:var sv = getComponent(“cbSwitchLanguage”).getValue()
if(sv != null && sv != “”) {
var locSet:Locale = new Locale(sv);

Language options

The getAllLanguages method in the language bean “registers” the available language options:

public List<String> getAllLanguages() {
List<String> languages = new ArrayList<String>();
return languages;

That is basically it!

Formula XPage

This page differs from the Bean page in the way it accesses the property files. It uses a formula which is defined in the XPages Toolkit library.

The formula follows the following pattern:

@XPTLanguageValue(“[properties file].[keyword]”)

Which could become something like:



A sample application for download is available under the following URL.


I am curious what method you use to make your applications available in multiple languages. Please drop a line how you have solved it.

I found the language bean in the XPages Toolkit very intuitive and easy to use. At least in some cases it solves the problem nice and quickly so my thanks go out to it’s project members.


Using XControls for developing cards-based UI for mobile and desktop applications


For a project I reviewed several frameworks to deliver a web interface. Among them was XControls which is a project on OpenNTF. XControls promises to deliver:

  • Faster design and assembly of modern user interfaces, using Card & List objects.
  • Easy the auto-optimization for smartphones, tablets and PCs.


XControls is built with Bootstrap and the Bootcards project.


Bootcards is a cards-based UI and it is built on top of Bootstrap. Unlike most other UI frameworks, it includes a dual-pane interface for tablet users.

The documentation describes well the structure and options for the two main objects, card and list (analagous to Forms and Views in traditional Notes development).

Basically you have 2 types of list:

  • Normal.
  • Detailed.

Below is an example of the Detailed list:


And 8 types of cards:

  • Base.
  • Form.
  • Table.
  • Chart.
  • Summary.
  • Media.
  • File.
  • Rich text.

Below is an example of the Media card:



Bootstrap claims to be the most popular HTML, CSS, and JS framework for developing responsive, mobile first projects on the web. We will not introduce this framework further.

Getting started with XControls

Part of the documentation for XControls is the Getting started page which will walk you through creating a new application using XControls. I suggest to read this first and keep the primer documentation side by side.

Download the files

The required files can be either downloaded from OpenNTF or Github. Unfortunately XControls is not available as a plugin for your XPages development so you need to copy the required files manually in your existing project/NSF or you can use the provided NTF as a starter-kit for a new project.  The files are:

  • All custom controls starting with UnpBoot naming.
  • All Xpages starting with Unp naming.
  • All Resources\Files.
  • The”blank” theme (set this as application theme in XSP Properties file).

After that you are ready to develop the UI for your application! A recommended tip is to install the sampler application provided with the OpenNTF download and open that one in a browser and Domino Designer.

Test: Notebook/Journal

For my review I decided to apply the XControls methodology on a simple existing Notes application: the Notebook. This application allows you store simple documents which can combine rich text and file attachments. You are also able to ‘tag’ these documents by applying categories.

I will describe the steps taken to apply the XControls cards-based UI to this application.

Step: Copy the required files

The documentation does not describe to copy the unpCommon server-side javascript library.

Step: Create XPage unpMain

When creating an application, if it is going to be used on Teamstudio Unplugged mobile devices then we recommend that the home XPage is called UnpMain. Otherwise you are free to name your XPage.

Step: Add UnpBootResources

Every XPage that will be opened by the end-user needs the UnpBootResources custom control added. This adds CSS, JavaScript and Server Side JavaScript to your application.


Step: Create a common application layout

To provide a common application layout the Common Header and Common Footer custom controls should be included in the XPages that are accessible by the end-user.

Common Header

In case you want the app to develop for Mobile and Desktop then add a UnpBootNavigator and UnpBootHeader.

  • UnpBootNavigator: for mobile (the so-called ‘hamburger’ menu).
  • UnpBootHeader for desktop.

Also define the navitems in UnpBootHeader.

<unp:UnpBootHeader title=”${javascript:return @DbTitle()}”>
{label: “All Entries”, hasSubMenu: false, page: “/UnpMain.xsp”, icon: “fa-database”},
{label: “By Category”, hasSubMenu: false, page: “/vwCategory.xsp”, icon: “fa-list”},
{label: “By Entry Date”, hasSubMenu: false, page: “/vwEntryDate.xsp”, icon: “fa-calendar”},
{label: “Trash”, hasSubMenu: false, page: “/vwTrash.xsp”, icon: “fa-trash-o”}


{label: “All Entries”, hasSubMenu: false, page: “/UnpMain.xsp”, icon: “fa-database”},
{label: “By Category”, hasSubMenu: false, page: “/vwCategory.xsp”, icon: “fa-list”},
{label: “By Entry Date”, hasSubMenu: false, page: “/vwEntryDate.xsp”, icon: “fa-calendar”},
{label: “Trash”, hasSubMenu: false, page: “/vwTrash.xsp”, icon: “fa-trash-o”}


Font Awesome

Font Awesome gives you scalable vector icons that can instantly be customized – size, color, drop shadow, and anything that can be done with the power of CSS. XControls supports Font Awesome icons everywhere.

As you can see in the code above Font Awesome is for example used in the common header.

Common Footer

In case you want to include synch (for when running on Unplugged) add the UnpBootFooter as the common footer. You can also apply tabs in the footer if desired.

<unp:UnpBootFooter synctype=”none”>
{label: “Google”, hasSubMenu: false, page: “;, icon: “fa-google”},
{label: “Like us”, hasSubMenu: false, page: “;, icon: “fa-facebook”}



Best practice tip

Since you will place the application layout just created across multiple XPages it is wise to store them in re-usable custom controls e.g. commonheader and commonfooter.

Step: Create the first content list

In the navigation we have declared that the initial XPage shall contain the All Entries overview. This overview simply lists the documents in a flat structure. You can use the UnpBootFlatView custom control for this.

Apply wrappers

To layout the content according to the bootcards definition apply a wrapper for the content:

<div id=”main” class=”container bootcards-container”>
<div class=”row fullheightrow”>
<!– add your list –>
<div id=”doccontent” class=”col-sm-7 bootcards-cards hidden-xs”>
<!– add your initial content e.g. a card–>

In the dual pane UI the target for dropping card content will be the div with ID doccontent.

Apply a list

<unp:UnpBootFlatView viewname=”($All)” summarycolumn=”$52″
numberofrows=”20″ newlink=”entry.xsp” xpagedoc=”UnpMain.xsp”
title=”All Entries” ajaxload=”Yes”>

A description for all the available properties for the UnpBootFlatview can be read here: link. Property xpagedoc defines the xpage to load documents with, by default this would be the same as the current XPage.

Below is the result (only 2 documents in the database at the moment):



Below is the result when clicking on the Add link:


The XPage entry.xsp will be opened in a dialog. For now entry.xsp contains an unconfigured Form Editor custom control only. As you can see this requires more work.



Apply a Form Viewer

A Form Viewer is a wrapper that allows you to display document data inside a card. I created a custom control named docviewer and placed a UnpBootFormViewer inside it and configured it as followed:

<unp:UnpBootFormViewer editxpagewithajax=”yes”
formname=”JournalEntry” title=”Notebook Entry”
titleiconfield=”thumbnail” showbuttons=”true”
<unp:this.footertext><![CDATA[#{javascript:var id = context.getUrlParameter(“documentId”);
if (id != “”){
var doc:NotesDocument = database.getDocumentByUNID(id);
if (doc !=null){
var date = doc.getLastModified();
return “Last modified: ” + date
<xp:this.rendered><![CDATA[#{javascript:context.getUrlParameter(“documentId”) != “”}]]></xp:this.rendered>
<xp:panel id=”list-group” xp:key=”facet_1″ styleClass=”panel”>
<div class=”list-group”>
<div class=”list-group-item”>
<xp:text id=”subject” tagName=”h4″ styleClass=”list-group-item-heading”>
<div class=”list-group-item”>
<xp:label value=”Category” id=”lblCategory” for=”category”></xp:label>
<xp:text tagName=”h4″ id=”category” value=”#{docview.Categories}” styleClass=”list-group-item-heading”></xp:text>
<div class=”list-group-item”>
<xp:label value=”Date” id=”lblDate” for=”date”></xp:label>
<xp:text tagName=”h4″ id=”date” value=”#{docview.DiaryDate}” styleClass=”list-group-item-heading”></xp:text>
<div class=”list-group-item”>
<xp:label value=”Content” id=”lblCnt” for=”content”></xp:label>
<xp:text tagName=”h4″ id=”content” value=”#{docview.Body}” styleClass=”list-group-item-heading” escape=”false”></xp:text>

Again the entry.xsp is set to offer the document in edit mode (in a dialog). It appears that docview is the representation of the document. If you want to use data from the document outside the facet e.g. in the card footer you seem not to be able to refer to docview.

Below is an example of a selected document from the list:


If you select Edit the document is presented in a dialog via XPage entry.xsp which is still empty. Let’s work on that one right now!

Apply a Form Editor

A Form Editor is a wrapper into which you can insert form fields for creating and editing documents. Fields can include auto clearing, type ahead, date pickers, numbers and rich text.

Below is the code that I included in the Xpage entry.xsp which is shown in dialog boxes when editing or creating a new document:

<unp:UnpBootFormEditor showbuttons=”true”
viewxpagename=”UnpMain.xsp” title=”Entry” formname=”JournalEntry”
footertext=”You can use your Notebook as a diary, to store meeting minutes or status reports, or simply as a place to create and store draft documents until they are ready for publication.”>
<xp:panel xp:key=”facet_1″ id=”list-group”>
<div class=”form-group”>
<xp:label styleClass=”col-xs-4 control-label” for=”subject” value=”Subject”></xp:label>
<div class=”col-xs-8″>
<xp:inputText id=”subject” value=”#{docedit.subject}” styleClass=”form-control required”>
<xp:attr name=”placeholder” value=”Subject”></xp:attr>
<a href=”” class=”bootcards-clearinput”>
<i class=”fa fa-lg fa-times-circle”></i>
<div class=”form-group”>
<xp:label value=”Date” id=”datetime_dairydatelabel” for=”dairydate”
styleClass=”col-xs-4 control-label”>
<div class=”col-xs-8″>
<xp:inputText id=”dairydate”
<xp:attr name=”datevalue”>
var date:lotus.domino.local.DateTime = docedit.getItemValueDateTime(‘DiaryDate’);
return date.toJavaDate().getTime();
return new Date().getTime();
<xp:convertDateTime type=”date”

<div class=”form-group”>
<xp:label styleClass=”col-xs-4 control-label” for=”Categories” value=”Category”></xp:label>
<div class=”col-xs-8″>
<xp:inputText id=”Categories” value=”#{docedit.Categories}” styleClass=”form-control required”>
<xp:attr name=”placeholder” value=”Category”></xp:attr>
<a href=”” class=”bootcards-clearinput”>
<i class=”fa fa-lg fa-times-circle”></i>
<div class=”form-group”>
<xp:label value=”Content” id=”biolabel” for=”content” styleClass=”col-xs-4 control-label”>
<div class=”col-xs-8″>
<unp:UnpBootRichTextEditor fieldname=”Body”></unp:UnpBootRichTextEditor>


  • For the viewxpagename property I have chosen the UnpMain.xsp Xpage, this is the XPage to open after saving the document. Normally this would be the same as the current XPage.
  • The date field is bound to a date-picker.
  • For the rich text field I included a UnpBootRichTextEditor custom control. This will give the field some edit options.

Below is an example of the result. As you can see I did not at so many bells & whistles to the form editor (yet) to improve usability:


Step: Create the categorized content list

Can you imagine a Notes application without a categorized view? Probably not. In XControls you seem to have 2 options:

  • A flat list.
  • An accordion list.

A flat list for categorization, really? If you bind the UnpBootFlatView custom control to a categorized view as in the example below, the categorized view will be displayed as a flat list, but with documents/entries grouped in the provided categories:

<unp:UnpBootFlatView title=”Entries By Category”
summarycolumn=”$52″ viewname=”By Category” numberofrows=”20″
ajaxload=”Yes” detailcolumn=”$44″ xpagedoc=”vwCategory.xsp”
newlink=”entry.xsp” footertext=”A Flat List but with Categories :-?”>

Below is an example of the result:


Accordion list

However, if you want to apply a collapsible Notes-a-like feature, you can choose the UnpBootAccordion custom control to provide an Accordion list.

<unp:UnpBootAccordionView title=”Dates” summarycolumn=”$39″
viewname=”By Diary Date” expandfirstcategory=”no” ajaxload=”Yes”
loaddocumenttarget=”doccontent” detailcolumn=”$44″
xpagedoc=”vwEntryDate.xsp” newdatatarget=”#editModal”
<unp:this.footertext><![CDATA[#{javascript:var date = @Date(@Today());
return “Today is: ” + date.toDateString()}]]></unp:this.footertext>

Below is an example of the result:


The ‘categories’ are collapsible. Note that I had to modify the column value for the date: @Text(DiaryDate).



So far my initial review took. It seems fair enough to say that XControls enables you to deliver a dual pane cards-based UI for your Notes application without too much amount of development time.

I did explore many other features the framework offers (calendaring, carousels, charts) but it is definitely an OpenNTF project to keep an eye on. Especially if you are not capable of running a full blown solution like Worklight or you want to test early feedback for delivering existing Notes applications to mobile devices.