Mobile tag

About Me

I am the "IBM Collaboration & Productivity Advisor" for IBM Asia Pacific. I'm based in Singapore.
Reach out to me via:
Follow notessensei on Twitter
Amazon Store
Amazon Kindle


Domino Upgrade

VersionSupport end
Upgrade to 9.x now!
(see the full Lotus lifcyle) To make your upgrade a success use the Upgrade Cheat Sheet.
Contemplating to replace Notes? You have to read this! (also available on Slideshare)


Other languages on request.


Useful Tools

Get Firefox
Use OpenDNS
The support for Windows XP has come to an end . Time to consider an alternative to move on.

« You approved what? | Main| Domino Development - Back to Basics - Part 2: Forms and Documents »

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


Gravatar Image1 - 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!

Gravatar Image2 - 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!

Gravatar Image3 - @Rakesh: coming in Part 3: Views and search. Might not be in table form.

Gravatar Image4 - "The serial number counts the times that note has been updated..."

I thought the "SN" stood for "Sequence Number?"

Gravatar Image5 - @Nathan serial/sequence all the same...

Gravatar Image6 - 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.

Post A Comment

Please note: Comments without a valid and working eMail address will be removed. This is my site, so I decide what stays here and what goes.



This site is in no way affiliated, endorsed, sanctioned, supported, nor enlightened by Lotus Software nor IBM Corporation. I may be an employee, but the opinions, theories, facts, etc. presented here are my own and are in now way given in any official capacity. In short, these are my words and this is my site, not IBM's - and don't even begin to think otherwise. (Disclaimer shamelessly plugged from Rocky Oliver)
© 2003 - 2014 Stephan H. Wissel - some rights reserved as listed here: Creative Commons License
Unless otherwise labeled by its originating author, the content found on this site is made available under the terms of an Attribution/NonCommercial/ShareAlike Creative Commons License, with the exception that no rights are granted -- since they are not mine to grant -- in any logo, graphic design, trademarks or trade names of any type. Code samples and code downloads on this site are, unless otherwise labeled, made available under an Apache 2.0 license. Other license models are available on written request and written confirmation.