Investigating private views, folders and agents in Lotus Notes applications

There’s little doubt that private design elements are powerful and flexible tools for Notes developers, but at the same time, managing them and understanding their intricacies can be a bit tricky. With this post, we’ll do our best to clear things up a bit.

First we’ll provide an overview of how private designs work and how they’re made; then we’ll highlight a few private design-related issues and offer some solutions; and finally we’ll show some time-saving tricks and interesting curiosities related to managing private designs in Ytria tools.

What is a private design?

If a design element is available to only one person, it’s known as a ‘private design.’ Designs that aren’t private are described as ‘public’ (or ‘shared’). Views, folders, and agents are the three types of designs that can be private. (That said, the Lotus Notes and Domino Application Development Wiki intriguingly states, “[i]n theory, any design element type can be private, but generally, only views, folders and agents can easily be created as private by users.” We’ve never seen any other sorts of private designs in the wild, so please leave a comment if you’ve managed to create any).

‘Server private’ vs ‘Desktop private’

There are two categories of private design elements: ‘Server private’ and ‘Desktop private.’

‘Server private‘ designs are stored in the actual application .nsf file when you have the ACL rights to create them. Private agents, as far as we’ve been able to determine, are always ‘server private’ designs.

‘Desktop private‘ designs are stored in a user’s desktop file. These designs are created when a user generates a private view or folder but doesn’t not have the authorization to create these designs in the .nsf file. We’ll talk some more about Desktop private designs and their unusual characteristics at the end of this post.

Private views and folders

Views and folders can be either shared (public), private, or something call ‘private on first use.’

‘Private’ views or folders are either created in the database itself (server private) or a user’s desktop (desktop private). They’re designed to allow users to organize documents in a way that suits their own specific needs. Private views and folders are not available on the Web.

‘Private on first use’ views or folders are initially ‘shared’ but become ‘private’ as soon as a user accesses and saves them. These designs can be a handy way to distribute personalized views and folders to multiple users. These designs will typically make use of the @UserName command to customize the display for users. Aside from workarounds with embedded views, these private-on-first-use designs offer the only methods for getting a view or folder to display personalized information (e.g. documents created by the current user).

It’s important to be aware that, after a user saves a private-on-first-use view or folder, the user’s copy of the design no longer inherits design changes. So if you add a new column to a view of this sort, current users won’t obtain the changes. In order to get an updated version of a private-on-first-use view, the user would need to delete their private version of the design and open the private-on-first use view again.

Private-on-first-use folders are a different matter altogether, as getting a user to delete and re-generate their private folders would mean losing all folder contents. There are techniques to allow you to update private folders (provides these are server private) such as those used in the mail template. This is out of the scope of this article, but we may explore this is a future post. (Incidentally, we’ve had a couple earlier posts on ‘Private on first use views,’ here’s one; and here’s the other.

‘Shared, desktop private-on-first-use’ views and folders are used when you want these designs to automatically be stored on a user’s desktop file (instead of the server).

Private agents

Agents can also be Private or Shared. Personal or Private agents are treated considerably different from their private view/folder brethren. If a private agent is not your own, it won’t be shown in the Actions menu of the Lotus Notes client. However, provided you have at least Designer access to a database, you’ll be able to see and execute any private agents (unlike private views and folders, there is no Reader/Author field restrictions). We can identify private agents by low-level attributes (use scanEZ to see them) that we will delve into later, or through Lotusscript and Java “Agent” classes’ Boolean Property “IsPublic”.

Because private agents have neither Reader/Author field restrictions nor indexes to contend with, they’re comparably easier to update and deal with after being created. Also, since end-users rarely have the rights (through their signature) to create an agent that will run on a schedule, private/personal agents will rarely give the Domino professional serious headaches.

How to look at server private designs in Ytria’s software

When Ytria tools gather lists of design elements, they offer two different methods (and the product interfaces always allow you to choose between the two):

Design Collection: This method is enabled by default in Ytria tools. It relies on something stored inside the database called the Design Collection. It will not retrieve private design elements. IBM’s own Inside Notes: The Architecture of Notes and the Domino Server publication explains that there is a single Design Collection note per database and it “[s]pecifies a special view that indexes all form, view, filter, field, replformula, and help-index notes in a database.”
Basic NSFSearch query. This method will reveal server private design elements (within the framework of Notes security of course) but can be considerably slower.

The low-level makeup of a private design

What makes a design private? Well, first and foremost, its low level Note Class is designated as private when it is created (the class value will be “0x1008″ for private agents and “0x1200″ for private views and folders). And for private views and folders (but not agents) there’s also a $Readers field and $Authors field which contains the the owner’s user ID. Lastly, server private views, folders and agents have a special “V” flag as part of their $Flags item, which indicates it’s a “server private” design.

The general rules of Lotus Notes security apply when using Ytria products to access private designs because the tools are fully compliant with Notes security. That means that you can see any private designs on local databases (Reader fields do not protect local databases) and any of your own private designs on databases on servers. It is possible to see private designs that you haven’t created for databases on servers if you enable Full Access Administration in a Ytria tool; you must be listed as a full access administrator on the server for this to work (again, the tools comply with Notes security).

Desktop private views and folders are a different matter as they are stored on a user’s local desktop file. There’s no way to access them by code. That said, check the sidebar below for a little trick for seeing all of a user’s desktop private designs with scanEZ.

The big picture: Get total private design counts across a server

Should you ever wish to survey the databases in your environment to find out how many private designs are being used, Ytria’s databaseEZ is an ideal tool for the job. It offers the ability to retrieve and display ‘note counters,’ including ‘Number of private design class notes,’ for any number of databases on a server.

There’s a slight catch to this though: loading notes counter columns will dramatically increase the time it takes to populate databaseEZ’s grid—that’s why the functionality is disabled by default. Just click Tools>Permit loading note counter columns and then you’ll be able to perform this type of scan. Next you need to add the ‘Number of private design class notes’ column in the Grid Data Composition panel and click ‘Apply.’ And of course you’ll need to have databases open and selected in the tree. Finally, complete database information needs to be loaded in the main databaseEZ grid (just select the databases in the grid and click Ctrl+L).

Tip: Even if a note counter scan takes a very long time, it will not tie up your Lotus Notes client. Also, you can open up a second databaseEZ session to do other work while it processing in the worst case scenario.

Share/Unshare agents in scanEZ

The note class which determines a design’s private or shared status is very low-level and unchangeable. That said, both Domino Designer and scanEZ do provide means to ‘Share/Unshare an Agent.’ But there is a bit of a catch: in order to work, it will delete and recreate the agent in question, thus generating a new UNID since we’re creating a whole new note by copying all items.

We’ve been asked in the past, ‘why don’t you offer a similar functionality for toggling the private/shared status for views?’ The reason why we haven’t is because we feel that deleting a view or folder and recreating it with a different UNID is quite likely to have unfavorable consequences since rebuilding the index can be very process intensive.

The mysterious world of desktop private views and folders

When users don’t have the rights in their ACLs to create private views or folders on a Lotus Notes application, they can create ‘desktop private’ view and folder. These design elements are stored in the user’s desktop file. And, interestingly enough, you can see these views and folders by opening your desktop file (desktop8.ndk if you’re using Notes 8.x) in Ytria scanEZ or viewEZ.

In most respects the desktop file is a ‘black box’ with very little information that’s readable for humans. But in the case of these ‘private desktop’ view and folders, they’re easily accessible in scanEZ’s tree and in viewEZ’s interface.

We did a couple quick tests and found that you can move a desktop private view to a database on a server and it will work. Folders can also be copied but their contents will be lost (but at least the design is maintained). One thing we couldn’t find was any sort of marker in the view or folder telling which database it is used in. In the hypothetical case of a power user with hundreds of these desktop private views in his or her desktop file, it’s nice that you can at least see (and delete) these designs all in one place.

Please note that you must make use of the ‘Basic Search’ (as opposed to the Design Collection) in order to see the private designs in a desktop file. In the case of scanEZ, this means un-checking the ‘Use Design Collection Note’ checkbox (shown below). In the case of viewEZ, you just need to tick the ‘Show Private Views and Folders’ checkbox in the tool’s first dialog.

Update: Patrick Tippner correctly notes in the comments that in the case of roaming users, the bookmark.nsf file is used to store private designs.