logo: Ytria - Essential Tools for IBM Notes and Domino (Lotus)
Ytria Tech Lab
Articles, Tips, and Code for IBM Notes and Domino Administrators & Developers

Investigating private views, folders and agents in Lotus Notes applications

on 9/06/12

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.

A brief introduction private design elements

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.

These ACL attributes dictate whether or not a user can create private design elements in a Lotus Notes database

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).

Note the ‘Private’, ‘Shared, private on first use’, and ‘Shared, desktop private on first use’ options in the Lotus Notes Create View dialog

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.

Managing private design elements with Ytria tools

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):

  1. 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.”
  2. Basic NSFSearch query. This method will reveal server private design elements (within the framework of Notes security of course) but can be considerably slower.

Tip: If you’re curious, you can actually see the Design Collection note inside scanEZ. It’s under Designs>Other>Design Collection in the Selection Tree.

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.

Tip: scanEZ’s in-product Help offers a handy table of $Flag values and their definitions

Access matters: How Notes security affects private designs

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.

A private Lotus Notes design (in this case a folder) as seen in scanEZ

Private folders as shown in viewEZ; note the ‘Read private design elements (views and folders)’ checkbox near the bottom of the screen

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.

Here we’ve grouped by ‘number of private design element notes’

Retrieving note counters can dramatically increase the time databaseEZ requires to load detailed database information, so it’s turned off by default

The Grid Data Composition Panel in databaseEZ lets you add ‘Note Counters’ to the main grid

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.

scanEZ lets you toggle private/shared status for an agent…

…but as this dialog warns: this will recreate the agent with different UNID

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.

Opening the desktop file in viewEZ lets us investigate the view and folder design for desktop private design elements

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.

Here we can see the private views in folders in this desktop file. Interestingly enough, the design class is *not* ‘private view’ but rather that of a shared view 

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.

4 Comments

  1. I think it’s worth to mention, that in case of roaming users, the desktop8.ndk isn’t used to store the desktop private design elements. Instead, they are stored within the users bookmark.nsf which we can be easily accessed, since you usually have replicas of the roaming databases on the domino server.

  2. That is an excellent point Patrick. Thanks for chiming in.

  3. Hi,

    I would like to know if there is a way to query private views with Domino Driver on a ODBC Connection. I tried such an exercise however the views are not visible.

    Thx

  4. Hi Bogdan,

    Thank you for your question – let me try and answer.

    When you’re trying to access private views by code (LS or Java) it’s important to realize that you can only reach those designs if they are stored in the database (i.e. ‘Server private’) and not locally (i.e. ‘Desktop private’).
    Plus, due to the readers field protection, these views are only available for the user they’ve been created for. There is a way to overcome this restriction though:
    – For server databases, you need to enable Full Access Administration (FAA). Note that enabling FAA from code (like an ODBC session) could be quite difficult if not impossible.
    – For a local database, you must unset the “Enable a consistent ACL across all replicas”
    What you could try first is to access a database using scanEZ and see what private designs you can access from there.
    One thing I’m not sure about is whether or not your ODBC Driver uses the Design Collection to search for designs, or even check / validate their existence. This method won’t return any private designs and so it could forbid you from accessing them through the driver. Using scanEZ you can get to these private designs, and copy their UNID or NoteID to try and access them by using these IDs – which could be a workaround.
    Apart from the above, I don’t see any reason why you couldn’t access private views using the ODBC Driver.

Leave a Comment

To diplay code in your comment, put the code between these brackets: [cc]your code[/cc]. You can also put inline code by using these: [cci]your inline code[/cci]