Upgrading Lotus Notes folder/view designs: a scanEZ tutorial for advanced users

We recently needed to update a number of folders in an internal application and found that scanEZ along with the undocumented ‘@UpdateViewDesign‘ @function provided us the best and easiest way to do this. The actual task at hand might not be something you’d personally need to do but if you can bear with us, the following tutorial will show some lesser known advanced features in scanEZ that anyone who owns the software ought to know about.

Here’s what needed to be done:

The internal application in question contains a very large number of folders which are used for many and various important tasks (e.g. assisting in upgrade processes; issue tracking; analysis; etc.). The ACL for this database permits employees to create shared folders; many of these new folders use the original view or folder as a ‘template.’

After we made some changes to the default view/folder (we added a new status flag along with various aesthetic enhancements), we wanted the many existing folders to be updated to take advantage of these changes.

We couldn’t just refresh the design because the folders that required updating weren’t part of the original database template and they were set to “prohibit refresh.”

Then it dawned upon us that the @UpdateViewDesign function is ideally suited for this task. This @function was introduced in Lotus Notes and Domino R5 and has been used in the Upgrade Folder Design agent in the mail template since R6; read more about it here (for a post where Alan Lepofsky shows how the Upgrade Folder Design in the mail database works).

As an aside, we theoretically could have done this job without scanEZ. But this would have involved copying the Upgrade Folder Design agent, along with the sundry other design elements required for its use, to the database in question. What’s more, we would’ve had to modify the code in order for it to work properly in this very different context.

In short, this is another case where scanEZ prevented us from having to do a lot of development work just for a one-off task.

So here’s how we used this @function along with scanEZ to get the job done:

Part 1: Selecting the folders to update

Let’s get started by opening scanEZ:

To gather the appropriate selection of folders, first expand the Designs category in the Selection Tree and then select the Folders category. With a category selected you should see the Diff panel interface.

Next click the Diff button to perform a differencing operation on all the items in your folders.

$TITLE – We need this to see the name and alias of the folders.

$Flags – Used to see which of the folders are set to never refresh.

$ViewInhereritedFrom – This tells us the name of the view or folder whose settings were used as a “template” for the current folder in the Create Folder dialog in Lotus Notes (as pictured below).

(Tip: hold the Ctrl key to select non-contiguous items in the grid).

Now click the Values button and pick Grouping Grid in the pop-up.

In the Values grid we can see the item values for all the folders in our application. Here’s how we can narrow things down to just the folders which are set to never refresh:

First we click the column header Filter button for the $Flags field then enter “P” (without the quotes) under Text filters>$Flags contains…

Now we should see all the designs with the “P” $Flag (which indicates the design is not to be updated in a design refresh or replacement).

However, the Text filter isn’t case sensitive so if your selection contains any $Flag values with only a lowercase “p” (which indicates it’s a private on first use design*) you can use a Values filter, as shown below, to remove them.

*If the flag contains both an uppercase “P” and lowercase “p” it means that it’s a private folder that was created from a private on first use design and as such is automatically set not to refresh; we’ll want to include such designs in our collection. Also note that scanEZ includes a handy $Flag value reference right inside the product; so see it, just click the Help button in the Field Value tab (which appears whenever an individual document or design item is selected).

Now that we’ve narrowed down our selection to only the folders that require modification we’ll select them all (Ctrl + A) and add them to a new ‘MySelection‘ virtual folder (Right click>Add to New MySelection). We’re doing this because those column header filters didn’t actually remove any designs in our collection–they just hid them on screen; any mass modifications performed on the selected category of folders would still affect the ‘filtered-out’ folders.

Now that all the folders are prepared, we’re ready to use the @UpdateViewDesign function.

At this point we’re going to do a test formula with curly quotes that won’t actually change anything but rather serve as an informational ‘dry run.’ What we input will return a string to show what the final formula is going to look like.

Click the Add Column button in Values dialog and choose the Formula radio button in the dialog that pops up.

Next click the Edit… button to enter a formula. The formula is designed to show the final code which we will execute in the next step. This final formula includes the evaluated variables showing which template design will be used to update folders via the @UpdateViewDesign function; we’ll include a ‘fallback design’ to use if the $ViewInheritedFrom item is empty.

Here’s the formula (the view/folder “My Favorites” is the one that will be used if the $ViewInheritedFrom field is blank):

{@UpdateViewDesign(“}+@If(@Contains($TITLE;”|”);@RightBack($TITLE;”|”);$TITLE)+{“;”}+@If($ViewInheritedFrom=””;”My Favorites”;$ViewInheritedFrom)+{“);}

Note: End-user created folders usually don’t have aliases but the example formulas assume the presence of aliases.

The new custom column should now be in the grid; click the Evaluate button to compute the formula and populate the grid with results.

Everything looks OK so let’s do the changes for real.

Let’s click the Add Column button once again, but his time we’ll use the following formula, which is basically the same as the last formula but with no curly quotes (again, the view/folder “My Favorites” will be used if the $ViewInheritedFrom field is blank):

@UpdateViewDesign(@If(@Contains($TITLE;”|”);@RightBack($TITLE;”|”);$TITLE);@If($ViewInheritedFrom=””;”My Favorites”;$ViewInheritedFrom))

Finally we click Evaluate to actually perform the @UpdateViewDesign operation on the the selected design elements. The formula will return a value of “0” unless an error is encountered, in which case a “Invalid or nonexistent document (551)” message will be shown (if that appear appears, there’s a good chance that the design element set in the $ViewInheritedFrom field can no longer be found in the database).

To see the newly updated folders or views, you just need to close and re-open the database in your Lotus Notes client.

This entire procedure shouldn’t take more than a few minutes to complete (depending, of course, on server response times).

We hope that this example will encourage you to experiment with the ‘Add Column‘ feature in the in the Diff/Values dialog. It’s one of our favorite scanEZ features (and a lot of scanEZ users out there that we’ve spoken to hadn’t even tried it).