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

How to compare, contrast and edit Lotus Notes document field values with scanEZ

on 7/22/10

Diff'ing and mass-editing Lotus Notes document fields in Ytria scanEZ

We’re always eager to hear how customers are using our software. Oftentimes folks surprise us with novel and creative uses we never would have thought of ourselves. But every so often, we hear from people who are so busy they haven’t had the chance to explore anything beyond the most immediate, hit-you-over-the-head noticeable aspects of the software (e.g. the Conflict Solver). This is truly a shame because the ‘just below the surface’ features are some of the biggest time-savers (note the cruel irony).

So when it comes to easily missed features, look no further than our scanEZ tool’s ability to Diff and mass-modify groups of documents in Lotus Notes databases. Hardcore scanEZ aficionados are already well aware of how its Diff’ing and mass-editing functionality helps avoid a lot of agonizing work (particularly use-once-and-throw-away agents and views). But if you haven’t had time to check it out, here’s how it works:

First, you need to have a Notes database open in scanEZ (you can select a database in your Notes Workspace and then click the scanEZ icon on the toolbar).

Launching scanEZ from the Lotus Notes Workspace

Customized or pre-made document selections

Next you need to gather some sort of collection of documents to work on. scanEZ automatically categorizes documents by their form name, so you could either select one of these pre-existing categories based on the form or highlight the entire Documents category in the Selection Tree to work on all documents in the database.

But beyond that there are a number of different ways to build your own custom collection of docs to work on, including:

  1. Selecting documents in a view in your Lotus Notes client and then clicking Actions>Open Selected Documents in scanEZ
  2. Using the various search options in scanEZ’s Search menu
  3. Using the checkboxes in scanEZ’s Selection Tree to make a selection, then clicking Checkbox Selection>Add to New ‘My Selection’

No matter which method you choose, your document selections will be placed in a sort of virtual folder that we call a  ‘My Selection‘ (you can re-name My Selections via the right-click menu).

For the sake of this demo, I’ll just tick the checkboxes for the ‘MyDoc’ and ‘MyResp’ categories in this database and click Checkbox Selection>Add to New My Selection. (Tip: I could have gathered the same ‘My Selection’ by performing a Search by Formula with the query: form=’MyDoc’|form=’MyResp’).

Gathering a customized collection of Lotus Notes documents for analysis and mass-modification

Once you have a My Selection that contains the documents that you’d like to work on,  you simply highlight it in the tree to reveal scanEZ’s Diff Panel.

A 'My Selection' virtual folder in scanEZ's Selection Tree

A 'My Selection' virtual folder in scanEZ's Selection Tree

Differencing your docs

From here we can click the Diff button to perform a scan that will give us a quick picture of the similarities and differences between of the fields in all the documents in our virtual folder collection:

These are the actions available in scanEZ's Diff Panel

So now we can see what’s going on with these docs on a very basic level–that is, which fields exist in all the docs; which fields are the same throughout; and which fields have different values across the doc collection.

scanEZ's Diff panel shows a complete list of the fields contained in the documents in your collection

scanEZ's Diff Panel: This grid lists all the items found in your document collection plus their basic status. You can instantly spot aberrant items; items with incorrect types etc.

Here we can select one-or-more fields  (Ctrl+Click) then click the Values button to take a closer look; this will show us the field values for all of the selected documents.

(Note:  When you click the Values button, you’ll be prompted to choose between the Grouping Grid or a Basic Grid. The Grouping Grid offers extensive grouping and filtering options but requires more resources, the Basic Grid option dispenses with some of the bells-and-whistles but uses less memory, which makes it handy for huge document collections. For this post, I’ll be using the Grouping Grid).

The Values grid lets you take a closer look at the values of any selected=

The Values grid: This works like a sort of instant 'virtual view' allowing you to take a closer look at any combination of fields in your document collection. Tip: You can customize the displayed titles (see the link to Ytria's Help at the bottom of this post for instructions).

Mass-editing fields part one: the test run

Now say we see something we want to change–for example, the fact that some of the ”Subject’ fields’ values are in all uppercase text…

Let’s do a little test to see what applying a formula to this field would do:

Click Add Column to add a customized temporary column…

The Add Column button in the Values grid lets you simulate field value mass-modification

The Add Custom Column dialog should appear; Choose the Formula radio button then click Edit

This is the dialog that appears after clicking 'Add Column'

Here we can edit a formula, like:

@ProperCase(subject)

…then click OK.

This is what a Custom Column looks like before it is evaluated

Now we click the Evaluate button…

The Evaluate button in the Values grid

…and here we can see what would happen if we applied this formula to this field in our collection of docs:

The Custom Column shows us what effect our formula would have on the document in our collection

Everything looks OK, so let’s close the Column Values grid and perform the change for real.

Mass-editing fields part two: making it count

Now we should be back in the Diff panel.

Make sure the ”Subject’ field is still selected and click the Modify button…

The Modify button in scanEZ's Diff panel

… and in the resulting Modify Item dialog, click the ‘Set Value Using Formula’ tab and once again enter:

@ProperCase(subject)

The Modify Item dialog: You can either enter a static value or apply a formula to change field values

…and then click Apply.

Done! scanEZ will display this confirmation dialog to let us know what changed:

This is the confirmation dialog that appears after modifying a field in the Diff panel

The confirmation dialog that appears after modifying a field in scanEZ. Note: If an error is encountered during the modification process, scanEZ will display a prompt that gives you the ability to skip to the next document.

I’ll believe when I see it

But just to prove to the skeptics among us that this operation worked, we’ll select the ‘Subject’ field and click the Values button once more to see the field value for all the documents in our collection:

Here is the proof that the 'Subject' field value was changed to 'proper case' in all our documents

The values grid once again: This time confirming the changes we made. Tip: The Values grid (and any other grid in Ytria's software) can be copied & pasted to a spreadsheet or text editor.

Looks good… so that’s all there is to it.

In this tutorial we used a very simple formula to solve a trivial issue for this tutorial, but there are myriad real world applications for Diff’ing and Mass-editing Lotus Notes documents. In fact, you could apply bewilderingly long and complex formulas across multiple items if the need arose—and because scanEZ runs independently of Lotus Notes/Domino Designer, it will never tie up your Notes session even if it’s engaged in a Herculean NSF data manipulation task.

So if you use scanEZ, we urge you to take the time to experiment with the Diff panel and the Values grid because once you understand them, these features will absolutely, positively save you time.

Print Friendly, PDF & Email

1 Comment

Trackbacks

  1. Tweets that mention How to compare, contrast and edit Lotus Notes document field values with scanEZ | Ytria Tech Lab -- Topsy.com

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]