Usability - Productivity - Business - The web - Singapore & Twins

Domino Development - Back to Basics - Part 1: The NSF

Over the last five years I have trained many developers on XPages. A good portion of them came from a non-Notes development background: Java, dotNet, PHP and others. Most of them had a better grasp on the necessities of web development than most of their die-hard-is-there-anything-other-than-the-Notes-client LotusScript colleagues. However they struggled to fully appreciate the finer points of the NSF based nature of Domino development. The little article series is for them.
In short: Notes is a distributed application platform with an integrated NoSQL document database featuring a rich security and event model. It can be accessed in many different languages and protocols. While it is written in C, the most prominent languages used to develop applications in Notes are LotusScript (a Basic dialect, now de emphasised), JavaScript and Java. The most used protocols are HTTP(s), NRPC and SMTP.

In the beginning was the NSF

Almost everything in Notes is stored in NSF databases (NSF = Notes Storage Facility).
The core structure of a Notes database
A NSF contains properties, an Access Control List, View indexes and a collection of Note elements, hence the name Note(s). The file name is not a property stored inside the NSF, however the title and the ReplicaID are. The ReplicaID has a special meaning: two databases sharing the same ReplicaID can synchronise their content in a process called replication, typically between a client and a server or multiple servers. When a server contains two or more NSF with the same replicaID replication can happen with any of them. A typical mistake: copy a NSF on the file system "as backup" creating not a copy but a replica. There is a menu action that creates a real copy for that (File - Application - New Copy).
Inside the NSF all data is stored in Note elements: both the design of the database, as well as the actual content. A data note (a.k.a Document) can be listed in a view (with the exception of a profile document), while a design note lists only in Domino Designer (unless you hack it). Design and data note elements share the same inner structure.
NSF do not contain any schema or data definitions. It is all Note and Item.

A Note is where you find anything

An individual note contains a series of properties and a collection of items (not to confuse with a field in an RDBMS or a field in a form). Besides data values for creation and update a note carries a UniversalId, a NoteId and a serial number. The NoteId is unique inside one specific NSF, the UniversalId is the identifier to link two note elements in two NSF (that have the same ReplicaId) together, so they synchronise on replication. The UniversalId is unique inside the NSF. Two different NSF can have documents with the same UniversalId. This is not an exception, but happens e.g. on mail routing. The serial number counts the times that note has been updated and is used in conflict resolution while replicating.
the basic unit of storage is a Note
The contained items follow the same pattern: they have a name, a set of properties and a collection of values. Two important properties are name and type. The name of an item doesn't need to be unique. Quite regular, especially when looking at the type RichText you have more than one item with the same name (for RichText the unwritten convention is to use the name Body). Items that start with the $ sign are used for system properties (e.g. $HasNativeMime indicates that the note contains a MIME document rather than RichText). Items also contain a serial number for conflict resolution in replication. The values in an item share the same data type. Items are always multi-value (a Vector in Java) even if the count is just one.
Next up: Forms and Documents

Posted by on 23 December 2013 | Comments (6) | categories: IBM Notes XPages


  1. posted by Ben M. on Monday 23 December 2013 AD:
    This is a very well written article Stephan, thank you. I've done many training on this matter and wanted to write up the basics myself but from here on out I'll just use this one.
    I find that even some developers are confused when it comes to discussing the difference between fields and items and I've heard the question "so what happens if I modify an item name on the back-end of a document - am I changing the form as well?" - way too many times...
    Looking forward to the next article!
  2. posted by Rakesh on Monday 23 December 2013 AD:
    This is a very good article. One suggestion would be to include a comparative table between sql and notes which helps in clarifying the concepts. Looking forward to the next one!
  3. posted by Stephan H. Wissel on Monday 23 December 2013 AD:
    @Rakesh: coming in Part 3: Views and search. Might not be in table form.
  4. posted by Nathan T. Freeman on Monday 23 December 2013 AD:
    "The serial number counts the times that note has been updated..."

    I thought the "SN" stood for "Sequence Number?"
  5. posted by Stephan H. Wissel on Tuesday 24 December 2013 AD:
    @Nathan serial/sequence all the same...
  6. posted by Paul Withers on Monday 06 January 2014 AD:
    The Seq Num on an Item is very useful for diagnosing when a value was updated and who by. $Revisions shows the amount of times the document was updated and $UpdatedBy shows the editors (although if I edit a doc third and fourth, I show only once; if I edit it 2nd and 4th, I'll show twice, either side of whoever edited it 3rd). With a combination of the three I've answered many a support query. It's another good reason to ensure, if you're using managed beans, that you're not updating an item on every save, only if the value's changed.