Your Development & Design Resource

MVC, Readers-type NotesItems, and Data Proxies in IBM Lotus Notes Domino Application Development

Here's a typical scenario:

You have a simple approval/rejection-style workflow application in Lotus Notes Domino (either as a Lotus Notes Client, Domino, or hybrid multi-client application).

Your application, let's say it's a IT requisition application (ie., "I need a new...[enter IT asset here]"), and it relies on Readers-type fields (or NotesItems) to limit who can see given requests.

I, of course, have a customer who does this very thing: they have a home-grown IT asset requisition solution that runs on IBM Lotus Notes Domino. The only problem they run into is when a reviewer is out of the office, on vacation, or for some reason can't approve the request.

See, the Readers NotesItems use a combination of information gathered from the NotesDocument. Basically, the only people that can read the given NotesDocument is the Author, the Author's Manager, the Author's VP, and the IT Department.

To restrict read-access to the given NotesDocument, the names of those individuals are added to a default-access list:

@Trim( @Unique( author : author_manager : author_vp : "[isAdmin]" : "[isReader]" ) )

Now, this method is pretty standard, and fails in two ways:

  1. What happens when the VP is out of the office?
    It's bound to happen, your VP just won't be there to approve/reject the request... and it will sit in limbo. Well, sitting in limbo is really the best case scenario here, as I've always found that the VP being AWOL often results in a phone call from someone who's trying to get that mouse (or whatever the requisition was for...) yesterday. This can result in you needing to modify the NotesDocument to add an additional reviewer or bypass the workflow on behalf of VP.

  2. The VP's assistant tries to go into the requisition via the workflow-generated email...
    ... and now, as far as they're concerned, your application doesn't work. Why? They're not in the Readers field for the given NotesDocument, and so they're presented with the MessageString via the $$ReturnGeneralError. Again, the UX here is that the application is broken. You'll get a call shortly asking you what's up, and you'll have to change the NotesDocument to comply.

In both of these scenarios, you find yourself needing to jump in and modify the NotesDocument to give someone access... and maybe it's because I'm ultimately a lazy person, but I think that's the wrong way to go about getting the job done.

Let's talk about when we should use Reader-type NotesItems.

Reader-type NotesItems are designed to lock down NotesDocuments. If you never want those NotesDocuments read by the wrong person, then you can use reader fields... or at least that's what we're used to doing.

See, via the web, a Reader-restricted (if you will) triggers the same error that a previously deleted or just plain bogus NotesDocument call will return. Pretty much the same thing for the Lotus Notes Client User Experience as well.

When using a Reader-type NotesItem, if you're not listed either explicitly in the field or via a User Role, that NotesDocument doesn't exist. This means that at best you won't know what you're missing, but at worst any links that you come across just won't work.

Anyone who's worked with Reader Fields and has locked themselves out of a NotesDocument will know this pain... but it's more the impact to the user where this standard development technique really shows it's cracks.

So understanding when we should use Readers fields (ie., when it absolutely, positively must not be see) and understanding when they shouldn't be used can really make or break your applications.

There is, of course, always a push to improve the not only the UX, but also create an ease of maintenance and evolution in tandem with business needs. With that, let's talk about MVC application architecture, and apply that to our example IT Requisitions application:

State IBM Lotus Notes/Domino equivalent
Model Non-UI rendered NotesView or your NotesDocumentCollections.
View Any visual element. Forms, Pages, Views, etc.
Controller In this case, it's the Form Design Element and your Readers-type Fields.

This, of course, isn't true MVC, as we can plainly see that the Controller shares the same elements as the View states.

So how could we leverage true MVC for workflow-type IBM Lotus Notes Domino Applications and get around the Reader-type NotesItem issues?

Well, I propose the following:

State IBM Lotus Notes/Domino equivalent
Model Non-UI rendered NotesView or your NotesDocumentCollections.
View Pages and XPages, and pretty much ANY external platform/technology that can make HTTP Requests...
Controller A data proxy Agent Design Element, Web Service, or XPage that consumes HTTP requests, processes those request against control settings that maintain the business logic, and returns XML, JSON, or other raw data to the View.

See, there's really no reason -- for this particular application or really any Lotus Notes Domino Application like our example IT requisitions app -- that we shouldn't be using a data proxy to query and return NotesData, submit NotesData changes, and ultimately separate all User Interface components from our backend data store.

The benefit to this is that we'll be accessing NotesDocumentCollections via API, and not via View Design Elements, NotesDocument Unique ID, or any other locked-to-Lotus Notes Domino rendering options. What this means is that not only could our application front-ends/UIs change as needed (or be ported to another technology with ease), but you can easily control who sees what without needing to modify the source NotesDocuments... such as adding or removing names to Reader-type NotesItems.

To get there, all we really need is a data proxy that handles CRUD while taking queues from user/admin-defined business logic in our application.

To do that, we'll need the following:

  • Control NotesDocuments
    We'll create a Form and Views to allow us to maintain Control NotesDocuments, which will contain all application business logic - ie., what NotesDocuments and NotesItems are created, read, updated, and deleted.

  • Controller
    Your Agent/Web Service/XPage that will act as your front-end HTTP Request consumer, query your Control NotesDocuments, and basically do all of the work.

  • A defined API
    You're building a custom API here... you call the shots. What are the commands, syntaxes, etc. to interact with your Controller, and ultimately interact with your NotesData.

Let's run with this and create a simple CRUD syntax:


http://server/db.nsf/controller?open&action=Read&UNID= 094E734F93F9BF7C852576950071D96D

http://server/db.nsf/controller?open&action=Update&UNID=094E734F93 F9BF7C852576950071D96D

http://server/db.nsf/controller?open&action=Delete&UNID=094E734F93 F9BF7C852576950071D96D

(Simple GET Method here, where you could append multiple QueryString Parameters to the HTTP Request, but for the sake of this example...)

Simple right? Of course not, but I guarantee you this: you write this once, and you're done.

With a proper MVC platform, data is data. Your View will interact with your Controller - submitting requests against your defined API. Your Controller will rely on your Control NotesDocuments for ALL logic. This means that your MVC could be a plug-in for any Lotus Notes Domino Application, from IT Requisition applications to Helpdesk Ticketing Systems to Project Management and beyond.

This ALSO means that your View can be any technology platform that is capable of making HTTP Requests. Drop a Domino Server in your DMZ and have this application lookup via Domino-to-Domino connections (read: your other Domino server's don't even need to run the HTTP task...!). Write your entire application in Adobe Air, Flex, Flash, Dreamweaver, PHP, Coldfusion, PHP, or Notepad - it doesn't matter.

The MVC model we're talking about here is something that I've discussed at length before..., and it's something that I believe again will make our lives all a little bit easier.

Looks like I need to put YellowCake 2.0 on my short list for deliverables...

About the author: Chris Toohey

Thought Leadership, Web & Mobile Application Development, Solutions Integration, Technical Writing & Mentoring

A published developer and webmaster of, Chris Toohey specializes in platform application development, solutions integration, and evangelism of platform capabilities and best practices.

More from is powered by IBM Notes Domino XPages & hosted by Prominic.NET

Contact Us

Use our Contact / Feedback form or one of these email addresses:

Creative Commons License

Except where otherwise noted, by Chris Toohey is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.